Skip to content

Sandbox 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. You can go to Notify Reward to have more information about notifyReward process. This endpoint allows you to emulate that behavior in the sandbox environment.

Endpoint

  • Base Url: https://poweredby.dosh.com
  • Path: /api/notify-reward/test
  • Method: POST
  • Content-Type: application/json; charset=UTF-8

Reward Request Body Format

If the optional fields are not provided, they will be populated with random values.

Field Required Example Description
eventId No 1111111-1111-1111-1111-111111111111 The unique id of the event. Each event will have a unique event id.
eventType No One of:
REWARD_PENDING,
REWARD_CONFIRMED,
REWARD_FAILED,
PAYOUT_PENDING,
PAYOUT_FAILED,
PAYOUT_CONFIRMED		 The reward event type.
transactionId No 33333333-3333-3333-3333-333333333333 This is the original transaction id for the transaction that earned this reward.
userId No 00000000-0000-0000-0000-00000000000 This is your marketplace’s unique identifier for your user. Supports an id up to 36 characters.
amount No 2000 The reward amount in pennies.
last4 No 1234 This is the last 4 digits of the card used for the transactions that earned this reward.
currency No USD The reward currency.
merchant No Dunkin' Donuts The normalized merchant/brand name. Please note that you need to be able to accept a full UTF-8 encoded character set.
icon No https://some.host/icon.png A url to an icon that best represents the merchant.
sandboxCallbackUrl Yes https://my-webhook.host.com Your sandbox webhook endpoint we will call to pass the reward information.
sandboxClientCertPem No -----BEGIN CERTIFICATE-----... The sandbox client cert pem to be used when sending reward to the callback url.
sandboxClientKey No -----BEGIN RSA PRIVATE KEY-----... The sandbox client key to be used when sending reward to the callback url.

Examples:

Request body with sandboxCallbackUrl the only required field. 

1
2
3
{
  "sandboxCallbackUrl": "https://my-webhook.host.com"
}

Request body with all fields provided

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "eventId":"1111111-1111-1111-1111-111111111111",
  "transactionId": "33333333-3333-3333-3333-333333333333",
  "userId": "00000000-0000-0000-0000-00000000000",
  "amount": 2000,
  "last4": "1234",
  "merchant": "Dunkin' Donuts",
  "icon": "https://some.host/icon.png",
  "currency": "USD",
  "sandboxCallbackUrl": "https://my-webhook.host.com"
}

Responses

When the event is correctly processed

1
2
3
4
5
6
7
8
9
{
  "success": true,
  "environment": "SANDBOX",
  "requestId": "9276a535-0f14-4722-9051-98bd608db0e9",
  "rewardStatus": {
    "statusCode": 200,
    "ipAddress": "34.200.22.120"
  }
}

When you do not provide sandboxCallbackUrl

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "success": false,
  "environment": "SANDBOX",
  "requestId": "11d37c1b-89da-4454-ad80-0b4004de5070",
  "error": {
    "category": "SERVICE_ERROR",
    "message": "Service error",
    "violations": [
      "Input failed validation"
    ]
  }
}

Webhook response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "eventId": "7a127d74-84b6-46c3-a954-91d224fa51fb",
  "event": "PAYOUT_CONFIRMED",
  "eventReasonCode": "",
  "eventTimestamp": "2021-04-29T20:16:41.949Z",
  "rewardId": "17e60754-652d-4fd4-afa2-b979b364cbec",
  "payoutId": "2cc8b552-be6b-44e0-935a-6a56f5067e90",
  "userId": "88480f3e-51cd-4d00-b2dd-73dadbb01678",
  "paymentNetworkId": "VISA",
  "transactionId": "34d3c8a1-a407-477d-8406-63719fee8136",
  "transactionAmount": 5000,
  "transactionCurrency": "USD",
  "transactionTimestamp": "2021-04-29T20:16:41.949Z",
  "cardId": "b83990a7-cc88-4f30-bcac-7f999d036b65",
  "last4": "1234",
  "merchant": "DOSH CAFE",
  "icon": "https://dosh-cash-res.cloudinary.com/image/upload/brand%20assets/DOSHCAFE/DEFAULT_BRANDING/logo/1579892831.png",
  "color": "#ffffff",
  "currency": "USD",
  "amount": 5000,
  "notificationTimestamp": "2021-04-29T20:16:43.518Z",
  "final": true,
  "finalTimestamp": "2021-04-29T20:16:41.949Z",
  "pushNotificationTitle": "",
  "pushNotificationBody": ""
}

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.

Originating IP Addresses

Cardlytics requests will always originate from the following IP addresses:

  • 34.200.22.120
  • 54.144.103.20
  • 54.235.87.177