---
updatedAt: 2026-08-27T18:50:47.000Z
agentTools:
  projectIndex: https://docs.moderntreasury.com/platform/llms.txt
---

# Cards

A card belongs to an [external account](https://docs.moderntreasury.com/platform/reference/external-account-object) and is used to push funds to a cardholder via push-to-card payments.

> 🚧 Send cardholder data only to `vault.moderntreasury.com`
>
> Card endpoints are not exposed on `app.moderntreasury.com`. All requests that carry cardholder data must be sent to `vault.moderntreasury.com`, which uses the same authentication, idempotency, and JSON conventions as the rest of the API.

| Attribute                          | Description                                                                                                               |
| :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |
| **id** *string*                    | Unique identifier for the card.                                                                                           |
| **pan** *string*                   | The card number (PAN). Write-only — not returned in API responses.                                                        |
| **cvv** *string*                   | Optional. The card verification value. Write-only — not returned in API responses.                                        |
| **external\_account\_id** *string* | The ID of the [External Account](https://docs.moderntreasury.com/platform/reference/external-account-object) this card belongs to.                                       |
| **expiration\_month** *string*     | Two-digit expiration month of the card (e.g. `"01"` through `"12"`).                                                      |
| **expiration\_year** *string*      | Four-digit expiration year of the card (e.g. `"2027"`).                                                                   |
| **first\_name** *string*           | The cardholder's first name.                                                                                              |
| **last\_name** *string*            | The cardholder's last name.                                                                                               |
| **billing\_address** *object*      | The cardholder's billing address. Contains `line1`, `line2`, `city`, `state`, `postal_code`, and `country`.               |
| **live\_mode** *boolean*           | This field will be `true` if this object was created with a production API key or `false` if created with a test API key. |
| **created\_at** *string*           | An ISO 8601 timestamp indicating when the card was created.                                                               |
| **updated\_at** *string*           | An ISO 8601 timestamp indicating when the card was last updated.                                                          |

A card can be created standalone via [Create Card](https://docs.moderntreasury.com/platform/reference/create-card), or alongside an external account via [Create External Account with Cardholder Data](https://docs.moderntreasury.com/platform/reference/create-external-account-with-cardholder-data).

```json Card Example
{
  "id": "85e8e06b-954b-42eb-8a25-ac409eef80ac",
  "object": "card",
  "external_account_id": "22c19f2f-14cf-4a17-b5d0-c6838e3eaeb3",
  "expiration_month": "12",
  "expiration_year": "2027",
  "first_name": "Jane",
  "last_name": "Smith",
  "billing_address": {
    "line1": "101 Main St",
    "line2": null,
    "city": "New York",
    "state": "NY",
    "postal_code": "07666",
    "country": "US"
  },
  "live_mode": true,
  "created_at": "2026-05-18T21:00:00.000Z",
  "updated_at": "2026-05-18T21:00:00.000Z"
}
```

## Testing cards in the sandbox

In test mode, the outcome of a push-to-card payment is controlled by the cardholder's `last_name`, not by the card number. Use any valid-format PAN (for example, `4111111111111111`) together with one of the last names below to simulate a specific result. Any last name not listed here results in a completed payment.

| Cardholder `last_name` | Payment outcome | `failure_reason`                     |
| :--------------------- | :-------------- | :----------------------------------- |
| `INVALID_CVV`          | Fails           | The CVV provided is invalid.         |
| `INVALID_PAN`          | Fails           | The card number provided is invalid. |
| `INSUFFICIENT_FUNDS`   | Fails           | The card has insufficient funds.     |
| Any other value        | Completes       | —                                    |