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 response Post-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.
    • PAYMENTINFOn_SETTLEMENTFEECURRENCYCODE - Currency code of PAYMENTINFOn_SETTLEAMT, in CNY.
    • PAYMENTINFOn_SETTLEAMTCURRENCYCODE - Currency code of PAYMENTINFOn_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 response Post-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 response Post-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 response Post-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.