为订单创建一笔一次性收款,并拿到这笔收款在百居易的付款页链接。把客人跳转到 payment_link,客人在该页面用房东自己的收款账户付款,钱进入这些账户的方式与房东在百居易里创建的收款相同。
预订网站的典型流程: 用 POST /reservations 创建订单,调用本接口传入要收的金额,把客人跳转到 payment_link,再读 GET /reservations 的 payment 判断是否已付款。客人付款后没有 Webhook 推送,付完款也不会跳回你的网站;未付款的订单百居易不会自动取消,需要时请自行用 DELETE /reservations/{reservation_code} 取消。
收款账户。 收款账户不由调用方指定。百居易会把房东所有已连接、开启了「用于收款」、并且能收这个币种的账户都提供给客人(微信支付账户只收人民币,Flywire 账户只收它自己的币种,PayPal 账户只收 PayPal 支持的币种)。房东没有这样的账户时请求返回 400,不会创建任何收款;房东需要先在百居易里连接收款账户。响应中的 payment_account_types 列出客人会看到的账户类型。
收入项目与付款状态。 客人付款后,这笔钱按收款的收入项目记为收入。GET /reservations 的 payment 只统计记为订单收入的款项,所以如果要靠 payment 判断客人是否已付款,请保持 income_item_id 为默认的 22(订单收入)。选了其他收入项目(例如清洁费)时,付款照样会记账,但 payment.received_amount 和 payment.status 不会变化。
通知。 房东在百居易里设置的收款通知规则同样适用于这里创建的收款。房东没有改过规则时,收款创建后客人会收到一封带同一付款链接的邮件,到期日前后会收到提醒,付款后会收到确认。
重试。 传 idempotency_key 可以安全重试:24 小时内,用同一个 key、同样的参数再次请求,会返回第一次请求创建的收款(created: false),不会再建一笔。带 key 的请求返回 500 时也一样:用同一个 key 重试,要么返回那次请求建出的收款,要么只建一笔。不传 key 时每次请求都会新建一笔收款,客人可能每一笔都付。
400参数不合法;币种与订单币种不一致;收入项目不存在;订单已取消、已拒绝或已超时;或房东没有已连接、开启「用于收款」且能收这个币种的收款账户。不会创建任何收款。
404订单不存在。
409idempotency_key 已用于不同参数的请求,或它创建的收款已被删除。请换一个新 key。
420房东当前的套餐不支持收款。
429使用同一 idempotency_key 的请求还在处理中。请稍后用同一个 key 重试。
