Introduction

Welcome to the Merit API! You can use our API to access Merit Giftcard platform.

This API has been created for partners to connect to the Gift Card Platform to create gift cards and send it to customers

• Current version of the API is V3 and the endpoints will be prefixed by v3/.

Authentication

Merit uses token based authentication. API keys to allow access to the API.

The client needs to send HTTP requests with the Authorization header that contains the word ‘Bearer’ followed by a space and the Key Secret.

Merit expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer secret_token

To authorize, use this code:

# With shell, you can just pass the correct header with each request

curl "api_endpoint_here" \
  -H "Authorization: Bearer secret_key"

Make sure to replace secret_key with your API key.

Base URL

Base URL for Merit API endpoints

Giftcard Fulfillment

Single Order Async

curl --location --request POST 'https://api.sandbox.meritincentives.com/gift-cards/v3/orders/async' \
--header 'Authorization: Bearer secret_key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "quantity": 1,
    "denomination": 10,
    "product_id": "product_c92jlkj234h4b3kb8c3d",
    "reference_id": "referenceId123",
    "delivery": [
      {
        "channel": "email",
        "send": true,
        "target": "example@example.com",
        "lang": "en"
      },
      {
        "channel": "sms",
        "send": true,
        "target": "+919876543210",
        "lang": "en",
        "variables": { "name": "A" }
      }
    ]
}'

The above command returns JSON structured like this:

{
  "id": "f6ecc851-3aef-4a74-b03a-83fd6e22c8bc",
  "status": "PROCESSING"
}

This request is for creating gift cards for a particular brand. The corresponding product_id for the brand needs to be known. This will be provided by Merit.

HTTP request

POST https://api.sandbox.meritincentives.com/gift-cards/v3/orders/async

Query Parameters

Single Order Async Response

Get Order Details

This request is for getting order status and gift card url. To request this endpoint you will need to provide an order_id parameter which you can obtain in the response to the Single Order Async API .

We recommend using Webhooks to learn when an order’s status changes instead of polling this endpoint on a fixed interval. To register or update your webhook URL, contact the Merit technical team.

When you call Get Order Details whether to reconcile after a webhook, recover from a missed delivery, or retrieve full gift card payload use an exponential backoff strategy if you need to poll. Typically, an order completes within 2 minutes. In rare occurrences, if an order remains in processing status after 30 minutes, please contact our support team for assistance.

Note: Date in YYYY-MM-DD format if an expiry date is applicable; otherwise, the expiry date will be "Unlimited"

HTTP request

GET https://api.sandbox.meritincentives.com/gift-cards/v3/orders/{id}

curl --location --request GET 'https://api.sandbox.meritincentives.com/gift-cards/v3/orders/f6ecc851-3aef-4a74-b03a-83fd6e22c8bc' \
--header 'Authorization: Bearer secret_key'

The above command returns JSON structured like this:

{
  "status": "COMPLETED",
  "total_count": 1,
  "success_count": 1,
  "failed_count": 0,
  "id": "f6ecc851-3aef-4a74-b03a-83fd6e22c8bc",
  "reference_id": "referenceId123",
  "items": [
    {
      "status": "COMPLETED",
      "product_id": "product_c92jlkj234h4b3kb8c3d",
      "currency_code": "AED",
      "denomination": 10,
      "giftcard": {
        "card_id": "20230208-12345678",
        "original_value": "10.0",
        "remaining_value": "10.0",
        "expiration_date": "2024-02-08",
        "url": "https://giftcardpreviewlink"
      },
      "recipient": {
        "email": "example@example.com",
        "last_name": "B",
        "first_name": "A"
      },
      "send_email": false,
      "delivery": [
        {
          "channel": "email",
          "send": true,
          "target": "example@example.com",
          "lang": "en"
        },
        {
          "channel": "sms",
          "send": true,
          "template_id": "custom_sms_template",
          "target": "+919876543210",
          "lang": "en",
          "variables": { "name": "A" }
        }
      ],
      "created_at": "2023-02-08T10:14:42.000Z"
    }
  ],
  "created_at": "2023-02-08T10:14:42.000Z",
  "total_pages": 1,
  "current_page": 1
}

Get Order Response

Order Item

Giftcard

Get Orders by Reference ID

This request returns every order created with the given reference_id. One reference_id can match more than one order — for example when an earlier order failed or was canceled and a later order with the same reference completed. Orders are returned newest first.

Use this endpoint when you know the reference_id you sent on Single Order Async and need the matching orders, including gift card details for completed items. To look up a single order by its Merit order id, use Get Order Details.

reference_id is required and is matched exactly, including case. If it is missing, the API returns HTTP 400 with error code 2004 (INVALID_REQUEST_ERROR). If no orders exist for that reference, the API returns HTTP 404 with error code 2010 (VALIDATION_ERROR, "order not found").

Results are paginated. limit defaults to 10 and must be between 1 and 20. When pagination.has_more is true, pass pagination.next_cursor as the cursor query parameter to fetch the next page. On the last page, next_cursor is null and has_more is false.

This response does not include total_pages or current_page.

HTTP request

GET https://api.sandbox.meritincentives.com/gift-cards/v3/orders?reference_id={reference_id}

curl --location --request GET 'https://api.sandbox.meritincentives.com/gift-cards/v3/orders?reference_id=referenceId123' \
--header 'Authorization: Bearer secret_key'

The above command returns JSON structured like this:

{
  "data": [
    {
      "status": "CANCELED",
      "total_count": 1,
      "success_count": 0,
      "failed_count": 0,
      "id": "7a1c2e44-91b0-4d3a-8f21-0c5e6a7b8d90",
      "reference_id": "referenceId123",
      "meta": null,
      "created_at": "2023-02-10T06:16:05.000Z",
      "items": [
        {
          "id": "10003",
          "status": "CANCELED",
          "product_id": "product_c92jlkj234h4b3kb8c3d",
          "currency_code": "AED",
          "denomination": 10,
          "giftcard": null,
          "recipient": {
            "email": "example@example.com",
            "last_name": "B",
            "first_name": "A"
          },
          "send_email": 0,
          "delivery": [
            {
              "lang": "en",
              "send": true,
              "target": "+919876543210",
              "channel": "sms",
              "variables": {
                "name": "A"
              },
              "template_id": "custom_sms_template"
            },
            {
              "lang": "en",
              "send": true,
              "target": "example@example.com",
              "channel": "email",
              "variables": {
                "name": "A"
              },
              "template_id": "custom_email_template"
            }
          ],
          "created_at": "2023-02-10T06:16:05.000Z"
        }
      ]
    },
    {
      "status": "COMPLETED",
      "total_count": 1,
      "success_count": 1,
      "failed_count": 0,
      "id": "f6ecc851-3aef-4a74-b03a-83fd6e22c8bc",
      "reference_id": "referenceId123",
      "meta": null,
      "created_at": "2023-02-08T10:14:42.000Z",
      "items": [
        {
          "id": "10002",
          "status": "COMPLETED",
          "product_id": "product_c92jlkj234h4b3kb8c3d",
          "currency_code": "AED",
          "denomination": 10,
          "giftcard": {
            "card_id": "20230208-12345678",
            "original_value": "10.0",
            "remaining_value": "10.0",
            "expiration_date": "2024-02-08",
            "url": "https://giftcardpreviewlink",
            "use_link": true
          },
          "recipient": {
            "email": "example@example.com",
            "last_name": "B",
            "first_name": "A"
          },
          "send_email": 0,
          "delivery": [
            {
              "lang": "en",
              "send": true,
              "target": "+919876543210",
              "channel": "sms",
              "variables": {
                "name": "A"
              },
              "template_id": "custom_sms_template"
            },
            {
              "lang": "en",
              "send": true,
              "target": "example@example.com",
              "channel": "email",
              "variables": {
                "name": "A"
              },
              "template_id": "custom_email_template"
            }
          ],
          "created_at": "2023-02-08T10:14:42.000Z"
        }
      ]
    },
    {
      "status": "FAILED",
      "total_count": 1,
      "success_count": 0,
      "failed_count": 1,
      "id": "2b9d4f18-55c1-4e7a-9a33-1d8f0c2e4b61",
      "reference_id": "referenceId123",
      "meta": null,
      "created_at": "2023-02-08T10:10:03.000Z",
      "items": [
        {
          "id": "10001",
          "status": "FAILED",
          "product_id": "product_c92jlkj234h4b3kb8c3d",
          "currency_code": "AED",
          "denomination": 10,
          "giftcard": null,
          "recipient": {
            "email": "example@example.com",
            "last_name": "B",
            "first_name": "A"
          },
          "send_email": 0,
          "delivery": [
            {
              "lang": "en",
              "send": true,
              "target": "+919876543210",
              "channel": "sms",
              "variables": {
                "name": "A"
              },
              "template_id": "custom_sms_template"
            },
            {
              "lang": "en",
              "send": true,
              "target": "example@example.com",
              "channel": "email",
              "variables": {
                "name": "A"
              },
              "template_id": "custom_email_template"
            }
          ],
          "created_at": "2023-02-08T10:10:04.000Z"
        }
      ]
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Query Parameters

Get Orders by Reference ID Response

Order

Pagination

Order Reprocess

curl --location  --request  POST  ' https://api.sandbox.meritincentives.com/gift-cards/v3/orders/6e755c0d-23d0-48a3-a047-0a754bca41b8/reprocess'  \
--header 'Authorization: Bearer secret_key'  \
--header 'idempotency-key: b8e0183f-51a8-49cc-96be-189fc9a4a4ee'  \

The above command returns JSON structured like this:

{
  "id": "6e755c0d-23d0-48a3-a047-0a754bca41b8",
  "status": "PROCESSING"
}

This request is for reprocessing the order that was FAILED or PARTIALLY_COMPLETED. The corresponding id from the create giftcard response needs to be provided.

HTTP request

POST https://api.sandbox.meritincentives.com/gift-cards/v3/orders/:id/reprocess

Query Parameters

Reprocess Response

Vendor Account

Get Account Balance

This Api returns the account balance.

HTTP request

GET https://api.sandbox.meritincentives.com/account/v3/balances

curl --location --request GET 'https://api.sandbox.meritincentives.com/account/v3/balances' \
--header 'Authorization: Bearer key'

The above command returns JSON structured like this:

{
  "availableFunds": {
    "amount": 47,
    "currencyCode": "AED"
  }
}

Get Account Balance Response

Types

Available Funds

Delivery

The delivery array lets you configure one or more delivery channels for the gift card on order endpoint orders/async, replacing the older recipient/send_email fields with support for multiple channels per order item.

{
  "delivery": [
    {
      "channel": "email",
      "send": true,
      "target": "example@example.com",
      "lang": "en"
    },
    {
      "channel": "sms",
      "send": true,
      "target": "+919876543210",
      "lang": "en",
      "variables": { "name": "A" }
    }
  ]
}

Delivery Entry

Recipient

Note: Language codes supported by the product will be shared by the Merit team

Order Status

Order Item Status

Errors

Merit uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with Merit's servers (these are rare).

Error Attributes

Error Types

HTTP Status Codes

Error codes

Example: Unauthorized Response - HTTP Status Code 401

{
  "errorType": "ACCESS_DENIED_ERROR",
  "errorCode": 2002,
  "errorMessage": "unauthorized"
}

Idempotency

Merit support idempotency to provides protection against accidental duplicate calls causing unintended consequences.

The client needs to send HTTP requests with the idempotency-key header that contains unique identifier string with a maximum of 20 - 64 characters.

If the idempotency-key is not provided, the request will be processed without considering idempotency, potentially leading to duplicate request processing.

Idempotency is applicable only to POST and DELETE calls; idempotency keys sent in GET calls will be ignored.

idempotency key header that looks like the following:

idempotency-key: XXXX-XXXXX-XXXXXX-XXXX

curl "api_endpoint_here"  \

-H  "idempotency-key: XXXX-XXXXX-XXXXXX-XXXX"

Throttle rate

Merit API will throttle/decline incoming requests to prevent misuse of the system. The request rate cannot exceed more than specified below.

When requests from your code exceed a throttle rate, your request fails and a ThrottlingException is returned with a HTTP status code 429 (Too Many Request)

Response will contain following headers.

• RateLimit-Limit: The maximum number of requests you're permitted to make per hour.
• RateLimit-Reset: the time at which the current rate limit window resets in UTC epoch seconds

Webhooks

Integration Guide

Webhooks provide a powerful mechanism to receive real-time notifications about events occurring within your Merit account. By registering a webhook URL, Merit can directly push event data to your application, enabling immediate and automated responses.

Registering a Webhook URL

To begin receiving webhook notifications, provide your webhook URL to the Merit team. Merit will register this URL and subscribe it to relevant events based on your application needs. For instance, accounts using Merit's Giftcard orders APIs will have their webhooks subscribed to related transaction events.
Upon registration, a secret key will be shared with you, essential for the secure verification of incoming notifications.

Webhook Endpoint Requirements

Your endpoint must be a HTTPS POST endpoint listening on port 443.

Handling Webhook requests

Receiving and processing webhook notifications consists of two primary steps:

1. Receipt of Message:

• Your endpoint should acknowledge successful reception by returning an HTTP 2xx status code. Failure to do so prompts Merit to retry according to its retry policy.

1. Verification of Message:

• Verify the X-Merit-Signature header to ensure the authenticity of the received event. A typical signature header is as follows:

The signature contains a timestamp (t) and several signature hashes (e.g., v0, v1). To confirm the legitimacy of an event, your server must validate that at least one of these hashes matches the locally computed version.

During key rotations, it's common to receive multiple hashes under the same version. Example: "X-Merit-Signature": "t=1492774577,v0=ansdoj213e9,v0=6ffbb59b". Even in this case, your sever should make sure that at least one hash matches the locally computed version.

However, note that in normal operations, you will typically encounter only one signature hash (initially, v0) and only one hash per version.

• Verification Process:
  1. Concatenate the timestamp and payload in the format {timestamp},{payload}.
  2. Using a HMAC library, compute your signature using the secret key, the concatenated message in step 1 and encode the result in base64.
  3. (Optional): Verify the timestamp to ensure it's within an acceptable range (e.g., ±10 minutes) to prevent replay attacks.
  4. Perform a constant time comparison between the computed signature and the received signatures to safeguard against timing attacks.

Use this streamlined approach to integrate webhooks efficiently into your application, ensuring real-time responsiveness and enhanced security.

Retry Policy

Merit attempts to deliver a given event to your webhook endpoint for up to 2 days with an exponential back-off. A max of 15 requests will be attempted.

Event

Event object

Data Object

This data object is sent for gift card order events (giftcards.order.*).

You will receive the orderId and order status in the webhook data. Upon receiving the webhook call, the client must make an API call to the Get Order Details API to retrieve the updated order details which include the giftcard information. The giftcard information will not be sent as part of the webhook event.

Inventory Event

Sent when a gift card product, or a single denomination of that product, goes out of stock or becomes available again. Contact the Merit team to subscribe your webhook URL to these events.

Example catalog.giftcards.inventory.out_of_stock notification:

{
  "id": "evt_3f1c2a9e-7b44-4d1a-9c6e-1a2b3c4d5e6f",
  "created_at": 1760000000,
  "event_type": "catalog.giftcards.inventory.out_of_stock",
  "data": {
    "sku": "product_c92jlkj234h4b3kb8c3d",
    "denomination": 10,
    "scope": "denomination",
    "event_type": "catalog.giftcards.inventory.out_of_stock",
    "event_timestamp": "2026-10-06T10:14:42Z",
    "inventory_status": "OUT_OF_STOCK"
  }
}

Example catalog.giftcards.inventory.available notification. denomination is null when the event applies to the whole product:

{
  "id": "evt_8a4d1b2c-6e55-4f0b-8d7a-9f0e1d2c3b4a",
  "created_at": 1760003600,
  "event_type": "catalog.giftcards.inventory.available",
  "data": {
    "sku": "product_c92jlkj234h4b3kb8c3d",
    "denomination": null,
    "scope": "product",
    "event_type": "catalog.giftcards.inventory.available",
    "event_timestamp": "2026-10-06T11:14:42Z",
    "inventory_status": "AVAILABLE"
  }
}

Inventory Event Object

Inventory Data Object

Event Types

This is a list of all the types of events we currently send. We may add more at any time, so in developing and maintaining your code, you should not assume that only these types exist.

Testing

Use these products in the sandbox environment (https://api.sandbox.meritincentives.com) to simulate order outcomes before going live.

Test Products

API Delay Simulation

These products simulate an API delay. The delay is based on the denomination you pass. The denomination value can be from 10 to 100.

Important Implementation Notes

• Reference ID: Save the reference ID in your system before making an API call. This prevents lost orders if the response is not received.
• Idempotency: The idempotency key must remain the same when retrying an order creation. See Idempotency.

Go-Live Process

To successfully transition from the test environment to production, the following steps must be completed.

1. Integration Completion Confirmation - The client confirms that the API integration is successfully completed and tested in the Test Environment.
2. Email Template Submission - The client shares a sample email template containing the Merit Gift Card URL, embedded as per the required format.
3. Email Template Validation & Approval - The Merit Team reviews, validates, and approves the email template.
4. Production Setup Requirements - The client provides their
   • Production IP address
   • Client shares the details of the products that need to be configured in the production environment and Merit Operations team allocates these selected products to the client catalog.
   • Forecast of volumes for the selected products
   • Low float balance alerts and email IDs for receiving low balance alerts emails.
5. Float Amount Deposit - The client deposits the agreed float amount to the Merit account to facilitate transactions.
6. Float Amount Confirmation- The Merit Finance Team confirms receipt of the float amount and updates the balance in the Merit System and set-up the low float balance thresholds.
7. Production Credentials Issuance- The Merit Team configures the agreed products for the client and provides Production Vendor ID & Secret Key.
8. Go-Live & Order Placement- The client integrates the production credentials, completes the final setup, and successfully places test/live orders to officially go live.