​
Physical vs Virtual Cards

Both physical and virtual cards are created and managed in the exact same manner; what differentiates the two and ultimately determines whether a physical card is issued is the Card Product used to issue the card. Card Products are configured for your specific card program by Treasury Prime and if virtual cards will be issued, a separate Card Product is created for this purpose. If you would like to issue a physical card that has a matching virtual representation of the card, you can expose the card details on the digital art you’ve created in your app. For more information see Exposing Card Details.

​
Issuing a Card

Card issuance is covered in-depth in our Issuing Cards guide.

​
Card Webhooks

When a new card is created, a webhook callback is made if you have subscribed to updates for card.create. Likewise, if a card is updated, the card.update webhook is called. The body of the webhook callback will contain information regarding the affected card.
Example Webhook Notification
{
  "event": "card.create",
  "op": "create",
  "url": "https://api.sandbox.treasuryprime.com/card/card_11hahfpjb18t7y",
  "id": "card_11hahfpjb18t7y"
}

​
Card Status

The below are the potential values for the card status:
StatusDescription
unactivatedDefault state assigned upon card creation.
activeCard is now active and ready for use.
suspendedCard has been frozen and is temporarily non-functional. A card can transition from active to suspended and back to active again. Refunds can still be completed while a card is suspended. Cards may be suspended through the API, often due to a customer request.
terminatedCard has been permanently deactivated by expiration or direct update of the card status. Cards in this status cannot be reactivated.

​
Printed Character Limits

Due to the limited space available for printing on a debit card, some Person object information may be truncated when personalizing a physical debit card. See the table below for the character limits on printed fields. These limits apply to all users who are issued a card.
FieldCharacter Limit
City18
Street Line 135
Street Line 235
Postal Code10
State2
Name (total of First + Middle + Last)21

​
Issuing a Replacement Card

If a card is lost, damaged, or nearing its expiration date, you can issue a replacement card by following the same steps used to issue any new debit card. Note that the new card will always be issued with a different PAN than the original card and it is not possible to re-issue a new card with the same PAN as any prior card.

​
Card Issuing Limits

By default, a Person can only have 10 cards in an active status at any given time (5 in the Developer Sandbox). This number is inclusive of both virtual and physical cards. If a person has reached their maximum allowed number of active cards, you will need to update the status of one or more existing cards prior to issuing or activating any additional cards for that person.
Note: It is possible to increase the card issuing limits with prior approval. Please contact your Treasury Prime Account Manager for more information.

​
Card Fulfillment and Delivery

​
Card Fulfillment Statuses

The below are the potential values for the card fulfillment status:
StatusDescription
issuedRequest to issue card has been received and will be sent to the card printer for production.
orderedThe card order has been produced and shipped. This is the terminal status for card fulfillment.
digitally_presentedThe card details have been digitally presented to the user by use of the show_pan value of the /card endpoint.
rejectedCard was rejected by card fulfillment provider.
shippedCard was shipped by card fulfillment provider. This field appears only if it is provided by the card fulfillment provider.

​
Shipping Address

Cards will always be shipped to the mailing_address listed on the Person object attached to the Card. If there is no mailing address present, it will ship to the physical_address.

​
Fulfillment Timelines

Printing a card takes between 1-3 business days from the time it is received by the card printer. The shipping delivery time is estimated from the time a cards’ fulfillment status transitions to ordered. Once this occurs, add on the number of days for the shipping option selected, and that is when you can expect your card to be delivered.

​
Cancelling Production of a Card

It is possible to cancel the request to issue a card as long as the card’s fulfillment status is issued. This is the initial fulfillment status that is set at the time of the card issuing request. Once the card status changes to ordered, the card has been sent to the printer for fulfillment and the process can no longer be stopped. To cancel the order for a card with a fulfillment status of issued, update the card object’s status property to terminated. Note that you cannot directly update the status in the fulfillment sub-object. Once terminated, the fulfillment status should not proceed to ordered.
Example
$ curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/card/card_zuhqnmz7e085 \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -d '{
          "status": "terminated"
        }'

​
Delivery Notifications

There is not currently a method of providing notifications for when a card has been delivered to the recipient.