Payment processing

The following sections introduce how to handle a payment and how to conduct risk control during the payment.

Handle a payment

Complete the following steps to handle a payment.

1. Optional: Perform payment evaluation

In certain cases, merchants need to verify the available funds in the user account before initiating a payment. Alipay+ sends the payment evaluation request to Mobile Payment Provider and Mobile Payment Provider returns the result.

Process flow

See Payment > Process flow for details.

Payment evaluation is also performed by using the Payment interface. In this case, both paymentFactor.isAgreementPaymentand paymentFactor.isPaymentEvaluation must be specified as true. Specify paymentMethodId by using the value of access token.

Processing logic

The following rules apply:

Verify whether the access token is correct. If not, return a result.resultCode of INVALID_TOKEN
Verify whether the scope of the access token is correct. If not, return a result.resultCode of INVALID_TOKEN
Verify whether the access token is within the expiry date. If not, return a result.resultCode of INVALID_TOKEN/EXPIRED_ACCESS_TOKEN
Check whether the balance is enough. If not, return a result.resultCode of USER_BALANCE_NOT_ENOUGH
If the user does not exist, or if the status is abnormal, return a result.resultCode of USER_NOT_EXIST/USER_STATUS_ABNORMAL
Optional: If the payment is declined for risk reasons, return a result.resultCode of RISK_REJECT
Optional: If the payment failed because the payment method used by the Mobile Payment Provider is not available, return a result.resultCode of UNAVAILABLE_PAYMENT_METHOD

Sample

Request sample:

copy

{
  "order":{
    "referenceOrderId":"OrderID_010xxx0101",
    "orderDescription":"SHOES",
    "orderAmount":{
       "value":"100",
       "currency":"JPY"
    },
       "merchant":{
          "referenceMerchantId":"M00xxxxx0001",
          "merchantMCC":"1405",
          "merchantName":"UGG",
          "merchantAddress":{
             "region":"JP",
             "city":"xxx"
          },
          "store":{
             "referenceStoreId":"S00xxxx0001",
             "storeName":"UGG-2",
             "storeMCC":"1405"
          }
       }
 }, 
 "acquirerId": "102xxxxxxxxxxxx0001",
 "pspId":"102xxxxxxxxxxxx0001",
 "paymentRequestId":"201xxxxxxxxxxxxxxxxxxxxxxxx7771",
 "paymentAmount":{
    "value":"100",
    "currency":"JPY"
 },
  "paymentMethod":{
       "paymentMethodType": "CONNECT_WALLET",
       "paymentMethodId": "281xxxxxxxxxxxxxxxxxxxxxxxxxJWDQ"
  },
  "payToAmount":{
    "value":"1000",
    "currency":"KRW"
 },
 "paymentQuote":{
    "quoteId":"1234567",
    "quoteCurrencyPair":"JPY/KRW",
    "quotePrice":"10.0000"
  },
 "paymentFactor": {
    "isAgreementPayment":"true",
    "isPaymentEvaluation":"true"
 } 
}

Response sample:

copy

{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"Success"
 }
}

More information

See pay for details.

2. Process the payment request from Alipay+

With the access token obtained, Alipay+ sends the payment request to Mobile Payment Provider by using the payment interface.

Process flow

The interface request contains the following fields:

No.	Field	Remards
1	acquirerId	/
2	pspId	/
3	order	/
4	paymentRequestId	This field is used for the idempotence control. For the payment requests which are initiated with the same paymentRequestId and reach a final status (`S` or `F`), MPP must return the unique result.
5	paymentAmount	The amount that Mobile Payment Provider requests to receive in the currency that A+ uses to create the payment order. If promotion exists, this is the amount that excluds the promotion amount.
6	payToAmount	The amount that Mobile Payment Provider settles to Alipay+ in Mobile Payment Provider's currency. When Mobile Payment Provider's currency is different from the merchant's currency, the following equation applies: payToAmount.value=paymentAmount.value*paymentQuote.quotePrice.
7	paymentMethod	When isAgreementPayment is `true`, paymentMethodType (value is `CONNECT_WALLET`) and paymentMethodId (value is same as that of accessToken) must be provided.
8	paymentFactor	needSurcharge must be `TRUE` if surcharge function is used. isAgreementPayment must be `TRUE`. For the payment that requires cross-border settlement, isCrossborderSettlement must be `TRUE`.
9	paymentQuote Optional	Required when paymentAmount is not equal to payToAmount. The value of payToAmount is computed based on values of paymentAmount and paymentQuote, by using a rounding mode of `HALF_EVEN`.
10	paymentExpiryTime	Required when payment is required to be successful before the expiration time.
11	paymentNotifyUrl Optional	/
13	paymentPromoInfo Optional	Required when the promotion is applied in the payment.
14	surchargeInfo Optional	Required when paymentFactor.needSurcharge is `true`.
16	otpVerification Optional	Required when the promotion is applied in the payment.
17	passThroughInf Optional	/

The interface response contains the following field:

No.	Field	Remarks
1	result	If result.resultCode is `UNKNOWN_EXCEPTION`, all optional response fields are not required.
4	paymentId Optional	Must be returned when the payment is successful.
6	paymentTime Optional	Must be returned when the payment is successful.
7	paymentAmount Optional	/
8	payToAmount Optional	/
9	customerId Optional	Must be returned when the payment is successful.
10	authExpiryTime Optional	Must be returned by MPP when the authorization payment is successful.

Processing logic

General

When processing payment requests, Mobile Payment Provider must pay attention to the following items:

Use the timeout value assigned by Alipay+. For Auto Debit, the timeout value is 1 minute by default. When timeout occurs, Mobile Payment Provider closes the payment order and returns an error code ORDER_IS_CLOSED.

Payment amount limitation exists

If payment amount limitation exists, it is recommended that Mobile Payment Provider pay attention to the following items:

Check whether the amount exceeds the payment amount limit of a single transaction. If yes, return an error code PAYMENT_AMOUNT_EXCEED_LIMIT
Check whether the accumulated amount exceeds the limit. If yes, return an error code USER_AMOUNT_EXCEED_LIMIT
Check whether the payment times exceed the limit. If yes, return an error code PAYMENT_COUNT_EXCEED_LIMIT

Promotion exists

If promotion exists, the amount user actually pays is specified in the payToAmount filed.

Surcharge exists

If surcharge exists, the amount user actually pays is specified in the surchargeAmount filed.

Payment with accessToken

When processing payment requests, Mobile Payment Provider must pay attention to the following items:

Mobile Payment Provider must be able to:

Handle the request in an idempotent mode.
Support the currency code defined in ISO-4217.
Return the payment result synchronously

If the payment failed, Mobile Payment Provider must return a result.resultStatus of F and an error code that is corresponding to a specific reason.

Verify whether the access token is correct. If not, return a result.resultCode of INVALID_TOKEN
Verify whether the scope of the access token is correct. If not, return a result.resultCode of INVALID_TOKEN
Verify whether the access token is within the expiry date. If not, return a result.resultCode of INVALID_TOKEN/EXPIRED_ACCESS_TOKEN
If the balance is not enough, return a result.resultCode of USER_BALANCE_NOT_ENOUGH
If the user does not exist, or if the status is abnormal, return a result.resultCode of USER_NOT_EXIST/USER_STATUS_ABNORMAL
Optional: If the payment is declined for risk reasons, return a result.resultCode of RISK_REJECT
Optional: If the payment failed because the payment method used by the Mobile Payment Provider is not available, return a result.resultCode of UNAVAILABLE_PAYMENT_METHOD
Optional: If all payment methods are unavaiable, return a result.resultCode of NO_PAY_OPTION
Optional: If the payment is declined because the user KYC is failed, return a result.resultCode of USER_KYC_NOT_QUALIFIED
Optional: If the payment is declined because the merchant verification is failed, return a result.resultCode of MERCHANT_NOT_REGISTERED

Payment with accessToken & OTP

Note: Pay with accessToken & Verification can also be divided into two steps: handle the payment request, and

When processing payment requests, Mobile Payment Provider must pay attention to the following items:

Mobile Payment Provider must be able to check the idempotency of the OTP before verifying whether OTP is correct.
Support the currency code defined in ISO-4217.
If the payment failed, Mobile Payment Provider must return a result.resultStatus of F and an error code that is corresponding to a specific reason.

Verify whether the access token is correct. If not, return a result.resultCode of INVALID_TOKEN
Verify whether the scope of the access token is correct. If not, return a result.resultCode of INVALID_TOKEN
Verify whether the access token is within the expiry date. If not, return a result.resultCode of INVALID_TOKEN/EXPIRED_ACCESS_TOKEN
If the balance is not enough, return a result.resultCode of USER_BALANCE_NOT_ENOUGH
If the user does not exist, or if the status is abnormal, return a result.resultCode of USER_NOT_EXIST/USER_STATUS_ABNORMAL
Optional: If the payment is declined for risk reasons, return a result.resultCode of RISK_REJECT
Optional: If the payment failed because the payment method used by the Mobile Payment Provider is not available, return a result.resultCode of UNAVAILABLE_PAYMENT_METHOD
Optional: If all payment methods are unavaiable, return a result.resultCode of NO_PAY_OPTION
Optional: If the payment is declined because the user verification is failed, return a result.resultCode of USER_PAYMENT_VERIFICATION_FAILED
Optional: If the payment is declined because the user KYC is failed, return a result.resultCode of USER_KYC_NOT_QUALIFIED
Optional: If the payment is declined because the merchant verification is failed, return a result.resultCode of MERCHANT_NOT_REGISTERED

Sample

Request sample:

copy

{
  "order": {
    "referenceOrderId": "OrderID_010101****",
    "orderDescription": "SHOES",
    "orderAmount": {
      "value": "100",
      "currency": "JPY"
    },
    "merchant": {
      "referenceMerchantId": "M00xxxxx0001",
      "merchantMCC": "1405",
      "merchantName": "UGG",
      "merchantAddress": {
        "region": "JP",
        "city": "xxx"
      }
    }
  },
  "acquirerId": "102218800000000****",
  "pspId": "102217200000000****",
  "paymentRequestId": "201811291907410100070000007****",
  "paymentAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "paymentMethod": {
    "paymentMethodType": "CONNECT_WALLET",
    "paymentMethodId": "281006050000000000125733DAHJ****"
  },
  "payToAmount": {
    "value": "1000",
    "currency": "KRW"
  },
  "paymentQuote": {
    "quoteId": "1234567",
    "quoteCurrencyPair": "JPY/KRW",
    "quotePrice": "10.0000"
  },
  "paymentFactor": {
    "isAgreementPayment": "true"
  }
}

Response sample:

copy

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "paymentId": "20181129190741010007000000****",
  "paymentTime": "2020-01-01T12:01:01+08:30"
}

More information

See pay for details.

Optional: Conduct risk control

When merchant detects that certain risks exist in the payment, merchant can initiate risk challenge to verify user identity or query the user's risk status for risk control. Mobile Payment Providers must be able to handle related requests such as sending one time password (OTP) and returning risk score.

Verify user identity by initiating risk challenge (send OTP and verify OTP)

The following figure illustrates the risk challenge workflow:

Figure 2. Risk challenge workflow

The risk challenge workflow contains the following steps:

Merchant detects risks and initiates the risk challenge to verify the user identity (step 1 and step 2).
Acquirer forwards the request to Alipay+ and Alipay+ sends sendOTP request to Mobile Payment Provider (step 2.1 and step 2.1.1).
Mobile Payment Provider server sends OTP to user and returns verifyRequestId to Alipay+ (step 2.1.1.1 and step 2.1.1.2).
After receiving verifyRequestId, merchant sends request to Acquirer to verify the OTP (step 3). Acquirer forwards the request to Alipay+ and Alipay+ calls the verifyOTP interface to send verification request to Mobile Payment Provider (step 3.1 and step 3.1.1).
Mobile Payment Provider verifies the received otpCode and verifyRequestId and then returns the verification result (step 3.1.1.1 and step 3.1.1.2).

In the risk control process, Mobile Payment Provider performs the following steps:

1. Send OTP to user and return verifyRequestId to Alipay+

After receiving the request of verifying the user identity, Alipay+ calls the sendOTP interface to send the request to Mobile Payment Provider. Mobile Payment Provider server sends the OTP to user and returns verifyRequestId to Alipay+.

Note: verifyRequestId must be returned when the value of result.resultStatus is S.

One access token can be used to apply for at least 3 OTPs in one day. In addition, it is recommended that the MPP:

Verify the access token. If not correct, return an error INVALID_TOKEN.
Verify the valid time span of the access token. If not correct, return an error EXPIRED_ACCESS_TOKEN/INVALID_TOKEN.
Verify the user status. If not correct, return an error USER_NOT_EXIST/USER_STATUS_ABNORMAL.
Verify how many times the access token is used. If the limit is exceeded, return an error OTP_SEND_TIMES_EXCEED_LIMIT.

Request sample

copy

{
  "acquirerId": "102218800000000****",
  "pspId":"102217200000000****",
  "accessToken": "281010033AB2F588D14B43238637264FCA5A****"
}

Response sample

copy

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "verifyRequestId": "0b9fc14b1571815309135213911****"
}

More information

See sendOTP for details.

2. Verify OTP and return the verification result to Alipay+

After receiving verifyRequestId, merchant initiates the verifying OTP request. Alipay+ calls the verifyOTP interface to send the request to Mobile Payment Provider and Mobile Payment Provider returns the verification result.

It is recommended that the MPP:

Verify the OTP. If not correct, return an error OTP_VERIFY_UNMATCHED.
Verify how many times the OTP is used for verification. If the limit is exceeded, return an error OTP_VERIFY_TIMES_EXCEED_LIMIT.

Request sample

copy

{
  "acquirerId": "102218800000000****",
  "pspId":"102217200000000****",
  "accessToken": "281010033AB2F588D14B43238637264FCA5A****",
  "verifyRequestId": "0b9fc14b1571815309135213911****",
  "otpCode": "66****"
}

Response sample

copy

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  }
}

More information

See verifyOTP for details.