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.

|<GrossAmount xsi:type="cc:BasicAmountType"
currencyID="USD">10.00</GrossAmount>

<FeeAmount xsi:type="cc:BasicAmountType"
currencyID="USD">0.59</FeeAmount>> |<GrossAmount xsi:type="cc:BasicAmountType"
currencyID="USD">10.00</GrossAmount>

<FeeAmount xsi:type="cc:BasicAmountType"
currencyID="USD">0.59</FeeAmount>

<SettleAmount xsi:type="cc:BasicAmountType"
currencyID="CNY">94.10</SettleAmount>

<ExchangeRate xsi:type="xs:string">10.00</ExchangeRate>

<SettlementFeeAmount xsi:type="cc:BasicAmountType"
currencyID="CNY">xx.xx</SettlementFeeAmount> |

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.

|<GrossAmount xsi:type="cc:BasicAmountType"
currencyID="USD">10.00</GrossAmount>

<FeeAmount xsi:type="cc:BasicAmountType"
currencyID="USD">0.59</FeeAmount> |<GrossAmount xsi:type="cc:BasicAmountType"
currencyID="USD">10.00</GrossAmount>

<FeeAmount xsi:type="cc:BasicAmountType"
currencyID="USD">0.59</FeeAmount>

<SettleAmount xsi:type="cc:BasicAmountType"
currencyID="CNY">94.10</SettleAmount>

<ExchangeRate xsi:type="xs:string">10.00</ExchangeRate>

<SettlementFeeAmount xsi:type="cc:BasicAmountType"
currencyID="CNY">xx.xx</SettlementFeeAmount> |

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.