● Payment methods and vault · /v1

Payment methods and vault

Card data lives only in the vault; your systems hold nothing but a token. Reuse, set as default, delete.

List a customer's payment methods

GET /v1/vault/methods

Query parameters

customer_uidrequired string

Response 200

token string Vault reference. This is the only value your systems should store.
type string
is_default boolean
card_brand string
card_last4 string
card_exp_month integer
card_exp_year integer
network_token boolean Whether it has been upgraded to a network token (survives card replacement)
customer_uid string
created_at string<date-time>
Request
curl -X GET https://api.baton.example/v1/vault/methods \
  -H "Authorization: Bearer sk_live_xxx"
Response · 200
[
  {
    "token": "pm_7c2a91f4",
    "type": "card",
    "is_default": true,
    "card_brand": "visa",
    "card_last4": "4242",
    "card_exp_month": 12,
    "card_exp_year": 2029,
    "network_token": true,
    "customer_uid": "CUS20261116000041",
    "created_at": "2026-10-02T03:11:00Z"
  }
]

Exchange raw card data for a token

POST /v1/vault/methods

Only H2H integrations need this endpoint, and only with a PCI DSS attestation. Card data must arrive inside a digital envelope; plaintext is rejected with 400. Signing is L2 (Ed25519).

The token returned is single-use by default; call vault to bind it to a customer for reuse. Without a PCI attestation, use a client session plus the SDK and card data never reaches your servers.

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Body

typerequired card
encryptedrequired object Digital envelope: a random AES-256-GCM key encrypted with our public key, encrypting the card number and CVV. JWE (RSA-OAEP + A256GCM) is accepted too
└key_idrequired string Our public key version. During rotation the previous key still decrypts for six months
└enc_keyrequired string
└noncerequired string
└ciphertextrequired string
└tagrequired string
customer_uid string Set it to bind the method to a customer immediately, saving a separate vault call

Response 201

token string Vault reference. This is the only value your systems should store.
type string
is_default boolean
card_brand string
card_last4 string
card_exp_month integer
card_exp_year integer
network_token boolean Whether it has been upgraded to a network token (survives card replacement)
customer_uid string
created_at string<date-time>

Errors

400Invalid parameters
401Key missing, invalid, wrong environment, or the signature failed verification
Request
curl -X POST https://api.baton.example/v1/vault/methods \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "type": "card",
  "encrypted": {
    "key_id": "pk_2026q4",
    "enc_key": "base64...",
    "nonce": "base64...",
    "ciphertext": "base64...",
    "tag": "base64..."
  }
}'
Response · 201
{
  "token": "pm_7c2a91f4",
  "type": "card",
  "is_default": false,
  "card_brand": "visa",
  "card_last4": "4242",
  "card_exp_month": 12,
  "card_exp_year": 2029,
  "network_token": false,
  "created_at": "2026-11-16T09:41:00Z"
}

Vault a payment method

POST /v1/vault/methods/{token}/store

Promote a single-use method into a reusable token bound to a customer. The card number reaches neither your database nor our business database.

Path parameters

tokenrequired string

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Body

customer_uidrequired string

Response 200

token string Vault reference. This is the only value your systems should store.
type string
is_default boolean
card_brand string
card_last4 string
card_exp_month integer
card_exp_year integer
network_token boolean Whether it has been upgraded to a network token (survives card replacement)
customer_uid string
created_at string<date-time>
Request
curl -X POST https://api.baton.example/v1/vault/methods/{token}/store \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "customer_uid": "CUS20261116000041"
}'

Set as default

POST /v1/vault/methods/{token}/default

Path parameters

tokenrequired string

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Response 200

token string Vault reference. This is the only value your systems should store.
type string
is_default boolean
card_brand string
card_last4 string
card_exp_month integer
card_exp_year integer
network_token boolean Whether it has been upgraded to a network token (survives card replacement)
customer_uid string
created_at string<date-time>
Request
curl -X POST https://api.baton.example/v1/vault/methods/{token}/default \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."

Delete a payment method

POST /v1/vault/methods/{token}/delete

Takes effect immediately, though subscription charges already in flight are unaffected. The deletion is written to the audit log.

Path parameters

tokenrequired string

Response 200

uid string
deleted boolean
Request
curl -X POST https://api.baton.example/v1/vault/methods/{token}/delete \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."