---
title: "Payment methods"
description: "Vaulted cards, addressed by their token. Read, update, retain and redact them."
image: "https://docs.ordercard.io/og.png"
---

> API Reference Index
> Fetch the complete API index at: https://docs.ordercard.io/api/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment methods

A payment method is a vaulted card. Its `token` (`tok_…`) is what you store in your own database and send when you charge. The card number is encrypted in the vault and never returned: responses carry the brand, first six and last four digits, expiry, card type and issuer.

Cards usually arrive through [hosted fields](/hosted-fields), which makes a **pending** token that expires after 24 hours. A successful charge retains it by default; you can also retain it without charging. **Redacting** destroys the number for good.

A card can belong to one of your [customers](/api/customers). Link it from your server, never from the browser: send `customer` (OrderCard's `cus_…` id) or `customer_reference` (your own id, which finds or creates the customer) when you create, update or retain the card, or when you charge it. Hosted fields refuse both, so a shopper can never put a card in someone else's wallet. List a customer's cards with `?customer=cus_…`.

## Fingerprints

`card.fingerprint` is the same for the same card number within your team, so you can spot a customer vaulting a card twice without ever seeing the number.

## The security code

The CVV is never stored. When a card is tokenized with one, it is kept encrypted for 15 minutes so the first customer-initiated charge can send it, then deleted. `cvv_available` tells you whether that charge would still include it.

## Vault a card from your server

`POST /v1/payment_methods`

Vaults a card number your server already holds. This puts your servers in PCI DSS scope, so it needs a key with the payment_methods:pan permission, which only team owners and admins can grant. Use hosted fields instead whenever you can.

- **Operation id:** `payment-methods.create`
- **Required ability:** `payment_methods:pan`
- **Rate limit:** 300 requests/minute per API key

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `card` | object | yes | The card itself. |
| `card.number` | string | yes | Card number; spaces and dashes are ignored. Must pass the Luhn check. Example: `4242 4242 4242 4242` |
| `card.exp_month` | integer | yes | 1 to 12. |
| `card.exp_year` | integer | yes | Four-digit year, not in the past. |
| `card.cvv` | string | no | Kept encrypted for 15 minutes for the first customer-initiated charge, then deleted. Never stored. |
| `billing` | object | no | Cardholder name, contact and billing address. Sent to gateways for address verification. Every field is optional; on update, sending a field as null clears it. |
| `billing.first_name` | string | no | Max 100 characters. |
| `billing.last_name` | string | no | Max 100 characters. |
| `billing.email` | string | no | A valid email address. Stored trimmed and in lowercase. |
| `billing.phone` | string | no | Max 32 characters. |
| `billing.address_line1` | string | no | Max 255 characters. |
| `billing.address_line2` | string | no | Max 255 characters. |
| `billing.city` | string | no | Max 100 characters. |
| `billing.state` | string | no | State or province, e.g. GA. |
| `billing.postal_code` | string | no | Max 20 characters. |
| `billing.country` | string | no | Two-letter ISO country code. Example: `US` |
| `customer` | string | no | The customer this card belongs to, by OrderCard id. Send null to unlink. Send this or customer_reference, not both. Example: `cus_01jaxr9m4q7t0w3y6b9d2f5h8k` |
| `customer_reference` | string | no | The customer this card belongs to, by your own id. OrderCard finds the customer with this reference, or creates one the first time. Send null to unlink. Example: `user_1001` |
| `metadata` | object | no | Up to 50 keys of your own, each with a text value of up to 500 characters. Replaces any metadata the card had. See Conventions for the rules. |
| `retain` | boolean | no | Keep the card until you redact it. Defaults to true; false makes a pending token that expires after 24 hours unless charged or retained. |

#### Request

```bash
curl -X POST https://api.ordercard.io/v1/payment_methods \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "card": { "number": "4242424242424242", "exp_month": 12, "exp_year": 2029, "cvv": "123" },
    "billing": { "first_name": "Jane", "last_name": "Doe", "postal_code": "30301", "country": "US" },
    "customer_reference": "user_1001"
  }'
```

#### Responses

##### 201 — The vaulted card. The number itself is never returned.

```json
{
  "object": "payment_method",
  "token": "tok_01jaxqk0pz7r8w5m3n2b4c6d8e",
  "status": "retained",
  "environment": "sandbox",
  "source": "hosted_fields",
  "card": {
    "brand": "visa",
    "brand_label": "Visa",
    "first6": "424242",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2029,
    "type": "credit",
    "category": "CLASSIC",
    "issuer": "OrderCard Test Bank",
    "country": "US",
    "prepaid": false,
    "commercial": false,
    "fingerprint": "8f14e45fceea167a5a36dedd4bea2543c1b4b2f7d1e6a1f0a8c9b3e2d5f6a7b8"
  },
  "cvv_available": false,
  "customer": "cus_01jaxr9m4q7t0w3y6b9d2f5h8k",
  "customer_reference": "user_1001",
  "billing": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": null,
    "address_line1": "1 Peachtree St",
    "address_line2": null,
    "city": "Atlanta",
    "state": "GA",
    "postal_code": "30301",
    "country": "US"
  },
  "checks": {
    "avs_result": "match",
    "cvv_result": "match",
    "verified_at": "2026-10-17T15:04:05+00:00"
  },
  "metadata": {},
  "retained_at": "2026-10-17T15:04:05+00:00",
  "redacted_at": null,
  "expires_at": null,
  "created_at": "2026-10-17T15:03:41+00:00",
  "updated_at": "2026-10-17T15:04:05+00:00"
}
```

##### 422 — The card is invalid.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "The card number is incorrect.",
    "errors": { "card.number": ["The card number is incorrect."] }
  }
}
```

##### 403 — The key lacks payment_methods:pan.

```json
{ "error": { "code": "forbidden", "message": "This action is unauthorized." } }
```

#### Caveats

- Live keys refuse the sandbox test card numbers with test_card_in_live_mode.
- Sandbox keys take only the test card numbers, and refuse any other with real_card_in_sandbox_mode.
- The same card vaulted twice gets two tokens with the same card.fingerprint.

## List payment methods

`GET /v1/payment_methods`

Lists the vaulted cards of the key's team and environment, newest first, with cursor pagination.

- **Operation id:** `payment-methods.list`
- **Required ability:** `payment_methods:read`
- **Rate limit:** 300 requests/minute per API key

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `customer` | string | no | Only this customer's cards, by OrderCard id. |
| `customer_reference` | string | no | Only the cards of the customer with this reference. |
| `status` | string | no | pending, retained or redacted. |
| `limit` | integer | no | 1 to 100, default 25. |
| `cursor` | string | no | The meta.next_cursor of the previous page. |

#### Request

```bash
curl "https://api.ordercard.io/v1/payment_methods?customer=cus_01jaxr9m4q7t0w3y6b9d2f5h8k" \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — A page of payment methods.

```json
{
  "data": [ { "object": "payment_method", "token": "tok_01jaxqk0pz7r8w5m3n2b4c6d8e", "...": "..." } ],
  "links": { "first": null, "last": null, "prev": null, "next": null },
  "meta": { "path": "https://api.ordercard.io/v1/payment_methods", "per_page": 25, "next_cursor": null, "prev_cursor": null }
}
```

## Retrieve a payment method

`GET /v1/payment_methods/{token}`

Returns one vaulted card. A token from another team or environment answers 404.

- **Operation id:** `payment-methods.get`
- **Required ability:** `payment_methods:read`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | yes | The payment method's token. Example: `tok_01jaxqk0pz7r8w5m3n2b4c6d8e` |

#### Request

```bash
curl https://api.ordercard.io/v1/payment_methods/tok_01jaxqk0pz7r8w5m3n2b4c6d8e \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — The payment method.

```json
{
  "object": "payment_method",
  "token": "tok_01jaxqk0pz7r8w5m3n2b4c6d8e",
  "status": "retained",
  "environment": "sandbox",
  "source": "hosted_fields",
  "card": {
    "brand": "visa",
    "brand_label": "Visa",
    "first6": "424242",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2029,
    "type": "credit",
    "category": "CLASSIC",
    "issuer": "OrderCard Test Bank",
    "country": "US",
    "prepaid": false,
    "commercial": false,
    "fingerprint": "8f14e45fceea167a5a36dedd4bea2543c1b4b2f7d1e6a1f0a8c9b3e2d5f6a7b8"
  },
  "cvv_available": false,
  "customer": "cus_01jaxr9m4q7t0w3y6b9d2f5h8k",
  "customer_reference": "user_1001",
  "billing": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": null,
    "address_line1": "1 Peachtree St",
    "address_line2": null,
    "city": "Atlanta",
    "state": "GA",
    "postal_code": "30301",
    "country": "US"
  },
  "checks": {
    "avs_result": "match",
    "cvv_result": "match",
    "verified_at": "2026-10-17T15:04:05+00:00"
  },
  "metadata": {},
  "retained_at": "2026-10-17T15:04:05+00:00",
  "redacted_at": null,
  "expires_at": null,
  "created_at": "2026-10-17T15:03:41+00:00",
  "updated_at": "2026-10-17T15:04:05+00:00"
}
```

##### 404 — No such token for this key.

```json
{ "error": { "code": "not_found", "message": "The requested resource does not exist." } }
```

## Update a payment method

`PATCH /v1/payment_methods/{token}`

Changes the expiry date or cardholder details. The card number can never change: a new card is a new token. Only the fields you send change.

- **Operation id:** `payment-methods.update`
- **Required ability:** `payment_methods:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | yes | The payment method's token. Example: `tok_01jaxqk0pz7r8w5m3n2b4c6d8e` |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `exp_month` | integer | no | Send together with exp_year. |
| `exp_year` | integer | no | Send together with exp_month. Not in the past. |
| `billing` | object | no | Cardholder name, contact and billing address. Sent to gateways for address verification. Every field is optional; on update, sending a field as null clears it. |
| `billing.first_name` | string | no | Max 100 characters. |
| `billing.last_name` | string | no | Max 100 characters. |
| `billing.email` | string | no | A valid email address. Stored trimmed and in lowercase. |
| `billing.phone` | string | no | Max 32 characters. |
| `billing.address_line1` | string | no | Max 255 characters. |
| `billing.address_line2` | string | no | Max 255 characters. |
| `billing.city` | string | no | Max 100 characters. |
| `billing.state` | string | no | State or province, e.g. GA. |
| `billing.postal_code` | string | no | Max 20 characters. |
| `billing.country` | string | no | Two-letter ISO country code. Example: `US` |
| `customer` | string | no | The customer this card belongs to, by OrderCard id. Send null to unlink. Send this or customer_reference, not both. Example: `cus_01jaxr9m4q7t0w3y6b9d2f5h8k` |
| `customer_reference` | string | no | The customer this card belongs to, by your own id. OrderCard finds the customer with this reference, or creates one the first time. Send null to unlink. Example: `user_1001` |
| `metadata` | object | no | Up to 50 keys of your own, each with a text value of up to 500 characters. Replaces any metadata the card had. See Conventions for the rules. |

#### Request

```bash
curl -X PATCH https://api.ordercard.io/v1/payment_methods/tok_01jaxqk0pz7r8w5m3n2b4c6d8e \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "exp_month": 12, "exp_year": 2031, "billing": { "postal_code": "30303" } }'
```

#### Responses

##### 200 — The updated payment method.

```json
{
  "object": "payment_method",
  "token": "tok_01jaxqk0pz7r8w5m3n2b4c6d8e",
  "status": "retained",
  "environment": "sandbox",
  "source": "hosted_fields",
  "card": {
    "brand": "visa",
    "brand_label": "Visa",
    "first6": "424242",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2029,
    "type": "credit",
    "category": "CLASSIC",
    "issuer": "OrderCard Test Bank",
    "country": "US",
    "prepaid": false,
    "commercial": false,
    "fingerprint": "8f14e45fceea167a5a36dedd4bea2543c1b4b2f7d1e6a1f0a8c9b3e2d5f6a7b8"
  },
  "cvv_available": false,
  "customer": "cus_01jaxr9m4q7t0w3y6b9d2f5h8k",
  "customer_reference": "user_1001",
  "billing": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": null,
    "address_line1": "1 Peachtree St",
    "address_line2": null,
    "city": "Atlanta",
    "state": "GA",
    "postal_code": "30301",
    "country": "US"
  },
  "checks": {
    "avs_result": "match",
    "cvv_result": "match",
    "verified_at": "2026-10-17T15:04:05+00:00"
  },
  "metadata": {},
  "retained_at": "2026-10-17T15:04:05+00:00",
  "redacted_at": null,
  "expires_at": null,
  "created_at": "2026-10-17T15:03:41+00:00",
  "updated_at": "2026-10-17T15:04:05+00:00"
}
```

##### 409 — The card was redacted.

```json
{ "error": { "code": "payment_method_redacted", "message": "This card was redacted and can no longer be changed." } }
```

## Retain a payment method

`POST /v1/payment_methods/{token}/retain`

Keeps a pending token (from hosted fields) until you redact it, and can link it to a customer at the same time. A successful charge with retain_on_success (the default) retains the card too, so you only need this to save a card without charging it.

- **Operation id:** `payment-methods.retain`
- **Required ability:** `payment_methods:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | yes | The payment method's token. Example: `tok_01jaxqk0pz7r8w5m3n2b4c6d8e` |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `customer` | string | no | Link the card to this customer, by OrderCard id. |
| `customer_reference` | string | no | Link the card to the customer with this reference of yours, created the first time. |

#### Request

```bash
curl -X POST https://api.ordercard.io/v1/payment_methods/tok_01jaxqk0pz7r8w5m3n2b4c6d8e/retain \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — The payment method, now retained.

```json
{
  "object": "payment_method",
  "token": "tok_01jaxqk0pz7r8w5m3n2b4c6d8e",
  "status": "retained",
  "environment": "sandbox",
  "source": "hosted_fields",
  "card": {
    "brand": "visa",
    "brand_label": "Visa",
    "first6": "424242",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2029,
    "type": "credit",
    "category": "CLASSIC",
    "issuer": "OrderCard Test Bank",
    "country": "US",
    "prepaid": false,
    "commercial": false,
    "fingerprint": "8f14e45fceea167a5a36dedd4bea2543c1b4b2f7d1e6a1f0a8c9b3e2d5f6a7b8"
  },
  "cvv_available": false,
  "customer": "cus_01jaxr9m4q7t0w3y6b9d2f5h8k",
  "customer_reference": "user_1001",
  "billing": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": null,
    "address_line1": "1 Peachtree St",
    "address_line2": null,
    "city": "Atlanta",
    "state": "GA",
    "postal_code": "30301",
    "country": "US"
  },
  "checks": {
    "avs_result": "match",
    "cvv_result": "match",
    "verified_at": "2026-10-17T15:04:05+00:00"
  },
  "metadata": {},
  "retained_at": "2026-10-17T15:04:05+00:00",
  "redacted_at": null,
  "expires_at": null,
  "created_at": "2026-10-17T15:03:41+00:00",
  "updated_at": "2026-10-17T15:04:05+00:00"
}
```

## Redact a payment method

`DELETE /v1/payment_methods/{token}`

Deletes the card for good: its number, any cached security code, its fingerprint and the cardholder's name, email, phone, billing address and metadata. The token stays, with status redacted, and keeps its brand, first six and last four digits, expiry and customer reference so transaction history still makes sense. It can no longer be charged.

- **Operation id:** `payment-methods.redact`
- **Required ability:** `payment_methods:redact`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | yes | The payment method's token. Example: `tok_01jaxqk0pz7r8w5m3n2b4c6d8e` |

#### Request

```bash
curl -X DELETE https://api.ordercard.io/v1/payment_methods/tok_01jaxqk0pz7r8w5m3n2b4c6d8e \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — The payment method, now redacted.

```json
{ "object": "payment_method", "token": "tok_01jaxqk0pz7r8w5m3n2b4c6d8e", "status": "redacted", "redacted_at": "2026-10-17T16:00:00+00:00", "...": "..." }
```

Source: https://docs.ordercard.io/api/payment-methods/index.mdx