comecerodocs
Customers

Add a payment method

POST
/customers/{customer_id}/payment_methods

Saves a card or US bank account to a customer. Comecero first checks it with a $0 payment at the gateway (in a currency guessed from the customer's location); if the check fails, nothing is saved and the call fails. The card number is vaulted and the security code is dropped.

The customer's first payment method becomes the default. Send is_default: true to make a later one the default.

If the account does not allow saved cards, this only works for a customer who already has a payment method on file (409 otherwise). The same card or account twice is a 409.

Secret tokens, and limited tokens tied to the customer. Only a secret token can skip the check with validate: false.

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Path Parameters

customer_id*string

The id of the customer. With a limited token from a customer login you can send me instead.

Query Parameters

expand?string

Comma-separated child objects to return in full instead of as a URL, for example customer,payments. Use dot notation for nested objects (items.product), up to four levels deep. A single object takes up to 12 paths; a list takes up to 2, applied to every item. Extra paths are dropped without an error. See Expanding objects.

show?string

Comma-separated fields to return; all others are left out. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

hide?string

Comma-separated fields to leave out of the response. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

formatted?boolean

When true, the object also has a formatted child with amounts and dates as display text in the shopper's language and currency (for example $19.99 or November 7, 2026). The default is false. See Localized formatting.

Defaultfalse

Request Body

application/json
  1. body

A card or US bank account to save to a customer. Only credit_card and ach can be added this way. Other kinds are saved by a payment with save: true.

type*string

The kind of payment method.

Value in"credit_card""ach"
data*|

The card or bank account details.

is_default?boolean

Make this the customer's default payment method. The customer's first payment method is always the default.

Defaultfalse
validate?boolean

Secret token only (a limited token's value is ignored). Send false to save without the $0 check at the gateway. A card sent as a token is always checked.

Defaulttrue

Response Body

The saved payment method.

application/json
  1. response

A payment method saved to a customer, used again for later payments and subscription renewals. What data holds depends on type. Card and bank numbers are kept encrypted in Comecero's vault and are never returned; only masks, the last four digits and the brand come back. A card's security code is never stored.

object*"payment_method"

The object type. Always payment_method.

Value in"payment_method"
url*|

The full URL of the payment method.

payment_method_id*string

The id of the payment method.

date_created*string

When the payment method was saved.

Formatdate-time
date_modified*string

When the payment method was last changed.

Formatdate-time
test*boolean

True for a test payment method. Always matches the customer.

type*string

The kind of payment method. stripe is Comecero Express Payments. wallet is Google Pay or Apple Pay.

Value in"credit_card""ach""paypal""amazon_pay""apple_pay""stripe""wallet"
data?|||||

The details for this type. Not present for apple_pay.

is_default*boolean

True for the customer's default payment method, the one used when a payment, renewal or new subscription names the customer but no payment method. The first method saved becomes the default.

date_last_used*|

When the payment method was last used for a successful payment.

Formatdate-time
formatted?

Only when you send formatted=true. Display text.

curl -X POST 'https://api.comecero.com/api/v1/customers/string/payment_methods' \  -H 'Content-Type: application/json' \  -d '{  "type": "credit_card",  "data": {    "number": "4444555566661111",    "cvv": "123",    "exp_month": 12,    "exp_year": 2030,    "cardholder_name": "John Doe"  }}'
Example Response
{  "url": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/payment_methods/0092503470929PmEP0ivO4",  "object": "payment_method",  "payment_method_id": "0092503470929PmEP0ivO4",  "date_created": "2026-11-02T18:20:31Z",  "date_modified": "2026-11-02T18:20:31Z",  "test": true,  "type": "credit_card",  "data": {    "object": "credit_card",    "mask": "4***********1111",    "fingerprint": "2321657x8123834dc21ea08f",    "exp_month": 12,    "exp_year": 28,    "cardholder_name": "John Doe",    "ending": "1111",    "type": "Visa",    "label": "Visa 1111",    "billing_address": {      "object": "address",      "name": "John Doe",      "address_1": "123 Main St.",      "address_2": null,      "city": "New York",      "state_prov": "NY",      "postal_code": "10019",      "country": "US",      "email": null,      "meta": null    }  },  "is_default": true,  "date_last_used": "2026-11-02T18:20:31Z"}

List a customer's payment methods GET

Lists the payment methods saved to a customer, oldest first. Every method comes back on one page: `limit`, `offset` and `sort_by` are not used here. Card and bank numbers are never returned, only masks, the last four digits and the brand. Secret tokens, and limited tokens tied to the customer.

Get a payment method GET

Gets one payment method saved to a customer. Secret tokens, and limited tokens tied to the customer.