billing
PATCH /v1/payment-methods/{paymentMethodId}
Nominate a stored payment method as primary or backup.
Autenticación
Envía una clave de API como token de portador. Este endpoint no especifica un permiso concreto en la especificación, así que otorga a tu clave los mínimos privilegios necesarios y comprueba la respuesta en lugar de dar por sentado.
Este endpoint no requiere ningún id de organización. Su clave ya identifica la organización a la que pertenece, y la respuesta está delimitada a ella.
Pruébalo
Reemplaza cualquier elemento entre corchetes angulares por tus propios valores, y el marcador de posición key con una clave de tu panel de control.
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>> }'¿Has iniciado sesión? La consola de la API en tu panel de control rellena el ID de tu organización real y tu propia clave, y ejecuta la solicitud contra la API en vivo para que puedas ver la respuesta real. Abre este endpoint en la consola de la API
Detalles
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).
Parámetros
| Nombre | Tipo | Obligatorio | ¿Qué es esto? |
|---|---|---|---|
paymentMethodId (path) | string | Sí | The stored payment method's id. |
Cuerpo de la solicitud
| Nombre | Tipo | Obligatorio | ¿Qué es esto? |
|---|---|---|---|
role | string<, primary, backup> | Sí | 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 s… |
Respuesta
| Nombre | Tipo | Obligatorio | ¿Qué es esto? |
|---|---|---|---|
id | string | Sí | — |
gateway | string<stripe, paypal> | Sí | 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> | Sí | Only `active` is chargeable; `pending` means the gateway has not confirmed it yet. |
role | string<, primary, backup> | Sí | Which job this mandate does for the **organisation**. `primary` is charged first; `backup` is charged immediately if the primary declines; `""` is simply stored. ⛔ Replaced `is_… |
removal_blocked_by | string<, subscription, adhoc_charge, reseller_programme> | Sí | 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 | Sí | 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 | Sí | 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 cu… |
brand | string | Sí | — |
last4 | string | Sí | — |
exp_month | integer | No | — |
exp_year | integer | No | — |
holder_name | string | No | — |
confirmed_at | string | No | When the gateway confirmed the mandate. Null while `pending`. |
created_at | string | Sí | — |
Errores que este endpoint puede devolver
401 · 403 · 404 · 422