UnionPay API

Integrate UnionPay through the KeyBS Pay unified /v1/payouts REST endpoint. Authentication, request/response, sandbox, webhooks, errors and rate limits.

Speed

Real-time

Currency

CNY

Method key

unionpay

Countries

Request sandbox key Full developer docs

UnionPay integrates through the same POST /v1/payouts endpoint used for every KeyBS Pay corridor — you set "method": "unionpay" and the router selects the UnionPay rail. If UnionPay is unavailable for the beneficiary bank at the moment of payment, the router falls back to the next eligible rail unless "strict": true is specified.

Authentication is via a Bearer API key issued from the KeyBS Pay dashboard. Every request MUST include an Idempotency-Key so retries after transient errors are safe. Webhook payloads carry an HMAC-SHA256 signature you must verify with your webhook secret before acting on the event.

Sandbox mode is available end-to-end: keys prefixed sk_test_ hit the sandbox environment, produce deterministic responses for testing, and never move real money. Production sk_live_ keys unlock the UnionPay rail once your KYB is approved.

Corridor data

Corridor mechanics at a glance

Every KeyBS Pay payout follows the same operational contract; only the rail changes.

Endpoint

POST /v1/payouts

Rail method key

"method": "unionpay"

Settlement currency

CNY

Countries

CN, HK, MO

Speed

Real-time

Auth

Bearer token · Idempotency-Key header · request-signed HMAC (optional)

Rate limit

600 req/min per API key · burst 60/s

Webhooks

payout.created · payout.approved · payout.settled · payout.failed — HMAC-SHA256 signed with your webhook secret

Request

POST /v1/payouts

POST https://api.keybs.io/v1/payouts
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "amount": { "value": "1000.00", "currency": "USD" },
  "beneficiary": {
    "name": "Acme Trading Ltd",
    "account_number": "0123456789",
    "country": "CN",
    "currency": "CNY"
  },
  "method": "unionpay",
  "reference": "INV-2026-0001",
  "purpose_code": "supplier_settlement",
  "metadata": { "invoice_id": "INV-2026-0001" }
}

Response

201 Created

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "po_01HZY8V7BQXP5F3AR2E9N4S6K1",
  "status": "approved",
  "amount":       { "value": "1000.00", "currency": "USD" },
  "beneficiary_amount": { "value": "..." /* rail-specific FX */ },
  "rail":         "unionpay",
  "estimated_settlement": "seconds",
  "reference":    "INV-2026-0001",
  "created_at":   "2026-02-14T09:12:00Z"
}

Webhook event

payout.settled — HMAC-signed

POST https://your-app.example/webhooks/keybs
X-KeyBS-Signature: t=1707902000,v1=<HMAC-SHA256(webhookSecret, timestamp + '.' + rawBody)>
Content-Type: application/json

{
  "id":   "evt_01HZY8V7BQXP5F3AR2E9N4S6K1",
  "type": "payout.settled",
  "data": {
    "id":       "po_01HZY8V7BQXP5F3AR2E9N4S6K1",
    "rail":     "unionpay",
    "status":   "settled",
    "settled_at": "2026-02-14T09:12:07Z"
  }
}

Error format

422 Unprocessable Entity

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code":    "beneficiary_verification_failed",
    "message": "Beneficiary account not found on UnionPay",
    "rail":    "unionpay",
    "retryable": false
  }
}

Ask KeyBS AI