Unified Payment API

Endpoint
POST {BASE_URL}/api/v2.0/payments/pay

The unified payment API supports various payment scenarios, and the specific payment scenario can be designated based on the scenarioCode.

For different scenarioCode, the required parameters may vary slightly. Please reference to Request Body for more details.

Create a QR Code order ONLINE_QRCODE

QR Code orders are suitable for payment via PC and mobile browsers. Customer pay by scanning QR code with WeChat or Alipay.

Payment Methods

  1. Pay by scanning the QR code generated from merchant payment page. Using:
    • paymentQRImage: Base64-encoded QR code image, this can be directly used as the "src" attribute of the "img" tag;
    • paymentUrl: Payment URL that can be used to generate the QR code.
  2. Using payUrl for redirecting to AlphaPay payment page.
Request Body
scenarioCodestringREQUIRED

Scenario code, representing the payment scenario, see more details at scenarioCode.
Allowed values: ONLINE_QRCODE ONLINE_WEB JSAPI NATIVE_JSAPI ONLINE_WAP APP MINI_APP CREDIT_CARD OFFLINE_QRCODE OFFLINE

paymentRequestIdstringREQUIRED

Merchant order ID

orderobjectREQUIRED

Order Information

Hide child parameters
order.orderAmountobjectREQUIRED

The amount of the order

Hide child parameters
order.orderAmount.valuestringREQUIRED

The value of order amount. All amount figures are based on the minimum denomination unit of given currency. Take CAD as an example, 100 means 1.00CAD.
If the currency is CNY, it must be higher than 0.01CAD after exchange rate conversion, otherwise, the order can be created, but an "amount error" will be thrown.

order.orderAmount.currencystringREQUIRED

Currency code, allowed values: CAD/USD CNY

order.descriptionstringREQUIRED

Title of the order (maximum length 128 characters) <= 128 characters

order.notifyUrlstring

Payment notification URL, the address to push the payment success notification after the payment is successful, see Notification for details

order.redirectUrlstring

Payment redirect URL, the address that will be redirected to after a successful payment.

paymentMethodobjectREQUIRED

Payment method information

Hide child parameters
paymentMethod.paymentMethodTypestringREQUIRED

Payment method, allowed values: Alipay Wechat UnionPay

QR Code Request Body
{
  "scenarioCode": "ONLINE_QRCODE",
  "paymentRequestId": "string",
  "order": {
      "orderAmount": {
          "value": "string",
          "currency": "CAD"
      },
      "description": "string",
      "notifyUrl": "string",
      "redirectUrl": "string"
  },
  "paymentMethod": {
      "paymentMethodType": "Alipay"
  }
}
Response (200 OK)
scenarioCodestring

Scenario code, representing the payment scenario, see more details at scenarioCode.
Allowed values: ONLINE_QRCODE ONLINE_WEB JSAPI NATIVE_JSAPI ONLINE_WAP APP MINI_APP CREDIT_CARD OFFLINE_QRCODE OFFLINE

paymentRequestIdstring

Merchant order ID

orderobject

Order Information

Hide child parameters
order.orderAmountobject

The amount of the order

Hide child parameters
order.orderAmount.valuestring

The value of order amount. All amount figures are based on the minimum denomination unit of given currency. Take CAD as an example, 100 means 1.00CAD.
If the currency is CNY, it must be higher than 0.01CAD after exchange rate conversion, otherwise, the order can be created, but an "amount error" will be thrown.

order.orderAmount.currencystring

Currency code, allowed values: CAD/USD CNY

order.descriptionstring

Title of the order (maximum length 128 characters) <= 128 characters

order.notifyUrlstring

Payment notification URL, the address to push the payment success notification after the payment is successful, see Notification for details

order.redirectUrlstring

Payment redirect URL, the address that will be redirected to after a successful payment.

paymentMethodobject

Payment method information

Hide child parameters
paymentMethod.paymentMethodTypestring

Payment method, allowed values: Alipay Wechat UnionPay

paymentInfoobject

Payment information

Hide child parameters
paymentInfo.paymentUrlstring

Payment URL for generating the QR code

paymentInfo.paymentQRImagestring

Base64-encoded image of the payment QR code

paymentInfo.payUrlstring

URL to AlphaPay payment page

paymentCreateTimestring <date-time>

Order creation time
Follow the ISO8601 standard, e.g. 2019-05-28T12:12:12+08:00

paymentExpireTimestring <date-time>

Payment expiration time
Follow the ISO8601 standard, e.g. 2019-05-28T12:12:12+08:00

paymentIdstring

AlphaPay order ID

resultobject

Process result

Hide child parameters
result.resultCodestring

Process result code, please refer to resultCode

result.resultMessagestring

Process result message

result.resultStatusstring

The status of an API call, please refer to resultStatus

  • S: API call succeeded.
  • F: API call failed, the resultMessage field will provide a detailed description of the error, which could be caused by either the merchant or the platform, when an error occurs during API invocation.
  • U: In cases where the handling result is unknown or in an intermediate state. Such as receiving a PAYMENT_IN_PROCESS status after submitting a payment order, the query interface can be used to confirm the status of the payment result.
QR code Response
{
  "scenarioCode": "ONLINE_QRCODE",
  "paymentRequestId": "string",
  "order": {
      "orderAmount": {
          "value": "string",
          "currency": "CAD"
      },
      "notifyUrl": "string",
      "redirectUrl": "string",
      "description": "string"
  },
  "paymentMethod": {
      "paymentMethodType": "string",
  },
  "paymentInfo": {
      "paymentUrl": "string",
      "paymentQRImage": "string",
      "payUrl": "string"
  },
  "paymentCreateTime": "2019-08-24T14:15:22Z",
  "paymentExpireTime": "2019-08-24T14:15:22Z",
  "paymentId": "string",
  "result": {
      "resultCode": "string",
      "resultMessage": "string",
      "resultStatus": "S"
  }
}