Skip to content

Notify Transaction

Your marketplace should notify Cardlytics each time a transaction has occurred for a user. Your marketplace should POST a json document to /webhook/transactions

Endpoint

  • Base Url: https://poweredby.dosh.com
  • Path: /webhook/transactions
  • Method: POST
  • Content-Type: application/json; charset=UTF-8

Request Body Format

The For? column below indicates what offer content and styles requires this field in order to be active on your marketplace.

  • All: All content and offer styles
  • Local Content (LC): Local and largely independently owned merchants like restaurants and dry cleaners.
  • Payment Method Offer (PMO): Offers that are restricted to how customers enter their payment method or the type of payment method.
  • Improved Match (IM): Note that an IM does not mean that the data isn't useful. Any data that can be passed about the transaction further identifying the merchant and location improves the matching rate and overall satisfaction for your customers.
  • Test: useful for sandbox testing and validation.
Field Required Type Example Description
userId Yes string 00000000-0000-0000-0000-000000000000 This is your marketplace’s unique identifier for your user. Supports an id up to 36 characters.

**Note: It's very important that this userId matches with the userId sent through the mobile sdk **
paymentMethodId Yes string 22222222-2222-2222-2222-222222222222 This is your marketplace’s unique identifier for the payment method (card, wallet, etc.) that your user used in the transaction. Supports an id up to 36 characters.
paymentMethod Yes string one of:
DEBIT,
CREDIT,
DIGITAL_WALLET		 Describes the payment method's type (debit card, credit card, etc)
transactionId Yes string 33333333-3333-3333-3333-333333333333 This is your marketplace’s unique identifier for the transaction on the paymentMethod. Supports an id up to 36 characters.

**Note: It's very important that this identifier be universally unique across all of your transactions. **
type Yes string one of:
AUTHORIZED,
CLEAR,
RETURN,
CHARGEBACK
paymentNetworkMerchant Yes string Dunkin' Donuts 128" This is the data that the payment networks provide to describe the merchant and transaction.

We require the raw data from the processor for this field (I.e. No truncation, transformation, or masking), as this data point can be used as part of the transaction matching process.
currency Yes string USD ISO three letter currency code.
amount Yes number 2575 When USD, the total number of pennies in the transaction. The amount should always be a positive integer regardless of the transaction type.

If your system tracks fractional pennies, we recommend truncating those fractional pennies off of the value. For example: 1.0175 would become 101.
transactionTimestamp Yes string 2012-03-29T10:05:45.000Z ISO 8601 format of the payment network’s record of the transaction timestamp
notificationTimestamp Yes string 2012-03-29T11:06:55.000Z ISO 8601 format of the marketplace’s first knowledge (notification from the payment network) of the transaction
paymentNetworkId Yes string one of:
VISA,
MASTERCARD,
AMEX,
DISCOVER,
PAYPAL		 If paymentMethod of DIGITAL_WALLET, describe the funding source payment method.
paymentMethodEntryType No string How the payment method was entered at the POS. One of:
NOT_SPECIFIED,
QRC,
SWIPE,
APPLE_PAY,
GOOGLE_PAY,
DEBIT_PIN
paymentMethodProductId No string RSC Your marketplace's payment method product ID, if known.
paymentMethodBillingPostalCode No string 78759 Payment Method's billing postal code.
paymentNetworkBrand No string DUNKIN When the brand is known, this is the marketplace identifier for that brand.
paymentNetworkMCC Yes string 5912 ISO 18245 number describing the merchant's category code
paymentNetworkMerchantId Yes string 8888888bbbbb The payment method network’s identifier for the merchant. For example, this is what MASTERCARD would call their "MID"
paymentNetworkMerchantIdType Yes string one of:
MID (Mastercard),
CAID (Visa),
VSID (Visa), SE (Amex)		 The payment method network’s identifier type for the merchant
paymentNetworkMerchantAddress1 No string 123 Main St Street address information.
paymentNetworkMerchantAddress2 No string Suite 100 Street address information.
paymentNetworkMerchantCity No string Austin Merchant's city.
paymentNetworkMerchantState No string TX Merchant's state.
paymentNetworkMerchantPostal No string 78733 Merchant's postal code.
paymentNetworkMerchantCountryCode No string US ISO two letter country code of the merchant.
iin Yes string 403647 the payment method issuer identification number (formerly bin). If paymentMethod of DIGITAL_WALLET, describe the funding source payment method's IIN.
last4 Yes string 0000 the payment method's last 4 digits. If paymentMethod of DIGITAL_WALLET, describe the funding source payment method.
cashAmount Yes number 2000 The amount of the transaction that was given to the consumer as cash. When specified, the amount should always be a positive integer or zero, regardless of the transaction type.

Example: A customer uses their debit card at a merchant and requests $20.00 cash on the point of sale. In this case the cashAmount would be 2000.

When not specified, assumes 0.
sandboxCallbackUrl No string https://sandbox.com/post The sandbox webhook endpoint Cardlytics will call to pass the reward information

Note: This should only be provided when using sandbox credentials.
sandboxClientCertPem No string -----BEGIN CERTIFICATE-----... The sandbox client cert pem to be used when sending reward to the callback url

Note: This should only be provided when using sandbox credentials and your webhook requires mutual TLS authentication.
sandboxClientKey No string -----BEGIN RSA PRIVATE KEY-----... The sandbox client key to be used when sending reward to the callback url

Note: This should only be provided when using sandbox credentials and your webhook requires mutual TLS authentication.
sandboxSimulateOfferSwap No boolean false The sandbox simulate offer swap is used to trigger a scenario where pending reward get cancelled and a different pending reward gets created because that the transaction was target to a different offer

Required fields for specific operations

Field Context where it's required
paymentMethodEntryType Payment Method Offer (PMO)
paymentMethodProductId Payment Method Offer (PMO)
paymentMethodBillingPostalCode Local Content (LC)
paymentNetworkBrand Improved Match (IM)
paymentNetworkMerchantAddress1 Improved Match (IM)
paymentNetworkMerchantAddress2 Improved Match (IM)
paymentNetworkMerchantCity Improved Match (IM)
paymentNetworkMerchantState Improved Match (IM)
paymentNetworkMerchantPostal Improved Match (IM)
paymentNetworkMerchantCountryCode Improved Match (IM)
sandboxCallbackUrl Test
sandboxClientCertPem Test
sandboxClientKey Test
sandboxSimulateOfferSwap Test

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "userId":"00000000-0000-0000-0000-000000000000",
  "paymentMethodId":"22222222-2222-2222-2222-222222222222",
  "paymentMethod":"DEBIT",
  "paymentMethodProductId":"Retirement Savings Card",
  "paymentMethodBillingPostalCode":"78759",
  "paymentNetworkId":"VISA",
  "iin":"403647",
  "last4":"0000",
  "transactionId":"33333333-3333-3333-3333-333333333333",
  "type":"AUTHORIZED",
  "paymentNetworkMerchantId":"8888888bbbbb",
  "paymentNetworkMerchantIdType":"MID",
  "paymentNetworkMerchant":"Dunkin' Donuts 128",
  "paymentNetworkMCC":"5912",
  "currency":"USD",
  "amount":2575,
  "cashAmount":2000,
  "transactionTimestamp":"2012-03-29T10:05:45.000Z",
  "notificationTimestamp":"2012-03-29T11:06:55.000Z"
}

Response

Top Level Entity

Field Returned? Example Description
success always true boolean of whether the request was a success or not.
requestId always 11111111-1111-1111-1111-111111111111 the Cardlytics assigned request id for used for debug purposes.
error when success is false {} (see error structure below) an error object describing the reason Cardlytics was unable to fulfill the request.

Error Entity

Field Returned? Example Description
id always 222222222-2222-2222-2222-222222222222 a unique id for the error.
category always INVALID_INPUT an error category.
message always Input failed validation Error message intended for consumption by engineers, not consumers.
violations When details are available ['userId is required'] Array of string defining violation details within the error.

Success Example

1
2
3
4
{
  "success": true,
  "requestId": "139dee88-6431-4110-8000-34bb99bd1530"
}

Important

200 OK HTTP status code is returned when we successfully process your request.

Failure Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "success": "false",
  "error": {
    "id": "89ca8190-a3fd-4b87-8123-1febcfe3ea88",
    "category": "INVALID_INPUT",
    "message": "Input failed validation",
    "violations": [
      "userId is a required field"
    ]
  }
}

Important

At this point, a 4xx/5xx HTTP status code is returned and the transaction request need to be retried.

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

Event Retry Handling

Transaction ingestion is considered to have failed when Cardlytics does not return a response with a HTTP status code of 200 and the success flag in the response payload is not set to true. Partners should retry the transaction event when the above scenario happens. The following is a suggestion about what a retry mechanism should look like:

  • 2 retries - 30 seconds after the last failed attempt
  • 3 retries - 5 minutes after the last failed attempt
  • 12 retries - 1 hour after the last failed attempt

For example if the Cardlytics transaction ingestion endpoint is down for 12 hours, the delivery of the transaction event should retry up to 18 times which will cover the outage duration and will eventually succeed.

Attempt Request type Time HTTP Response
1 Initial request ~ 01:00:00 500
2 30 second retry ~ 01:00:30 500
3 30 second retry ~ 01:01:00 500
4 5 minutes retry ~ 01:06:00 500
5 5 minutes retry ~ 01:11:00 500
6 5 minutes retry ~ 01:16:00 500
7 1 hour retry ~ 02:16:00 500
8 1 hour retry ~ 03:16:00 500
... ... ... ...
18 1 hour retry ~ 13:16:00 500