Refund for the excess amount and unlinked refund

The NFC refund supports the following types of refunds: normal, excess, and unlinked refunds. This guide explains how to handle excess and unlinked refunds:

Workflow

The NFC refund process consists of the following steps:

The Acquiring Service Provider (ACQP) server sends a refund request to the Ant server. (Steps 1-2)
The Ant server initiates a refund request to the Mobile Payment Provider (MPP) server based on the refund type: (Steps 3-10)

Normal refund: The Ant server calls the refund API to initiate a refund request for the total refund amount. (Steps 3-4)
Excess refund: The Ant server first calls the refund API to initiate a refund request for the payment amount and then calls the adjustRefund API to initiate a refund request for the additional amount exceeding the payment. (Steps 5-8)
Unlinked refund: The Ant server calls the adjustRefund API to initiate a refund request for the total refund amount. (Steps 9-10)

Step 1: Initiate refund request

The ACQP server sends a refund request to the Ant server.

Step 2: Process the refund through Alipay+

For different kinds of refunds, the Ant server processes the refund using different strategies:

For a normal refund, the Ant server calls the refund API for the total refund amount.
For an excess refund, the Ant server first calls the refund API for the original payment and then uses the adjustRefund API for any additional amount.
For an unlinked refund, the Ant server uses the adjustRefund API for the total refund amount.

Processing logic

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

Handle the request parameters properly:

refundRequestId: indicates 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 in 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.

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

Handle the request parameters properly:

originalCreditRequestId: The unique ID that is assigned by Alipay+ to identify a refund. This field is an API idempotency field. For requests that are initiated with the same originalCreditRequestId, the MPP must return the same result.
subScenarioType: The detailed business scenario that is specified on the scenarioType parameter. Alipay+ will configure this parameter according to the scenario. Valid values are:

UNLINKED_REFUND: indicates that the refund is not associated with any prior payment.
EXCEED_REFUND: indicates that the refund amount is greater than the amount of the payment.

Return the response properly:

result: The result of the refund, including the result status, result code, and the result message. The MPP must return the result based on the refund processing result as follows:

If the refund succeeds: Set result.resultStatus to S and result.resultCode to SUCCESS.
If the refund fails: Set result.resultStatus to F and assign the appropriate value to result.resultCode. See the Result code section.
If the refund result is unknown: Set result.resultStatus to U and assign the appropriate value to result.resultCode. See the Result code section.

Sample

refund

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"
}

adjustRefund

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

Unlinked refund request from Alipay+ to the MPP

copy
{
  "acquirerId": "A10221XX000000000000",
  "pspId": "10221XXXX0000000000",
  "originalCreditRequestId": "20190608114010800100188820200350000",
  "initialOriginalCreditId": "gb_tax_1089760038715669_102775745070000",
  "payeeAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "payerAmount": {
    "value": "1000",
    "currency": "KRW"
  },
  "quote": {
    "quoteId": "123000",
    "quoteCurrencyPair": "JPY/KRW",
    "quotePrice":"10.0000"
  },
  "payer": {
    "referenceMerchantId": "2188245U41144145",
    "merchantAddress": {
      "region": "JP"
    },
    "merchantName": "Merchant Name",
    "merchantMCC": "5411"
  },
  "payee": {
    "userId": "2088245U41144145"
  },
  "scenarioType": "REFUND",
  "subScenarioType": "UNLINKED_REFUND",
  "isDomestic":"false"
}

Excess refund request from Alipay+ to the MPP

copy
{
  "acquirerId": "A10221XX000000000000",
  "pspId": "10221XXXX0000000000",
  "originalCreditRequestId": "20190608114010800100188820200350000",
  "initialOriginalCreditId": "gb_tax_1089760038715669_102775745070000",
  "associateDebitRequestId":"20190608114010800100188820200350001",
  "payeeAmount": {
    "value": "100",
    "currency": "JPY"
  },
  "payerAmount": {
    "value": "1000",
    "currency": "KRW"
  },
  "quote": {
    "quoteId": "123000",
    "quoteCurrencyPair": "JPY/KRW"
    "quotePrice":"10.0000"
  },
  "payer": {
    "referenceMerchantId": "2188245U41144145",
    "merchantAddress": {
      "region": "JP"
    },
    "merchantName": "Merchant Name",
    "merchantMCC": "5411"
  },
  "payee": {
    "userId": "2088245U41144145"
  },
  "scenarioType": "REFUND",
  "subScenarioType": "EXCEED_REFUND",
  "isDomestic":"false"
}

Response from the MPP to Alipay+

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "originalCreditId": "201000000000000000000000004444"
}