NVP/SOAP operations

The Express Checkout NVP/SOAP API returns additional settlement-related response fields for cross-border transactions that settle in CNY.

DoExpressCheckoutPayment NVP

After migrating to a PayPal China account, the DoExpressCheckoutPayment NVP response returns additional fields for cross-border transactions because PayPal does a currency conversion to settle in CNY.

The following pseudocode is simplified to highlight post-migration changes to the response and is not a working sample. The sample assumes a transaction in USD that settles in CNY.

The following list describes the post-migration response fields returned and provides integration guidance:

• Existing fields - The following fields are the same across pre- and post-migration responses:
  • PAYMENTINFO_n_AMT
  • PAYMENTINFO_n_CURRENCYCODE
  • PAYMENTINFO_n_FEEAMT
    
    **Guidance**: Because these are existing fields, your integration is already handling the fields for your use case.
• Additional, existing fields - The following existing fields are now returned because a currency conversion occurs:
  • PAYMENTINFO_n_EXCHANGERATE
  • PAYMENTINFO_n_SETTLEAMT
    
    **Guidance**: At a minimum, you must determine if your integration needs to be updated to handle these fields. Factors that might help you make this decision: * Do you need to track the currency conversion information for your business? * Will your integration break if additional fields are returned? Most integrations can handle additional response fields, but it is dependent on your code.
• New fields - The following fields are new to version 216 of the API:
  • PAYMENTINFO_n_SETTLEMENTFEEAMOUNT- Amount of the settlement fee, in `CNY`.
  • PAYMENTINFO_n_SETTLEMENTFEECURRENCYCODE - Currency code of PAYMENTINFO_n_SETTLEAMT, in `CNY`.
  • PAYMENTINFO_n_SETTLEAMTCURRENCYCODE - Currency code of PAYMENTINFO_n_SETTLEMENTFEEAMOUNT, in `CNY`.
    
    **Guidance**: If you want to track the settlement information in `CNY`, you'll need to: * Upgrade to version 216 of the API. * Update your integration to process these new fields.

DoExpressCheckoutPayment SOAP

After migrating to a PayPal China account, the DoExpressCheckoutPayment SOAP response returns additional fields for cross-border transactions because PayPal does a currency conversion to settle in CNY.

The following psuedo-code is simplified to highlight post-migration changes to the response and is not a working sample. The sample assumes a transaction in USD that settles in CNY.

|

1<
2         GrossAmount xsi:type="cc:BasicAmountType" currencyID="USD"
3         >
4         10.00
5         <
6         /GrossAmount
7         >
8         <
9         FeeAmount xsi:type="cc:BasicAmountType" currencyID="USD"
10         >
11         0.59
12         <
13         /FeeAmount>
14         >

1<
2         GrossAmount xsi:type="cc:BasicAmountType" currencyID="USD">10.00
3         <
4         /GrossAmount
5         >
6            <
7         FeeAmount xsi:type="cc:BasicAmountType" currencyID="USD"
8         >
9         0.59
10         <
11         /FeeAmount
12         >
13            <
14         SettleAmount xsi:type="cc:BasicAmountType" currencyID="CNY"
15         >
16         94.10
17         <
18         /SettleAmount
19         >
20            <
21         ExchangeRate xsi:type="xs:string"
22         >
23         10.00
24         <
25         /ExchangeRate
26         >
27            <
28         SettlementFeeAmount xsi:type="cc:BasicAmountType" currencyID="CNY"
29         >
30         xx.xx
31         <
32         /SettlementFeeAmount
33         >

The following list describes the post-migration response fields returned and provides integration guidance:

• Existing fields - The following fields are the same across pre- and post-migration responses:
  • GrossAmount
  • FeeAmount
    
    **Guidance**: Because these are existing fields, your integration is already handling the fields for your use case.
• Additional, existing fields - The following existing fields are now returned because a currency conversion occurs:
  • SettleAmount
  • ExchangeRate
    
    **Guidance**: At a minimum, you must determine if your integration needs to be updated to handle these fields. Factors that might help you make this decision: * Do you need to track the currency conversion information for your business? * Will your integration break if additional fields are returned? Most integrations can handle additional response fields, but it is dependent on your code.
• New field - The following fields are new to version 216 of the API:
  • SettlementFeeAmount- Amount of the settlement fee, in CNY.
    
    **Guidance**: If you want to track the settlement information in `CNY`, you'll need to: * Upgrade to version 216 of the API. * Update your integration to process this new field.

DoCapture NVP

After migrating to a PayPal China account, the DoCapture NVP response returns additional fields for cross-border transactions because PayPal does a currency conversion to settle in CNY.

The following psuedo-code is simplified to highlight post-migration changes to the response and is not a working sample. The sample assumes a transaction in USD that settles in CNY.

The following list describes the post-migration response fields returned and provides integration guidance:

• Existing fields - The following fields are the same across pre- and post-migration responses:
  • AMT
  • CURRENCYCODE
  • FEEAMT
    
    **Guidance**: Because these are existing fields, your integration is already handling the fields for your use case.
• Additional, existing fields - The following existing fields are now returned because a currency conversion occurs:
  • EXCHANGERATE
  • SETTLEAMT
    
    **Guidance**: At a minimum, you must determine if your integration needs to be updated to handle these fields. Factors that might help you make this decision: * Do you need to track the currency conversion information for your business? * Will your integration break if additional fields are returned? Most integrations can handle additional response fields, but it is dependent on your code.
• New fields - The following fields are new to version 216 of the API:
  • SETTLEMENTFEEAMOUNT- Amount of the settlement fee, in CNY.
  • SETTLEMENTFEECURRENCYCODE - Currency code of SETTLEAMT, in CNY.
  • SETTLEAMTCURRENCYCODE - Currency code of SETTLEMENTFEEAMOUNT, in CNY.
    
    **Guidance**: If you want to track the settlement information in `CNY`, you'll need to: * Upgrade to version 216 of the API. * Update your integration to process these new fields.

DoCapture SOAP

After migrating to a PayPal China account, the DoExpressCheckoutPayment SOAP response returns additional fields for cross-border transactions because PayPal does a currency conversion to settle in CNY.

The following psuedo-code is simplified to highlight post-migration changes to the response and is not a working sample. The sample assumes a transaction in USD that settles in CNY.

|

1<
2         GrossAmount xsi:type="cc:BasicAmountType" currencyID="USD"
3         >
4         10.00
5         <
6         /GrossAmount
7         >
8         <
9         FeeAmount xsi:type="cc:BasicAmountType" currencyID="USD"
10         >
11         0.59
12         <
13         /FeeAmount
14         >

1<
2         GrossAmount xsi:type="cc:BasicAmountType" currencyID="USD">10.00
3         <
4         /GrossAmount
5         >
6            <
7         FeeAmount xsi:type="cc:BasicAmountType" currencyID="USD"
8         >
9         0.59
10         <
11         /FeeAmount
12         >
13            <
14         SettleAmount xsi:type="cc:BasicAmountType" currencyID="CNY"
15         >
16         94.10
17         <
18         /SettleAmount
19         >
20            <
21         ExchangeRate xsi:type="xs:string"
22         >
23         10.00
24         <
25         /ExchangeRate
26         >
27            <
28         SettlementFeeAmount xsi:type="cc:BasicAmountType" currencyID="CNY"
29         >
30         xx.xx
31         <
32         /SettlementFeeAmount
33         >

The following list describes the post-migration response fields returned and provides integration guidance:

• Existing fields - The following fields are the same across pre- and post-migration responses:
  • GrossAmount
  • FeeAmount
    
    **Guidance**: Because these are existing fields, your integration is already handling the fields for your use case.
• Additional, existing fields - The following existing fields are now returned because a currency conversion occurs:
  • SettleAmount
  • ExchangeRate
    
    **Guidance**: At a minimum, you must determine if your integration needs to be updated to handle these fields. Factors that might help you make this decision: * Do you need to track the currency conversion information for your business? * Will your integration break if additional fields are returned? Most integrations can handle additional response fields, but it is dependent on your code.
• New field - The following fields are new to version 216 of the API:
  • SettlementFeeAmount- Amount of the settlement fee, in CNY.
    
    **Guidance**: If you want to track the settlement information in `CNY`, you'll need to: * Upgrade to version 216 of the API. * Update your integration to process this new field.

See also

IPN notifications - Instead of pulling these API responses from PayPal, you can listen for the corresponding Express Checkout notifications and let PayPal push the notifications to you.