创建订单收款

为订单创建一笔一次性收款,并拿到这笔收款在百居易的付款页链接。把客人跳转到 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 时每次请求都会新建一笔收款,客人可能每一笔都付。

Path Params
string
required

订单的 reservation_code,即 POST /reservations 与 GET /reservations 返回的值。收款属于整张订单。

Body Params
number
required

客人需要支付的金额,大于 0,最多 2 位小数。

string
required

收款币种。必须与订单币种(GET /reservations 中 rates 的币种)一致。更多信息见 支持的币种。

date
required

付款截止日期,YYYY-MM-DD。会展示给客人,也用于房东的提醒规则;过了这一天付款链接仍然可以付款。

string
length ≤ 191

付款页上向客人展示的收款标题。默认取收入项目在房东界面语言下的名称(22 为「订单收入」)。

string
length ≤ 191

随收款保存的备注,可选。

integer
Defaults to 22

付款记入的收入项目,取 GET /income_items 返回的 id。默认 22(订单收入)。GET /reservations 的 payment 只统计订单收入:选其他项目时,付款不会改变 payment。

string
^[A-Za-z0-9_-]{8,64}$

可选。8-64 位字母、数字、- 或 _。每笔新收款用一个新 key,重试同一个请求时用同一个 key。24 小时内,已经创建过收款的 key 再次请求会返回那笔收款,created: false;同一个 key 换了参数返回 409。失败的请求不占用 key。

Responses

idempotency_key 的请求创建。

400

参数不合法;币种与订单币种不一致;收入项目不存在;订单已取消、已拒绝或已超时;或房东没有已连接、开启「用于收款」且能收这个币种的收款账户。不会创建任何收款。

404

订单不存在。

409

idempotency_key 已用于不同参数的请求,或它创建的收款已被删除。请换一个新 key。

420

房东当前的套餐不支持收款。

429

使用同一 idempotency_key 的请求还在处理中。请稍后用同一个 key 重试。

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json