Search Dispositions

This endpoint allows you to search dispositions of transactions 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. This endpoint matches dispositions based on the parameters provided. It is useful when you don't have the transaction identifier. When you do have this indentifier, Lookup Disposition might be a better option.

Endpoint

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

Request Body Format

Field	Required	Example	Description
userId	Yes	00000000-0000-0000-0000-000000000000	This is your marketplace’s unique identifier for the user
transactionTimestamp	Yes	2020-07-26T16:55:17.702Z	This is the approximate transaction timestamp
cardId	No	00000000-0000-0000-0000-000000000000	The transaction card id
merchant	No	Dunkin' Donuts	The Powered By normalized merchant/brand name.
transactionAmount	No	125	The transaction Amount in pennies
transactionCurrency	No	USD	The transaction currency

{
  "userId": "00000000-0000-0000-0000-000000000000",
  "transactionTimestamp":"2020-07-26T16:55:17.702Z",
  "transactionAmount": 2000 ,
  "transactionCurrency": "usd",
  "cardId": "",
  "merchant": "Dunkin' Donuts",
}

Sort and Matching

To bring the most valuable information, this endpoint uses the given fields to sort or match. It's important to know that some fields are going to be used to match and others to sort. This helps you to bring the right disposition for the right transaction

Field	Match	Sort
userId	Yes	No
transactionTimestamp	Yes	Yes
cardId	Yes	No
merchant	Yes	Yes
transactionAmount	No	Yes
transactionCurreny	Yes	no

Response

The following are examples of successful and failure responses

Success Example

{
   "success":true,
   "requestId":"6abb555a-1a6d-473a-80a6-baea501f2f40",
   "dispositions":[
      {
        "asOf": "2021-03-31T17:23:37.910Z",
        "source": "<marketplace>_<payment-network-id>", // YOURMARKETPLACE_MASTERCARD,
        "disposition": "NORMALIZED",
        "motive": "RECEIVED_AUTH",
        "cardId": "00000000-0000-0000-0000-000000000000",
        "merchant": "Dunkin",
        "transactionId": "4596774432",
        "transactionAmount": 2000,
        "transactionCurrency": "USD",
        "transactionTimestamp": "2021-03-31T17:21:17.000Z",
        "description": "Dosh has received this transaction and is unsure of the status of this ticket. Please check communal Slack channel for updates and resolution ETA in case this is happening on a multiple case basis, otherwise we will follow up once we have more information."
      },
   ],
   "environment":"LIVE"
}

Failure Example

  { 
    "success": false,
    "environment": "LIVE",
    "requestId": "139dee88-6431-4110-8000-34bb99bd1530",
    "error": {
      "id":"0000000",
      "category": "SERVICE_ERROR",
      "statusCode": 400,
      "message":"Input failed validation",
      "violations": [
        "transactionTimestamp is a required field"
      ]
    }
  }

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 adhere to standard HTTP status codes.

Below are the response codes that you may see when calling Cardlytics endpoints and webhooks.

HTTP Response Code	Description
`200 OK`	Success. The request is understood and acknowledged. The body of the response may indicate additional context or error conditions.
`301 Moved Permanently` `302 Found`	Cardlytics does not currently require clients to handle redirects. For future proofing, following 1 redirect for a request to Cardlytics is recommended
`401 Unauthorized`	Request does not include required credentials
`403 Forbidden`	Caller is not allowed to invoke the endpoint
`404 Not Found`	Cardlytics cannot locate the resource requested
`405 Method Not Allowed`	Cardlytics does not support the HTTP method requested. Note that most Cardlytics endpoints support `POST` only
`415 Unsupported Media Type`	Cardlytics does not understand the body of the request. Note that most Cardlytics endpoints support `application/json` only
`429 Too Many Requests`	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`	An unknown or not-handled error
`501 Not Implemented`	Endpoint does not understand the request passed
`503 Service Unavailable`	The specific service is down for maintenance or other reasons