如何通过自定义参数调用PayPal API获取订单/支付详情
首先得说,你遇到的这个场景太常见了——用户在PayPal完成支付后直接关闭页面,不跳转回你的网站,导致PDT拿不到交易ID,系统里的订单和PayPal的支付记录脱节。
先直接给你结论:你提到的/v2/checkout/orders/{id}和/v2/payments/captures/{capture_id}这两个接口都是需要具体ID才能调用的,没法直接用custom_id=xxx这种方式传参。不过别担心,有两种靠谱的解决方案可以帮你通过自定义参数匹配订单和支付记录:
方案一:用Webhooks(推荐,最可靠)
这是PayPal官方推荐的异步通知方案,不管用户跳不跳转回你的网站,只要支付完成,PayPal都会主动把支付事件推送到你预先配置好的服务器地址上。
具体操作:
- 在PayPal商家后台创建一个Webhook,订阅
CHECKOUT.ORDER.COMPLETED(订单完成)或者PAYMENT.CAPTURE.COMPLETED(支付捕获完成)这两个事件类型。 - 当PayPal推送事件到你的服务器时,返回的payload里会包含你当初传递的
custom参数值(也就是你的订单ID)。你拿到这个订单ID后,直接更新系统里对应订单的状态就行。
这种方式不需要你主动去查,PayPal主动给你送数据,实时性和可靠性都比主动查询高很多。
方案二:用PayPal的搜索API(兜底方案)
如果暂时没法配置Webhooks,或者需要做一些补单的操作,可以用PayPal的列表搜索接口,通过custom参数过滤找到对应的订单或支付记录。
步骤1:确保创建订单时正确传递custom参数
在调用PayPal创建订单的API(POST /v2/checkout/orders)时,一定要把你的订单ID放到purchase_units[0].custom字段里,比如:
{ "intent": "CAPTURE", "purchase_units": [ { "amount": { "currency_code": "USD", "value": "10.00" }, "custom": "MyOrderId_12345" } ] }
步骤2:调用搜索接口匹配custom参数
- 搜索订单:调用
GET /v2/checkout/orders接口,加上filter参数来过滤特定custom值的订单:
GET /v2/checkout/orders?filter=custom:'MyOrderId_12345'
接口会返回所有匹配该custom值的订单列表,你可以从中提取订单ID,再调用GET /v2/checkout/orders/{id}获取完整的订单和支付详情,然后更新系统订单状态。
- 搜索支付捕获记录:如果需要直接找支付捕获的细节,可以调用
GET /v2/payments/captures接口,同样用filter参数:
GET /v2/payments/captures?filter=custom:'MyOrderId_12345'
⚠️ 注意:使用搜索接口需要你的API凭证拥有orders:read和payments:read的权限,另外如果你的订单量很大,建议加上时间范围过滤(比如filter=custom:'xxx' AND create_time:2024-01-01T00:00:00Z..2024-01-02T00:00:00Z),避免返回过多数据影响性能。
总结一下:优先用Webhooks解决实时同步的问题,搜索API可以作为补单或者异常场景的兜底方案。
备注:内容来源于stack exchange,提问作者Sciabal




