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

      Post-payment services

      After processing a payment, merchants can perform post-payment actions such as inquiry, cancel, and refund.


      #Optional: Query the result

      You can query the status of a transaction order by using the inquiryPayment interface (/v1/payments/inquiryPayment). Call the inquiryPayment interface when you encounter one of the following cases:

      • 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
      copy
      {
          "paymentId": "212302615674274268857659685498868097avhIBxVMMX201909020000024285"
      }


      Response: 

      copy
      {
          "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 will 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 inquiryPayment 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.


      #Cancel the transaction

      You can cancel a transaction if the transaction encounters technical issues during making the payment. The cancel interface (/v1/payments/cancelPaymentcan 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"
      }


      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. After the maximum number of retries, if still no S or F is returned, the system alarm will be triggered and the merchant must investigate and solve the problem.


      图片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.


      #Refund a payment

      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. The 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:

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


      Sample response:

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


      After Alipay completes a refund, the transaction cannot be canceled. Compared with the cancel interface (/v1/payments/cancel), the refund service does not impose a 24-hour constraint.


      That means the merchant server can invoke this service any time between the time when the transaction was paid to when the refund period expires.


      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 finish. 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.


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


      图片1.png


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

      • If the merchant gets an S result status, the refund request was received successfully.
      • If the 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, meaning the order exists and is refundable in Alipay system, the merchant should retry the refund API request again.
      • If the merchant gets a U result status, the merchant needs to call the refund API multiple times until the S or F result status is obtained. If S or F is not obtained after the maximum number of retries, the merchant needs to initialize an asynchronous refund request.
      • When the maximum number of asynchronous refund request is reached, the system alarm will be triggered to 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 of 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.
      • The merchant might implement the store and forward logic in the gateway. If the refund request reaches to the gateway before gateway gets the success payment result, the refund request should not be relayed to the next hop.


      #More information

      Integration preparation

      Sandbox integration