Skip to content
OrderCard

Payment methods

Vaulted cards, addressed by their token. Read, update, retain and redact them.

Updated View as Markdown

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, 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. 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.
Required ability
payment_methods:pan
Rate limit
300 requests/minute per API key

Body parameters

cardobjectrequired
The card itself.
card.numberstringrequired
Card number; spaces and dashes are ignored. Must pass the Luhn check.
Example: 4242 4242 4242 4242
card.exp_monthintegerrequired
1 to 12.
card.exp_yearintegerrequired
Four-digit year, not in the past.
card.cvvstringoptional
Kept encrypted for 15 minutes for the first customer-initiated charge, then deleted. Never stored.
billingobjectoptional
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_namestringoptional
Max 100 characters.
billing.last_namestringoptional
Max 100 characters.
billing.emailstringoptional
A valid email address. Stored trimmed and in lowercase.
billing.phonestringoptional
Max 32 characters.
billing.address_line1stringoptional
Max 255 characters.
billing.address_line2stringoptional
Max 255 characters.
billing.citystringoptional
Max 100 characters.
billing.statestringoptional
State or province, e.g. GA.
billing.postal_codestringoptional
Max 20 characters.
billing.countrystringoptional
Two-letter ISO country code.
Example: US
customerstringoptional
The customer this card belongs to, by OrderCard id. Send null to unlink. Send this or customer_reference, not both.
Example: cus_01jaxr9m4q7t0w3y6b9d2f5h8k
customer_referencestringoptional
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
metadataobjectoptional
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.
retainbooleanoptional
Keep the card until you redact it. Defaults to true; false makes a pending token that expires after 24 hours unless charged or retained.
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.
Requestbash
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"
  }'
201The vaulted card. The number itself is never returned.
{
  "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"
}
422The card is invalid.
{
  "error": {
    "code": "invalid_request",
    "message": "The card number is incorrect.",
    "errors": { "card.number": ["The card number is incorrect."] }
  }
}
403The key lacks payment_methods:pan.
{ "error": { "code": "forbidden", "message": "This action is unauthorized." } }

List payment methods

GET/v1/payment_methods
Lists the vaulted cards of the key's team and environment, newest first, with cursor pagination.
Required ability
payment_methods:read
Rate limit
300 requests/minute per API key

Query parameters

customerstringoptional
Only this customer's cards, by OrderCard id.
customer_referencestringoptional
Only the cards of the customer with this reference.
statusstringoptional
pending, retained or redacted.
limitintegeroptional
1 to 100, default 25.
cursorstringoptional
The meta.next_cursor of the previous page.
Requestbash
curl "https://api.ordercard.io/v1/payment_methods?customer=cus_01jaxr9m4q7t0w3y6b9d2f5h8k" \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
200A page of payment methods.
{
  "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.
Required ability
payment_methods:read
Rate limit
300 requests/minute per API key

Path parameters

tokenstringrequired
The payment method's token.
Example: tok_01jaxqk0pz7r8w5m3n2b4c6d8e
Requestbash
curl https://api.ordercard.io/v1/payment_methods/tok_01jaxqk0pz7r8w5m3n2b4c6d8e \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
200The payment method.
{
  "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"
}
404No such token for this key.
{ "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.
Required ability
payment_methods:write
Rate limit
300 requests/minute per API key

Path parameters

tokenstringrequired
The payment method's token.
Example: tok_01jaxqk0pz7r8w5m3n2b4c6d8e

Body parameters

exp_monthintegeroptional
Send together with exp_year.
exp_yearintegeroptional
Send together with exp_month. Not in the past.
billingobjectoptional
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_namestringoptional
Max 100 characters.
billing.last_namestringoptional
Max 100 characters.
billing.emailstringoptional
A valid email address. Stored trimmed and in lowercase.
billing.phonestringoptional
Max 32 characters.
billing.address_line1stringoptional
Max 255 characters.
billing.address_line2stringoptional
Max 255 characters.
billing.citystringoptional
Max 100 characters.
billing.statestringoptional
State or province, e.g. GA.
billing.postal_codestringoptional
Max 20 characters.
billing.countrystringoptional
Two-letter ISO country code.
Example: US
customerstringoptional
The customer this card belongs to, by OrderCard id. Send null to unlink. Send this or customer_reference, not both.
Example: cus_01jaxr9m4q7t0w3y6b9d2f5h8k
customer_referencestringoptional
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
metadataobjectoptional
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.
Requestbash
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" } }'
200The updated payment method.
{
  "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"
}
409The card was redacted.
{ "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.
Required ability
payment_methods:write
Rate limit
300 requests/minute per API key

Path parameters

tokenstringrequired
The payment method's token.
Example: tok_01jaxqk0pz7r8w5m3n2b4c6d8e

Body parameters

customerstringoptional
Link the card to this customer, by OrderCard id.
customer_referencestringoptional
Link the card to the customer with this reference of yours, created the first time.
Requestbash
curl -X POST https://api.ordercard.io/v1/payment_methods/tok_01jaxqk0pz7r8w5m3n2b4c6d8e/retain \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
200The payment method, now retained.
{
  "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.
Required ability
payment_methods:redact
Rate limit
300 requests/minute per API key

Path parameters

tokenstringrequired
The payment method's token.
Example: tok_01jaxqk0pz7r8w5m3n2b4c6d8e
Requestbash
curl -X DELETE https://api.ordercard.io/v1/payment_methods/tok_01jaxqk0pz7r8w5m3n2b4c6d8e \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
200The payment method, now redacted.
{ "object": "payment_method", "token": "tok_01jaxqk0pz7r8w5m3n2b4c6d8e", "status": "redacted", "redacted_at": "2026-10-17T16:00:00+00:00", "...": "..." }
Navigation

Type to search…

↑↓ navigate↵ selectEsc close