Remove payment method

DELETE/v1/payments/methods/{methodId}

Idempotency-Key requiredAccepts bearer

Remove a saved payment method

Deletes the method and its PSP token reference.Show more

Deletes the method and its PSP token reference. Removing the default makes the newest remaining method the default. Removing the last method of a tenant on the CARD money model: before the tenant is LIVE it is allowed and rail step money_model returns to needs_you (needs[] payment_method); once the tenant is LIVE it is 409 CONFLICT details.reason LAST_METHOD_IN_USE (add another method first). An unknown id and another tenant's id are the same 404 NOT_FOUND. Human session only; Owner only (403 PERMISSION_DENIED details.reason OWNER_ONLY). Idempotency-Key required. Audited (payments.method_removed).

Path parameters

methodIdstringRequired
A saved payment method's id (SavedPaymentMethod.id)

Headers

Idempotency-KeystringRequired
Mandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate…Show more
Mandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate is 409 IDEMPOTENCY_IN_PROGRESS.

Request body

This operation takes no request body.

Responses

204Removed
401
UNAUTHENTICATED — missing or expired token.Show more
UNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401.
ApiErrorResponse
403ApiErrorResponse
404NOT_FOUND — unknown or expired ref (unguessable refs, 15)ApiErrorResponse
405
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show more
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
ApiErrorResponse
409CONFLICT LAST_METHOD_IN_USE — the last method of a LIVE tenant on the CARD money model; or IDEMPOTENCY_CONFLICTApiErrorResponse
414
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show more
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
ApiErrorResponse
500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
501
NOT_IMPLEMENTED PAYMENT_METHODS_UNAVAILABLE — saved payment methods are off on this deployment (aikonic.payment-methods.enabled, off by default, on at DEV and SANDBOX).Show more
NOT_IMPLEMENTED PAYMENT_METHODS_UNAVAILABLE — saved payment methods are off on this deployment (aikonic.payment-methods.enabled, off by default, on at DEV and SANDBOX). Not retryable.
ApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

401	UNAUTHENTICATED The bearer token is expired. Re-authenticate and retry.	not retryable
403	PERMISSION_DENIED Reading wallets needs the finance:read permission.	not retryable
404	NOT_FOUND searchRef SR-F-7b31d0a9 is unknown or has expired; re-search	not retryable
405	VALIDATION This method is not served.	not retryable
409	CONFLICT This is the only payment method of a live account paying by card. Add another method before removing it.	not retryable
409	IDEMPOTENCY_CONFLICT Idempotency-Key 7f0c33d1-9a1e-4d2c-9f77-1c0f2b3a4d55 was used with a different body; never executed	not retryable
414	VALIDATION The request URI is longer than 8 KiB.	not retryable
500	INTERNAL An unexpected error occurred. Quote the traceId to support.	retryable
501	NOT_IMPLEMENTED Saved payment methods are not available on this deployment.	not retryable