Skip to content

Disposition Lookup

This endpoint allows you to lookup the disposition of a transaction for the purposes of support and servicing. Occasionally end consumers will have a question about the state of their reward: is it pending, why hasn't it paid out yet, etc. The disposition returned by this endpoint encodes the current reward state for a given transaction.

Note

Statuses provided in the Dispositions responses are not guaranteed to be ordered the same as the web hooks, since the Disposition service events are propagated asynchronously.

Endpoint

  • Base Url: https://poweredby.dosh.com
  • Path: /api/transaction-dispositions/lookup-disposition
  • Method: POST
  • Content-Type: application/json

Request Body Format

Field Required Example Description
transactionId Yes 33333333-3333-3333-3333-333333333333 This is your marketplace’s unique identifier for the transaction
type No one of:
LATEST,
ALL		 Default to LATEST which gives the last transaction disposition state. ALL, on the other hand, give all disposition states for the given transactionId 
1
2
3
4
{
  "transactionId":"33333333-3333-3333-3333-333333333333",
  "type": "LATEST"
}

Response

The following are examples of successful and failure responses

Success Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "success": true,
  "requestId": "139dee88-6431-4110-8000-34bb99bd1530",
  "environment": "LIVE",
  "dispositions": [{
    "transactionId": "33333333-3333-3333-3333-333333333333",
    "asOf": "2020-07-01T15:00:00.136Z",
    "source": "<marketplace>_<payment-network-id>", // YOURMARKETPLACE_MASTERCARD
    "disposition": "QUALIFIED",
    "motive": "AWAITING_CLEAR"
  }]
}

Failure Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "success": false,
  "requestId": "139dee88-6431-4110-8000-34bb99bd1530",
  "environment": "LIVE",
  "error": {
    "id": "6b154bfd-5925-4d09-8304-5b7428ee8ae1",
    "category": "INVALID_INPUT",
    "message": "Input failed validation",
    "violations": [
        "Failed to decode token: jwt expired"
    ]
  }
}

NOTE: category, message and violations might change depending on the actual issue.

Security

The endpoints you expose and that Cardlytics exposes are available over the public internet. To validate that the request originated from an authenticated client, all requests include a JWT which attests to the authenticity of the request. For more details, see: the API Reference: Overview: Cardlytics JWT Authorization Token.

HTTP Conventions

Cardlytics's API endpoints and webhooks all try to adhere to and honor standard HTTP status codes. Below are the response codes that you may see when calling Cardlytics's endpoints and webhooks.

  • 200 OK - Success. The request is understood and acknowledged. The body of the response may indicate additional context or error conditions.
  • 301 and 302 - Cardlytics does not currently require clients to handle redirects. For future proofing, following 1 redirect for a request to Cardlytics is recommended.
  • 401 Unauthorized - Will be returned when the request does not include required credentials.
  • 403 Forbidden - Will be returned when the caller is not allowed to invoke the endpoint.
  • 404 Not Found - Will be returned when Cardlytics cannot locate the resource requested.
  • 405 Method Not Allowed - Will be returned when Cardlytics does not support the HTTP method requested. Note that most Cardlytics endpoints support POST only.
  • 415 Unsupported Media Type - Will be returned when Cardlytics does not understand the body of the request. Note that most Cardlytics endpoints support application/json only.
  • 429 Too Many Requests - Will be returned when Cardlytics is throttling requests from your client. Note that Cardlytics tries to never respond with this response code but may under extreme circumstances.
  • 500 Internal Server Error - Will be returned when Cardlytics emits an unknown or not-handled error.
  • 501 Not Implemented - Will be returned when Cardlytics completely does not understand the request passed.
  • 503 Service Unavailable - Will be returned if the specific service is down for maintenance or other reasons.