Convert authorization to pay

Alipay+ converts the regular authorization, authorization reversal, clearing, and authorization expiration of Mastercard into payment and refund requests. The following content shows how Alipay+ processes the conversion.

Note: You only need to integrate the pay API and the refund API to handle the converted requests from the Ant server. This document is only for you to understand how the conversions work.

Authorization

The Ant server converts a Mastercard authorization request into a completed payment.

Workflow

The process of converting authorization request consists of the following steps:

Mastercard sends an authorization request to the Ant server. (Step 1)
The Ant server then converts the authorization request into a pay API request to the MPP server. (Step 2)
The MPP server processes the payment request and returns the payment result to the Ant server. (Step 3)
The Ant server records the MPP user's paid amount and returns the authorization result to Mastercard based on the payment result. (Steps 4-5)

Step 1: Initiate authorization request

Mastercard sends an authorization request to the Ant server.
The Ant server converts the authorization request into a pay API request to the MPP server.

Processing logic

When receiving the pay API request, take the following into consideration:

Handle the request parameters properly:

paymentRequestId: The unique ID that is assigned by Alipay+ to identify a payment order. This field is an API idempotency field. The MPP must regard the requests with the same paymentRequestId as repeated and process them only once. The MPP is recommended to check the consistency of the following key request parameters: paymentAmount, payToAmount, surchargeInfo, paymentMethod, and paymentPromoInfo. If any values differ from the previous request, the MPP needs to return the REPEAT_REQ_INCONSISTENT result code.

Return the response properly:

result: The result of the business processing, including the result code, result status, and result message. Specify optional parameters based on the business processing result as follows:

If the payment succeeds, set the value of result.resultStatus to S and specify the following optional parameters: paymentId, paymentTime, and customerId.
If the payment fails, set the value of result.resultStatus to F.
If the payment result is unknown, set the value of result.resultStatus to U and the value of result.resultCode to UNKNOWN_EXCEPTION.

Sample

Request from Alipay+ to the MPP

copy
{
  "order":{
    "referenceOrderId":"OrderID_0100000101",
    "orderDescription":"SHOES",
    "orderAmount":{
       "value":"100",
       "currency":"JPY"
    },
       "merchant":{
          "referenceMerchantId":"M00000000001",
          "merchantMCC":"5411",
          "merchantName":"UGG",
          "merchantDisplayName":"UGG",
          "merchantAddress":{
             "region":"JP",
             "city":"xxx"
          },
          "store":{
             "referenceStoreId":"S0000000001",
             "storeName":"UGG-2",
             "storeMCC":"5411",
             "storeTerminalId":"69014001"
          }
       },
    "env":{
      "deviceTokenId":"89D64DD5D06B0CBA901DEF4321290ADEF7900B2016E8429AC43BE97BDDD0765D"
    }
 }, 
 "acquirerId": "1020000000000000001",
 "pspId":"1020000000000000001",
 "paymentRequestId":"2010000000000000000000000007771",
 "paymentExpiryTime": "2020-01-01T12:01:01+08:30",
 "paymentAmount":{
    "value":"100",
    "currency":"JPY"
 },
 "paymentMethod":{
    "paymentMethodType": "CONNECT_WALLET",
    "customerId":"2160000000000001",
    "customData":"0000008c21c727f2be19"
  },
 "payToAmount":{
    "value":"1000",
    "currency":"KRW"
 },
 "paymentQuote":{
    "quoteId":"1234567",
    "quoteCurrencyPair":"JPY/KRW",
    "quotePrice":"10.0000"
  },
 "paymentFactor": {
     "authorizationType": "FINAL_AUTHORIZATION",
     "inStorePaymentScenario": "NfcPayment",
     "isSupplementalPayment": "false",
     "isInStorePayment": "true",
     "isTransitDebtRecovery": "false",
     "isDomestic":"false"
 },
 "paymentNetworkAdditionalInfo": {
     "orderSource": "TERMINAL",
     "paymentNetworkLifecycleId": "7dbbf678-a720-488a-9040-cbe728a846f4",
     "paymentNetworkOrderId": "9142e53b-f1f5-484a-a786-9a3a9472ce40",
     "paymentNetworkType": "MASTER_CARD"
 }
}

Response from the MPP to Alipay+

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "paymentId": "201000000000000000000000004444",
  "paymentTime": "2020-01-01T12:01:01+08:30",
  "customerId": "2160000000000001"
}

For more information, see the pay API.

Step 2: Process payment request

The MPP server processes the payment request and returns the payment result to the Ant server.
The Ant server records the MPP user's paid amount and returns the authorization result to Mastercard based on the payment result.

Authorization reversal

The Ant server converts Mastercard authorization reversal requests into a refund request or cancel request based on the reversal scenarios.

Workflow

The process of converting authorization reversal request consists of the following steps:

Mastercard initiates a partial reversal request of the authorization amount to the Ant server. (Steps 1-2)
The Ant server converts this reversal request into a refund API request of the partial amount for the MPP server to process and reduces the recorded MPP user's paid amount. (Steps 3-5)
Mastercard initiates a full reversal request of the authorization amount to the Ant server. (Steps 6-7)

If the full authorization reversal is initiated on the same day as the authorization. The Ant server calls the cancelPayment API to the MPP server. (Steps 8-9)
If the full authorization reversal is initiated on a different day than the authorization. The Ant server calls the refund API to the MPP server. (Steps 10-11)

The Ant server reduces the refund amount from the recorded MPP user's paid amount and cancels the authorization. The recorded MPP user's paid amount is 0. (Steps 12-13)

Section 1: Partial amount authorization reversal

Mastercard initiates a partial reversal request to the Ant server, which converts it into a refund API request for the partial amount to the MPP server.
The MPP server processes the refund and notifies the Ant server, resulting in an adjustment to the user's paid amount recorded.

Processing logic

When receiving the refund API request, take the following into consideration:

Handle the request parameters properly:

refundRequestId: The unique ID that is assigned by Alipay+ to identify a refund request. This field is an API idempotency field. The MPP must regard the requests with the same refundRequestId as repeated and process them only once. The MPP is recommended to check the consistency of the following key request parameters: refundAmount, refundFromAmount, refundPromoInfo, and surchargeInfo. If any values differ from the previous request, the MPP needs to return the REPEAT_REQ_INCONSISTENT result code.

Return the response properly:

result: The refund result. The MPP needs to return the result (specified on the result parameter) based on the business processing result as follows:

If the refund succeeds, set the value of result.resultStatus to S and the value of result.resultCode to SUCCESS.
If the refund fails, set the value of result.resultStatus to F and the value of result.resultCode accordingly. See the Result code section.
If the refund result is unknown, set the value of result.resultStatus to U and the value of result.resultCode accordingly. See the Result code section.

Sample

The following samples show the request and response when Alipay+ calls the refund API.

Request from Alipay+ to the MPP

copy
{
 "acquirerId": "1022188000000000000",
 "pspId":"1022172000000000000",
 "paymentRequestId":"201811291907410100070000000000",
 "paymentId": "201811291907410100070000000000",
 "refundRequestId":"201811291907410200070000000000",
 "refundAmount":{
    "value":"90",
    "currency":"JPY"
 },
 "refundFromAmount":{
    "value":"900",
    "currency":"KRW"
 },
 "refundQuote":{
    "quoteId":"1230000",
    "quoteCurrencyPair":"JPY/KRW",
    "quotePrice":"10.0000"
  }
}

Response from the MPP to Alipay+

copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"Success"
  },
 "refundId":"201811291907410200070000000000",
 "refundTime": "2020-10-10T12:01:01+08:30"
}

For more information about the refund API, see the refund API.

Section 2: Full amount authorization reversal

Mastercard initiates a full reversal request to the Ant server.
If the reversal is on the same day as the authorization, the Ant server calls the cancelPayment API to the MPP server. If the reversal is on a different day from the authorization, the Ant server calls the refund API to the MPP server.
The MPP server processes the requests and notifies the Ant server, resulting in reducing the user's paid amount recorded.
The authorization is canceled, and the pre-recorded MPP user's paid amount is 0.

Processing logic

When receiving the cancelPayment API request, take the following into consideration:

Handle the request parameters properly:

paymentRequestId: The unique ID that is assigned by Alipay+ to identify the original payment request. This field is an API idempotency field. For requests that are initiated with the same paymentRequestId, the MPP needs to return the same result.

Return the response properly:

result: The result of the payment cancellation.

If the payment cancellation succeeds, set the value of result.resultStatus to S and the value of result.resultCode to SUCCESS.
If the payment cancellation fails, set the value of result.resultStatus to F and the value of result.resultCode accordingly. See the Result code section.
If the payment cancellation result is unknown, set the value of result.resultStatus to U and the value of result.resultCode accordingly. See the Result code section.

For more information about the cancelPayment API, see the cancelPayment API.

Sample

The following samples show the request and response when Alipay+ calls the cancelPayment API.

Request from Alipay+ to the MPP

copy
{
  "acquirerId": "1022188000000000001",
  "pspId":"1022172000000000001",
  "paymentRequestId":"20200101234567890132"
}

Response from the MPP to Alipay+

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

Clearing

The Ant server converts a Mastercard clearing request into payment or refund based on the clearing scenarios.

Workflow

The process of converting clearing request consists of the following steps:

Mastercard initiates a non-final clearing request to the Ant server. (Step 1)
The Ant server adds the Mastercard clearing amount. (Step 2)
If the sum of Mastercard clearing amount is greater than the MPP user's paid amount, the Ant server sends a pay API request on the excess amount to the MPP server, and adds the excess amount to the recorded MPP user's paid amount. (Steps 3-6)
Mastercard initiates a final clearing request to the Ant server. (Steps 7-8)
The Ant server adds the Mastercard clearing amount. (Step 9)

If the sum of Mastercard clearing amount is greater than the MPP user's paid amount, the Ant server sends a pay API request on the excess amount to the MPP server to process and adds the excess amount to the recorded MPP user's paid amount. (Steps 10-12)
If the sum of Mastercard clearing amount is less than the MPP user's paid amount, the Ant server sends a refund API request on the insufficient amount to the MPP server and reduces the insufficient amount to the recorded MPP user's paid amount. (Steps 13-15)

The Ant server completes the authorization, and the final Mastercard clearing amount equals the MPP user's paid amount. (Step 16)

Step 1: Mastercard initiates non-final clearing requests to Alipay+

If the total Mastercard clearing amount is greater than the MPP user's paid amount, the Ant server calls the pay API for the excess amount to the MPP app.
The MPP app processes the payment request.
The Ant server adds up the MPP user's paid amount.

Step 2: Mastercard initiates final clearing requests to Alipay+

If the total Mastercard clearing amount is greater than the MPP user's paid amount.

The Ant server calls the pay API for the excess amount to the MPP app.
The MPP app processes the payment request.
The Ant server adds up the MPP user's paid amount.

If the total Mastercard clearing amount is less than the MPP user's paid amount.

The Ant server calls the refund API for the insufficient amount to the MPP app.
The MPP app processes the refund request.
The Ant server reduces the MPP user's paid amount.

Step 3: Complete the authorization

The Ant server completes the authorization, and the final Mastercard clearing amount should equal the MPP user's paid amount.

Mastercard authorization expiration

The Ant server converts a Mastercard expire request into a refund request.

Workflow

The process of converting Mastercard expiration request consists of the following steps:

Mastercard sends the authorization expiration request to the Ant server. (Step 1-2)
If the sum of Mastercard clearing amount is less than the MPP user's paid amount, the Ant server calls the refund API to send a refund request to the MPP server to process and reduces the recorded MPP user's paid amount. (Steps 3-5)
The Ant server completes the authorization, and the final Mastercard clearing amount equals the MPP user's paid amount. (Step 6)

Step 1: Mastercard initiates the expiration

Mastercard sends an authorization expiration request to the Ant server.

Step 2: The Ant server processes the request

If the sum of the recorded Mastercard clearing amount is less than the recorded MPP user's paid amount, the Ant server calls the refund API to the MPP server to refund the difference amount. Then the Ant server reduces the recorded MPP user's paid amount.
The Ant server completes the authorization, and the final Mastercard clearing amount equals the recorded MPP user's paid amount.

Step 3: Complete the authorization

The Ant server completes the authorization, and the final Mastercard clearing amount should equal the MPP user's paid amount.

Alipay+ automatic authorization expiration

Alipay+ also supports automatic authorization expiration. The Ant server detects authorization expry and initiates refund request if necessary. And when Mastercard initiates an overdue clearing request, the Ant server converts the clearing request into a pay request.

Workflow

The process of processing Alipay+ automatic expiration request consists of the following steps:

The Ant server detects the authorization expiration automatically in two days after the Mastercard expiration date. (Step 1)
If the sum of Mastercard clearing amount is less than the MPP user's paid amount, the Ant server calls the refund API to send a refund request to the MPP server to process and reduces the MPP user's paid amount. (Steps 2-4)
The Ant server completes the authorization, and the final Mastercard clearing amount equals the MPP user's paid amount. (Step 5)
Mastercard sends an overdue clearing request to the Ant server. (Steps 6-7)
The Ant server sends a pay API request on the excess amount to the MPP server. (Step 8-9)

Step 1: Alipay+ initiates the authorization expiration

The Ant server detects the authorization expiration two days after the Mastercard expiration date.

Step 2: Alipay+ processes the authorization expiration

If the sum of the recorded Mastercard clearing amount is less than the recorded MPP user's paid amount, the Ant server calls the refund API to the MPP server to refund the difference amount. Then the Ant server reduces the recorded MPP user's paid amount.
The Ant server completes the authorization, and the final Mastercard clearing amount equals the recorded MPP user's paid amount.

Step 3: Alipay+ processes further clearing request from Mastercard

Mastercard initiates a clearing when authorization expires. The Ant server sends a pay API request on the excess amount the MPP server.
The MPP server processes the supplementary payment request.