Post payments

After making a payment, further actions might be required, such as inquiry, cancellation, and refund.

Payment result notification

When a payment reaches a final state of success or failure, Mobile Payment Partner sends payment result notification to Alipay+.

Process flow

The following figure illustrates the service flow:

Figure 1. Payment result notification flow

The interface request contains the following fields:

No.	Field	Remarks
1	paymentResult	The paymentResult.resultStatus field reflects the payment status, with `S` representing success and `F` representing failure. The resultStatus field doesn't have a value `U`.
2	paymentRequestId	/
3	paymentId Optional	This field is required when paymentResult.resultStatus is `S`.
4	paymentAmount Optional	This field is required when paymentResult.resultStatus is `S`.
5	payToAmount Optional	This field is required when paymentResult.resultStatus is `S` and payToAmount is not equal to paymentAmount.
6	paymentTime Optional	This field is required when paymentResult.resultStatus is `S`.
7	customerId Optional	This field is required when paymentResult.resultStatus is `S`.
8	passThroughInfo Optional	/

The interface response contains the following field:

No.	Field
1	result

Processing logic

If Alipay+ provides the address to receive payment result notification, Mobile Payment Partner must send notifications to the specified address.

When processing payment request inquiry requests, Mobile Payment Partner must pay attention to the following items:

When a payment reaches a final state of success or failure, Mobile Payment Partner must send payment result notification to Alipay+.
Mobile Payment Partner must be able to detect whether Alipay+ failed to send the acknowledgement, and has the capability to retry the notification sending. The retry rule is suggested as below:

Retry 1~2 times within 5 seconds.
The subsequent intervals increase consecutively. For example, 30s, 1m, 2m, ...
A total of 15 retries is suggested.

If the payment failed, Mobile Payment Partner must send a paymentResult.resultStatus of F and an error code that is corresponding to a specific reason.

If the balance is not enough, return a paymentResult.resultCode of USER_BALANCE_NOT_ENOUGH
If the user does not exist, or if the status is abnormal, return a paymentResult.resultCode of USER_NOT_EXIST/USER_STATUS_ABNORMAL
Optional: If the payment is declined for risk reasons, return a paymentResult.resultCode of RISK_REJECT
Optional: If the payment failed because the payment method used by the Mobile Payment Partner is not available, return a paymentResult.resultCode of UNAVAILABLE_PAYMENT_METHOD
Optional: If all payment methods are unavailable, return a paymentResult.resultCode of NO_PAY_OPTION
Optional: If the payment is declined because the payment verification is failed, return a paymentResult.resultCode of USER_PAYMENT_VERIFICATION_FAILED
Optional: If the payment is declined because the user KYC is failed, return a paymentResult.resultCode of USER_KYC_NOT_QUALIFIED
Optional: If the payment is declined because the merchant verification is failed, return a paymentResult.resultCode of PAYMENT_NOT_QUALIFIED

Mobile Payment Partner might return payment result in one of the following methods:

The response of the Payment interface
The request of the notifyPayment interface to send asynchronize notification
The response of the inquiryPayment interface

No matter which method is used, Mobile Payment Partner must ensure that resultCode and resultStatus are the same. However, one exception is allowed: the payment succeeds (Payment.resultCode is SUCCESS and Payment.resultStatus is S), and then the payment is successfully cancelled. In this case, when the inquiryPayment interface is called, the result reads Payment.resultCode is ORDER_IS_CLOSED and Payment.resultStatus is F.

Sample

Sample request

copy

{
 "paymentResult": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 },
 "paymentRequestId":"2020010123456789****", 
 "paymentId":"202001012345678901322222", 
 "paymentTime": "2020-01-01T12:01:01+08:30",
 "paymentAmount":{
    "value":"100",
    "currency":"JPY"
 },
 "payToAmount":{
    "value":"1000",
    "currency":"KRW"
 }, 
 "customerId":"1234567"
}

Sample response

copy

{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"Success"
 }
}

More information

See notifyPayment for details.

Query the payment result

Alipay+ can call the inquiryPayment interface to query the payment result of MPP (MPP) when the payment result notification is not returned timely because of network or system problems.

Process flow

The following figure illustrates the payment status inquiry flow:

Figure 2. Payment status inquiry flow

The interface request contains the following fields:

No.	Field	Remarks
1	acquirerId	/
2	pspId	/
3	paymentRequestId	/

The interface response contains the following fields:

No.	Field	Remarks
1	result	If result.resultStatus is `F` or `U`, Alipay+ uses the same refundRequestId to retry.
2	paymentResult Optional	The payment result, which is returned only when result.resultStatus is `S`. The paymentResult.resultStatus field reflects the payment status, with `S` representing success and `F` representing failure.
3	paymentRequestId Optional	This field must be returned when the refund is successful.
4	paymentId Optional	Must be returned for successful payments when paymentResult.resultStatus is `S`.
5	paymentAmount Optional	Must be returned for successful payments when paymentResult.resultStatus is `S`.
6	payToAmount Optional	Must be returned for successful payments when paymentResult.resultStatus is `S` and payToAmount is not equal to paymentAmount.
7	paymentTime Optional	Must be returned for successful payments when paymentResult.resultStatus is `S`.
8	customerId Optional	Must be returned for successful payments when paymentResult.resultStatus is `S`.
9	passThroughInfo Optional	/

Processing logic

When processing payment result inquiry requests, Mobile Payment Partner must pay attention to the following items:

If the payment doesn't exist, return a result.resultStatus of F and a result.resultCode of ORDER_NOT_EXIST.
If the payment exists and is successful, return a result.resultStatus of S and a paymentResult.resultStatus of S.
If the payment exists but is failed, return a result.resultStatus of S and paymentResult.resultStatus of F.
If the payment is cancelled, return a result.resultStatus of S and paymentResult.resultStatus of F. In addition, specify the failure reasons in result.resultCode.
If the payment failed, Mobile Payment Partner must return a result.resultStatus of S, paymentResult.resultStatus of F, and an error code that is corresponding to a specific reason.

If the balance is not enough, return a paymentResult.resultCode of USER_BALANCE_NOT_ENOUGH
If the user does not exist, or if the status is abnormal, return a paymentResult.resultCode of USER_NOT_EXIST/USER_STATUS_ABNORMAL
Optional: If the payment is declined for risk reasons, return a paymentResult.resultCode of RISK_REJECT
Optional: If the payment failed because the payment method used by the Mobile Payment Partner is not available, return a paymentResult.resultCode of UNAVAILABLE_PAYMENT_METHOD
Optional: If all payment methods are unavailable, return a paymentResult.resultCode of NO_PAY_OPTION
Optional: If the payment is declined because the payment verification is failed, return a paymentResult.resultCode of USER_PAYMENT_VERIFICATION_FAILED
Optional: If the payment is declined because the user KYC is failed, return a paymentResult.resultCode of USER_KYC_NOT_QUALIFIED
Optional: If the payment is declined because the merchant verification is failed, return a paymentResult.resultCode of PAYMENT_NOT_QUALIFIED

When no response is received, Alipay+ retries the request at incremental time intervals for about 10 minutes.

Sample

Sample request:

copy

{
 "acquirerId": "102218800000000****",
 "pspId":"102217200000000****",
 "paymentRequestId":"2020010123456789****"
}

Sample response:

copy

{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"Success"
  },
 "paymentResult": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"Success"
 },
 "paymentId":"2020010123456789013****", 
 "paymentTime": "2020-01-01T12:01:01+08:30",
 "paymentAmount":{
    "value":"100",
    "currency":"JPY"
 },
 "payToAmount":{
    "value":"1000",
    "currency":"KRW"
 }, 
 "customerId":"123****"
}

More information

See inquiryPayment for details.

Cancel the transaction

When Alipay+ does not receive the payment result from MPP within 1 minute after the payment is initiated, or when the inquiry of the payment result remains unknown within 1 minute after the payment is initiated, Alipay+ closes the transaction and initiates the cancellation request to MPP.

Process flow

The following figure illustrates the flow of payment cancellation initiated by Alipay+:

Figure 3. Flow of payment cancellation initiated by Alipay+

The interface request contains the following fields:

No.	Field	Remarks
1	acquirerId	/
2	pspId	/
3	paymentRequestId	Mobile Payment Partner uses this field for the idempotence control. For cancellation requests which are initiated with the same `paymentRequestId` and reach a final status (`S` or `F`), Mobile Payment Partnermust return the unique result.

The interface response contains the following field:

No.	Field
1	result

Processing logic

When cancel a payment, Mobile Payment Partner must pay attention to the following items:

The payment can only be cancelled within the agreed cancellable period, which is from the time when the transaction is initiated to 00:30 UTC+8 of T+1 day. The cancellable period is extended to T+1 day so that MPP can cancel payments for transactions that are initiated at around 24:00 UTC+8 of T day.
When the cancellation request is initiated within the agreed time window, MPP must process the cancellation request as below. In short, MPP must ensure that the cancellation is successful. This prevents complaints from users when an order is successfully canceled at the merchant side but no refund is received due to cancellation failures at the MPPside.

If the payment is successful, cancel the payment.
If the payment does not exist or is failed, return cancellation success. When a payment request that has the same paymentRequestId with the non-existent payment is sent to MPP, MPP must reject the request.
If the payment is being processed, close the transaction and ensure that no payment occurs for the order.

When no response is received, Alipay+ retries the request at incremental time intervals for about 2 hours.

Sample

Sample request:

copy

{
 "acquirerId": "1022188000000000001",
 "pspId":"1022172000000000001",
 "paymentRequestId":"20200101234567890132"
}

Sample response:

copy

{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"Success"
  }
}

More information

See cancelPayment for details.

Refund the payment

The refund interface can be used to return funds to users based on successful payment transactions. When the foreign exchange process is involved in the payment process, Alipay+ performs the refund based on the original payment rate or market rate according to the contract.

Process flow

The following figure illustrates the refund flow:

Figure 4. Refund flow

The interface request contains the following fields:

No.	Field	Remarks
1	acquirerId	/
2	pspId	/
3	paymentRequestId	/
4	refundRequestId	This field is used for the idempotence control. For the refund requests with the same refundRequestId and reach a final status (`S` or `F`), Alipay+ and MPP must return the unique result.
5	refundAmount	The value of refundAmount.currency and payAmount.currency must be the same. If multiple refunds exist for a particular PaymentOrder, the total successful refunded amount must not exceed the value of paymentAmount in paymentOrder.
6	refundFromAmount	The value of refundFromAmount.currency and payToAmount.currency must be the same. In the guaranteed price model, if multiple refunds exist for a particular PaymentOrder, the total successful refunded amount must not exceed the value of paymentAmount in paymentOrder.
7	refundQuote Optional	This field is required if the value of refundAmount.currency isn't equal to that of refundFromAmount.currency. The value of this field is the same as that of paymentQuote for the guaranteed price model.
8	refundPromoInfo Optional	This field is required when the promotion is applied.
9	surchargeInfo Optional	Specify this field if surcharge information exists in the payment that is related to this refund request.

The interface response contains the following fields:

No.	Field	Remarks
1	result	If result.resultStatus is `F` or `U`, Alipay+ uses the same refundRequestId to retry.
2	refundId Optional	This field must be returned when the refund result is successful.
3	refundTime Optional	This field must be returned when the refund is successful.

Processing logic

When processing refund requests, Mobile Payment Partner must pay attention to the following items:

Support full refund, partial refund, and multiple partial refunds. The total amount of multiple partial refunds cannot exceed the original amount paid by the user.
The refund time window should be at least 366 days.
Support refund requests with the same refundRequestId by performing idempotence control.
When no response is received, Alipay+ retries the request at incremental time intervals for about 2 hours.

Unable to process refund disputes

If the Mobile Payment Partner is unable to process refund disputes, it's suggested that the Mobile Payment Partner returns Success for all refund requests.

Promotion exists

If promotion exists, refund according to the refundFromAmount field.

Surcharge exists

If surcharge exists, refund according to the surchargeAmount field.

Sample

Sample request:

copy

{
 "acquirerId": "102218800000000****",
 "pspId":"102217200000000****",
 "paymentRequestId":"20181129190741010007000000****",
 "refundRequestId":"20181129190741020007000000****",
 "refundAmount":{
    "value":"90",
    "currency":"JPY"
 },
 "refundFromAmount":{
    "value":"900",
    "currency":"KRW"
 },
 "refundQuote":{
    "quoteId":"123****",
    "quoteCurrencyPair":"JPY/KRW",
    "quotePrice":"10.0000"
  }
}

Sample response:

copy

{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"Success"
  },
 "refundId":"20181129190741020007000000****",
 "refundTime": "2020-10-10T12:01:01+08:30"
}

More information

See refund for details.