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

Post-payment services

After making a payment, further actions might be required, such as canceling, and refund. This page illustrates when to use the cancel and refund processes.

Refund a payment

A merchant can refund a payment by using refund (/v1/payments/refund) API and the paymentId that is returned from the payAPI.

Request URL: https://open-na.alipay.com/ams/sandbox/api/v1/payments/refund.

Set the value of paymentId to the value of paymentId that was from the response of the payment request, which is 071329156697640993635741494609211863FOkUAZHdoQ201908280000008675.

Request body

copy
{
  "refundRequestId": "20190826081529156680732967870397L",
  "paymentId": "071329156697640993635741494609211863FOkUAZHdoQ201908280000
  "refundAmount": {"value":"800","currency":"PHP"},
  "refundReason": "Test",
}

Response

copy
{
  "result": {
      "resultStatus": "S",
      "resultCode": "SUCCESS",
      "resultMessage": "success."
  },
  "amount": {
      "currency": "PHP",
      "value": "800"
  },
  "paymentId": "071329156697640993635741494609211863FOkUAZHdoQ201908280
  "refundTime": "2019-08-27T14:12:27+0800",
  "refundRequestId": "20190826081529156680732967870397L",
  "refundId": "061227156688634729535651431967411641rCrEUohYWN2019082600
  "resultInfo": {
      "resultStatus": "S",
      "resultCode": "SUCCESS",
      "resultMessage": "success."
  }
}

Inquire the refund status

A merchant can obtain a refund result in two ways: wait for the refund interface's response or actively call the inquiryRefund interface.

For the following situations, call the inquiryRefund interface to get a refund result:

  • No clear refund result is obtained for a timeout.
  • A user requests a refund result from the merchant.

If the domain name is open-na.alipay.com, the request URLs for the inquiryRefund interface are as follows:

As a merchant, you can use refundId or refundRequestId to initiate the inquiryRefund request.

If the refund times out and refundId cannot be obtained, you can only use the refundRequestId field to send the inquiryRefund request.

If refundId is obtained, it is recommended to use the refundId field.

Note that if both refundId and refundRequestId are specified, refundId takes precedence.

The following example shows an inquiryRefund request with the refundId field specified.

copy
{     "refundId": "2021080419401080130018866020092XXXX" }

The following example shows a response to an inquiryRefund request. The refund result is presented in the refundStatus field.

copy
{
    "refundAmount": {
        "currency": "HKD",
        "value": "10000"
    },
    "refundId": "2021080419401080130018866020092XXXX",
    "refundRequestId": "amsdemorefund_zhangsan_zs_20210804_165236_XXX",
    "refundStatus": "SUCCESS",
    "refundTime": "2021-08-04T01:52:37-07:00",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}
  • refundId: The unique refund processing ID. To implement the same refund polling, this field must be unique. To implement different refunds polling, this field must be different.
  • refundRequestId: The unique ID assigned by a merchant to identify a refund request.
  • refundStatus: This field indicates the refund result of the order. This field is returned when the value of result.resultStatus is S or the refund record can be found. The value of this field can be:
    • SUCCESS: This value indicates the refund succeeds.
    • PROCESSING: This value indicates that the refund is still processing. When this value is returned, the merchant can retry the refund interface.
  • result: This field only indicates the calling status of this inquiry request. It does not indicate the refund status.

Details about the result status that might be returned for a refund inquiry request are as follows:

    • S: indicates that the inquiryRefund API successfully and the merchant can get the payment status from the value of refundStatus.
    • F: indicates that the inquiryRefund API was failed to be called, which might be caused by system error or invalid parameters.
    • U: indicates that the calling status of the inquiryRefund API is unknown. Use the same request parameters to retry the inquiry request.

Cancel a transaction

You can cancel a transaction if the transaction encounters technical issues during making the payment. The cancel (/v1/payments/cancel) API can be used to roll back all the actions performed in the Alipay system regarding the specific transaction. The cancellable period is specified in the contract. The cancellation cannot be performed if it is not within the agreed cancellable period. Use the same paymentId that is used in the payment API to cancel the payment transaction.

Request URL:

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

Sample request:

copy
//You can use paymentId to request a cancel
{
   "paymentId":"20190608114010800100188820200355883"
}

//You can also use paymentRequestId to request a cancel
{
   "paymentRequestId": "pay_1089760038715669_102775745075669"   
}

Sample response:

copy
{
    "result": 
    {
        "resultCode":"SUCCESS",
        "resultStatus":"S",
        "resultMessage":"success"
    },
    "paymentRequestId":"pay_1089760038715669_102775745075669",
    "paymentId":"20190608114010800100188820200355883",
    "cancelTime":"2019-06-12T19:07:11+08:00"
}
copy
{
    "result": 
    {
        "resultCode":"SUCCESS",
        "resultStatus":"S",
        "resultMessage":"success"
    },
    "paymentRequestId":"pay_1089760038715669_102775745075669",
    "paymentId":"20190608114010800100188820200355883",
    "cancelTime":"2019-06-12T19:07:11+08:00"
}

For a payment transaction, the merchant must get a confirmative result status of the payment, which is S or F. Otherwise, the cancel API needs to be called. For example, during the payment process of a transaction:

  • If the merchant receives a U result status, the merchant needs to repeat the inquiryPayment API request until gets the confirmative payment status, either SUCCESS, FAIL or CANCELED. If the merchant cannot get any of those payment status before timeout, the transaction must be canceled.
  • If a network issue occurs, and the merchant cannot get any response from Alipay, the merchant must call the cancel API to ensure that the transaction is canceled and the payment result is consistent.

Merchant must get a result status of S or F for the cancel API response:

  • S: indicates that the cancellation was successful.
  • F: a system alert is to be triggered after getting a resultStatus of F. Investigate the root cause. If the root cause is fixed and the order still exists in the Alipay system, the merchant can retry the cancel API until a result of S is obtained.
  • U: the merchant needs to call the cancel API with the same parameters multiple times after getting a resultStatus of U, until a result of S or F is obtained. If S or F is not returned after the maximum number of retries, the system alarm will be triggered and the merchant must investigate and solve the problem.

Cashier Payment Post payments 1.png

Notes:

  • The merchant might implement the store and forward logic in the gateway. If the cancel request reaches to gateway before the payment API request, the cancel request should not be relayed to the next hop. 
  • When the cancellation is not allowed, the merchant needs to try the refund service.
  • Cancelation is allowed before the cancelation window expires, which is 15 minutes after the transaction time.

More information

Integration preparation

Sandbox integration