Direct payment

Important

The Direct Payment API involves transmitting sensitive cardholder data. Integrators must hold a valid PCI DSS certification.
Please ensure your systems are PCI DSS compliant and provide Sunbay with the relevant certification documentation before using this API.

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`	Yes	Bearer Token authentication, format: Bearer {your_api_key} Example: `"Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"`
`Content-Type`	`string`	Yes	Request content type, fixed value: application/json
`X-Client-Request-Id`	`string(64)`	Yes	Unique request ID for deduplication and tracing. UUID recommended; must be unique per request. Example: `"550e8400-e29b-41d4-a716-446655440000"`
`X-Timestamp`	`string`	Yes	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)`	Yes	Application ID assigned by SUNBAY Example: `"smgq9m496ty14ouw"`
`merchantId`	`string(32)`	Yes	Merchant ID assigned by SUNBAY Example: `"M1260231004"`
`referenceOrderId`	`string(6-32)`	Yes	Merchant-assigned reference identifying a business order in your system, used to associate this transaction. A single order may be shared across multiple transactions. Length: 6-32 characters. Allowed characters: letters, digits, and `_-\|`. Pattern: `^[A-Za-z0-9_\-\|]+$` Example: `"ORDER_20260311_001"`
`transactionRequestId`	`string(32)`	Yes	Transaction request ID. Client-generated unique identifier for API idempotency control. Must be unique per request. Pattern: `^[A-Za-z0-9_\-]+$` Example: `"sale_req_1741680000000"`
`description`	`string(128)`	Yes	Order description Example: `"iPhone 16 Pro purchase"`
`amount`	`object`	Yes	Amount breakdown. Charged total = orderAmount + taxAmount + surchargeAmount + tipAmount.
`productList`	`array`	No	Line items. If sent, the sum of each item's amount × num must equal amount.orderAmount.
`paymentMethod`	`string`	Yes	Payment method. Must be sent with `cardEncryptedData` containing the encrypted token / JSON string returned by the wallet. Possible values: `GOOGLE_PAY` Example: `"GOOGLE_PAY"`
`cardEncryptedData`	`string`	No	Digital wallet encrypted token (JSON string). Required when `paymentMethod` is `GOOGLE_PAY`. Example: `"<Google Pay token JSON string>"`
`customerEmail`	`string(128)`	No	Buyer email Format: `email` Example: `"buyer@example.com"`
`customerName`	`string(64)`	No	Buyer name Example: `"John Doe"`
`billingAddress`	`object`	No	Billing address
`shippingAddress`	`object`	No	Shipping address; same structure as billingAddress.
`notifyUrl`	`string(200)`	No	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. See Transaction Result Webhook. Format: `uri` Example: `"https://merchant.example.com/webhook/payment"`
`merchantReturnUrl`	`string(256)`	No	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",
  "referenceOrderId": "ORDER_20260311_001",
  "transactionRequestId": "sale_req_1741680000000",
  "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