如何用 Hyperswitch Payments API 完成手动捕获manual capture支付流程【免费下载链接】hyperswitchOpen source, composable payments platform | PCI compliant | SaaS and Self-host options | Enables connectivity to multiple payment, payout, fraud, vault and tokenization providers | Uplifts authorization with intelligent routing and revenue recovery | Reduce payment processing costs with cost observability | Reduces payment ops with reconciliation项目地址: https://gitcode.com/GitHub_Trending/hy/hyperswitch如果你的业务是先授权、后结算例如发货完成后再真正扣款就需要把支付拆成两步先对用户的支付工具做一次授权Authorize得到一笔处于requires_capture状态的交易等触发结算时再调用 Capture 接口完成扣款。Hyperswitch 的 Payments API v1 用capture_method字段和独立的 capture 端点实现了这个流程创建支付时传capture_method: manualHyperswitch 只做授权返回状态requires_capture随后POST /payments/{payment_id}/capture将资金真正捕获状态流转为succeeded。本文按这条路径给出可直接执行的请求示例、验证方式和边界条件请求可先在 sandbox 环境演练。流程与状态流转Hyperswitch 的 Payment Flows 文档 把手动捕获定义为 Two-Step Manual Capture适用于延迟结算场景例如 ship before charging。完整路径为授权POST /payments请求体中带capture_method: manual状态变为requires_capture捕获POST /payments/{payment_id}/capture最终状态变为succeededcapture_method共有四个取值见 OpenAPI 规范 中的CaptureMethod定义automatic授权成功后立即捕获资金是字段省略时的默认行为manual资金被授权但不捕获需要单独请求/payments/{payment_id}/capture端点manual_multiple通过多个独立请求分多次捕获部分金额scheduled在未来预定义时间自动捕获本文只针对manual。状态机方面文档给出的流转是processing→requires_capturemanual capture→succeededcapture API 调用或partially_captured部分捕获succeeded、failed、cancelled、partially_captured是终态无需进一步操作。准备条件根据 API 文档 的说明在 Hyperswitch Dashboard 注册并创建 merchant account 后会获得一个 secret key即 api-key和 publishable key。所有 API 请求通过在请求的Authorization头中提供对应的 key 来鉴权服务端到服务端的支付请求使用 secret api-key。secret key 不能暴露在前端或移动端应用中。请求的 Base URL 按环境选择环境Base URLSandboxhttps://sandbox.hyperswitch.ioProductionhttps://api.hyperswitch.io文档同时注明目前 sandbox 环境已可用production 环境仍在开发中。做接口联调时建议先用 sandbox 验证整条授权—捕获链路。以下示例中的sk_...替换为你的 secret api-keypay_xxx替换为第一步返回的payment_id。第一步创建手动捕获支付仅授权对POST {base_url}/payments发起请求。下面是基于 OpenAPI 规范中 Create a manual capture payment 示例amount: 6540, capture_method: manual, currency: USD补全了支付方式和confirm后的完整请求。卡号4242424242424242、CVC、有效期均为文档示例值sandbox 测试可直接使用curl -X POST https://sandbox.hyperswitch.io/payments \ -H Authorization: sk_..._your_secret_api_key \ -H Content-Type: application/json \ -d { amount: 6540, currency: USD, capture_method: manual, confirm: true, payment_method: card, payment_method_data: { card: { card_number: 4242424242424242, card_cvc: 123, card_exp_month: 10, card_exp_year: 25, card_holder_name: joseph Doe } } }字段说明均依据 OpenAPI 规范amount以货币最小单位计6540即 65.40 USDcapture_method: manual本次支付只授权、不捕获confirm: true创建时即发起授权若不想一步到位可省略confirm或显式设为false先创建支付意图稍后调用POST /payments/{payment_id}/confirm再授权。规范说明 confirm 后若授权成功且capture_method为manual状态为requires_capturepayment_method/payment_method_data实际扣款需要真实的支付方式只传金额和capture_method的基础请求会返回requires_payment_method状态见下文文档示例请求成功后判断下一步的依据是响应体中的两个字段status应为requires_captureamount_capturable当前还可以捕获的金额最小单位。规范说明该字段在capture_method为manual时才有意义完全捕获后或automatic模式下成功后会变为 0文档示例注意其中payment_id等为示意值不是固定预期{ amount: 6540, attempt_count: 1, capture_method: manual, client_secret: pay_manualcap_xxxxxxxxxxxx_secret_szzzzzzzzz, created: 2023-10-26T10:15:00Z, currency: USD, expires_on: 2023-10-26T10:30:00Z, merchant_id: merchant_myyyyyyyyyyyy, payment_id: pay_manualcap_xxxxxxxxxxxx, status: requires_payment_method }上面的示例对应基础创建请求未带支付方式时requires_payment_method的中间态补全支付方式并 confirm 后应观察到requires_capture。如果创建后需要再次确认状态可用GET {base_url}/payments/{payment_id}查询规范说明该接口也可用于获取已发起支付的状态或进行中支付的下一步动作next action。第二步调用 Capture 接口完成扣款在业务触发点例如发货后调用POST {base_url}/payments/{payment_id}/capture。规范中的描述捕获之前已授权、capture_method为manual且处于requires_capture状态的支付意图资金捕获成功后支付状态通常流转为succeeded。捕获全额不传金额默认捕获全部可捕获金额curl -X POST https://sandbox.hyperswitch.io/payments/pay_xxx/capture \ -H Authorization: sk_..._your_secret_api_key \ -H Content-Type: application/json \ -d {}捕获部分金额文档示例值 654即 6.54 USDcurl -X POST https://sandbox.hyperswitch.io/payments/pay_xxx/capture \ -H Authorization: sk_..._your_secret_api_key \ -H Content-Type: application/json \ -d { amount_to_capture: 654 }请求体字段PaymentsCaptureRequestamount_to_capture本次捕获金额最小单位。必须小于或等于当前amount_capturable省略时捕获全部可捕获金额。refund_uncaptured_amount布尔决定是否退回未捕获部分。规范明确标注目前未完全支持行为可能因连接器而异使用前提前确认你的连接器行为。statement_descriptor_prefix/statement_descriptor_suffix卡片账单描述前缀/后缀statement_descriptor_suffix已标记废弃建议使用billing_descriptor。all_keys_required布尔为true时返回字符串化的连接器原始响应体用于调试。响应为200 Payment captured返回PaymentsResponse对象400表示缺少必填字段。结果验证看捕获响应HTTP 200 且响应体status为succeeded说明资金已捕获。amount_received字段记录已捕获的总金额最小单位注意规范提示在fauxpaysandbox 连接器下即使capture_method是manualamount_received在succeeded时也可能反映的是授权金额判断以status为准。再查一次支付GET {base_url}/payments/{payment_id}确认status为succeeded且amount_capturable为 0。部分捕获场景捕获部分金额后状态为partially_captured相关的中间态文档状态机中RequiresCapture → PartiallyCaptured由 partial capture 触发剩余金额仍留在amount_capturable中可用同样的 capture 请求继续捕获manual_multiple模式即分多次部分捕获的正式叫法。错误与边界条件对非requires_capture状态的支付发起捕获会报错。规范原文对一个已succeeded且已完全捕获的支付或处于无效状态的支付调用 capture 会导致错误。所以捕获前先查一次状态避免重复扣款。授权过期或需要延长POST /payments/{payment_id}/extend_authorization仅对当前处于requires_capture状态的支付可用用于延长授权有效期。发货取消、释放授权支付处于requires_payment_method、requires_capture、requires_confirmation、requires_customer_action状态时可用POST {base_url}/payments/{payment_id}/cancel取消可选cancellation_reason如requested_by_customer。已扣款后的取消POST /payments/{payment_id}/cancel_post_capture适用于succeeded、partially_captured、partially_captured_and_capturable状态的支付。增量授权规范中 incremental authorization 端点同样要求支付处于requires_capture状态可在捕获前提高授权金额。终态succeeded、failed、cancelled、partially_captured是终态到达后不再需要 capture 操作。继续深入手动捕获与其他流程即时支付、解耦式 confirm、3DS、MIT的对比payment--flows.mdxcapture 端点定义payments--capture.mdxconfirm 端点解耦流程第二步payments--confirm.mdxcancel 端点payments--cancel.mdx完整字段与响应结构openapi_spec_v1.json【免费下载链接】hyperswitchOpen source, composable payments platform | PCI compliant | SaaS and Self-host options | Enables connectivity to multiple payment, payout, fraud, vault and tokenization providers | Uplifts authorization with intelligent routing and revenue recovery | Reduce payment processing costs with cost observability | Reduces payment ops with reconciliation项目地址: https://gitcode.com/GitHub_Trending/hy/hyperswitch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考