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://testapi.meritincentives.com/api/v3/giftcard/orders/async'  \
--header 'Authorization: Bearer secret_key'  \
--header 'Content-Type: application/json'  \
--header 'idempotency-key: b8e0183f-51a8-49cc-96be-189fc9a4a4ee'  \
--data-raw '{
"quantity": 1,
"denomination": 10,
"product_id": "product_c92jlkj234h4b3kb8c3d",
"reference_id": "referenceId123",
"recipient": {
"first_name": "A",
"last_name": "B",
"email": "example@example.com",
"lang":"fr"
},
"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.

Once an order has been successfully placed using the "Single Order Async" API, you can use the "Get Order Details" API to get the order status.

HTTP request

POST https://testapi.meritincentives.com/api/v3/giftcard/orders/async

Query Parameters

Single Order Async Response

Get Order Details

This request is for getting order status and gift card details. 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 .

An exponential backoff strategy is recommended for getting the order details. Typically, an order completes within 2 minutes. In rare occurences, if an order remains in processing status after 30 minutes, please contact our support team for assistance.

Please note that the only way to determine in advance how a particular gift card product fulfills—whether by link, code, link and pin, or code and pin—is by inspecting the order details. To avoid this complexity, we recommend using gift card links (Giftcard.url), as this field will always be present.

HTTP request

GET https://testapi.meritincentives.com/api/v3/giftcard/orders/{{order_id}}

curl --location  --request  GET  'https://testapi.meritincentives.com/api/v3/giftcard/orders/f6ecc851-3aef-4a74-b03a-83fd6e22c8bc'  \

--header 'Authorization: Bearer secret_key' \
--header 'idempotency-key: b8e0183f-51a8-49cc-96be-189fc9a4a4ee'  \

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": {
        "number": "giftcard_number",
        "card_id": "20230208-12345678",
        "original_value": "10.0",
        "remaining_value": "10.0",
        "expiration_date": "2024-02-08",
        "url": "https://giftcardpreviewlink",
        "pin": null
      },
      "recipient": {
        "email": "example@example.com",
        "last_name": "B",
        "first_name": "A",
        "lang":"fr"
      },
      "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://testapi.meritincentives.com/api/v3/giftcard/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://testapi.meritincentives.com/api/v3/giftcard/orders/:id/reprocess

Query Parameters

Reprocess Response

Vendor Account

Get Account Balance

This Api returns the account balance.

HTTP request

GET https://testapi.meritincentives.com/api/v3/vendor/balance

curl --location --request GET 'https://testapi.meritincentives.com/api/v3/vendor/balance' \
--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