submitPay

2026-09-15 15:07

POST /v1/payments/submitPay

Call this API to initiate a payment request. The system processes the transaction based on the request parameters and returns the payment status, a payment link used to invoke the cashier page, or a unique payment request ID.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：

Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:

If the data type of a field is Integer and its value is 20, set it as "20".
If the data type of a field is Boolean and its value is true, set it as "true".

Request parameters

paymentSessionId String REQUIRED

Payment session ID.

More information:

Maximum length: 64 characters

paymentAmount Amount

Payment amount.

order Order

Order information.

Response parameters

result Result REQUIRED

The result of the API call.

paymentRequestId String REQUIRED

The unique ID that is assigned by a merchant to identify a payment request.

More information:

Maximum length: 64 characters

paymentId String REQUIRED

The unique ID that is assigned by APO to identify a payment.

More information:

Maximum length: 64 characters

paymentAmount Amount

The payment amount.

paymentCreateTime Datetime

The date and time when the payment is created.

More information:

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

applinkUrl URL

The URL that redirects users to open an app when the target app is installed, or to open a WAP page when the target app is not installed. For Android, the URL is a Native App Link. For iOS, the URL is a Universal Link.

More information:

Maximum length: 2048 characters

normalUrl URL

The URL that redirects users to a WAP or WEB page in the default browser or the embedded WebView.

More information:

Maximum length: 2048 characters

schemeUrl URL

The URL scheme that redirects users to open an app in an Android or iOS system when the target app is installed.

More information:

Maximum length: 2048 characters

acquirerInfo AcquirerInfo

The information of the acquirer that processes the payment.

API Explorer

Request

URL

Method

POST

{
  "paymentSessionId": "PAYMENT_SESSIONID_20260129144822724_AUTO",
  "paymentAmount": {
    "currency": "SGD",
    "value": "120"
  },
  "order": {
    "orderAmount": {
      "currency": "SGD",
      "value": "100"
    },
    "orderTaxAmount": {
      "currency": "SGD",
      "value": "10"
    },
    "orderDiscountAmount": {
      "currency": "SGD",
      "value": "20"
    },
    "shipping": {
      "shippingFee": {
        "currency": "SGD",
        "value": "30"
      }
    }
  }
}

Response

{
  "result": {
    "resultStatus": "U",
    "resultCode": "PAYMENT_IN_PROCESS",
    "resultMessage": "payment in process"
  },
  "paymentId": "2022091619401080010018861020428****",
  "paymentRequestId": "QvagvxbRBZdJ00U48KOByGChhMgC8f5BNF3Cl86OIXljytdNZD6flwC7nU5U****",
  "applinkUrl": "",
  "schemeUrl": "",
  "normalUrl": "https://demo-domain.alipay.com/page/apm-factor/code.html?merchantId=188oOYrCvQObmAa9gqme42YsFhHjpexPusV0TSebnZ9Nik%3D&paymentRequestId=w9iOyEkQ7yFSXyrc4UtVvlRUf%2Bt7UTVMY7BkUzeqQP2oGXIzuGhhv8cqbOKYIQgST8oKUsbd4x2Rr8ai6DgfZMYbjonojR6N2F9JRuBYrxg%3D&clientId=5J5Y63382Y3HH006786",
  "paymentAmount": {
    "currency": "BRL",
    "value": "96080"
  },
  "paymentCreateTime": "2022-09-15T20:20:20-07:00",
  "acquirerInfo": {
    "acquirerMerchantId": "21811100024730H6",
    "acquirerName": "ALIPAY",
    "acquirerResultCode": "SUCCESS",
    "acquirerResultMessage": "success",
    "acquirerTransactionId": "202508201140108001001814F0276126015",
    "referenceRequestId": "PAYMENT_20250820143310572_AUTO"
  }
}

Result/Error codes

*resultCode*	*resultStatus*	*resultMessage*	Further action
`SUCCESS`	`S`	Success	The payment is successful, no further action is needed.
`PAYMENT_IN_PROCESS`	`U`	The payment is being processed.	Get any of the URLs (appLinkUrl, normalUrl, schemeUrl) and open the cashier page. If no URL is returned, call the pay API again with a new paymentRequestId value. If the issue persists, contact APO Technical Support.
`PROCESS_FAIL`	`F`	A general business failure occurred.	Do not retry. Human intervention is usually needed. It is recommended that you contact APO Technical Support to troubleshoot the issue.
`UNKNOWN_EXCEPTION`	`U`	An API call has failed, which is caused by unknown reasons.	Call the interface again to resolve the issue. If not resolved, contact APO Technical Support.
`ORDER_STATUS_INVALID`	`F`	The transaction cannot be further processed because the order status is invalid.	Check the order status of the transaction or contact APO Technical Support for detailed reasons.
`INVALID_MERCHANT_STATUS`	`F`	The merchant status is abnormal because restrictions exist.	Contact APO Technical Support for detailed reasons.
`CARD_NOT_SUPPORTED`	`F`	The card used for the transaction is not supported.	Use another card to pay the transaction.
`RISK_REJECT`	`F`	The transaction cannot be further processed because of risk control. If the user has already paid for the transaction, the transaction will be refunded.	If the user does not receive the refund within two weeks, contact APO Technical Support.
`DO_NOT_HONOR`	`F`	The payment is declined by the issuing bank.	Retry the payment using a different card or contact the issuing bank.
`USER_AMOUNT_EXCEED_LIMIT`	`F`	The payment amount exceeds the user payment limit.	Create a new payment by using an amount less than or equal to the account's available balance, or contact APO Technical Support.
`FRAUD_REJECT`	`F`	The transaction cannot be further processed because of risk control. If the user has already paid for the transaction, the transaction will be refunded.	Contact APO Technical Support when one of the following conditions is met: You want to make an appeal. The user does not receive the refund within two weeks.
`USER_STATUS_ABNORMAL`	`F`	The user status is abnormal on the wallet side.	Contact APO Technical Support to know the specific reasons.
`PARAM_ILLEGAL`	`F`	The required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are wrong.	Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid.