Post payments

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


    #Refund a payment

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


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

    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, merchant needs to repeat the inquiryPayment 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.


    Cashier Payment Post payments 1.png


    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.  


    #More information

    Integration preparation

    Sandbox integration