Issuing a Card

Cards provide a mechanism to easily conduct transactions with merchants both online and in-person. Using our API, the entire card lifecycle—from issuing, to activation, to deactivation—can be managed programmatically. With the ability to issue virtual cards, you can get to market quickly while providing incredible digital experiences for your customers.

This guide uses the following endpoints

1. Get the Account ID

Before you can issue a card, you will need to obtain the id for the account that the card will be issued against. This can be accomplished by making a GET request to the account endpoint.

curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/account

This returns a list of of Account objects. Select the id for the account that the card will be issued against.

{
  "data": [
    {
      "account_type": "savings",
      "bank_id": "bank_treasuryprime",
      "updated_at": "2021-02-01T16:32:34Z",
      "currency": null,
      "routing_number": "000000000",
      "account_number": "123000012345",
      "id": "acct_qda4pJZfpzn4fc",
      "created_at": "2021-01-13T15:05:14Z",
      "userdata": null
    },
    {
      "account_type": "checking",
      "bank_id": "bank_treasuryprime",
      "updated_at": "2021-02-01T16:32:34Z",
      "currency": null,
      "routing_number": "000000000",
      "account_number": "123000067890",
      "id": "acct_wVwR87rxhMRdwD",
      "created_at": "2021-01-13T15:05:13Z",
      "userdata": null
    }
  ],
  "total_estimated": 10
}

2. Get the Card Product ID

Individual cards (both physical and virtual) are based on a what is known as a card product. Card products act much like templates. They contain all of the program settings, customizations, and behaviors for the cards that you issue (including whether the card are physical or virtual).

In general, Card Products will be configured by Treasury Prime when you set up your card program. The cardproduct endpoint is available for reference purposes, but will not allow you to directly configure a card product at this time.

To obtain the id for the card product that the card will be modeled after, make a GET request to the cardproduct endpoint.

curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/cardproduct

This returns a list of Card Product objects. Select the id for the card product that the card will be modeled after.

{
  "data": [
    {
      "created_at": "2021-02-09T18:58:31Z",
      "updated_at": "2021-02-09T18:58:31Z",
      "card_back_image_file_id": null,
      "type": "virtual",
      "card_front_image_file_id": null,
      "status": "active",
      "id": "cdpt_xjwj391iu6rv",
      "userdata": null
    },
    {
      "created_at": "2021-02-02T21:31:14Z",
      "updated_at": "2021-02-02T21:31:14Z",
      "card_back_image_file_id": null,
      "type": "virtual",
      "card_front_image_file_id": null,
      "status": "active",
      "id": "cdpt_b7z5bfb0my2u",
      "userdata": null
    }
  ],
  "total_estimated": 10
}

3. Get the Person ID

Cards are issued against accounts, but they also need to be tied to a specific person. To specify the person this card will be issued to, we need to obtain their Person ID.

The first step in acquiring the Person ID is to make a GET request to the accounts endpoint, passing in the ID (shown here as :id) of the account that this card will be issued against (which was retrieved earlier in this exercise).

curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/account/:id

The response data includes two properties from which you can obtain the Person ID. The first is primary_person_id which contains the Person ID of the primary account holder. The second is person_ids which contains an Array of Person IDs representing each of the listed owners for this account.

{
  "address": {
    "street_line_1": "8 Lowsy Lane",
    "street_line_2": null,
    "city": "Seattle",
    "state": "WA",
    "postal_code": "98102"
  },
  "account_type": "checking",
  "bank_id": "bank_treasuryprime",
  "person_ids": ["psn_exae5qrzrnp4"],
  "available_balance": "4991.00",
  "name": "Bob Iger",
  "updated_at": "2021-02-11T20:24:38Z",
  "currency": "USD",
  "routing_number": "000000000",
  "status": "open",
  "primary_person_id": "psn_u8rky8gm8i3h",
  "account_number": "723500012345",
  "locked": false,
  "id": "acct_go719z39lg9k",
  "funded": false,
  "business_ids": [],
  "current_balance": "4991.00",
  "created_at": "2021-02-11T20:07:29Z",
  "userdata": null
}

4. Issue the Card

Now that you have collected the Account ID, Card Product ID, and Person ID, it's time to issue the card!

In production, this will result in a card being issued to the specified account and user; however, physical issuance of a card has been disabled in the Developer Sandbox for testing purposes.

To issue the card, make a POST request to the card endpoint, passing along the account_id, card_product_id, and person_id.

You may also include optional creation_options sub-object with name_line_two text to be printed under the cardholder name, up to a maximum of 21 characters.

curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/card \\
    -H 'Content-Type: application/json' \\
    -d '{
          "account_id": "acct_v1p3ay8w4b0x",
          "card_product_id": "cdpt_5merj00eudnp",
          "person_id": "psn_xjwj391iu6rv",
          "creation_options": {
            "name_line_two": "Founder & CEO"
          }
        }'

A successful response will return a Card object with the data for the newly created card. Note that at this point, the card status is set to "unactivated". Before transactions can be made with this card, the card will need to be activated, which we will cover in the next section.

{
  "cvv": null,
  "account_id": "acct_wVwR87rxhMRdwD",
  "pan": null,
  "expiration": "0225",
  "person_id": "psn_01d6y044p21s",
  "last4": "3385",
  "card_product_id": "cdpt_14nk2w1k2a52",
  "updated_at": "2021-02-19T20:42:41Z",
  "status": "unactivated",
  "fulfillment": {
    "status": "shipped"
  },
  "id": "card_11g308p0hn4b",
  "pin_is_set": false,
  "created_at": "2021-02-19T20:42:40Z",
  "userdata": null
}

Reissuing an Existing Card

If you'd like to reissue a card with the same PAN and pin number, but a new CVV and expiration date you can use the optional reissue_pan_from_card_id field and input an existing card object when creating a card.

{% alert severity="warning" %} Reissuing a card is a great option when a card may be damaged or about to expire. If a card has been compromised, lost, or stolen it is best to create an entirely new card and PAN. {% /alert %}

curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/card \\
    -H 'Content-Type: application/json' \\
    -d '{
          "account_id": "acct_v1p3ay8w4b0x",
          "card_product_id": "cdpt_5merj00eudnp",
          "person_id": "psn_xjwj391iu6rv",
          "creation_options": {
            "name_line_two": "Founder & CEO"
          },
          "reissue_pan_from_card_id": "card_104"
        }'

5. Activate the Card

The final step in the card issuance process is card activation. To accomplish this, make a PATCH request to the card endpoint passing the id of the card to be updated, and set the status property to "active" in the request body.

curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/card/card_zuhqnmz7e085 \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -d '{
          "status": "active"
        }'