billing

PATCH `/v1/payment-methods/{paymentMethodId}`

Nominate a stored payment method as primary or backup.

所有 billing 端点

所有开发者文档 →

身份验证

请将 API 密钥作为 bearer 令牌发送。此端点在规范中未指明具体的权限，因此请为您的密钥赋予所需的最小权限，并通过检查响应来确认，而不是盲目假设。

此端点不需要组织 ID。您的密钥已用于识别其所属的组织，且响应范围也仅限于该组织。

免费试用

将尖括号中的内容替换为您自己的值，并将键占位符替换为您仪表板中的一个键。

curl -X PATCH https://api.zinndigital.com/v1/payment-methods/{paymentMethodId} \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "role": <string<, primary, backup>> }'

已登录？您仪表板中的 API 控制台会自动填入您真实的组织 ID 和您自己的密钥，并针对实时 API 运行请求，以便您查看实际的响应。在 API 控制台中打开此端点

详细信息

Sets the mandate's account-wide role, demoting whichever method held that slot. A method that is not usable (unconfirmed, revoked, or past its printed expiry) is rejected with 422 rather than silently accepted — the customer must not believe their renewals are covered when they are not. Nominating the current primary as backup (or the reverse) swaps them atomically, so the account is never left holding two of one slot and none of the other. Promoting a method that currently has no role demotes the outgoing primary to backup when — and only when — the backup slot is empty (owner ruling 2026-08-24, #3798). A backup the customer nominated deliberately is never overwritten; the outgoing primary simply loses its role, as before. Without this the account could end up with a primary and no fallback without being told, and the automatic backup-on-decline charge could not fire. ⛔ This operation described a field named is_default until 2026-08-25. No such field has existed since roles replaced it — the request schema has required role throughout — so the published description named a parameter no client could send (D13613).

参数

名称	类型	必填	内容简介
`paymentMethodId (path)`	`string`	是	The stored payment method's id.

请求正文

名称	类型	必填	内容简介
`role`	`string<, primary, backup>`	是	Nominate this mandate as the account's `primary` or `backup`, or send `""` to clear its role. Roles are account-wide: promoting a method demotes whichever method held that…

响应

名称	类型	必填	内容简介
`id`	`string`	是	—
`gateway`	`string<stripe, paypal>`	是	The rail holding the mandate. Crypto (NOWPayments) is absent by design — it has no mandate primitive, so those customers are invoiced ahead rather than rebilled (ADR 0011 §6).
`status`	`string<pending, active, expired, revoked>`	是	Only `active` is chargeable; `pending` means the gateway has not confirmed it yet.
`role`	`string<, primary, backup>`	是	Which job this mandate does for the organisation. `primary` is charged first; `backup` is charged immediately if the primary declines; `""` is simply stored. ⛔ Replaced…
`removal_blocked_by`	`string<, subscription, adhoc_charge, reseller_programme>`	是	Empty when this method may be removed. Otherwise the obligation that keeps the floor binding: this is the account's last operational way to pay and the named thing is still…
`method_type`	`string`	是	The gateway's own name for what kind of mandate this is — Stripe's `PaymentMethod.type` (`card`, `sepa_debit`, `klarna`, `kakao_pay`, …). Empty on a rail that does not type its…
`can_auto_renew`	`boolean`	是	Whether this mandate can be charged off-session, i.e. whether a renewal can be taken without the customer present. `false` means the subscription renews manually: the…
`brand`	`string`	是	—
`last4`	`string`	是	—
`exp_month`	`integer`	否	—
`exp_year`	`integer`	否	—
`holder_name`	`string`	否	—
`confirmed_at`	`string`	否	When the gateway confirmed the mandate. Null while `pending`.
`created_at`	`string`	是	—

此端点可能返回的错误

401 · 403 · 404 · 422

PATCH /v1/payment-methods/{paymentMethodId}