Checkout Create (Hosted Checkout Order)

This API creates a checkout order and returns a cashier URL and JWT token. The hosted checkout currently supports INTERNATIONAL_CARD only.

1. Endpoint

Item	Description
HTTP Method	POST
URL	/payIn/orders/create
Content-Type	application/json
Auth	Merchant signature (X-Merchant-Id / X-Timestamp / X-Nonce / X-Sign)

Signing rules: Signing and Verification.

2. Request

2.1 Top-level fields

Field	Type	Required	Description
merchantOrderNo	String	Yes	Merchant order number (idempotent)
amount	Decimal	Yes	Order amount (>= 0.01)
currency	String	Yes	Currency (e.g., USD)
methodCode	String	No	Payment method code (only INTERNATIONAL_CARD, default)
productName	String	No	Product name
productDesc	String	No	Product description
billingAddress	Object	No	Billing address
shippingAddress	Object	No	Shipping address
remark	String	No	Remark
returnUrl	String	No	Sync redirect URL (lower priority than merchant config)
extParams	Object	No	Extended parameters (JSON)
lineItems	Array	No	Order line items

2.2 Address object (billingAddress / shippingAddress)

Field	Type	Required	Description
country	String	No	Country (ISO-3166-1 alpha-2)
state	String	No	State or province
city	String	No	City
postalCode	String	No	Postal code
addressLine1	String	No	Address line 1
addressLine2	String	No	Address line 2
name	String	No	Recipient / cardholder name

2.4 lineItems (order line items)

Field	Type	Required	Description
name	String	No	Product name
quantity	Integer	No	Quantity
sku	String	No	SKU
unitPrice	Long	No	Unit price (minor units)
totalAmount	Long	No	Total amount (minor units)
taxAmount	Long	No	Tax amount (minor units)
taxPercentage	Long	No	Tax rate (percentage * 100)

3. Response

Unified response:

{
  "success": true,
  "data": {
    "payNo": "P202412220002",
    "cashierUrl": "https://cashier.example.com/pay?token=xxx",
    "token": "eyJhbGciOi..."
  },
  "errCode": null,
  "errMsg": null
}

data fields

Field	Type	Description
payNo	String	Platform order number
cashierUrl	String	Cashier URL (includes token)
token	String	Cashier JWT (used by frontend)

4. Request example

{
  "merchantOrderNo": "M202412220001",
  "amount": "100.00",
  "currency": "USD",
  "methodCode": "INTERNATIONAL_CARD",
  "productName": "T-shirt",
  "billingAddress": {
    "country": "US",
    "state": "CA",
    "city": "San Francisco",
    "postalCode": "94102",
    "addressLine1": "123 Test Street"
  }
}

5. Notes

• merchantOrderNo is idempotent. Repeated creation returns the existing payNo and a new cashierUrl/token.
• Redirect the user to cashierUrl to complete payment.
• Checkout supports INTERNATIONAL_CARD only; card data is encrypted and submitted by the checkout frontend.