OpenAPI Quick Reference

OpenAPI and the user-info endpoint use OAuth Access Tokens. Send:

Request header


Authorization: Bearer {ACCESS_TOKEN}

For browser authorization, open the platform website’s authorization page and let the platform handle sign-in. The token endpoint receives parameters for the chosen grant instead of the Bearer header above. See the quickstart for API addresses and placeholders.

Only currently routed capabilities are listed here. Responses may gain fields over time, so clients should ignore unknown fields. For a complete transaction example, see Products, orders and payments.

OAuth and identity

Method	Path	Scope	Description
`GET` / `POST`	`/oauth/authorize`	Within the client grant	Read consent data / submit consent
`POST`	`/oauth/token`	—	Exchange a code, refresh token, or client credentials
`GET`	`/oauth/userinfo`	`openid`	Read the subject; `profile` controls basic profile fields

Merchant and products

Method	Path	Scope	Description
`GET`	`/openapi/v1/merchant`	`merchant.profile.read`	Read the bound merchant’s public profile
`GET`	`/openapi/v1/products`	`products.read`	Paginate enabled products for the bound merchant

Product listing supports page, limit, gd_no, and search_value. The maximum limit is 100.

Orders and payments

These endpoints require a user-authorized token. The order must belong to both the authorized user and the bound merchant.

Method	Path	Scope	Description
`POST`	`/openapi/v1/orders`	`orders.create`	Create an order
`GET`	`/openapi/v1/orders/{order_no}`	`orders.read`	Read order details
`POST`	`/openapi/v1/orders/{order_no}/payment`	`payments.create`	Create a payment session
`GET`	`/openapi/v1/orders/{order_no}/payment`	`payments.read`	Read payment status

Create-order request:

Create-order request


{
  "gd_no": "PRODUCT_NO",
  "quantity": 1,
  "payment_no": "PAYMENT_CHANNEL_NO",
  "other_ipu": {}
}

A successful response uses HTTP 201:

201 Created


{
  "order_no": "ORDER_NO"
}

General collection for external business orders

These routes require a merchant server’s Client Credentials token. They do not create a TDCloud catalog order or require buyer OAuth authorization.

Method	Path	Scope	Description
`GET`	`/openapi/v1/merchant-payment-channels`	`merchant_payments.read`	Discover this merchant’s available channels
`POST`	`/openapi/v1/merchant-payments`	`merchant_payments.create`	Create with amount, external reference and idempotency key
`GET`	`/openapi/v1/merchant-payments/{order_no}`	`merchant_payments.read`	Query this merchant’s collection
`GET`	`/openapi/v1/merchant-payments`	`merchant_payments.read`	Filter by external reference or order number
`GET`	`/openapi/v1/merchant-payments/{order_no}/notifications`	`merchant_payments.read`	Read delivery records
`POST`	`/openapi/v1/merchant-payments/{order_no}/notifications/{event_id}/retry`	`merchant_payments.create`	Replay an exhausted notification

Creation accepts external_reference, idempotency_key, amount_minor, currency, payment_no, optional description, expires_in, return_url, optional notify_enabled, and paired notify_url / notify_secret. Merchants can enable default notifications in Payment and settlement; notify_enabled: false disables them for one order, and changing defaults never changes existing orders. The stored HTTPS destination is opened only after server-confirmed paid. USD 10.50 uses amount_minor: 1050; this is not the catalog-order eight-decimal scale. Collection statuses are strings. See General merchant collection for complete parameters, response fields, filtering, errors and retries.

Integration constraints

Never expose a confidential client’s secret in frontend code.
Request only the minimum scopes the application uses.
Catalog-order amounts use a fixed eight-decimal integer scale; general collection uses currency minor units. See Amounts and data formats.
Reauthorize or refresh on 401 invalid_token; do not blindly retry 403 insufficient_scope.
merchant_inactive means the merchant must be re-enabled first.
Apply idempotency protection around order and payment actions to prevent duplicate user submissions.