Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

Refund a payment

You can issue a refund by using the refund API or through the Alipay Global Merchant Portal. The refund service is only applicable to a transaction that has been successfully paid. The refund of a transaction can be full or partial, that is, the refund amount can be the same as or less than the original transaction amount that has been paid. If a refund request encounters a failure, retry calling the refund API.

After Alipay processes a refund request, the refund is settled by transferring funds to the payer's funding instrument. It depends on a bank's policy to determine when a refund settlement can be completed. If a payer makes a payment with a credit card and rejects to pay for the credit card's balance, the rejected amount cannot be refunded.

Refundable period

The refund service is only applicable to a transaction that has been successfully paid. You can invoke a refund any time after the transaction was paid and before the refund period expires. The refundable period is determined by the contract, which is usually 12 months after the initial payment was made.

Note: After Alipay completes a refund, the transaction cannot be canceled.

How to refund

You can issue a refund by using the refund API or through the Alipay Global Merchant Portal. Each refund must meet the minimum refund amount specified in the contract.

Use the refund API

To refund a transaction, call the refund API by specifying the paymentId or paymentRequestId field with the same value as that of the transaction to refund against. Assume that the domain name is open-na.alipay.com, the request URLs are:

  • Sandbox environment: https://open-na-global.alipay.com/ams/sandbox/api/v1/payments/refund
  • Production environment: https://open-na-global.alipay.com/ams/api/v1/payments/refund

You can use the refund API to initiate a refund and the inquiryRefund API to check the refund status in the following procedure. After making a partial or full refund, the transaction status remains SUCCESS.

Use the refund API.jpg

Figure 1. Further actions for different refund results

The example below shows a refund request:

copy
{
  "refundRequestId": "RRID202013143454551",
  "paymentId": "202001021940108001001885D0203562766",
  "refundAmount": {
    "currency": "JPY",
    "value": 9999
  },
  "refundReason": "For test",
  "isAsyncRefund": false
}

About the refundAmount field:

  • The value of refundAmount.currency needs to be consistent with that of paymentAmount in the payment request.
  • The value of refundAmount.value needs to be smaller than the payment amount. For multiple refunds, ensure that the total refund amount is less than or equal to the original payment amount. The minimum amount allowed for the refundAmount field varies for each wallet. For details, see Minimum amount rules.

The example below shows a refund response. The refund status is indicated by result.resultStatus and the time when the refund succeeds is indicated by refundTime. You can use the value of the refundAmount field for comparing amounts.

copy
{
  "paymentId": "202001021940108001001885D0203562766",
  "refundAmount": {
    "currency": "JPY",
    "value": "9999"
  },
  "refundId": "202001021940108013001885D0200258776",
  "refundRequestId": "RRID202013143454551",
  "refundTime": "2020-01-02T19:34:55-08:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

The refund status is indicated by the result.resultStatus field with the following values:

  • S: This value indicates that the refund succeeded.
  • U: This value indicates the refund result is unknown. Use the same request parameters to call the refund API multiple times until a result of S or F is obtained. Alipay supports idempotence when using the same parameters to call the refund API. If S or F is not obtained after the maximum number of retries, the system alarm needs to be triggered to involve the technical support team.
  • F: This value indicates that the refund failed. Take further actions according to resultCode. For example, if a result code of MERCHANT_BALANCE_NOT_ENOUGH is returned, it indicates that the balance of the merchant to be settled is less than the refund amount. Therefore, you need to wait until successful payments are generated and the balance to be settled is greater than the refund amount of the transaction, and then initiate the refund process again. When reinitiating the refund process, the value of request.refundRequestId must be updated.

Note: The store and forward logic might be implemented in the gateway. If the refund request reaches the gateway before the gateway gets the successful payment result, the refund request should not be relayed to the next hop.

Issue refunds on Alipay Merchant Portal

Follow these steps to issue refunds on Alipay Merchant Portal:

  1. Search for the transaction that you want to issue a refund against. Click Details.

image

Figure 2. Find the transaction to be issued a refund against

  1. Click Refund.

image

Figure 3. Issue a refund

  1. Enter the refund amount and choose the reason for refund. A payment password is required after you confirm to refund. The refund amount must be equal to or less than the transaction amount.

If it is the first time you are issuing a refund, click Change password to reset the payment password. If it is not your first time issuing a refund, use the password that you set the first time you issue a refund.

image

Figure 4. Set the payment password