Payment Gateway API

Complete API Documentation for Payment Processing

Table of Contents

Overview

This API provides payment processing capabilities including deposits, withdrawals, balance queries, and order management.

Base URL: https:///api/v1
Content-Type: application/json
API Key Header: x-api-key

Authentication

All API requests require authentication using API key and JWT signature.

Required Headers:
• x-api-key: Your API key
• Content-Type: application/json
• IP Whitelist: Your server IP must be whitelisted

JWT Signature Process

All requests must include a valid JWT signature for security.

Step 1: Prepare Parameters

// Example parameters (exclude 'signature' field)
const params = {
    merchantId: "your_merchant_id",
    transactionId: "unique_transaction_id",
    bankAccountNumber: "1234567890",
    bankName: "KBANK",
    name: "John Doe",
    amount: 1000,
    callbackUrl: "https://your-domain.com/callback",
    type: "QR",
    timestamp: 1640995200
};

Step 2: Sort Parameters

// Sort parameters alphabetically by key
const sortedParams = {};
Object.keys(params)
    .sort()
    .forEach(key => {
        sortedParams[key] = params[key];
    });

Step 3: Generate JWT Signature

// Using jsonwebtoken library
const jwt = require('jsonwebtoken');

const signature = jwt.sign(sortedParams, apiKey, {
    algorithm: 'HS256',
    noTimestamp: true
});

Step 4: Add Signature to Request

// Add signature to your parameters
const requestData = {
    ...params,
    signature: signature
};
Note: You can also use our JWT creation endpoint to generate signatures if needed.

Payment Endpoints

Core payment processing functionality

POST /deposit
Create a new deposit order for payment collection.

Request Parameters

Parameter Type Required Description
merchantId string Yes Your merchant ID
transactionId string Yes Unique transaction identifier
bankAccountNumber string Yes Customer's bank account number
bankName string Yes Customer's bank name (e.g., KBANK, SCB)
name string Yes Customer's name
amount number Yes Amount in THB
callbackUrl string Yes Webhook callback URL
type string Yes Payment type (QR, BANK_TRANSFER)
signature string Yes JWT signature
timestamp number Yes Unix timestamp

Response

{
    "status": "success",
    "message": "Create Success",
    "data": {
        "merchantId": "your_merchant_id",
        "referenceId": "DP1640995200ABC123",
        "transactionId": "unique_transaction_id",
        "status": "pending",
        "amount": 1000,
        "depositAmount": 995,
        "qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
        "bankAccountNumber": "1234567890",
        "bankAccountName": "Platform Bank Account",
        "bankName": "KBANK",
        "promptpayNumber": "0812345678",
        "expireDate": "2024-01-01T12:05:00.000Z",
        "customerData": {
            "bankAccountNumber": "1234567890",
            "bankName": "KBANK",
            "name": "John Doe"
        }
    }
}
POST /withdrawal
Create a withdrawal request to transfer funds to customer's bank account.

Request Parameters

Parameter Type Required Description
agent_order_no string Yes Unique order identifier
amount number Yes Amount in THB
bank_code string Yes Bank code (e.g., KBANK, SCB)
account_no string Yes Bank account number
account_name string Yes Account holder name
callback_url string Yes Webhook callback URL
timestamp string Yes Unix timestamp
signature string Yes JWT signature

Response

{
    "code": 200,
    "message": "Success",
    "data": {
        "order_no": "WD1640995200XYZ789",
        "agent_order_no": "unique_order_id",
        "amount": 1000,
        "fee": 15,
        "transfer_amount": 985,
        "status": "pending"
    }
}
GET /balance
Get current account balance information.

Request Parameters

Parameter Type Required Description
timestamp number Yes Unix timestamp
signature string Yes JWT signature

Response

{
    "code": 200,
    "message": "Success",
    "data": {
        "balance": 50000,
        "currency": "THB"
    }
}
GET /order/query
Query order status and details.

Request Parameters

Parameter Type Required Description
order_no string No Platform order number
agent_order_no string No Agent order number
timestamp number Yes Unix timestamp
signature string Yes JWT signature

Response

{
    "code": 200,
    "message": "Success",
    "data": {
        "order_no": "DP1640995200ABC123",
        "agent_order_no": "unique_transaction_id",
        "status": "completed",
        "amount": 1000,
        "fee": 5,
        "actual_amount": 995,
        "created_at": "2024-01-01T12:00:00.000Z",
        "completed_at": "2024-01-01T12:03:00.000Z"
    }
}

Utility Endpoints

Helper endpoints for common operations

POST /jwt/create
Generate JWT signature for API requests. Useful for testing and development.

Request Parameters

Parameter Type Required Description
params object Yes Parameters to sign (excluding 'signature')
api_key string No API key (uses header if not provided)

Response

{
    "code": 200,
    "message": "Success",
    "data": {
        "signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "algorithm": "HS256",
        "payload": {
            "amount": 1000,
            "merchantId": "your_merchant_id",
            "transactionId": "unique_transaction_id"
        }
    }
}
GET /banks
Get list of supported banks and payment methods.

Response

{
    "code": 200,
    "message": "Success",
    "data": {
        "banks": [
            {
                "code": "KBANK",
                "name": "Kasikorn Bank",
                "name_th": "ธนาคารกสิกรไทย",
                "active": true
            },
            {
                "code": "SCB",
                "name": "Siam Commercial Bank",
                "name_th": "ธนาคารไทยพาณิชย์",
                "active": true
            }
        ]
    }
}
GET /health
Health check endpoint to verify API status.

Response

{
    "code": 200,
    "message": "OK",
    "data": {
        "status": "healthy",
        "timestamp": "2024-01-01T12:00:00.000Z",
        "uptime": 3600.5
    }
}

Webhook Callbacks

Our server will send HTTP POST requests to your callback URLs when payment status changes.

Callback Request Format

POST https://your-domain.com/callback
Content-Type: application/json

{
    "order_no": "DP1640995200ABC123",
    "agent_order_no": "unique_transaction_id",
    "type": "deposit",
    "amount": 1000,
    "fee": 5,
    "transfer_amount": 995,
    "actual_amount": 995,
    "status": "completed",
    "timestamp": "1640995380",
    "signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Callback Parameters

Parameter Type Description
order_no string Platform order number
agent_order_no string Your transaction ID
type string Transaction type (deposit/withdrawal)
amount number Original amount
fee number Processing fee
transfer_amount number Amount to transfer
actual_amount number Actual received amount
status string Payment status (pending/completed/failed/expired)
timestamp string Unix timestamp
signature string JWT signature for verification

Expected Response

// Your server should respond with:
{
    "code": 200,
    "message": "Success"
}
Important:
• Callbacks are sent with JWT signatures for verification
• Your server should respond with HTTP 200 status
• We will retry failed callbacks up to 3 times
• Verify the signature before processing the callback

Error Codes

Common error responses and their meanings

Code Message Description
200 Success Request completed successfully
400 Invalid signature JWT signature verification failed
400 transactionId already exists Transaction ID is already used
401 Invalid API key API key is invalid or missing
403 IP not in whitelist Your IP address is not authorized
403 merchantId does not match API key Merchant ID doesn't match the API key
500 Internal server error Server encountered an unexpected error

Payment Gateway API Documentation | Version 1.0