Notify Reward
Reward webhooks allow you to be notified of rewards on transactions for your users. Your marketplace should expose an https endpoint that accepts a POST of a json document encoded in the UTF-8 character encoding. Cardlytics will publish a reward notification to this endpoint each time a reward changes state.
Reward Lifecycle
| State | Final State? | Description |
|---|---|---|
| REWARD_PENDING | No | This state is triggered when a potential reward has been identified for a transaction. The reward amount can change prior to a REWARD_CONFIRMED state. This state can be triggered by an AUTHORIZED or CLEAR transaction. Once a CLEAR transaction is received, there is a 4 day holding period to facilitate reward confirmation and fraud checking by the Cardlytics platform. After the holding period is successfully completed, the reward moves into REWARD_CONFIRMED state. |
| REWARD_CONFIRMED | Yes | The final reward amount has been calculated. If your marketplace is managing the payout to your users, rewards in this state are guaranteed to be paid out. |
| REWARD_FAILED | Yes* | For almost all cases, this means that we have determined that the transaction didn't qualify for the reward. The most common case for a reward moving into this state is when an AUTHORIZED transaction is received but a CLEAR for the same transaction isn't received within 10 days. In this case Cardlytics assumes the transaction was never captured, meaning the user never actually completed the purchase, and as a result the transaction would not qualify for a reward. In this scenario, if a CLEAR was received after the reward was failed, it would move back to a REWARD_PENDING state. * This state is considered final after 90 days. |
| PAYOUT_PENDING | No | We have initialized the marketplace configured payout for the user for this reward. |
| PAYOUT_FAILED | No | When we tried to pay out through the marketplace configured mechanism, it failed. This state may transition to PAYOUT_PENDING. |
| PAYOUT_CONFIRMED | Yes | Cardlytics has successfully completed the marketplace configured reward payout for the user. The reconciliation file will include all rewards that were in this state within the time period the report was run for. As the Partner, you will be managing the payout to your users, rewards in this state are guaranteed to be paid out to the Partner by Cardlytics in-line with the terms laid out in your contract |
Reward Request Body Format
All fields are going to exist in the request body, except for payoutId. payoutId will only exist in the request
body when the event is in the PAYOUT phase.
| Field | Example | Description |
|---|---|---|
| eventId | 11111111-1111-1111-1111-111111111111 | The unique id of the event. Each event will have a unique event id. |
| event | one of: REWARD_PENDING, REWARD_CONFIRMED, REWARD_FAILED, PAYOUT_PENDING, PAYOUT_CONFIRMED, PAYOUT_FAILED |
The reward event type. |
| eventTimestamp | 2021-04-29T11:06:55.000Z | ISO 8601 formatted timestamp representing when the event happened. |
| notificationTimestamp | 2012-04-29T11:15:55.000Z | ISO 8601 formatted timestamp representing when the event was sent to your configured webhook. |
| userId | 00000000-0000-0000-0000-000000000000 | This is your marketplace’s unique identifier for your user. Supports an id up to 36 characters. |
| rewardId | 44444444-4444-4444-4444-444444444444 | This universally unique identifier refers to a reward for a transaction. You will receive one or more events with the same rewardId as the reward transitions through it move through it's lifecycle. |
| paymentNetworkId | one of: VISA, MASTERCARD, AMEX, DISCOVER, PAYPAL |
The payment network the transaction originated from. |
| transactionId | 33333333-3333-3333-3333-333333333333 | This is the original transaction id that was passed when notifying Cardlytics about the transaction. Note: it's possible for there to be multiple rewards for a single transaction depending on the marketplaces offer configuration.. |
| transactionAmount | 200 | This is the original transaction amount that was passed when notifying Cardlytics about the transaction. |
| transactionCurrency | USD | This is the original transaction currency that was passed when notifying Cardlytics about the transaction. |
| transactionTimestamp | 2021-04-29T11:06:45.000Z | This is the original transaction timestamp that was passed when notifying Cardlytics about the transaction. |
| paymentMethodId | f33b1907-f0d1-4c49-8ae3-8222dc10add2 | This is the Cardlytics assigned identifier for the payment method described in the original transaction |
| last4 | 1234 | This is the original card last4 that was passed when notifying Cardlytics about the transaction. Note: This field is optional and will only be present when the original notify transaction includes it.. |
| merchant | "Dunkin' Donuts" | The Powered By normalized merchant/brand name. Please note that you need to be able to accept a full UTF-8 encoded character set. |
| icon | https://some.host/icon.png | A url to an icon that best represents the merchant. |
| color | #ffffff | Hex color descriptor for the merchant’s preferred reward color. |
| currency | USD | The reward currency. |
| amount | 125 | The reward amount. Note: REWARD_FAILED and PAYOUT FAILED notifications will have a zeroed out amount. |
| payoutId | 66666666-6666-6666-6666-666666666666 | A unique value representing the credit to a user for a reward. Depending on the marketplace's configuration, this may or may not move funds for that user. Note: This is field is only present when sending the PAYOUT web hooks. This field will be null until a PAYOUT_CONFIRMED state is reached. |
| pushNotificationTitle | "You just got $0.90 cash back!" | This field is present on Production web hooks and will only contain values for reward events (no value for payout events) |
| pushNotificationBody | "Congratulations!" | This field is present on Production web hooks and will only contain values for reward events (no value for payout events) |
Reward pending payload example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | |
Payout confirmed payload example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | |
Endpoint Delivery Semantics
Your endpoint should be idempotent. Cardlytics guarantees at-least-once delivery policies for each event. You may use the eventId of an event to help with idempotency as every event Cardlytics sends will have a unique eventId. The eventId for a given event does not change and will be used for all subsequent retries to send the event to your webhook.
Acknowledgment and Error Handling
Once you have successfully received a reward notification, you endpoint should return a 200 HTTP status code.
While 301 and 302 HTTP status codes are both supported be aware we will only follow a redirect once.
All other status codes will be considered an error. For debugging purposes we recommend that partners follow the HTTP spec:
400 Bad Request401 Unauthorized403 Forbidden404 Not Found405 Method Not Allowed406 Not Acceptable500 Internal Server Error501 Not Implemented503 Service Unavailable
Timeout
Your endpoint must respond within 20 seconds or it will be considered an unsuccessful delivery attempt.
Event Retry Handling
Delivery of a webhook payload is considered to have failed when Cardlytics does not receive a response with an HTTP status code of 200 within 20 seconds of sending. Cardlytics will automatically resend notifications multiple times before marking it as failure.
The best-effort retries are set to happen like so:
- 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 your webhook is down for 24 hours, Cardlytics will try to send the payload up to 18 times. The number of times and the timeout window are subject to change, so you should not write code relying on the explicit number.
| 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 |
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.
Originating IP Addresses
Cardlytics requests will always originate from the following IP addresses:
34.200.22.12054.144.103.2054.235.87.177