PayPal China REST API features

The PayPal Rest APIs return additional settlement-related response fields for cross-border transactions that settle in CNY.

Payments v1

After migrating to a PayPal China account, some Payments v1 endpoints return additional objects for cross-border transactions because PayPal does a currency conversion to settle in CNY.

Endpoints affected:

• Capture authorization
• Capture order
• Show captured payment details
• Show sale details

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.

|"transaction_fee":{
    "value":"0.22",
    "currency":"USD"
}, |"transaction_fee":{
    "value":"0.22",
"currency":"USD"
},
"receivable_amount":
    "value":"59.26",
"currency":"CNY"
},
"transaction_fee_in_receivable_currency":
    "value":"xx.xx",
    "currency":"CNY"
},
"exchange_rate": "5.9483297432325", |

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

• Existing object - The following object is the same across pre- and post-migration responses:
  • transaction_fee
    
    **Guidance**: Because this is an existing object, your integration is already handling the object for your use case.
• Additional existing and new objects - The following existing objects are now returned because a currency conversion occurs:
  • receivable_amount - Existing object in the Payments v1 API.
  • exchange_rate - Existing object in the Payments v1 API.
  • transaction_fee_in_receivable_currency- New object in the Payments v1 API. Amount of the settlement fee, in CNY.
    
    **Guidance**: At a minimum, you must determine if your integration needs to be updated to handle these objects. Factors that might help you make this decision: * Do you need to track the currency conversion information for your business? * Do you want to track the transaction fee in `CNY`? * Will your integration break if additional objects are returned? Most integrations can handle additional response objects, but it is dependent on your code.

Payments v2

After migrating to a PayPal China account, some Payments v2 endpoints return additional objects for cross-border transactions because PayPal does a currency conversion to settle in CNY.

Endpoints affected:

• Capture authorized payment
• Show captured payment details

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 object - The following objects are the same across pre- and post-migration responses:
  • gross_amount
  • paypal_fee
  • net_amount
    
    **Guidance**: Because these are objects fields, your integration is already handling the objects for your use case.
• Additional existing and new objects - The following existing objects are now returned because a currency conversion occurs:
  • receivable_amount - Existing object in the Payments v2 API.
  • exchange_rate - Existing object in the Payments v2 API.
  • paypal_fee_in_receivable_currency- New object in the Payments v2 API. Amount of the settlement fee, in CNY.
    
    **Guidance**: At a minimum, you must determine if your integration needs to be updated to handle these objects. Factors that might help you make this decision: * Do you need to track the currency conversion information for your business? * Do you want to track the transaction fee in `CNY`? * Will your integration break if additional objects are returned? Most integrations can handle additional response objects, but it is dependent on your code.

Orders v2

After migrating to a PayPal China account, some Orders v2 endpoints return additional objects for cross-border transactions because PayPal does a currency conversion to settle in CNY.

Endpoints affected:

• Capture payment for order

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 object - The following objects are the same across pre- and post-migration responses:
  • gross_amount
  • paypal_fee
  • net_amount
    
    **Guidance**: Because these are existing objects, your integration is already handling the objects for your use case.
• Additional existing and new objects - The following existing objects are now returned because a currency conversion occurs:
  • receivable_amount - Existing object in the Orders v2 API.
  • exchange_rate - Existing object in the Orders v2 API.
  • paypal_fee_in_receivable_currency- New object in the Orders v2 API. The fee for this transaction in CNY. Returned only when the PayPal fee is charged in CNY.
    
    **Guidance**: At a minimum, you must determine if your integration needs to be updated to handle these objects. Factors that might help you make this decision: * Do you need to track the currency conversion information for your business? * Do you want to track the transaction fee in `CNY`? * Will your integration break if additional objects are returned? Most integrations can handle additional response objects, but it is dependent on your code.

Transaction search

The List transactions endpoint in the Transaction Search REST API has balance-related query parameters that behave differently than with your previous PayPal account because PayPal China accounts don't hold a balance.

• ending_balance - Always returns empty. The money movement into the PayPal China account is considered non-balance impacting.
• balance_affecting_records_only - Always returns all transactions, because no records are considered balance-impacting.

See also

Webhooks - Instead of pulling these API responses from PayPal, you can listen for the corresponding Checkout and Payments webhook events and let PayPal push the notifications to you.