Webhooks for PayPal China

Instead of pulling REST API responses from PayPal, you can listen for the corresponding Orders and Payments webhook events and let PayPal push the notifications to you. Because the webhook event payloads directly correlate to REST API responses, this topic aligns closely with the changes outlined in REST APIs.

Webhooks related to the Payments v1 REST API

After migrating to a PayPal China account, some webhooks related to the Payments v1 REST API returns additional objects for cross-border transactions because PayPal does a currency conversion to settle in CNY.

Webhook events affected:

• PAYMENT.CAPTURE.COMPLETED
• PAYMENT.CAPTURE.DENIED
• PAYMENT.CAPTURE.PENDING
• PAYMENT.SALE.COMPLETED
• PAYMENT.SALE.DENIED
• PAYMENT.SALE.PENDING

The following pseudocode is simplified to highlight post-migration changes to the event payload 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.

Webhooks related to the Payments v2 REST API

After migrating to a PayPal China account, some webhooks related to the Payments v2 REST API returns additional objects for cross-border transactions because PayPal does a currency conversion to settle in CNY.

Webhook events affected:

• PAYMENT.CAPTURE.COMPLETED
• PAYMENT.CAPTURE.DENIED
• PAYMENT.CAPTURE.PENDING

The following pseudocode is simplified to highlight post-migration changes to the event payload 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 fields, your integration is already handling the fields 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.

Webhooks related to the Orders v2 REST API

After migrating to a PayPal China account, some webhooks related to the Orders v2 REST API returns additional objects for cross-border transactions because PayPal does a currency conversion to settle in CNY.

Webhook events affected:

• CHECKOUT.ORDER.APPROVED
• CHECKOUT.ORDER.COMPLETED

The following psuedo-code is simplified to highlight post-migration changes to the event payload 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 fields, your integration is already handling the fields 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.
  • transaction_fee_in_receivable_currency- New object in the Orders 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.

See also

Webhooks - Learn more about using Webhook events in your integration.