NVP/SOAP operations

APICurrent


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.

Pre-migration responsePost-migration response
PAYMENTINFO_0_AMT 10
PAYMENTINFO_0_CURRENCYCODE USD
PAYMENTINFO_0_FEEAMT 0.59
PAYMENTINFO_0_AMT 10
PAYMENTINFO_0_CURRENCYCODE USD
PAYMENTINFO_0_FEEAMT 0.59
PAYMENTINFO_0_EXCHANGERATE 10.00
PAYMENTINFO_0_SETTLEAMT 94.10
PAYMENTINFO_0_SETTLEMENTFEEAMOUNT xx.xx
PAYMENTINFO_0_SETTLEMENTFEECURRENCYCODE CNY
PAYMENTINFO_0_SETTLEAMTCURRENCYCODE 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.

Pre-migration responsePost-migration response

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

Pre-migration responsePost-migration response
AMT 10
CURRENCYCODE USD
FEEAMT 0.59
AMT 10
CURRENCYCODE USD
FEEAMT 0.59
EXCHANGERATE 10.00
SETTLEAMT 94.10
SETTLEMENTFEEAMOUNT xx.xx
SETTLEMENTFEECURRENCYCODE CNY
SETTLEAMTCURRENCYCODE 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.

Pre-migration responsePost-migration response

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