Understand different amounts

Multiple fields that are related with the amount are involved in the Payment interface and Refund interface. See the following list for explanations.

The following list describes refundAmount and refundFromAmount:

• refundAmount is the amount that's refunded to the user by Mobile Payment Provider.
• refundFromAmount is the refund amount that the user receives eventually.

Mobile Payment Provider refunds the amount to the user according to refundFromAmount.

The following list describes orderAmount, paymentAmount, payToAmount, surchargeAmount, savingsAmount, paymentQuote.

• orderAmount: The orginal order amount displayed by the merchant for user consumption records or payment results page display.
• paymentAmount: The amount that Mobile Payment Provider requests to receive in the currency that Alipay+ uses to create the payment order. If promotion exists, this is the amount that excludes the promotion amount.
• payToAmount: The amount that Mobile Payment Provider settles to Alipay+ in Mobile Payment Provider's currency. When Mobile Payment Provider's currency is different from paymentAmount.currency, the following equation applies: payToAmount.value=paymentAmount.value*paymentQuote.quotePrice.
• surchargeAmount: If this field is used, this is the actual amount that the user pays, but the amount that Mobile Payment Provider settles to Alipay+ is still payToAmount. surchargeAmount.value=paymentAmount.value*surchargeQuote.quotePrice.
• savingsAmount: The total amount that is saved if payment promotion exists. savingsAmount.currency is the same with payToAmount.currency.
• paymentQuote: The exchange rate between paymentAmount and payToAmount. This filed is only used when payToAmount.currency is not the same with paymentAmount.currency.

The following figure illustrates where the amounts are used in an actual situation:

Figure 1. Amounts in UX

Notes:

• orderAmount is displayed at merchant's order confirmation page and Mobile Payment Provider's payment confirmation page.
• quotePrice can be paymentQuote.quotePrice or surchargeQuote.quotePrice, depending on whether surcharge is used.
• paymentAmount is optional. In this case, it is not on the UI. It can be different from orderAmount if there is any promotion from Acquirer. However, Mobile Payment Provider should store paymentAmount in the system for reference.
• savingsAmount is the sum of paymentPromoInfo.paymentPromoDetails.savingsAmount.

The following figures describe the roles of each amount in a transaction:

• orderAmount

orderAmount is a pass-through field in the information flow.

Figure 2. orderAmount

• Amounts in a payment request when surchargeAmount is not used:

• Alipay+ passes paymentAmount, payToAmount, (and savingsAmount, if any) to Mobile Payment Provider.
• The user sees payToAmount in the payment page as the payment amount, and pays in the amount and currency accordingly.
• Mobile Payment Provider settles to Alipay+ by using payToAmount.

Figure 3. Amounts in a payment

• Amounts in a payment request when surchargeAmount is used:

• Alipay+ passes paymentAmount, payToAmount, surchargeAmount, (and savingsAmount, if any) to Mobile Payment Provider.
• The user sees surchargeAmount in the payment page as the payment amount, and pays in the amount and currency accordingly.
• Mobile Payment Provider still settles to Alipay+ by using payToAmount.

Figure 4. Amounts in a payment when surchargeAmount is used