Payment Methods — EPD Commerce

Payment methods represent a customer's stored payment instruments (currently cards held in EPD's secure vault).

Each customer can have multiple payment methods. One is always designated as the default, which is used for new subscriptions and orders when no specific method is provided.

Important: Add a card with a card_token from EPD Elements, or capture it server-to-server with Inbound Card Capture, which attaches it for you (no card_token).

POST /customers/{id}/payment_methods

Add a payment method

Attaches a card to a customer using a card_token: a single-use cct_… from EPD Elements. Your frontend captures the card in the browser and exchanges it for the token; your backend sends that token here with your secret key.

No browser in the loop? Inbound Card Capture is a server-to-server alternative: you POST the raw card to secure.epd.com and it captures and attaches the card in one call, returning the same payment method object. There is no card_token and no separate call to this endpoint.

How It Works (EPD Elements)

Capture the card in the browser with EPD Elements and your publishable key
The SDK returns a single-use card_token (cct_…, valid 15 minutes)
Send that card_token to this endpoint with your secret key: EPD vaults the card and creates the payment method

Options

Parameter	Default	Description
`set_as_default`	`false`	Make this the customer's default payment method
`update_subscriptions`	`false`	Update all active subscriptions to use this card

Tip: Set both set_as_default: true and update_subscriptions: true when replacing an expired card.

Sandbox Testing

In sandbox mode, capture a test card with EPD Elements or Inbound Card Capture to get a usable card_token.

Path parameters

NameTypeDescription

idrequired

string

Customer ID (UUID).

e.g. "550e8400-e29b-41d4-a716-446655440000"

Header parameters

NameTypeDescription

EPD-Version

string

API version override (format `YYYY-MM-DD`). If omitted, your account's pinned version or the latest version is used.

e.g. "2026-02-11"

X-EPD-Idempotency-Key

string (uuid)

Optional UUID v4 idempotency key for retry safety.

e.g. "550e8400-e29b-41d4-a716-446655440000"

Request body required

FieldTypeDescription

card_token

string

Single-use card-capture token (`cct_…`) produced by the [EPD Elements](/guides/elements) browser SDK. Your frontend captures the card with your **publishable** key and exchanges it for this token; your backend then attaches it here with your **secret** key. Expires 15 minutes after creation and can be used once.

e.g. "cct_3f8a1c9e7b2d4a6f0e1c3b5d7f9a1c3e5b7d9f0a2c4e6b8d"

set_as_default

boolean

Set this as the customer's default payment method.

e.g. true

update_subscriptions

boolean

Update all active subscriptions to use this payment method.

e.g. false

billing_details

object

Optional cardholder billing details to store alongside the card.

name

string

Cardholder name.

e.g. "Jane Doe"

address1

string

Street address, line 1.

e.g. "123 Market St"

address2

string

Street address, line 2 (apartment, suite, unit).

e.g. "Suite 400"

city

string

e.g. "San Francisco"

state

string

State, province, or region.

e.g. "CA"

zip

string

Postal or ZIP code.

e.g. "94103"

country

string

Two-letter ISO 3166-1 alpha-2 country code.

e.g. "US"

string (email)

e.g. "jane@example.com"

phone

string

e.g. "+14155551234"

Code samples

curl -X POST https://api.epd.com/v1/customers/550e8400-e29b-41d4-a716-446655440000/payment_methods \
  -H "Authorization: Bearer epd_test_sk_xxxx" \
  -H "Content-Type: application/json" \
  -H "EPD-Version: 2026-02-11" \
  -d '{
    "card_token": "cct_3f8a1c9e7b2d4a6f0e1c3b5d7f9a1c3e5b7d9f0a2c4e6b8d",
    "set_as_default": true,
    "update_subscriptions": true
  }'

const response = await fetch(
  'https://api.epd.com/v1/customers/550e8400-e29b-41d4-a716-446655440000/payment_methods',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer epd_test_sk_xxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      card_token: 'cct_3f8a1c9e7b2d4a6f0e1c3b5d7f9a1c3e5b7d9f0a2c4e6b8d',
      set_as_default: true,
    }),
  }
);

const pm = await response.json();
console.log(pm.id);        // 6ba7b815-9dad-11d1-80b4-00c04fd430c8
console.log(pm.card.last4); // "4242"

Responses

201 Payment method added.

FieldTypeDescription

idrequired

string

e.g. "6ba7b815-9dad-11d1-80b4-00c04fd430c8"

typerequired

enum

card

cardrequired

object

brand

string

e.g. "visa"

last4

string

e.g. "4242"

card_expiresnullable

string

Card expiration date.

e.g. "12/2025"

customer

string

ID of the customer this payment method belongs to.

e.g. "550e8400-e29b-41d4-a716-446655440000"

is_defaultrequired

boolean

e.g. true

created_at

string (date-time)

e.g. "2024-01-15T10:30:00.000Z"

400 Bad Request. The request was invalid or cannot be served.

FieldTypeDescription

errorrequired

object

typerequired

enum

The type of error.

invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error

coderequired

string

A short string identifying the specific error.

e.g. "validation_error"

messagerequired

string

A human-readable message providing details about the error.

e.g. "Request validation failed"

paramnullable

string

The parameter that caused the error, if applicable.

e.g. "email"

request_id

string

Unique request identifier for debugging.

e.g. "req_a1b2c3d4e5f67890abcdef0123456789"

field_errors

array[object]

Detailed field-level errors for validation failures.

401 Unauthorized. Authentication failed.

FieldTypeDescription

errorrequired

object

typerequired

enum

The type of error.

invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error

coderequired

string

A short string identifying the specific error.

e.g. "validation_error"

messagerequired

string

A human-readable message providing details about the error.

e.g. "Request validation failed"

paramnullable

string

The parameter that caused the error, if applicable.

e.g. "email"

request_id

string

Unique request identifier for debugging.

e.g. "req_a1b2c3d4e5f67890abcdef0123456789"

field_errors

array[object]

Detailed field-level errors for validation failures.

404 Not Found. The requested resource doesn't exist.

FieldTypeDescription

errorrequired

object

typerequired

enum

The type of error.

invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error

coderequired

string

A short string identifying the specific error.

e.g. "validation_error"

messagerequired

string

A human-readable message providing details about the error.

e.g. "Request validation failed"

paramnullable

string

The parameter that caused the error, if applicable.

e.g. "email"

request_id

string

Unique request identifier for debugging.

e.g. "req_a1b2c3d4e5f67890abcdef0123456789"

field_errors

array[object]

Detailed field-level errors for validation failures.

DELETE /customers/{id}/payment_methods/{pm_id}

Delete a payment method

Removes a payment method from a customer. If it's the default or used by active subscriptions, a replacement must be provided.

Path parameters

NameTypeDescription

idrequired

string

Customer ID.

e.g. "550e8400-e29b-41d4-a716-446655440000"

pm_idrequired

string

Payment method ID.

e.g. "6ba7b815-9dad-11d1-80b4-00c04fd430c8"

Header parameters

NameTypeDescription

EPD-Version

string

API version override (format `YYYY-MM-DD`). If omitted, your account's pinned version or the latest version is used.

e.g. "2026-02-11"

X-EPD-Idempotency-Key

string (uuid)

Optional UUID v4 idempotency key for retry safety.

e.g. "550e8400-e29b-41d4-a716-446655440000"

Request body

FieldTypeDescription

replacement_payment_method

string

Required if the payment method is default or used by active subscriptions.

e.g. "6ba7b815-9dad-11d1-80b4-00c04fd430d1"

Responses

200 Payment method deleted.

FieldTypeDescription

idrequired

string

e.g. "6ba7b815-9dad-11d1-80b4-00c04fd430c8"

deletedrequired

true

messagerequired

string

e.g. "Payment method successfully deleted."

400 Bad Request. The request was invalid or cannot be served.

FieldTypeDescription

errorrequired

object

typerequired

enum

The type of error.

invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error

coderequired

string

A short string identifying the specific error.

e.g. "validation_error"

messagerequired

string

A human-readable message providing details about the error.

e.g. "Request validation failed"

paramnullable

string

The parameter that caused the error, if applicable.

e.g. "email"

request_id

string

Unique request identifier for debugging.

e.g. "req_a1b2c3d4e5f67890abcdef0123456789"

field_errors

array[object]

Detailed field-level errors for validation failures.

401 Unauthorized. Authentication failed.

FieldTypeDescription

errorrequired

object

typerequired

enum

The type of error.

invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error

coderequired

string

A short string identifying the specific error.

e.g. "validation_error"

messagerequired

string

A human-readable message providing details about the error.

e.g. "Request validation failed"

paramnullable

string

The parameter that caused the error, if applicable.

e.g. "email"

request_id

string

Unique request identifier for debugging.

e.g. "req_a1b2c3d4e5f67890abcdef0123456789"

field_errors

array[object]

Detailed field-level errors for validation failures.

404 Not Found. The requested resource doesn't exist.

FieldTypeDescription

errorrequired

object

typerequired

enum

The type of error.

invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error

coderequired

string

A short string identifying the specific error.

e.g. "validation_error"

messagerequired

string

A human-readable message providing details about the error.

e.g. "Request validation failed"

paramnullable

string

The parameter that caused the error, if applicable.

e.g. "email"

request_id

string

Unique request identifier for debugging.

e.g. "req_a1b2c3d4e5f67890abcdef0123456789"

field_errors

array[object]

Detailed field-level errors for validation failures.