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",
    "recipient": {
      "first_name": "A",
      "last_name": "B",
      "email": "example@example.com"
    },
    "send_email": false
}'

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,
      "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

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

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

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.

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.

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.