Create checkout session

Version: 1.0.0

ENDPOINT

POST

https://open.sunbay.us/v1/checkout/create-session

Creates a Hosted Payment Page session. Redirect the customer to complete payment on the Hosted Payment Page. Session lifetime defaults to 30 minutes.

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 identifier 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"`
`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: `"ORDER20231119001"`
`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: `"req_1773729578551"`
`merchantId`	`string(32)`	Yes	Merchant ID assigned by SUNBAY Example: `"M1260231004"`
`amount`	`object`	Yes	Amount breakdown. Payable total = orderAmount + taxAmount + surchargeAmount + tipAmount.
`description`	`string(128)`	Yes	Order description shown on checkout Example: `"iPhone 15 Pro - integration test"`
`productList`	`array`	No	Cart line items. If sent, sum of amount × num must equal amount.orderAmount. Example: `[{"amount":9999,"name":"iPhone 15 Pro","num":1}]`
`collectBillingAddress`	`boolean`	No	Whether to collect billing address on checkout Default: `false` Example: `true`
`collectShippingAddress`	`boolean`	No	Whether to collect shipping address on checkout Default: `false` Example: `false`
`merchantReturnUrl`	`string(256)`	No	Merchant return URL after payment completes or is cancelled Format: `uri` Example: `"https://example.com/result"`
`notifyUrl`	`string(200)`	No	Optional. Webhook URL for async payment notifications; if sent, must be public HTTPS. If omitted, no Webhook is sent—obtain final status by other means. See Transaction Result Webhook. Format: `uri` Example: `"https://example.com/webhook"`

Request Example

{
  "appId": "smgq9m496ty14ouw",
  "referenceOrderId": "ORDER20231119001",
  "transactionRequestId": "req_1773729578551",
  "merchantId": "M1260231004",
  "amount": {
    "orderAmount": 9999,
    "taxAmount": 800,
    "priceCurrency": "USD"
  },
  "description": "iPhone 15 Pro - integration test",
  "productList": [
    {
      "amount": 9999,
      "name": "iPhone 15 Pro",
      "num": 1
    }
  ],
  "collectBillingAddress": true,
  "collectShippingAddress": false,
  "merchantReturnUrl": "https://example.com/result",
  "notifyUrl": "https://example.com/webhook"
}

Code Examples

cURLbash

Javajava

Node.jsjavascript

Pythonpython

Response parameters

Name	Type	Required	Description
`code`	`string`	Y	Response code; "0" indicates success Example: `"0"`
`msg`	`string`	N	Response description Example: `"Success"`
`traceId`	`string`	Y	Trace ID for troubleshooting Example: `"TRACE123456789"`
`data`	`object`	Y