Merchant Integration Handbook

curl -X POST 'https://api.hyronpay.com/api/v1/payment/create' \
  -H 'X-API-Key: sk_test_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 100.37,
    "orderId": "ORD-10001",
    "description": "Topup",
    "metadata": {
      "customerId": "u_123",
      "senderAccountNumber": "1673585481",
      "senderBankCode": "GSB",
      "memberName": "นาย ทองดี ใจงาม",
      "memberNameEn": "THONGDEE JAINGAM"
    }
  }'

{
  "success": true,
  "transaction": {
    "id": "uuid",
    "orderId": "ORD-10001",
    "amount": 100.37,
    "fee": 2.01,
    "netAmount": 98.36,
    "status": "PENDING",
    "paymentMethod": "PROMPTPAY",
    "qrCode": "data:image/png;base64,...",
    "qrExpiry": "2026-03-05T08:15:00.000Z",
    "createdAt": "2026-03-05T08:00:00.000Z",
    "copy": {
      "amount": "100.37"
    }
  },
  "paymentAccounts": {
    "channels": {
      "promptPayEnabled": true,
      "bankTransferEnabled": true
    },
    "promptPay": {
      "id": "payin_pp_uuid",
      "type": "PROMPTPAY",
      "name": "Hyronpay PromptPay",
      "accountNumber": "0812345678",
      "bankCode": null,
      "bankName": null,
      "isDefault": true,
      "updatedAt": "2026-03-05T07:58:00.000Z",
      "copy": {
        "account_number": "0812345678"
      }
    },
    "bankAccounts": [
      {
        "id": "payin_bank_uuid",
        "type": "BANK",
        "name": "Hyronpay SCB Main",
        "accountNumber": "1234567890",
        "accountName": "Hyronpay SCB Main",
        "bankCode": "014",
        "bankName": "ธนาคารไทยพาณิชย์",
        "isDefault": true,
        "updatedAt": "2026-03-05T07:59:00.000Z",
        "copy": {
          "account_number": "1234567890"
        }
      }
    ]
  },
  "paymentContractPolicy": {
    "mode": "enforce_all",
    "enforceForThisMerchant": true,
    "reason": "enforce_all mode",
    "enforceNewMerchantFrom": null
  },
  "integrationWarnings": []
}

{
  "success": true,
  "transaction": {
    "id": "uuid",
    "orderId": "ORD-10002",
    "amount": 200.55,
    "fee": 4.01,
    "netAmount": 196.54,
    "status": "PENDING",
    "paymentMethod": "PROMPTPAY",
    "qrCode": null,
    "qrExpiry": "2026-03-05T08:25:00.000Z",
    "createdAt": "2026-03-05T08:10:00.000Z",
    "copy": {
      "amount": "200.55"
    }
  },
  "paymentAccounts": {
    "channels": {
      "promptPayEnabled": false,
      "bankTransferEnabled": true
    },
    "promptPay": null,
    "bankAccounts": [
      {
        "id": "payin_bank_uuid",
        "type": "BANK",
        "name": "Hyronpay SCB Main",
        "accountNumber": "1234567890",
        "accountName": "Hyronpay SCB Main",
        "bankCode": "014",
        "bankName": "ธนาคารไทยพาณิชย์",
        "isDefault": true,
        "updatedAt": "2026-03-05T07:59:00.000Z",
        "copy": {
          "account_number": "1234567890"
        }
      }
    ]
  }
}

curl -X POST 'https://api.hyronpay.com/api/v1/payment/create' \
  -H 'X-API-Key: sk_test_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 300,
    "orderId": "LINK-30001",
    "description": "Topup via hosted page",
    "metadata": {
      "customerId": "u_456",
      "senderAccountNumber": "1234567890",
      "senderBankCode": "SCB",
      "memberName": "สมชาย ใจดี"
    }
  }'

Hosted payment URL pattern
 
1) เรียก POST /api/v1/payment/create ด้วย X-API-Key
2) รับค่า transaction.id จาก response
3) ประกอบลิงก์เป็น https://hyronpay.com/pay/<transaction.id>
 
Example:
https://hyronpay.com/pay/2cda2e8e-7832-4a05-93fc-256c87612529

{
  "success": true,
  "transaction": {
    "id": "uuid",
    "orderId": "ORD-10001",
    "amount": 100.37,
    "fee": 2.01,
    "netAmount": 98.36,
    "status": "PENDING",
    "paymentMethod": "PROMPTPAY",
    "qrCode": "data:image/png;base64,...",
    "qrExpiry": "2026-03-05T08:15:00.000Z",
    "createdAt": "2026-03-05T08:00:00.000Z",
    "copy": {
      "amount": "100.37"
    }
  },
  "paymentAccounts": {
    "channels": {
      "promptPayEnabled": true,
      "bankTransferEnabled": true
    },
    "promptPay": {
      "id": "payin_pp_uuid",
      "type": "PROMPTPAY",
      "name": "Hyronpay PromptPay",
      "accountNumber": "0812345678",
      "bankCode": null,
      "bankName": null,
      "isDefault": true,
      "updatedAt": "2026-03-05T07:58:00.000Z",
      "copy": {
        "account_number": "0812345678"
      }
    },
    "bankAccounts": [
      {
        "id": "payin_bank_uuid",
        "type": "BANK",
        "name": "Hyronpay SCB Main",
        "accountNumber": "1234567890",
        "accountName": "Hyronpay SCB Main",
        "bankCode": "014",
        "bankName": "ธนาคารไทยพาณิชย์",
        "isDefault": true,
        "updatedAt": "2026-03-05T07:59:00.000Z",
        "copy": {
          "account_number": "1234567890"
        }
      }
    ]
  },
  "paymentContractPolicy": {
    "mode": "enforce_all",
    "enforceForThisMerchant": true,
    "reason": "enforce_all mode",
    "enforceNewMerchantFrom": null
  },
  "integrationWarnings": []
}

curl 'https://api.hyronpay.com/api/payment/pay/<transactionId>'

{
  "transaction": {
    "id": "2cda2e8e-7832-4a05-93fc-256c87612529",
    "orderId": "LINK-30001",
    "amount": "300",
    "status": "PENDING",
    "qrCode": null,
    "qrExpiry": "2026-03-08T07:18:51.322Z",
    "merchantName": "Demo Store",
    "description": "Topup via hosted page"
  },
  "paymentAccounts": {
    "promptPay": null,
    "bankAccounts": [
      {
        "id": "payin_bank_uuid",
        "name": "Hyronpay SCB Main",
        "accountNumber": "1234567890",
        "bankCode": "014",
        "bankName": "ธนาคารไทยพาณิชย์",
        "isDefault": true
      }
    ]
  }
}

Merchant ต้องสร้าง headers เองจาก backend ของตัวเอง (Hyronpay ไม่ได้ generate ให้):
 
1) X-API-Key
- ใช้ secret key ของร้านค้า: sk_live_... / sk_test_...
 
2) Idempotency-Key
- สร้างใหม่ต่อ 1 คำสั่งถอน (แนะนำ UUID v4)
- ถ้า retry คำสั่งเดิม ให้ใช้ key เดิม
 
3) X-Signature-Timestamp
- Unix time หน่วยวินาที ตอนที่ยิง request
 
4) X-Signature
- hex(HMAC_SHA256(secret_api_key, "<timestamp>.<raw_body_json>"))
 
5) X-Signature-Nonce
- optional, recommended (ช่วยกัน replay เพิ่มเติม)
 

payload = "<X-Signature-Timestamp>.<raw_body_json>"
X-Signature = hex(HMAC_SHA256(secret_api_key, payload))
 
Required Headers:
- X-API-Key (secret key)
- Idempotency-Key
- X-Signature-Timestamp (unix seconds)
- X-Signature
- X-Signature-Nonce (optional, recommended)
 
Tip: ตรวจค่ากติกาปัจจุบันผ่าน GET /api/v1/payout/signature-settings

const crypto = require('crypto');
 
const secretApiKey = process.env.HYRONPAY_SECRET_KEY; // sk_live_... หรือ sk_test_...
const body = {
  amount: 100,
  destination: {
    bankCode: 'SCB',
    accountNumber: '4190621964',
    accountName: 'เจษฎา',
  },
  metadata: { sourceSystem: 'merchant-backoffice' },
};
 
const rawBody = JSON.stringify(body);
const timestamp = Math.floor(Date.now() / 1000).toString();
const idempotencyKey = crypto.randomUUID();
const signature = crypto
  .createHmac('sha256', secretApiKey)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex');
 
const headers = {
  'X-API-Key': secretApiKey,
  'Content-Type': 'application/json',
  'Idempotency-Key': idempotencyKey,
  'X-Signature-Timestamp': timestamp,
  'X-Signature': signature,
};
 
// ส่งด้วย fetch/axios โดยใช้ headers + rawBody เดียวกันกับที่ sign

curl -X POST 'https://api.hyronpay.com/api/v1/payout/create' \
  -H 'X-API-Key: sk_test_xxxxxxxxx' \
  -H 'Idempotency-Key: m01-wd-20260304-0001' \
  -H 'X-Signature-Timestamp: <unix_seconds>' \
  -H 'X-Signature: <hmac_sha256_hex>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 100,
    "destination": {
      "bankCode": "SCB",
      "accountNumber": "4190621964",
      "accountName": "เจษฎา"
    },
    "metadata": {
      "sourceSystem": "merchant-backoffice"
    }
  }'

{
  "success": true,
  "object": "payout",
  "idempotent": false,
  "payout": {
    "object": "payout",
    "id": "po_123",
    "merchant_id": "m_123",
    "merchant_ref": "M01-WD240001",
    "amount": 100,
    "fee": 0,
    "net_amount": 100,
    "currency": "THB",
    "destination": {
      "bank_code": "014",
      "bank_name": "ธนาคารไทยพาณิชย์",
      "account_number": "4190621964",
      "account_name": "เจษฎา"
    },
    "status": "QUEUED",
    "status_reason": null,
    "external_ref": null,
    "requested_at": "2026-03-05T08:05:00.000Z",
    "processed_at": null,
    "created_at": "2026-03-05T08:05:00.000Z",
    "metadata": {
      "sourceSystem": "merchant-backoffice"
    },
    "copy": {
      "amount": "100.00",
      "account_number": "4190621964"
    }
  }
}

{
  "error": "idempotencyKey is required (send Idempotency-Key header or idempotencyKey field)",
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "details": null
}

copy field contract (internal APIs)
- copy.amount: string ทศนิยม 2 ตำแหน่ง เช่น "100.00"
- copy.account_number: string สำหรับคัดลอกเลขบัญชี
- ถ้ามีเฉพาะ amount -> ส่งเฉพาะ copy.amount
- ถ้ามีเฉพาะ accountNumber/account_number -> ส่งเฉพาะ copy.account_number

{
  "payouts": [
    {
      "id": "po_001",
      "merchantId": "m_123",
      "merchantRef": "M01-WD240001",
      "amount": "100",
      "bankCode": "014",
      "bankName": "ธนาคารไทยพาณิชย์",
      "accountNumber": "4190621964",
      "accountName": "เจษฎา",
      "status": "QUEUED",
      "createdAt": "2026-03-09T10:00:00.000Z",
      "copy": {
        "amount": "100.00",
        "account_number": "4190621964"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  },
  "filters": {
    "status": "all"
  }
}

{
  "settlements": [
    {
      "id": "st_001",
      "merchantId": "m_123",
      "amount": "1200.5",
      "fee": "12.01",
      "netAmount": "1188.49",
      "bankAccount": "1234567890",
      "bankName": "ธนาคารไทยพาณิชย์",
      "status": "PENDING",
      "createdAt": "2026-03-09T10:05:00.000Z",
      "copy": {
        "amount": "1200.50",
        "account_number": "1234567890"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  },
  "filters": {
    "status": "all"
  }
}

{
  "payouts": [
    {
      "id": "po_001",
      "merchantId": "m_123",
      "merchantRef": "M01-WD240001",
      "amount": "100",
      "accountNumber": "4190621964",
      "status": "QUEUED",
      "merchant": {
        "businessName": "Demo Store",
        "username": "merchant_demo"
      },
      "batch": null,
      "copy": {
        "amount": "100.00",
        "account_number": "4190621964"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 1,
    "totalPages": 1
  }
}

{
  "settlements": [
    {
      "id": "st_001",
      "merchantId": "m_123",
      "amount": "1200.5",
      "bankAccount": "1234567890",
      "bankName": "ธนาคารไทยพาณิชย์",
      "status": "PENDING",
      "merchant": {
        "id": "m_123",
        "businessName": "Demo Store",
        "username": "merchant_demo",
        "balance": "9500"
      },
      "copy": {
        "amount": "1200.50",
        "account_number": "1234567890"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  },
  "filters": {
    "status": "ALL",
    "q": ""
  }
}

{
  "transactions": [
    {
      "id": "tx_001",
      "merchantId": "m_123",
      "orderId": "ORD-10001",
      "amount": "100",
      "status": "PAID",
      "referenceId": "ORD-10001",
      "confirmedAt": "2026-03-09T10:10:00.000Z",
      "copy": {
        "amount": "100.00"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalItems": 1,
    "totalPages": 1
  }
}

{
  "success": true,
  "data": [
    {
      "id": "acct_001",
      "type": "BANK",
      "usage": "PAYOUT",
      "name": "SCB Debit Main",
      "accountNumber": "1234567890",
      "bankCode": "014",
      "bankName": "ธนาคารไทยพาณิชย์",
      "isDefault": true,
      "copy": {
        "account_number": "1234567890"
      }
    }
  ]
}

curl 'https://api.hyronpay.com/api/v1/payment/accounts' \
  -H 'X-API-Key: sk_test_xxxxxxxxx'

{
  "object": "payment_accounts",
  "merchant": {
    "id": "merchant_uuid",
    "username": "merchant_demo",
    "business_name": "Demo Store",
    "status": "ACTIVE"
  },
  "channels": {
    "promptpay_enabled": true,
    "bank_transfer_enabled": true
  },
  "promptpay": {
    "id": "payin_pp_uuid",
    "type": "PROMPTPAY",
    "name": "Hyronpay PromptPay",
    "account_number": "0812345678",
    "bank_code": null,
    "bank_name": null,
    "is_default": true,
    "updated_at": "2026-03-06T09:10:00.000Z"
  },
  "bank_accounts": [
    {
      "id": "payin_bank_uuid",
      "type": "BANK",
      "name": "Hyronpay SCB Main",
      "account_number": "1234567890",
      "account_name": "Hyronpay SCB Main",
      "bank_code": "014",
      "bank_name": "ธนาคารไทยพาณิชย์",
      "is_default": true,
      "updated_at": "2026-03-06T09:12:00.000Z"
    }
  ],
  "updated_at": "2026-03-06T09:12:00.000Z"
}

{
  "object": "payment_accounts",
  "merchant": {
    "id": "merchant_uuid",
    "username": "merchant_demo",
    "business_name": "Demo Store",
    "status": "ACTIVE"
  },
  "channels": {
    "promptpay_enabled": false,
    "bank_transfer_enabled": true
  },
  "promptpay": null,
  "bank_accounts": [
    {
      "id": "payin_bank_uuid",
      "type": "BANK",
      "name": "Hyronpay SCB Main",
      "account_number": "1234567890",
      "account_name": "Hyronpay SCB Main",
      "bank_code": "014",
      "bank_name": "ธนาคารไทยพาณิชย์",
      "is_default": true,
      "updated_at": "2026-03-06T09:12:00.000Z"
    }
  ],
  "updated_at": "2026-03-06T09:12:00.000Z"
}