Card Management

There are a number of scenarios which may require you to take additional actions on a specific card after it has been issued to a cardholder including activation, renewal, suspension, and termination. Each of these scenarios is outlined below with accompanying examples.

Activating a Card

Before a card can be used for the first time, it will need to be activated.
This can be accomplished by updating the card's status to active. Optionally,
a PIN number can also be set for the card at this time by passing a pin value in the JSON body of the request.

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": "active",
        "pin": "1234"
      }'

Physical Card Activation Best Practices

While it is ultimately up to you to determine the best method for verifying card information prior to activation, it is best practice to require the cardholder to enter their physical card details within your application UI before activating the card. This helps to prevent fraudulent transactions in the event that the card is intercepted by another party before reaching the cardholder.

Suspending a Card

To temporarily prevent a card from making any additional transactions, you can update its status to suspended. Any authorizations received while a card is suspended will be denied; however, refunds will still be processed. Cards that have been suspended can be reactivated by setting their status back to active.

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": "suspended"
      }'

Terminating a Card

To permanently disable a card, update its status to terminated. Once a card has been terminated, it cannot be reactivated, and all future transactions will be denied.

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"
      }'

Setting a PIN

A four digit PIN can be set for a card by updating the pin value. Once the PIN has been set, the value of the pin_is_set property of the Card object will be changed to true. This same method can be used to update an existing PIN.

Example

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

Renewing an Expired Card or Issuing a Replacement Card

If a card is nearing its expiration date or has been damaged and requires replacement, you will need to submit a request to issue a new card. Cards may not be renewed beyond their original listed expiration.

Replacement Best Practices

When the date is approaching the expiration listed on a card, it is best practice to proactively issue a new card to the cardholder.

When the cardholder receives a new card, you can allow the user to activate it through your app UI before terminating the expiring card. This ensures that the user has continued debit card access to their account.

Note that it is not possible to issue a new card with the same PAN as a previously issued card.

Lost or Stolen Cards

If a cardholder reports a card as lost or stolen, it is recommended you set the card's status to suspended, temporarily preventing any further transactions from being approved. Alternatively, a card can be terminated to permanently prevent any future transactions from being made on the original card. If desired, a new card can then be issued.

Exposing Card Details

Card details such as PAN and CVV are highly sensitive and should be treated with great care. By default, both the pan and cvv in the card object fields will return a value of null. If you need to retrieve or display this information, you have two options: retrieving the PAN and CVV; or using the Marqeta.js widget.

Retrieving the PAN and CVV

In order to maintain security and legal compliance, full PAN and CVV values are not available by default via the API. If you need to retrieve the full PAN and CVV values to present them to users of your application, you will first need to provide proof of PCI compliance. Contact your Treasury Prime Account Manager to learn more about how to have this permission granted for your account.

Once enabled, you can then retrieve the pan and cvv values by making a request to /card/:id and passing values of “true” for show_pan and show_cvv in the query string parameters.

Example

curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/card/card_zuhqnmz7e085?show_pan=true&show_cvv=true

Using the Marqeta.js Widget

To eliminate the burden of proving PCI compliance, you can use the Marqeta.js JavaScript library to present full PAN and CVV details to your users. This library injects iframes into your webpage or application allowing you to display this information to your end users without requiring you to store sensitive data on your servers. Marqeta is fully PCI-Level 1 compliant, and the widget can be styled to match the look and feel of your application.

More information on the implementation of the Marqeta.js widget can be found at: https://www.marqeta.com/docs/developer-guides/using-marqeta-js
The use of this library requires that a token be generated by the API. Information on this topic is outlined here.

Card Management Methods

Card activation, suspension, and termination are performed using the Treasury Prime API. Alternative methods of of customer card management, such as Interactive Voice Response, are not supported at this time.