Direct payment

Version: 1.0.0

Initiates and completes a payment. The public integration supports digital wallets such as Google Pay and Apple Pay (submit the encrypted payload returned by the wallet); it does not document merchant-submitted plaintext card data.

ENDPOINT

POST

https://open.sunbay.us/v1/checkout/sale

Creates a payment without creating a Hosted Payment Page session first. Used for online checkout flows.

Parameters

Header parameters

Name	Type	Required	Description
`Authorization`	`string`	Y	Bearer Token authentication, format: Bearer {your_api_key} Example: `"Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"`
`Content-Type`	`string`	Y	Request content type, fixed value: application/json
`X-Client-Request-Id`	`string(64)`	Y	Unique request ID for deduplication and tracing. UUID recommended; must be unique per request. Example: `"550e8400-e29b-41d4-a716-446655440000"`
`X-Timestamp`	`string`	Y	Request timestamp, Unix milliseconds (13 digits), within ±10 minutes of server time. Pattern: `^[0-9]{13}$` Example: `"1742198978000"`

Body parameters

Name	Type	Required	Description
`appId`	`string(32)`	Y	Application ID assigned by SUNBAY Example: `"smgq9m496ty14ouw"`
`merchantId`	`string(32)`	Y	Merchant ID assigned by SUNBAY Example: `"M1260231004"`
`transactionRequestId`	`string(32)`	Y	Merchant-generated unique request ID for idempotency. Repeating the same value returns the first result. Only letters, digits, underscore, and hyphen; max length 32. Pattern: `^[A-Za-z0-9_\-]+$` Example: `"sale_req_1741680000000"`
`referenceOrderId`	`string(6-32)`	Y	Merchant order ID, 6–32 characters: letters, digits, _-\|* only. Pattern: `^[A-Za-z0-9_\-\|*]+$` Example: `"ORDER_20260311_001"`
`description`	`string(128)`	Y	Order description Example: `"iPhone 16 Pro purchase"`
`amount`	`object`	Y	Amount breakdown. Charged total = orderAmount + taxAmount + surchargeAmount.
`productList`	`array`	N	Line items. If sent, the sum of each item's amount × num must equal amount.orderAmount.
`paymentMethod`	`string`	Y	Payment method. Must be sent with `cardEncryptedData` containing the encrypted token / JSON string returned by the wallet. Possible values: `GOOGLE_PAY` `APPLE_PAY` Example: `"GOOGLE_PAY"`
`cardEncryptedData`	`string`	N	Digital wallet encrypted token (JSON string). Required when `paymentMethod` is `GOOGLE_PAY` or `APPLE_PAY`. Example: `"<Google Pay / Apple Pay token JSON string>"`
`customerEmail`	`string(128)`	N	Buyer email Format: `email` Example: `"buyer@example.com"`
`customerName`	`string(64)`	N	Buyer name Example: `"John Doe"`
`billingAddress`	`object`	N	Billing address
`shippingAddress`	`object`	N	Shipping address; same structure as billingAddress.
`notifyUrl`	`string(200)`	N	Optional. Webhook URL for async payment results; if sent, must be publicly reachable HTTPS. If omitted, no Webhook is sent—use other means (e.g. transaction query) for final status. Format: `uri` Example: `"https://merchant.example.com/webhook/payment"`
`merchantReturnUrl`	`string(256)`	N	Browser return URL after payment (used for 3DS redirect flow). Format: `uri` Example: `"https://merchant.example.com/order/result"`

Request Example

{
  "appId": "smgq9m496ty14ouw",
  "merchantId": "M1260231004",
  "transactionRequestId": "sale_req_1741680000000",
  "referenceOrderId": "ORDER_20260311_001",
  "description": "iPhone 16 Pro purchase",
  "amount": {
    "orderAmount": 99999,
    "taxAmount": 8000,
    "priceCurrency": "USD"
  },
  "paymentMethod": "GOOGLE_PAY",
  "cardEncryptedData": "<Google Pay token JSON string>",
  "notifyUrl": "https://merchant.example.com/webhook/payment"
}

Code Examples

cURLbash

Javajava

Node.jsjavascript

Pythonpython

Response parameters

Name	Type	Required	Description
`code`	`string`	N	Response code. "0" means the request was accepted. Example: `"0"`
`msg`	`string`	N	Response message Example: `"Success"`
`traceId`	`string`	N	Trace ID for troubleshooting Example: `"TRACE123456789"`
`data`	`object`	N