跳转到主要内容
POST
/
payment
curl --request POST \
  --url https://uat-api.clinkbill.com/api/payment \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-Timestamp: <x-timestamp>' \
  --data '
{
  "customerId": "cus_xxxxx",
  "productId": "prd_xxxxx",
  "priceId": "price_xxxxx",
  "paymentInstrumentId": "pi_xxxxx",
  "paymentMethodType": "CARD",
  "returnUrl": "https://merchant.example.com/payment/return",
  "merchantReferenceId": "pay_ref_123",
  "platformType": "WEB",
  "deviceType": "Android"
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "orderId": "<string>",
    "sessionId": "<string>",
    "action": {
      "redirectUrl": "<string>",
      "walletHandleRedirectOrDisplayQrCode": {
        "imageUrlPng": "<string>",
        "imageUrlSvg": "<string>",
        "imageDataUrl": "<string>",
        "hostedInstructionsUrl": "<string>",
        "mobileAuthUrl": "<string>",
        "fallbackUrl": "<string>",
        "packageName": "<string>",
        "expiresAt": 123,
        "expiresSecond": 123
      },
      "paymentMethodType": "<string>",
      "postData": {}
    },
    "amount": 123,
    "currency": "<string>"
  }
}
"<string>"

授权

​
X-API-KEY
string
header
必填

Your secret API key obtained from the Clink dashboard (Developers section)

请求头

​
X-Timestamp
string
必填

Current timestamp in milliseconds since Unix epoch (required for request signing)

示例:

"1783513683000"

请求体

application/json

Parameters required to create a one-time payment by API. Provide at least one customer identifier. Provide either priceId with productId, or amount with currency. Use paymentCurrency to charge the customer in a different supported payment currency.

​
paymentInstrumentId
string
必填

Existing payment instrument ID.

​
paymentMethodType
enum<string>
必填

Payment method type. Supported values are uppercase.

可用选项:
ALIPAY,
CARD,
CASHAPP,
GCASH,
KAKAO,
PIX,
PROMPTPAY,
QRIS,
TNG,
UPI,
WECHAT
​
returnUrl
string
必填

URL where the customer is redirected after required payment actions.

​
customerId
string

Existing customer ID. At least one customer identifier is required.

​
customerEmail
string

Customer email. Used to resolve or create a customer when customerId is not provided.

​
referenceCustomerId
string

Merchant-side customer ID used to resolve, create, or bind a customer.

​
priceId
string

Predefined one-time price ID. If provided, productId is required.

​
productId
string

Product ID. Required when priceId is provided.

​
priceDataList
object[]

Product and price line items for direct amount payments or display/risk data.

​
amount
number

Direct payment amount. Required with currency when priceId is not provided.

​
currency
string

Original pricing currency. Required with amount when priceId is not provided. If paymentCurrency is not provided, this currency is also used as the payment currency.

​
paymentCurrency
string

Optional target payment currency. When provided, Clink uses the configured fixed multi-currency price when available, otherwise automatically converts from the original pricing currency. The requested payment method must support the target currency.

示例:

"HKD"

​
merchantReferenceId
string

Merchant-side reference ID for reconciliation.

​
promotionCode
string

Promotion code to apply.

​
metadata
object

Merchant metadata. Values must be strings.

​
platformType
enum<string>

Platform type. Supported values are WEB and WAP.

可用选项:
WEB,
WAP
​
deviceType
enum<string>

Device type. Supported values are Android and iOS.

可用选项:
Android,
iOS

响应

Payment created successfully

​
code
integer<int32>

Response status code, 200 when success

示例:

200

​
msg
string

Brief description of what happened, 'success' when happy case

示例:

"success"

​
data
object

Response data returned after creating a one-time payment. It contains the order and session identifiers, together with the payment flow result.