Merchant API

Overview

Base URL: https://{gateway-host}/api/pay

All API requests use the POST method. The request and response body are JSON format {"payload": "<AES encrypted Base64 string>"}. Communication is secured by AES encryption + RSA signature.

All JSON field names use lower camel case. Enum values must be sent exactly as documented, for example CREDIT_CARD and LOCAL.

Security Protocol

Keys

Request Format

Headers (all required)

Body

The request body is JSON format. The encrypted ciphertext is placed in the payload field.

{"payload": "<AES encrypted Base64 string>"}

Encryption Process

1. Serialize business parameters to JSON string (the "plaintext")
2. AES encrypt the plaintext → encrypted string (Base64)
3. Concatenate sign string: merchantNo|version|requestId|timestamp|<encrypted string>
4. RSA sign with merchant private key (SHA256withRSA) → sign (Base64)
5. Send request, body is {"payload": "<encrypted string>"}

AES Details

Response Format

Headers

Body

The response body is JSON format. The encrypted ciphertext is in the payload field. Empty string if the request failed.

{"payload": "<AES encrypted Base64 string>"}

Decryption Process

1. Extract the payload value from the response body JSON
2. Verify signature: concatenate merchantNo|version|requestId|timestamp|code|message|<payload value>, verify with platform public key
3. If code is 200, AES decrypt the payload value to get business response JSON
4. If code is not 200, the request failed — check code and message

Response Codes

All date-time fields in merchant API responses use yyyy-MM-dd HH:mm:ss. Date-only fields use yyyy-MM-dd, and time-only fields use HH:mm:ss.

Card Acquiring Products and Flows

Card acquiring supports hosted checkout and API integration modes.

Query Dynamic Required Fields

POST/api/pay/required-fields

Queries extension fields required for the selected payment method before order creation. Checkout mode returns an empty array.

Request Parameters

context Fields

Response Fields

{
  "action": "PAY",
  "currency": "USD",
  "amount": 100,
  "payType": "CREDIT_CARD",
  "integrationMode": "DIRECT"
}

{
  "action": "PAY",
  "currency": "USD",
  "payType": "CREDIT_CARD",
  "integrationMode": "DIRECT",
  "schemaVersion": "54c29e37dbf9431a",
  "fields": [
    {"fieldName":"senderCardNumber","path":"cardInfo.number","required":true},
    {"fieldName":"senderFirstName","path":"extra.senderFirstName","required":true}
  ]
}

integrationMode is provider-neutral. Pay-in defaults to HOSTED; query required fields before creating a DIRECT order.

Items in fields

Merchants should rely on path and required. Put cardInfo.number in top-level cardInfo, customerEmail at the top level, and extra.senderFirstName in extra. If several required fields are absent, create-order returns all missing paths in missingFields.

Create Card Payment

POST/api/pay/in

Creates a collection (pay-in) order and returns a payment URL.

Request Parameters (plaintext JSON before encryption)

Card Acquiring Mode Parameters

integrationMode is a top-level platform-standard field: HOSTED (default) or DIRECT.

Pay-in extra Fields

For API mode, submit card data in top-level cardInfo. Submit other dynamic fields in extra using the exact names returned by Query Required Fields.

actionType is not a create-order request field. The platform returns it in the response: REDIRECT means the payer must open payUrl, while NOMORE means no additional action is required.

cardInfo Object

payType Enum

currency Enum

Response (decrypted payload)

The response also includes userId, payType, customer details, notification/redirect URLs, and timestamps. Its structure matches Pay-in Query and pay-in callbacks.

Example

{
  "userId": "USER10001",
  "outTradeNo": "ORD20240101001",
  "amount": 500.00,
  "currency": "EUR",
  "payType": "CREDIT_CARD",
  "notifyUrl": "https://merchant.com/notify",
  "returnUrl": "https://merchant.com/return",
  "customerName": "John",
  "customerPhone": "9876543210",
  "customerEmail": "[email protected]",
  "cardInfo": {
    "number": "4111111111111111",
    "expireMonth": "12",
    "expireYear": "2026",
    "cvv": "123",
    "name": "John"
  }
}

{
  "tradeId": "T20240101120000001",
  "outTradeNo": "ORD20240101001",
  "tradeStatus": "PAYING",
  "tradeAmount": 500.00,
  "currency": "EUR",
  "checkoutUrl": "https://pay.example.com/checkout?token=opaque-token"
}

Query Card Payment

POST/api/pay/in/query

Query a pay-in order by tradeId or outTradeNo.

Request Parameters

Response

Order Status Values

Example

{
  "outTradeNo": "ORD20240101001"
}

{
  "tradeId": "T20240101120000001",
  "outTradeNo": "ORD20240101001",
  "tradeStatus": "SUCCESS",
  "tradeAmount": 500.00,
  "merchantAmount": 485.00,
  "currency": "INR",
  "checkoutUrl": "https://pay.example.com/checkout?token=opaque-token"
}

Query Local Payout

POST/api/pay/out/query

Query a payout order by tradeId or outTradeNo.

Request Parameters

Response Parameters

Order Status Values

Example

{
  "tradeId": "T20240101120000002"
}

{
  "tradeId": "T20240101120000002",
  "outTradeNo": "PAYOUT20240101001",
  "tradeStatus": "SUCCESS",
  "tradeAmount": 500.00,
  "merchantAmount": 485.00,
  "feeAmount": 15.00,
  "debitAmount": 515.00,
  "currency": "INR",
  "utr": "UTR202401010001"
}

Query Account Balance

POST/api/pay/balance

Query the merchant's account balances. Optionally filter by currency.

Request Parameters

Response

Each item in the array:

Example

{
  "currency": "INR"
}

{
  "collection": [
    {
      "currency": "INR",
      "totalAmount": 100000.00,
      "frozenAmount": 5000.00,
      "availableAmount": 95000.00
    }
  ],
  "payment": [
    {
      "currency": "INR",
      "totalAmount": 20000.00,
      "frozenAmount": 0.00,
      "availableAmount": 20000.00
    }
  ]
}

// Request
{}

// Response
{
  "collection": [
    { "currency": "INR",  "totalAmount": 100000.00, "frozenAmount": 5000.00, "availableAmount": 95000.00 },
    { "currency": "USDT", "totalAmount": 5000.00,   "frozenAmount": 0.00,    "availableAmount": 5000.00  }
  ],
  "payment": []
}

Create Local Payout

POST/api/pay/out

Creates a payout order and returns the platform order ID and current status.

Payout extra Fields

Requirements vary by country, payment method, and supplier. Query dynamic required fields before order creation and submit every returned fieldName in extra.

Response Fields

The response also includes userId, payType, customer details, notification URL, and timestamps. Its structure matches Payout Query and payout callbacks.

{"tradeId":"T202608070001","outTradeNo":"PAYOUT20260807001","tradeStatus":"PAYING"}

Create Refund

POST/api/pay/refund

Creates a refund request for an original pay-in order.

The platform first verifies that the original payment succeeded, cumulative refunds do not exceed the original amount, and both the channel adapter and account support refunds. No refund order is created when refunds are unsupported.

Response Fields

Query Refund

POST/api/pay/refund/query

Exactly one query field must be provided. Response data is always an array. Original-payment queries return an empty array when no refunds exist; refund-ID queries return a single-element array.

Refund Notification

Sent when a refund reaches SUCCESS / FAIL. event is always TRADE_REFUND_ORDER_CALLBACK.

Failed notifications are retried with increasing delays. Respond with plain text SUCCESS.

Card Payment Notification

When a pay-in reaches SUCCESS / FAIL, the platform sends a POST notification to its notifyUrl. event is always TRADE_IN_ORDER_CALLBACK.

Notification Parameters

Rules

• Failed notifications are retried with increasing delays.
• Respond with plain text SUCCESS (case-insensitive).
• Any other response or timeout (5 seconds) triggers a retry.

Example

{
  "event": "TRADE_IN_ORDER_CALLBACK",
  "tradeId": "T20240101120000001",
  "outTradeNo": "ORD20240101001",
  "tradeStatus": "SUCCESS",
  "tradeAmount": 500.00,
  "merchantAmount": 485.00,
  "currency": "INR",
  "checkoutUrl": "https://pay.example.com/checkout?token=opaque-token"
}

Merchant response: SUCCESS

Local Payout Notification

When a payout reaches SUCCESS / FAIL, the platform sends a POST notification to its notifyUrl. event is always TRADE_OUT_ORDER_CALLBACK.

Notification Parameters

Rules

• Failed notifications are retried with increasing delays.
• Respond with plain text SUCCESS (case-insensitive).
• Any other response or timeout (5 seconds) triggers a retry.

Example

{
  "event": "TRADE_OUT_ORDER_CALLBACK",
  "tradeId": "T20240101120000002",
  "outTradeNo": "PAYOUT20240101001",
  "tradeStatus": "SUCCESS",
  "tradeAmount": 500.00,
  "merchantAmount": 485.00,
  "feeAmount": 15.00,
  "debitAmount": 515.00,
  "currency": "INR",
  "utr": "UTR202401010001"
}

Merchant response: SUCCESS

Code Examples

import javax.crypto.Cipher;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.security.*;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Arrays;
import java.util.Base64;

public class OpenApiClient {

    /** AES/CBC/PKCS5Padding encrypt */
    public static String aesEncrypt(String plainText, String aesKeyBase64) throws Exception {
        byte[] keyBytes = Base64.getDecoder().decode(aesKeyBase64);
        SecretKeySpec keySpec = new SecretKeySpec(keyBytes, "AES");
        IvParameterSpec iv = new IvParameterSpec(Arrays.copyOf(keyBytes, 16));
        Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
        cipher.init(Cipher.ENCRYPT_MODE, keySpec, iv);
        return Base64.getEncoder().encodeToString(
            cipher.doFinal(plainText.getBytes("UTF-8")));
    }

    /** AES/CBC/PKCS5Padding decrypt */
    public static String aesDecrypt(String cipherBase64, String aesKeyBase64) throws Exception {
        byte[] keyBytes = Base64.getDecoder().decode(aesKeyBase64);
        SecretKeySpec keySpec = new SecretKeySpec(keyBytes, "AES");
        IvParameterSpec iv = new IvParameterSpec(Arrays.copyOf(keyBytes, 16));
        Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
        cipher.init(Cipher.DECRYPT_MODE, keySpec, iv);
        return new String(
            cipher.doFinal(Base64.getDecoder().decode(cipherBase64)), "UTF-8");
    }

    /** SHA256withRSA sign */
    public static String rsaSign(String data, String privateKeyPem) throws Exception {
        String key = privateKeyPem
            .replace("-----BEGIN PRIVATE KEY-----", "")
            .replace("-----END PRIVATE KEY-----", "")
            .replaceAll("\\s+", "");
        byte[] keyBytes = Base64.getDecoder().decode(key);
        PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(keyBytes);
        PrivateKey privKey = KeyFactory.getInstance("RSA").generatePrivate(spec);
        Signature signature = Signature.getInstance("SHA256withRSA");
        signature.initSign(privKey);
        signature.update(data.getBytes("UTF-8"));
        return Base64.getEncoder().encodeToString(signature.sign());
    }

    /** Build and send API request */
    public static void example() throws Exception {
        String merchantNo    = "M20240101001";
        String aesKey        = "your-aes-key-base64";
        String merchantPK    = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----";

        // 1. Business parameters
        String bizJson = "{\"outTradeNo\":\"ORD001\",\"amount\":500,\"currency\":\"EUR\"}";

        // 2. AES encrypt
        String encryptedBody = aesEncrypt(bizJson, aesKey);

        // 3. Build sign string
        String requestId = "req_" + System.currentTimeMillis();
        String timestamp = String.valueOf(System.currentTimeMillis());
        String signData  = String.join("|",
            merchantNo, "1.0", requestId, timestamp, encryptedBody);

        // 4. RSA sign
        String sign = rsaSign(signData, merchantPK);

        // 5. Send HTTP POST with headers; Body is {"payload": "<encrypted string>"}
        String requestBody = "{\"payload\":\"" + encryptedBody + "\"}";
        // Send requestBody as the HTTP POST body
    }
}

<?php
function aesEncrypt(string $plainText, string $aesKeyBase64): string {
    $key = base64_decode($aesKeyBase64);
    $iv  = substr($key, 0, 16);
    $encrypted = openssl_encrypt($plainText, 'AES-128-CBC', $key, OPENSSL_RAW_DATA, $iv);
    return base64_encode($encrypted);
}

function aesDecrypt(string $cipherBase64, string $aesKeyBase64): string {
    $key = base64_decode($aesKeyBase64);
    $iv  = substr($key, 0, 16);
    return openssl_decrypt(base64_decode($cipherBase64), 'AES-128-CBC', $key, OPENSSL_RAW_DATA, $iv);
}

function rsaSign(string $data, string $privateKeyPem): string {
    $privKey = openssl_pkey_get_private($privateKeyPem);
    openssl_sign($data, $signature, $privKey, OPENSSL_ALGO_SHA256);
    return base64_encode($signature);
}

// --- Example: Create Payment Order ---
$merchantNo = 'M20240101001';
$aesKey     = 'your-aes-key-base64';
$privateKey = file_get_contents('/path/to/merchant_private_key.pem');

$bizJson       = json_encode([
    'outTradeNo' => 'ORD001',
    'amount'     => 500,
    'currency'   => 'EUR',
    'payType'    => 'CREDIT_CARD',
]);
$encryptedBody = aesEncrypt($bizJson, $aesKey);

$requestId = 'req_' . time();
$timestamp = (string)(time() * 1000);
$signData  = implode('|', [$merchantNo, '1.0', $requestId, $timestamp, $encryptedBody]);
$sign      = rsaSign($signData, $privateKey);

$ch = curl_init('https://gateway-host/api/pay/in');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        "merchantNo: $merchantNo",
        'version: 1.0',
        "requestId: $requestId",
        "timestamp: $timestamp",
        "sign: $sign",
    ],
    CURLOPT_POSTFIELDS => json_encode(['payload' => $encryptedBody]),
]);
$response = curl_exec($ch);
curl_close($ch);