Merchant API Documentation — Integrate Gift Card Purchasing

Introduction

The KTN Gift Card Merchant API is a RESTful service that lets you programmatically list available gift cards, purchase them, manage orders, retrieve gift card credentials, and handle refunds. All communication happens over HTTPS with JSON request and response bodies.

Base URL

All API requests should be made to the following base URL. All communication is over HTTPS.

text

https://api.ktngiftcard.katronai.com/katron-gift-card

All endpoints in this documentation are relative to the base URL above. For example,/api/v1/merchant/getAccountDetails resolves to https://api.ktngiftcard.katronai.com/katron-gift-card/api/v1/merchant/getAccountDetails.

Authentication

The API uses Bearer Token authentication. When you create a Merchant API profile, an API key (JWT token) is sent to your registered email address. Include this token in theAuthorization header of every request.

http

GET /api/v1/merchant/getAccountDetails HTTP/1.1
Host: api.ktngiftcard.katronai.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Keep your API key secret. Do not share it in public repositories, client-side code, or any insecure location. If your key is compromised, regenerate it immediately from your API Profile page or by calling the reissue token endpoint.

Quick Start Guide

Get up and running in two simple steps. Create your merchant API profile from the API Profile page, then start making requests.

Retrieve Your API Key

After creating your profile from the API Profile page, your API key (Bearer token) is sent to your registered email address. This token is used for all subsequent calls to /api/v1/merchant/* endpoints.

Tip: Check your spam/junk folder if you don't receive the email. You can regenerate your token at any time from the API Profile page.

Make Your First Request

Use your merchant API key to list all available gift cards:

bash

curl -X GET \
  "https://api.ktngiftcard.katronai.com/katron-gift-card/api/v1/merchant/giftCard/listGiftCards" \
  -H "Authorization: Bearer YOUR_MERCHANT_API_KEY" \
  -H "Content-Type: application/json"

Example successful response:

json

{
  "status": 200,
  "message": "cards fetched successfully",
  "data": [
    {
      "productId": 18808,
      "productName": "Rewarble VISA Global US",
      "denominationType": "RANGE",
      "minSenderDenomination": 5,
      "maxSenderDenomination": 100,
      "fixedSenderDenominations": null,
      "brand": {
        "brandId": 561,
        "brandName": "Rewarble Visa"
      },
      "redeemInstruction": {
        "concise": "Visit the Redemption Website: www.rewarble.com/redeem.\nEnter Rewarble Code...",
        "verbose": "Description:\nExperience the simplicity and privacy of digital payments..."
      }
    }
  ]
}

Account

Get Account Details

Retrieve your merchant account information including profile status, balance, and configuration.

GET/api/v1/merchant/getAccountDetails

Returns detailed information about your merchant API profile including your current balance, active status, charge type, and other account metadata.

bash

curl -X GET \
  "https://api.ktngiftcard.katronai.com/katron-gift-card/api/v1/merchant/getAccountDetails" \
  -H "Authorization: Bearer YOUR_MERCHANT_API_KEY"

Example response:

json

{
  "status": 200,
  "message": "fetched merchant api profile",
  "data": {
    "id": 1,
    "createdAt": "2026-04-15T18:25:05.437+00:00",
    "updatedAt": "2026-04-24T03:13:16.558+00:00",
    "version": 3,
    "active": true,
    "merchantApiProfileBalanceAccount": {
      "id": 1,
      "createdAt": "2026-04-15T18:25:05.439+00:00",
      "updatedAt": "2026-04-15T18:25:05.439+00:00",
      "version": 0,
      "active": false,
      "balance": 0,
      "chargeType": "CHARGE_CARD"
    }
  }
}

Get Active Fee Preference

Retrieve the current fee schedule that applies to your merchant API transactions.

GET/api/v1/merchant/giftCard/getActiveFeePreference

Fees are tier-based and vary by purchase amount. The response contains fixed fees for smaller amounts and a percentage-based fee for larger transactions.

bash

curl -X GET \
  "https://api.ktngiftcard.katronai.com/katron-gift-card/api/v1/merchant/giftCard/getActiveFeePreference" \
  -H "Authorization: Bearer YOUR_MERCHANT_API_KEY"

Example response:

json

{
  "status": 200,
  "message": "successfully fetched",
  "data": {
    "id": 3,
    "createdAt": "2026-04-15T18:20:53.228+00:00",
    "updatedAt": "2026-04-15T18:20:53.228+00:00",
    "version": 0,
    "active": true,
    "giftCardFeeType": "FEE_TYPE_MERCHANT_API",
    "feeFor1To99": 0.6,
    "feeFor100To250": 0.5,
    "feeFor251To500": 0.4,
    "feeFor501To750": 0.3,
    "feeFor751To999": 0.2,
    "feePercentageFor1000To5000": 2
  }
}

Amount Range	Fee Type	Field
$1 – $99	Fixed ($)	`feeFor1To99`
$100 – $250	Fixed ($)	`feeFor100To250`
$251 – $500	Fixed ($)	`feeFor251To500`
$501 – $750	Fixed ($)	`feeFor501To750`
$751 – $999	Fixed ($)	`feeFor751To999`
$1,000 – $5,000	Percentage (%)	`feePercentageFor1000To5000`

Gift Cards

List Gift Cards

Retrieve all available gift cards that can be purchased through your merchant API profile.

GET/api/v1/merchant/giftCard/listGiftCards

Returns a comprehensive list of gift cards including product details, denominations, pricing, brand information, country availability, and redemption instructions. Each card has eitherFIXED orRANGE denomination types.

bash

curl -X GET \
  "https://api.ktngiftcard.katronai.com/katron-gift-card/api/v1/merchant/giftCard/listGiftCards" \
  -H "Authorization: Bearer YOUR_MERCHANT_API_KEY"

Response fields per gift card:

Parameter	Type	Required	Description
`productId`	integer (int64)	Required	Unique identifier for the gift card product. Used when purchasing.
`productName`	string	Required	Display name of the gift card.
`denominationType`	string	Required	FIXED (specific amounts) or RANGE (min/max range).
`fixedRecipientDenominations`	number[]	Optional	Available fixed denominations (when type is FIXED).
`minRecipientDenomination`	number	Optional	Minimum denomination (when type is RANGE).
`maxRecipientDenomination`	number	Optional	Maximum denomination (when type is RANGE).
`recipientCurrencyCode`	string	Required	Currency code for the gift card (e.g., USD, EUR).
`senderFee`	number	Required	Fixed fee charged to the sender.
`senderFeePercentage`	number	Required	Percentage fee charged to the sender.
`discountPercentage`	number	Required	Discount percentage applied to the card.
`logoUrls`	string[]	Required	Array of logo image URLs for the card.
`brand`	object	Required	Brand info: { brandId, brandName }.
`category`	object	Required	Category info: { id, name }.
`country`	object	Required	Country info: { isoName, name, flagUrl }.
`redeemInstruction`	object	Required	Redemption instructions: { concise, verbose }.

Purchase Gift Card

Purchase a gift card through your merchant API profile. The purchase will be charged according to your configured charge type.

POST/api/v1/merchant/giftCard/purchaseGiftCard

Send a JSON request body with the gift card details. The productId can be obtained from the list gift cards endpoint. The unitPrice must match one of the available denominations for the selected gift card.

Idempotent-Key Required: This API expects a unique Idempotent-Key in the request headers to prevent accidental duplicate purchases. This should be a cryptographically generated UUID for every unique transaction attempt. Retries of the same transaction should send the original Idempotent-Key.

Headers

Parameter	Type	Required	Description
`Idempotent-Key`	string	Required	A unique key (UUID recommended) to guarantee idempotency and prevent duplicate charges.

Request Body

Parameter	Type	Required	Description
`productId`	integer (int64)	Required	The ID of the gift card product to purchase.
`unitPrice`	number (float)	Required	The denomination/amount of the gift card.
`email`	string	Optional	Recipient email address for gift card delivery.
`senderName`	string	Required	Name of the sender/purchaser.

bash

curl -X POST \
  "https://api.ktngiftcard.katronai.com/katron-gift-card/api/v1/merchant/giftCard/purchaseGiftCard" \
  -H "Authorization: Bearer YOUR_MERCHANT_API_KEY" \
  -H "Idempotent-Key: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": 1234,
    "unitPrice": 50.00,
    "email": "recipient@example.com",
    "senderName": "Acme Corp"
  }'

Example response:

json

{
  "status": 200,
  "message": "gift card order created!",
  "data": {
    "id": 65,
    "createdAt": "2026-04-24T03:21:54.084+00:00",
    "updatedAt": "2026-04-24T03:21:54.084+00:00",
    "version": 0,
    "active": false,
    "productId": 20308,
    "quantity": 1,
    "unitPrice": 1,
    "fee": 0.6,
    "subTotal": 1,
    "total": 1.6,
    "transactionId": null,
    "customIdentifier": null,
    "email": "mdibrahimk935@gmail.com",
    "productName": "Visa Prepaid US $1 to $150",
    "redeemInstruction": {
      "concise": "Description:\n\nUse your Visa Prepaid card anywhere...",
      "verbose": "Description:\n\nUse your Visa Prepaid card anywhere..."
    },
    "senderName": "ibrahim",
    "paymentStatus": "PENDING",
    "giftCardStatus": "PENDING",
    "giftCardTransactionId": null,
    "giftCardCustomIdentifier": null,
    "paymentTransactionId": "onDXOXLWWWbboObL",
    "productPhoto": "https://cdn.reloadly.com/giftcards/...",
    "merchantApiProfileId": null,
    "chargeType": "CHARGE_CARD"
  }
}

FIXED denomination cards: The unitPrice must exactly match one of the values in fixedRecipientDenominations.

RANGE denomination cards: The unitPrice must be between minRecipientDenomination and maxRecipientDenomination.

Orders

List All Orders

Retrieve a list of all gift card orders placed through your merchant API profile.

GET/api/v1/merchant/giftCard/listAllGiftCardOrders

Returns all orders with details including order status, product information, pricing, and timestamps. Use this to reconcile purchases and track delivery status.

bash

curl -X GET \
  "https://api.ktngiftcard.katronai.com/katron-gift-card/api/v1/merchant/giftCard/listAllGiftCardOrders" \
  -H "Authorization: Bearer YOUR_MERCHANT_API_KEY"

Example response:

json

{
  "status": 200,
  "message": "gift card order list fetched successfully",
  "data": [
    {
      "id": 65,
      "createdAt": "2026-04-24T03:21:54.084+00:00",
      "updatedAt": "2026-04-24T03:22:44.510+00:00",
      "version": 2,
      "active": false,
      "productId": 20308,
      "quantity": 1,
      "unitPrice": 1,
      "fee": 0.6,
      "subTotal": 1,
      "total": 1.6,
      "email": "mdibrahimk935@gmail.com",
      "productName": "Visa Prepaid US $1 to $150",
      "senderName": "ibrahim",
      "paymentStatus": "SUCCESS",
      "giftCardStatus": "SUCCESS",
      "giftCardTransactionId": "67767",
      "giftCardCustomIdentifier": "81d71b7a-3b70-4ade-9bf9-6b5138b598c1",
      "paymentTransactionId": "onDXOXLWWWbboObL",
      "merchantApiProfileId": 1,
      "chargeType": "CHARGE_CARD"
    }
  ]
}

Get Order By ID

Retrieve detailed information about a specific gift card order.

GET/api/v1/merchant/giftCard/getGiftCardOrderById?orderId={orderId}

Parameter	Type	Required	Description
`orderId`	integer (int64)	Required	The ID of the gift card order to retrieve.

bash

curl -X GET \
  "https://api.ktngiftcard.katronai.com/katron-gift-card/api/v1/merchant/giftCard/getGiftCardOrderById?orderId=5678" \
  -H "Authorization: Bearer YOUR_MERCHANT_API_KEY"

Example response:

json

{
  "status": 200,
  "message": "gift card fetched successfully",
  "data": {
    "id": 65,
    "createdAt": "2026-04-24T03:21:54.084+00:00",
    "updatedAt": "2026-04-24T03:22:44.510+00:00",
    "version": 2,
    "active": false,
    "productId": 20308,
    "quantity": 1,
    "unitPrice": 1,
    "fee": 0.6,
    "subTotal": 1,
    "total": 1.6,
    "email": "mdibrahimk935@gmail.com",
    "productName": "Visa Prepaid US $1 to $150",
    "senderName": "ibrahim",
    "paymentStatus": "SUCCESS",
    "giftCardStatus": "SUCCESS",
    "giftCardTransactionId": "67767",
    "giftCardCustomIdentifier": "81d71b7a-3b70-4ade-9bf9-6b5138b598c1",
    "paymentTransactionId": "onDXOXLWWWbboObL",
    "chargeType": "CHARGE_CARD"
  }
}

Get Gift Card Credentials

Retrieve the actual gift card details (activation code, PIN, URL, etc.) for a completed order.

GET/api/v1/merchant/giftCard/getGiftCardCredentials?orderId={orderId}

Parameter	Type	Required	Description
`orderId`	integer (int64)	Required	The ID of the gift card order.

bash

curl -X GET \
  "https://api.ktngiftcard.katronai.com/katron-gift-card/api/v1/merchant/giftCard/getGiftCardCredentials?orderId=5678" \
  -H "Authorization: Bearer YOUR_MERCHANT_API_KEY"

Example response:

json

{
  "status": 200,
  "message": "credentials fetched successfully",
  "data": [
    {
      "cardNumber": "9onzdtest",
      "pinCode": "24485test",
      "redemptionUrl": null
    }
  ]
}

Gift card credentials typically include an activation code, PIN, and/or a redemption URL depending on the card brand. Some cards may take a few moments to be fulfilled — use the Refresh Order endpoint if the credentials are not yet available.

Refresh Order

Refresh the status of a gift card order. Useful if the order is still processing or if credentials haven't been delivered yet.

POST/api/v1/merchant/giftCard/refreshOrder?orderId={orderId}

Parameter	Type	Required	Description
`orderId`	integer (int64)	Required	The ID of the order to refresh.

bash

curl -X POST \
  "https://api.ktngiftcard.katronai.com/katron-gift-card/api/v1/merchant/giftCard/refreshOrder?orderId=5678" \
  -H "Authorization: Bearer YOUR_MERCHANT_API_KEY"

Example response:

json

{
  "status": 200,
  "message": "gift card order initiated!",
  "data": ""
}

Refund Order Payment

Request a refund for a gift card order. Refund eligibility depends on the card brand and order status.

POST/api/v1/merchant/giftCard/refundOrderPayment?orderId={orderId}

Parameter	Type	Required	Description
`orderId`	integer (int64)	Required	The ID of the order to refund.

bash

curl -X POST \
  "https://api.ktngiftcard.katronai.com/katron-gift-card/api/v1/merchant/giftCard/refundOrderPayment?orderId=5678" \
  -H "Authorization: Bearer YOUR_MERCHANT_API_KEY"

Example response:

json

{
  "status": 200,
  "message": "refunded successfully",
  "data": "refunded"
}

Refund availability varies by card provider. Some gift cards are non-refundable once fulfilled. The endpoint will return an error if the order is not eligible for a refund.

Void Order Payment

Void the payment for a pending or recently placed order before it is fully processed.

POST/api/v1/merchant/giftCard/voidOrderPayment?orderId={orderId}

Parameter	Type	Required	Description
`orderId`	integer (int64)	Required	The ID of the order to void.

bash

curl -X POST \
  "https://api.ktngiftcard.katronai.com/katron-gift-card/api/v1/merchant/giftCard/voidOrderPayment?orderId=5678" \
  -H "Authorization: Bearer YOUR_MERCHANT_API_KEY"

Example response:

json

{
  "status": 200,
  "message": "voided successfully",
  "data": "void"
}

Voiding a payment is different from a refund. A void cancels a pending transaction before it has fully settled, while a refund reverses a completed transaction. Use void for recent orders that haven't been processed yet.

Schemas

Response Object

All API endpoints return a standardized response envelope with the following structure:

json

{
  "status": 200,         // HTTP status code (integer)
  "message": "Success",  // Human-readable message (string)
  "data": { ... }        // Response payload (object, array, or null)
}

Parameter	Type	Required	Description
`status`	integer (int32)	Required	HTTP status code mirrored in the response body.
`message`	string	Required	Human-readable status message.
`data`	object \| null	Required	The response payload. May be null on errors.

MerchantApiProfileGiftCardOrderRequest

The request body schema for purchasing a gift card through the merchant API.

typescript

interface MerchantApiProfileGiftCardOrderRequest {
  productId: number;   // int64 — Gift card product ID
  unitPrice: number;   // float — Denomination amount
  email?: string;      // Recipient email for delivery
  senderName: string;  // Required — Sender/purchaser name
}

Parameter	Type	Required	Description
`productId`	integer (int64)	Required	The product ID from the list gift cards response.
`unitPrice`	number (float)	Required	Must match a fixed denomination or fall within the min/max range.
`email`	string	Optional	Email address where the gift card credentials will be sent.
`senderName`	string	Required	The name displayed as the sender of the gift card.

ChargeType Enum

The charge type determines how gift card purchases are billed to your merchant account.

Value	Description
`CHARGE_CARD`	Purchases are charged directly to the credit/debit card on file. Ideal for pay-as-you-go usage patterns.
`CHARGE_ACCOUNT_BALANCE`	Purchases are deducted from the pre-loaded merchant account balance. Ideal for high-volume, prepaid usage.

Error Handling

Error Response Format

When an error occurs, the API returns a consistent error envelope. The HTTP status code is mirrored in the response body for convenience.

json

// Example 401 Unauthorized
{
  "status": "error",
  "message": "Full authentication is required to access this resource",
  "errors": "InsufficientAuthenticationException"
}

// Example 400 or 500
{
  "status": "error",
  "message": "message goes to here",
  "errors": "additional error details goes here"
}

Common Error Codes

Status	Meaning	How to Fix
400	Bad Request — Invalid or missing parameters	Check the request format, required parameters, and enum values.
401	Unauthorized — Missing or invalid API key	Ensure the Authorization header contains a valid Bearer token.
403	Forbidden — Access denied for this resource	Ensure you're using the correct endpoint and your profile is active.
404	Not Found — Resource does not exist	Verify the order ID or product ID is correct.
500	Internal Server Error	Retry after a moment. If the issue persists, contact support.

Best practice: Always check the status field in the response body, not just the HTTP status code. Some successful operations may return additional context in themessage field.

Get Started

Ready to integrate?

Create your Merchant API profile and start purchasing gift cards programmatically in minutes.

KTN Gift CardAPI Documentation

Introduction

Base URL

Authentication

Quick Start Guide

Retrieve Your API Key

Make Your First Request

Account

Get Account Details

Get Active Fee Preference

Gift Cards

List Gift Cards

Purchase Gift Card

Orders

List All Orders

Get Order By ID

Get Gift Card Credentials

Refresh Order

Refund Order Payment

Void Order Payment

Schemas

Response Object

MerchantApiProfileGiftCardOrderRequest

ChargeType Enum

Error Handling

Error Response Format

Common Error Codes

Ready to integrate?

KTN Gift Card
API Documentation