---
title: "Register a Card"
method: POST
path: "/payments/cards"
tags: ["Payments", "Card Account Updates"]
---

# Register a Card

`POST /payments/cards`

## Request

- Base URL: `https://api.evervault.com`
- URL: `https://api.evervault.com/payments/cards`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/evervault/apis/evervault-api/docs/payments/cards/post.ts> (a function with typed inputs; its response is checked against the schema)

When registering a card, you can provide either an Evervault encrypted card number or a plaintext card number. If you provide a plaintext card number it will be encrypted and the encrypted value will be returned in the response.

Card registration is idempotent on card number. Registering the same card number a second time returns the existing Card object, rather than creating a new one. This means you can use the Card object `id` as a unique identifier. If you register an existing card number but with a different expiry date, the existing Card object is updated with the new date, and Evervault returns a `200 OK` response. A `201 Created` response indicates that a new Card object was created.

## Request body

- object
  - `number` string, required: The card number. This should be a valid Evervault encrypted card number or a valid plaintext card number.
  - `expiry` CardExpiry, required: The card expiry date.
    - `month` string, required: The card expiry month, in MM format (e.g. 12 for December)
    - `year` string, required: The card expiry year, in YY format (e.g. 29 for 2029)
  - `externalCustomerReference` string: An optional reference of your choice, such as a correlation ID, that is attached to the request. The reference will be visible in your logs. Must be between 1 and 255 characters.

## Response `200`

Returns an existing Card object. If the card number is already registered but with a different expiry date, the date is updated to the value in the request before the Card object is returned.

- Card
  - `id` string: The unique identifier for the card.
  - `number` string, required: The Evervault encrypted card number. This can be decrypted using Relay decryption or using a function.
  - `expiry` CardExpiry: The card expiry date.
    - `month` string, required: The card expiry month, in MM format (e.g. 12 for December)
    - `year` string, required: The card expiry year, in YY format (e.g. 29 for 2029)
  - `bin` string, required: The first 6 or 8 digits of the card number.
  - `lastFour` string, required: The last 4 digits of the card number.
  - `brand` 'visa' | 'mastercard' | 'american-express' | 'discover' | 'diners-club' | 'jcb' | 'unionpay': The card brand associated with the payment card.
  - `funding` 'debit' | 'credit' | 'prepaid' | 'deferred-debit' | 'charge': The card funding type specifies the method by which transactions are financed.
  - `segment` 'consumer' | 'commercial' | 'business' | 'government' | 'payouts' | 'all': The card segment indicates the primary market or usage category of the card.
  - `country` string, iso-3166-1-alpha-2: The country where the card was issued.
  - `currency` string, iso-4217-alphabetic: The currency of the card.
  - `issuer` string: The name of the card issuer.
  - `status` 'active' | 'replaced' | 'closed' | 'invalid': The current status of the card.
  - `replacement` string, nullable: The ID of the replacement card. This field is only present if the card has been replaced.
  - `automaticUpdates` 'enabled' | 'issuer-not-enrolled' | 'disabled': The status of Card Account Updater on this card. Evervault currently supports Card Account Updates for Visa, Mastercard and American Express cards.
  - `createdAt` integer, required: The Unix timestamp of when the card was created.
  - `updatedAt` integer, nullable: The Unix timestamp of when the card was last updated.

## Other responses

- `201`: Returns a new Card object.

## Changes

- **2026-11-06** `8d0ca833fa04`: 3 info
  - added the new optional request property `externalCustomerReference`
  - removed the `cardholder-opted-out` enum value from the `automaticUpdates` response property for the response status `200`
  - removed the `cardholder-opted-out` enum value from the `automaticUpdates` response property for the response status `201`
- **2026-04-17** `5e1eb58d42d5`: 4 info
  - the `country` response's property pattern `^[a-z]{2}$` was removed for the status `200`
  - the `country` response's property pattern `^[a-z]{2}$` was removed for the status `201`
  - the `currency` response's property pattern `^[a-z]{3}$` was removed for the status `200`
  - the `currency` response's property pattern `^[a-z]{3}$` was removed for the status `201`
- **2025-11-18** `30ea25af4354`: 3 info
  - api tag `Card Account Updates` added
  - api tag `Payments` added
  - api tag `payments` removed
- **2025-06-23** `c3d154b940fb`: 1 info
  - api operation id `createCard` removed and replaced with `registerCard`

[Operation history](https://skmtc.dev/evervault/apis/evervault-api/changes/payments/cards/post.md)

---

[API](https://skmtc.dev/evervault/apis/evervault-api.md) - [All operations](https://skmtc.dev/evervault/apis/evervault-api/llms.txt) - [OpenAPI document](https://skmtc.dev/evervault/apis/evervault-api/revisions/8d0ca833fa04?raw)