Create checkout session

Version: 1.0.0

OpenAPI for **Create checkout session** in the Hosted Payment Page flow; returns the checkout page URL and related data. Behavior, session lifetime, and constraints are documented under **POST /v1/checkout/create-session** below.

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**: **30 minutes** from a successful response; see `data.expiresAt`. After expiry, call this API again to create a new session before redirecting to `checkoutUrl`.

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 identifier 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"`
`transactionRequestId`	`string(32)`	Y	Unique transaction request ID for idempotency. Letters, digits, underscore, hyphen only; max 32; unique per request. Pattern: `^[A-Za-z0-9_\-]+$` Example: `"req_1773729578551"`
`referenceOrderId`	`string(6-32)`	Y	Reference order ID, 6–32 chars, letters digits _-\|* only. Used for tracking and disputes. Pattern: `^[A-Za-z0-9_\-\|*]+$` Example: `"ORDER20231119001"`
`merchantId`	`string(32)`	Y	Merchant ID assigned by SUNBAY Example: `"M1260231004"`
`amount`	`object`	Y	Amount breakdown. Payable total = orderAmount + taxAmount + surchargeAmount.
`description`	`string(128)`	Y	Order description shown on checkout Example: `"iPhone 15 Pro - integration test"`
`productList`	`array`	N	Cart line items. If sent, sum of amount × num must equal amount.orderAmount. Example: `[{"amount":9999,"name":"iPhone 15 Pro","num":1}]`
`collectBillingAddress`	`boolean`	N	Whether to collect billing address on checkout Default: `false` Example: `true`
`collectShippingAddress`	`boolean`	N	Whether to collect shipping address on checkout Default: `false` Example: `false`
`merchantReturnUrl`	`string(256)`	N	Merchant return URL after payment completes or is cancelled Format: `uri` Example: `"https://example.com/result"`
`notifyUrl`	`string(200)`	N	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. Format: `uri` Example: `"https://example.com/webhook"`

Request Example

{
  "appId": "smgq9m496ty14ouw",
  "transactionRequestId": "req_1773729578551",
  "referenceOrderId": "ORDER20231119001",
  "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