RevKeenDocs
StatusSupport
API Reference
👥 Customers & VaultPayment Methods

Set a payment method as its customer's default

Makes this payment method the default payment method of the customer it belongs to. The previous default, if any, stops being the default.

POST/payment-methods/{id}/set-default

Makes this payment method the default payment method of the customer it belongs to. The previous default, if any, stops being the default.

This sets the customer's default only. It does not move any existing subscription to this payment method: a subscription keeps the payment method it already bills on.

A payment method that is not active (detached or expired) is refused with 409 payment_method_not_active and nothing is changed. Setting a payment method that is already the default is a no-op that returns it.

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

Related endpoints

  • POST /payment-methods/{id}/detach — Detach a payment method from its customer

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/set-default" \
  -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"}