Card Issuing and Fulfillment
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_event.create
. Likewise, if a card is updated, the card_event.update
webhook is called. The body of the webhook callback will contain information regarding the affected card.
Example Webhook Notification
{
"event": "card_event.create",
"op": "create",
"url": "https://api.sandbox.treasuryprime.com/card_event/cnm_11hahfpjb18t7y",
"id": "cnm_11hahfpjb18t7y"
}
Card Status
The below are the potential values for the card status:
Status | Description |
---|---|
unactivated | Default state assigned upon card creation. |
active | Card is now active and ready for use. |
suspended | Card 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. |
terminated | Card 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.
Field | Character Limit |
---|---|
City | 18 |
Street Line 1 | 35 |
Street Line 2 | 35 |
Postal Code | 10 |
State | 2 |
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:
Status | Description |
---|---|
issued | Request to issue card has been received and will be sent to the card printer for production. |
ordered | The card order has been produced and shipped. This is the terminal status for card fulfillment. |
digitally_presented | The card details have been digitally presented to the user by use of the show_pan value of the /card endpoint. |
rejected | Card was rejected by card fulfillment provider. |
shipped | Card 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.
Updated about 2 months ago