Payment Methods — EPD Commerce

Payment methods represent a customer's stored payment instruments (currently cards via EPD Gateway 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: Payment methods are created by providing a billing_id from the EPD Gateway payment vault. You must first vault the card through EPD Gateway's client-side SDK, then attach it to a customer via this API.

POST /customers/{id}/payment_methods

Add a payment method

Attaches a payment method to a customer using a billing_id from the EPD Gateway payment vault. The card details are fetched from EPD Gateway and stored securely.

How It Works

Vault the card through EPD Gateway's client-side SDK (Collect.js or similar)
Pass the resulting billing_id to this endpoint
EPD fetches the card details from EPD Gateway 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, pass a test card token (e.g. card_visa, card_insufficient_funds) as the billing_id to add a simulated payment method — no card vaulting required. See the Testing Guide for all available tokens.

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

billing_idrequired

string

EPD Gateway billing ID from the payment vault. **Sandbox only:** Pass a test card token (e.g. `card_visa`, `card_insufficient_funds`) to add a simulated payment method. See the [Testing Guide](/guides/testing) for all available tokens.

e.g. "987654"

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

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 '{
    "billing_id": "987654",
    "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({
      billing_id: '987654',
      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.