PayPal订单v2 API实现1%佣金扣除及相关功能技术问询

业务需求说明 #

我运营一个连接各类商户的收款平台，支持商户向客户收取款项。需实现如下分账规则：当商户发起100美元收款请求时，1%的金额转入平台账户，扣除PayPal手续费及1%佣金后的剩余金额转入商户账户。

示例计算：

收款请求金额：100美元
PayPal手续费：3.98美元
1%佣金：1美元
商户到账金额：100 - 3.98 - 1 = 95.02美元

即1美元转入平台账户，95.02美元转入商户账户。

待解决疑问 #

1. 如何在订单中添加自定义变量，以便通过https://api-m.sandbox.paypal.com/v2/checkout/orders/1CH72974UG290335P/capture接口获取这些值？
2. 客户完成支付请求金额后，如何触发沙箱回调？
3. 如何启用Webhook、实现1%佣金扣除以及添加自定义变量？

更新后的PayPal Order v2 API请求代码 #

curl --location 'https://api-m.sandbox.paypal.com/v2/checkout/orders' \
--header 'Content-Type: application/json' \
--header 'PayPal-Request-Id: paypal-request-id-1-sandbox' \
--header 'Authorization: Bearer A11AAJl4blmlkUnocTX2KQYUdm2gz3d94isr2tL6RvemrN49bPCmI_d5EzvhdZAqOTLl-nxIycCfdaGGvHljfnhtPR2fl_CJA' \
--header 'PayPal-Partner-Attribution-ID: TEST_SP_PPCP' \
--data-raw '{
   "intent": "CAPTURE",
   "purchase_units": [
      {
         "custom_id": "customer_paying_against_invoice_using_order_v2=1_=_company_auto_id=1_=_job_auto_id=181",
         "amount": {
            "currency_code": "USD",
            "value": "100.00",
            "breakdown": {
               "item_total": {
                  "currency_code": "USD",
                  "value": "100.00"
               }
            }
         },
         "payee": {
            "email_address": "sb-xyz@business.example.com",
            "merchant_id": "L6HQNC247QXGQ"
         },
         "platform_fees": [
            {
               "amount": {
                  "currency_code": "USD",
                  "value": "1.00"
               },
               "payee": {
                  "email_address": "sb-abc@business.example.com",
                  "merchant_id": "4LZCA37NTSXH4"
               }
            }
         ],
         "items": [
            {
               "name": "Invoice 1 - Test Job",
               "description": "-",
               "unit_amount": {
                  "currency_code": "USD",
                  "value": "100.00"
               },
               "quantity": "1"
            }
         ]
      }
   ],
   "payment_source": {
      "paypal": {
         "experience_context": {
            "payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
            "brand_name": "Project Name",
            "locale": "en-US",
            "landing_page": "LOGIN",
            "user_action": "PAY_NOW",
            "return_url": "https://test.com/pay.php?paypal_return_url=1",
            "cancel_url": "https://test.com/pay.php?cancel_url=1"
         }
      }
   }
}'

疑问解答 #

1. 添加自定义变量并通过Capture接口获取 #

可在purchase_units对象中使用custom_id字段存储自定义变量（如你代码中已实现的方式），也可通过description字段补充额外信息。调用Capture接口后，响应数据会包含purchase_units[].custom_id和purchase_units[].description字段，直接读取即可获取自定义值。若需结构化数据，可将JSON字符串转义后存入custom_id，后续捕获响应后再解析为对象。

2. 触发沙箱回调 #

沙箱环境回调触发逻辑与生产环境一致：

• 客户完成支付并成功捕获款项后，PayPal会自动向配置的Webhook URL发送事件通知
• 可通过沙箱后台的「Webhook Simulator」手动触发测试事件，模拟支付完成后的回调
• 订单配置的return_url会在客户支付成功后跳转回你的页面，可作为前端层面的回调逻辑，但服务器端需依赖Webhook确保可靠性

3. 启用Webhook、实现1%佣金扣除及添加自定义变量 #

启用Webhook

1. 登录PayPal沙箱开发者后台，进入对应应用
2. 在「Webhooks」选项中点击「Create Webhook」
3. 输入服务器接收URL，选择需监听的事件（如CHECKOUT.ORDER.APPROVED、PAYMENT.CAPTURE.COMPLETED）
4. 保存配置后，PayPal会在对应事件发生时向该URL发送POST请求

实现1%佣金扣除

你代码中已通过platform_fees字段实现佣金扣除逻辑：

• 在purchase_units.platform_fees数组中添加平台佣金金额及平台账户信息（邮箱或商户ID）
• 款项被捕获时，PayPal会自动将1美元佣金转入指定平台账户，剩余金额扣除PayPal手续费后打给商户
• 需确保平台账户已完成PayPal商家认证，且具备接收平台费用的权限

添加自定义变量

参考问题1的方案，直接在purchase_units下使用custom_id、description或invoice_id字段即可，按需选择合适的字段存储自定义信息。

内容的提问来源于stack exchange，提问作者Arslan Ahmed Awan