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 Partner and Mobile Payment Partner 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 Partner is not available, return a result.resultCode of
UNAVAILABLE_PAYMENT_METHOD
Sample
Request sample:
{
"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:
{
"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 Partner 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 ( |
5 | paymentAmount | The amount that Mobile Payment Partner 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 Partner settles to Alipay+ in Mobile Payment Partner's currency. When Mobile Payment Partner's currency is different from the merchant's currency, the following equation applies: payToAmount.value=paymentAmount.value*paymentQuote.quotePrice. |
7 | paymentMethod | When isAgreementPayment is |
8 | paymentFactor | needSurcharge must be isAgreementPayment must be For the payment that requires cross-border settlement, isCrossborderSettlement must be |
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 |
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 |
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 |
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 Partner must pay attention to the following items:
- Use the timeout value assigned by Alipay+, if Alipay+ does not provide the timeout value, for Auto Debit, set the timeout value as 1 minute at most. When timeout occurs, Mobile Payment Partner closes the payment order and returns an error code
ORDER_IS_CLOSED
.
Payment amount limitation exists
If payment amount limitation exists, Mobile Payment Partner must 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 Partner must pay attention to the following items:
- Mobile Payment Partner 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 Partner 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 Partner 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 Partner must pay attention to the following items:
- Mobile Payment Partner 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 Partner 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 Partner 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 payment 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:
{
"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:
{
"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 Partners 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 Partner (step 2.1 and step 2.1.1).
- Mobile Payment Partner 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 Partner (step 3.1 and step 3.1.1).
- Mobile Payment Partner 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 Partner 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 Partner. Mobile Payment Partner 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 20 OTPs in one day. In addition, the following rules apply:
- Mobile Payment Partner must verify the access token. If not correct, return an error
INVALID_TOKEN
. - Verify the scope of 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
{
"acquirerId": "102218800000000****",
"pspId":"102217200000000****",
"accessToken": "281010033AB2F588D14B43238637264FCA5A****"
}
Response sample
{
"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 Partner and Mobile Payment Partner returns the verification result.
The OTP must be valid for at least 60 seconds, and becomes invalid once used. In addition, the following rules apply:
- Verify the access token. If not correct, return an error
INVALID_TOKEN
. - Verify the scope of 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 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
{
"acquirerId": "102218800000000****",
"pspId":"102217200000000****",
"accessToken": "281010033AB2F588D14B43238637264FCA5A****",
"verifyRequestId": "0b9fc14b1571815309135213911****",
"otpCode": "66****"
}
Response sample
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "Success"
}
}
More information
See verifyOTP for details.
Query the risk status of a user
After a user selects a digital wallet, Merchant can query the risk status of the user before the user binds wallet or uses promotion tools. The user risk status is measured by the risk score. The total risk score is 100, and the higher the score the greater the risk. For the calculation logic of the risk score, contact Alipay+ Technical Support team.
Process flow
The following figure illustrates the risk score inquiry workflow:
Figure 3. Risk score inquiry workflow
The user risk score inquiry workflow contains the following steps:
- Merchant initiates the request of querying the user risk score.
- Alipay+ calls the inquiryRiskScore interface to send the request to Mobile Payment Partner.
- Mobile Payment Partner calculates the risk score and returns the result to Alipay+.
Sample
Request sample
{
"acquirerId": "102218800000000****",
"pspId":"102208800000000****",
"customerIdType": "EMAIL",
"customerId": "example@gmail.com",
"customerBelongsTo":"ALIPAY_CN",
"referenceMerchantId":"218810000088****",
"riskScoreTypes": ["NSF_SCORE"]
}
Response sample
{
"result": {
"resultCode":"SUCCESS",
"resultStatus":"S",
"resultMessage":"Success"
},
"riskScoreResults":[
{
"riskScoreType": "NSF_SCORE",
"riskScore": "67.121",
"riskScoreDetails":[
{
"riskInfoCode":"MALICIOUS_REGISTRATION",
"riskInfoCodeResult":"0"
},
{
"riskInfoCode":"BATCH_REGISTRATION",
"riskInfoCodeResult":"0"
},
{
"riskInfoCode":"ACCOUNT_TENURE",
"riskInfoCodeResult":"4"
},
{
"riskInfoCode":"TOTAL_PURCHASE",
"riskInfoCodeResult":"0"
}
]
}
]
}
More information
See inquiryRiskScore for details.