Add a Card to An External Account

📘
All card data must be transmitted through Modern Treasury's API via the subdomain vault.moderntreasury.com

Overview

A card is an object that is added to an External Account in Modern Treasury. That is because, in a push-to-card payment, the card is the recipient of the funds, just like an External Account.

There are two ways to add a card to an External Account:

Create an External Account first and then add a card to it later
Create the card inline when creating the External Account

  "party_name": "John Smith",
  "account_type": "other",
  "counterparty_id": "f47a9c31-8e5d-4b62-a19f-3d76c8e42f0a",
  "party_type": "individual",
  "card": {
    "pan": "4111111111111111",
	  "expiration_month": "02",
	  "expiration_year": "2029",
	  "cvv": "",
	  "first_name": "John",
	  "last_name": "Smith",
	  "billing_address": {
	    "line1": "555 Other Street",
	    "line2": "Suite 4A",
	    "city": "San Francisco",
	    "state": "CA",
	    "postal_code": "11111",
	    "country": "US"

An External Account that will receive push-to-card payments must have a card object. It can also store bank account info, but that will not be used for the push-to-card payment.

📘
Once card data is submitted, it is not retrievable from Modern Treasury's API.

Before making requests, you will need your API Key and Organization ID. To find these, you can follow this guide: Retrieve your API Key. You will also need to create a Counterparty first.

Add a card to an existing External Account

Retrieve your External Account ID:

There are three ways to retrieve an External Account ID:

You can retrieve the External Account ID in the response payload after creation.
You can also retrieve a single External Account ID from the Dashboard, by navigating to the External Accounts page.
Lastly, you can list all External Accounts via the API to find the ID you are looking for.

curl --request GET \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/external_accounts

{
    "id": "a3f2c891-6d4b-4e7a-9c15-8b3f2e6a91d4",
    "object": "external_account",
    "live_mode": true,
    "account_type": "other",
    "party_name": "John Smith",
    "party_type": "individual",
    "party_address": {
        "id": "894eaa50-3d32-408d-b451-95894f4c9e28",
        "object": "address",
        "live_mode": true,
        "line1": "123 Main Street",
        "line2": null,
        "locality": "San Francisco",
        "region": "CA",
        "postal_code": "11111",
        "country": "US",
        "created_at": "2026-08-05T16:59:52Z",
        "updated_at": "2026-08-05T16:59:52Z"
    },
    "account_details": [],
    "routing_details": [],
    "name": null,
    "metadata": {},
    "verification_status": "unverified",
    "verification_source": null,
    "external_id": null,
    "contact_details": [
        {
            "id": "5207b3aa-733d-48ae-afc2-229cba2bcd8c",
            "object": "contact_detail",
            "live_mode": true,
            "contact_identifier": "[email protected]",
            "contact_identifier_type": "email",
            "discarded_at": null,
            "created_at": "2026-08-17T16:21:43Z",
            "updated_at": "2026-08-17T16:21:43Z"
        }
    ],
    "ledger_account_id": null,
    "counterparty_id": "f47a9c31-8e5d-4b62-a19f-3d76c8e42f0a",
    "discarded_at": null,
    "created_at": "2026-08-17T16:21:43Z",
    "updated_at": "2026-08-17T16:21:43Z"
}

Add a card to your External Account:

Using the External Account ID from the prior step in the URL, add a card object.
The address should be the card's billing address, the name should be the cardholder's name, and the CVV is optional.

Each External Account can only have one card. To replace an expired card, see the delete card section.

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://vault.moderntreasury.com/api/external_accounts/a3f2c891-6d4b-4e7a-9c15-8b3f2e6a91d4/cards \
  -H 'Content-Type: application/json' \
  -d '{
  "pan": "4111111111111111",
  "expiration_month": "02",
  "expiration_year": "2029",
  "cvv": "",
  "first_name": "John",
  "last_name": "Smith",
  "billing_address":{
    "line1": "555 Other Street",
    "line2": "",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "11111",
    "country": "US"
  }
}'

{
    "id": "5e93c274-8a1b-7d42-b3f6-91c4e7a58d2f",
    "object": "card",
    "live_mode": true,
    "billing_address": {
        "line1": "555 Other Street",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "11111",
        "country": "US",
        "line2": ""
    },
    "first_name": "John",
    "last_name": "Smith",
    "external_account_id": "a3f2c891-6d4b-4e7a-9c15-8b3f2e6a91d4",
    "created_at": "2026-08-17T16:39:56Z",
    "updated_at": "2026-08-17T16:39:56Z"
}

Create an External Account with an embedded card

You can also create the card directly when creating the External Account. Instead of calling the base External Account URL at app.moderntreasury.com/api/external_accounts, you will call vault.moderntreasury.com/api/external_accounts.

The card's address should be the billing address, the name should be the cardholder's name, and the cvv is optional.

Each External Account can only have one card. To replace an expired card, see the delete card section.

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://vault.moderntreasury.com/api/external_accounts \
  -H 'Content-Type: application/json' \
  -d '{
  "party_name": "John Smith",
  "account_type": "other",
  "counterparty_id": "f47a9c31-8e5d-4b62-a19f-3d76c8e42f0a",
  "party_type": "individual",
  "card": {
    "pan": "4111111111111111",
	  "expiration_month": "02",
	  "expiration_year": "2029",
	  "cvv": "",
	  "first_name": "John",
	  "last_name": "Smith",
	  "billing_address": {
	    "line1": "555 Other Street",
	    "line2": "",
	    "city": "San Francisco",
	    "state": "CA",
	    "postal_code": "11111",
	    "country": "US"
      }
}
}'

{
    "id": "a3f2c891-6d4b-4e7a-9c15-8b3f2e6a91d4",
    "object": "external_account",
    "live_mode": true,
    "account_type": "other",
    "party_name": "John Smith",
    "party_type": "individual",
    "party_address": null,
    "account_details": [],
    "routing_details": [],
    "name": null,
    "metadata": {},
    "verification_status": "unverified",
    "verification_source": null,
    "external_id": null,
    "contact_details": [
        {
            "id": "6c2f8b41-9d3e-47a5-b81c-e5a942f7d360",
            "object": "contact_detail",
            "live_mode": true,
            "contact_identifier": "[email protected]",
            "contact_identifier_type": "email",
            "discarded_at": null,
            "created_at": "2026-08-17T17:06:17Z",
            "updated_at": "2026-08-17T17:06:17Z"
        }
    ],
    "ledger_account_id": null,
    "counterparty_id": "f47a9c31-8e5d-4b62-a19f-3d76c8e42f0a",
    "discarded_at": null,
    "created_at": "2026-08-17T17:06:17Z",
    "updated_at": "2026-08-17T17:06:17Z",
    "card_id": "5e93c274-8a1b-7d42-b3f6-91c4e7a58d2f"
}