开始之前
您需要为同一客户准备好已就绪的入金能力和已就绪的发行目的钱包。请通过能力与任务完成所有待办事项,然后重新拉取这两个资源。1. 创建报价
使用POST /v3/quotes 创建价格。请使用以下请求头:
data.id 保存为 QUOTE_ID。请展示返回的金额和费用,而不要基于汇率自行重新计算。
2. 执行报价
在过期前使用POST /v3/transfers 执行当前报价。请为这笔预期的转账使用一个新的幂等键:
data.id 保存为 TRANSFER_ID 并保留其当前状态。
为银行卡和 Apple Pay 添加返回 URL
对于银行卡或 Apple Pay 报价,您可以在同一请求中包含可选的redirectUrl。当客户完成托管结账后,结账页面会打开此 URL,将客户带回您的应用。
redirectUrl 必须是不超过 2048 个字符的绝对 HTTPS URL,且不得包含内嵌凭据。对于不支持返回跳转的报价,发送 redirectUrl 会导致校验失败,而不会被忽略。
到达 redirectUrl 仅代表浏览器完成了跳转。它并不确认付款或转账已完成。请根据第 4 步中的转账状态以及 Webhook 事件来判断是否完成。
为银行卡报价预选结账方式
对于银行卡报价,您可以在同一请求中包含可选的checkoutMethod,用于选择托管结账打开时预选的付款选项。当前取值为 card、apple_pay、google_pay、cash_app、sepa 和 blik。该列表是开放的,可能会增加,因此在转账读取中请容忍您不认识的值。当请求的方式对客户及其设备可用时,结账会以该方式打开,客户仍可选择结账提供的任何其他方式。省略该字段即可保留默认预选。
checkoutMethod 是一种偏好,而不是保证。可用性取决于客户、其设备和结账页面,因此请求某种方式并不会使其变得可用。这里的 sepa 和 blik 是银行卡结账内部的付款选项,而不是 Swipelux 的能力、通道或账户。预选不会更改报价的能力、金额或费用,最终费用由结账页面确认。转账读取会回显请求的值,但不会确认客户实际使用了哪种方式。对于非银行卡报价发送 checkoutMethod 会导致校验失败,而不会被忽略;使用相同幂等键的重放必须发送相同的 checkoutMethod。
3. 获取入金指令
读取GET /v3/transfers/{transferId}/instructions。按返回的 data.instructions 变体进行渲染,不要臆测其类型。
这些信息与本次转账绑定。切勿将某一笔转账的银行账户信息、代码、托管页面 URL、金额、备注或过期时间用于另一笔入金。
对于银行入金指令,当 reference.required 为 true 时,请在银行账户信息旁展示准确的 reference.value 并允许复制。请展示同一指令集中返回的金额和币种。
发行的银行账户则不同:它提供可用于后续入账的可复用账户信息。若您期望的是这种体验,请参阅发行银行账户。
4. 跟踪结算
在执行后以及每次事件之后,读取GET /v3/transfers/{transferId}。根据最新的 data.state 驱动面向客户的状态。
当转账需要下一步操作时,请使用 data.stateDetail 和 data.openTaskIds。不要根据预期的时间表就将其标记为已完成。
接下来,请添加 Webhook,并持续同步转账状态,直到其达到您产品所能处理的最终结果。