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

You can query the status of a transaction order by using the Payment Result Inquiry interface (/v1/payments/inquiryPayment). Call the inquiry interface when one of the following cases is encountered:

• No clear result of the payment result can be obtained.
• The payment process times out and no payment result is obtained,
• A refund record related to the transaction needs to be checked.

With paymentId or paymentRequestId, you can query the result of a payment by using query API /v1/payments/inquiryPayment.

Request URL:

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

{
    "paymentId": "212302615674274268857659685498868097avhIBxVMMX201909020000024285"
}

Response: 

{
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."
    },
    "paymentResultCode": "SUCCESS",
    "paymentResultMessage": "success",
    "paymentStatus": "SUCCESS",
    "paymentId": "212302615674274268857659685498868097avhIBxVMMX201909020000024285",
    "paymentRequestId": "pay_1029760066716669_102775765079666",
    "paymentAmount": {
        "currency": "PHP",
        "value": "800"
    },
    "RediretActionForm": {
        "redirectUrl": "https://render.alipay.com/p/c/jzmcoal2/igg-checkout-counter.html",
        "method": "POST"
    },
    "transactions":[
      {
      "transactionResult":{
          "resultCode":"SUCCESS",
          "resultStatus":"S",
          "resultMessage":"success"
        },
        "transactionId":"1111111111111111111",
        "transactionType":"REFUND",
        "transactionStatus":"SUCCESS",
        "transactionRequestId":"pay_1089760038715669_102775745075671",
        "transactionAmount":{
          "value":"800",
          "currency":"PHP"
        },
        "transactionTime":"2019-06-01T12:01:01+08:00"
      }
    ]
}

Notes:

Here are details about the result status that might be returned for a payment result inquiry request:

• S: indicates that the inquiry was successful and the merchant can get the payment status from the value of paymentStatus.
• F: a system alert is to be triggered after getting a resultStatus of F. The merchant's technical support team must investigate the root cause. If the root cause is fixable and the order still exists in the Alipay system, the merchant needs to retry the inquiry API until a result of S is obtained.
• U: the merchant must call the inquiry API with the same parameters multiple times after getting a resultStatus of U, until a result of S or F is obtained. After the maximum number of retries, if still no S or F is returned, the merchant must call the cancel interface to cancel the transaction.

You can cancel a transaction if the transaction encounters technical issues during making the payment. The Payment Cancellation interface (/v1/payments/cancelPayment) 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. If being out of the agreed cancellable period, the cancellation cannot be performed. 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:

//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:

{
    "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, merchant needs to repeat the inquiry API request until gets the confirmative payment status, either SUCCESS, FAIL or CANCELED. If merchant cannot get any of those payment status before timeout, the transaction must be cancelled.
• 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 cancelled 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, 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. After the maximum number of retries, if still no S or F is returned, the system alarm is to be triggered and merchant must investigate and solve the problem.

Notes:

• 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.
• Canceling is allowed before the cancelling window expired which is the cut off time of the transaction date plus 15 minutes.  

You can issue a refund by using the Refund interface (/v1/payments/refund). 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 for a reasonable number of times. Maximum number of retires and interval for synchronous refund should be configured.

Request URL:

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

Sample request:

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

Sample response:

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

After Alipay completes a refund, the transaction cannot be cancelled. Comparing with the cancel interface (/v1/payments/cancel), refund service does not impose the 24-hours constraint, i.e. the merchant server can invoke this service at any time that between the moment when the transaction was paid and the time before the refund period expires.

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

For a transaction that has been successfully paid, the customer can request the merchant for refund as long as the refund period is still valid, and the refund interface is used to complete the refund through the following business flow.

The merchant MUST get a confirmative result status, either S or F for a refund request:  

• If merchant gets an S result status, the refund request was received successfully.
• If merchant gets an F result status, the system alert should be triggered, the merchant's tech support team MUST investigate the root cause. If the root cause is fixable, order exists and refundable in Alipay system, merchant should retry the refund API request one more time.
• If merchant gets a U result status, merchant needs to call the refund API multiple times until get the S or F result status. After the maximum number of retries, if merchant still cannot get the S or F result, merchant should initialize an async refund request.
• After retried the maximum number of async refund request, system alarm should be triggered and involve the merchant's tech support team.

Notes:

• If a merchant's refund request call times out or gets a response with an unknown status, take one the following actions:

1. Use the refund request ID or payment request ID to check the final result of a refund. If the result shows that the refund is not in a success status, the merchant can retry the refund with the same request ID
2. Use the original refund request ID and retry the refund request. Alipay supports idempotence if a merchant uses the same refund request.

• Merchant might implement the store and forward logic in the gateway. If the refund request reaches to gateway before gateway gets the success payment result, the refund request should not be relayed to the next hop.

Integration preparation

Sandbox integration