RevKeenDocs
StatusSupport
API Reference
👥 Customers & VaultPayment Methods

Detach a payment method from its customer

Detaches a payment method from its customer. After detaching, the payment method can no longer be used for payments.

POST/payment-methods/{id}/detach

Detaches a payment method from its customer. After detaching, the payment method can no longer be used for payments.

This operation soft-deletes the payment method by setting its status to inactive; nothing is deleted from the card vault.

Refused with 409 payment_method_in_use (and nothing is changed) when the payment method is:

  • the customer's default payment method (set another default first), or
  • the payment method of a subscription that is active, trialing or past_due (move the subscription to another payment method first).

Detaching a payment method that is already inactive returns it unchanged.

Requires the payment_methods:write scope and the payment_method:detach permission. Send an Idempotency-Key header to make retries safe.

Related endpoints

  • POST /payment-methods/{id}/set-default — Set a payment method as its customer's default

Common errors

  • 401 authentication_error — missing, invalid, expired, or revoked credential. Codes: authentication_failed, invalid_api_key, expired_api_key, api_key_revoked, session_invalid, merchant_required. Carries a WWW-Authenticate: Bearer challenge.
  • 403 authorization_error — the caller is identified but the action is denied. Codes include insufficient_permissions, ip_not_allowed, merchant_mismatch, and origin_not_allowed.
  • 404 resource_missing — the referenced resource does not exist or is not visible to your key.
  • 409 conflict — Idempotency-Key collision with a different body, or a concurrent state-transition conflict.
  • 429 rate_limit_error — code rate_limit_exceeded. Back off using the Retry-After header (whole seconds); X-RateLimit-Reset is a UNIX timestamp in seconds.

Idempotency

Pass an Idempotency-Key header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see the idempotency guide.

Authorization

apiKey
x-api-key<token>

Your RevKeen merchant API key. Create and manage keys in Dashboard → Settings → Developer. Use rk_sandbox_* for staging/test and rk_live_* for production. The same key may be sent as Authorization: Bearer <key> if that suits your HTTP client better. A missing, invalid, expired, or revoked key returns 401 with a WWW-Authenticate: Bearer challenge; a valid key without the required scope returns 403.

In: header

Path Parameters

id*string

Payment method UUID

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

Stuck on an error response? Ask the RevKeen assistant to explain it.
curl -X POST "https://api.revkeen.com/v2/payment-methods/550e8400-e29b-41d4-a716-446655440000/detach" \
  -H "x-api-key: $REVKEEN_API_KEY"

Synthetic documentation data, validated against the response schema; not a live API result.

{  "id": "550e8400-e29b-41d4-a716-446655440000",  "object": "payment_method",  "public_id": "pm_1a2b3c4d5e6f",  "type": "card",  "status": "active",  "customer_id": "00000000-0000-4000-8000-000000000001",  "is_default": true,  "card": {    "brand": "visa",    "last4": "4242",    "exp_month": 12,    "exp_year": 2028,    "funding": "credit"  },  "us_bank_account": {    "bank_name": "Chase",    "last4": "6789",    "routing_number_last4": "1234",    "account_type": "checking"  },  "bacs_direct_debit": {    "sort_code": "XX-XX-**",    "account_number_last4": "1234",    "bank_name": "Barclays",    "mandate_id": "00000000-0000-4000-8000-000000000001",    "mandate_ref": "string",    "mandate_status": "active"  },  "billing_details": {    "name": "string",    "email": "user@example.com",    "phone": "string",    "address": {      "line1": "string",      "line2": "string",      "city": "string",      "state": "string",      "postal_code": "string",      "country": "string"    }  },  "metadata": {    "property1": null,    "property2": null  },  "created_at": "2026-09-01T12:00:00Z",  "updated_at": "2026-09-01T12:00:00Z"}