Skip to content

Sandbox Notify Transactions

The transaction webhook endpoint gives you the ability to test transaction notification as well as the reward notifications. Make sure to use your SANDBOX credentials and provide a sandboxCallbackUrl attribute in the transaction payload which specifies the endpoint that reward notification should be posted to. There are a few rules that allow you to specify the desired behavior of the transaction notification and reward notification

Info

Sandbox testing runs each transaction notification all the way to reward notification synchronously with the intention of simulating an end-to-end cashback reward experience, that means:

1) Your marketplace publishes a test transaction using your sandbox credentials
2) Cardlytics accepts the transaction notification and identifies it as a sandbox environment transaction
3) Checks are performed to make sure the test transaction is qualified for a reward
4) Cardlytics triggers a cashback reward notification to the sandboxCallbackUrl passed in on the test transaction
5) Cardlytics waits for a response from the test transaction's sandboxCallbackUrl
6) Cardlytics returns the result of the webhook, or any other errors, all the way to caller as a response to the test transaction notification
7) The above described process is all performed synchronously. This is different from normal production transaction notifications which will notify of rewards asynchronously

In case of timeout during sandbox testing, make sure your processor is posting data with a timeout configured to 10s or more

Transaction with Reward Notification ✅

  1. Any whole dollar amount between 100 and 2000 will generate a reward notification call to your sandboxCallbackUrl.
  2. By modifying the paymentNetworkMerchant attribute you are able to control the type of reward notification that will be sent to the sandboxCallbackUrl.
  3. while on Sandbox, the reward amount will be calculated based at 5% of the transaction amount passed in.
Reward Notification Types
REWARD_PENDING
REWARD_CONFIRMED
REWARD_FAILED
PAYOUT_PENDING
PAYOUT_FAILED
PAYOUT_CONFIRMED

The above are the possible reward notification types. By modifying the paymentNetworkMerchant with the format of REWARD_NOTIFICATION_TYPE plus other text we will call your sandboxCallbackUrl with a reward notification of the type REWARD_NOTIFICATION_TYPE. Example: REWARD_PENDING some merchant name will induce a type of REWARD_PENDING

The following is a mapping of the reward type to the reward notification it will produce to the sandbox callback URL.

Types Reward Notification(s) Generated Sequence Total Notifications
REWARD_PENDING REWARD_PENDING 1
REWARD_CONFIRMED REWARD_PENDING, REWARD_CONFIRMED 2
REWARD_FAILED REWARD_PENDING, REWARD_FAILED 2
PAYOUT_PENDING REWARD_PENDING, REWARD_CONFIRMED, PAYOUT_PENDING 3
PAYOUT_FAILED REWARD_PENDING, REWARD_CONFIRMED, PAYOUT_PENDING, PAYOUT_FAILED 4
PAYOUT_CONFIRMED REWARD_PENDING, REWARD_CONFIRMED, PAYOUT_PENDING, PAYOUT_CONFIRMED 4

Transaction with no Reward Notification ❌

  1. Any transaction with an amount > 2000 will not generate a reward notification.
  2. Any transaction with non-zero cents in it will not generate a reward notification. 1900 will generate a notification, but 1910 will not.

Mutual TLS testing

Cardlytics exposes the ability to test Mutual TLS authentication by passing the following fields sandboxClientCertPem and sandboxClientKey, which are the client certificate pem file and client key respectively, in the input payload.

When delivering the webhook to the callback url passed in, Cardlytics will then attach the client cert pem and its client key into the request so the mutual TLS could be authenticated in your webhook side.

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.