Debit Card Issuance Guide

Overview

Prime Issuance is a Prime Trust PrimeCore product that enables integrators to issue their own white label debit cards to their customers.

Card features include:

  • White label debit MasterCard available to United States residents
  • One card per tax ID per Organization
  • Account balance funded by cardholder’s custodial fiat account at Prime Trust
  • Default virtual cards with optional physical card provisioning (five to seven days for physical card delivery)
  • IVR and live support
  • Customized card options:
    • standard: custom background color and logo (two-week turnaround)
    • premium: custom artwork (four-to-six-week turnaround)

Prerequisites

You've contacted your Prime Trust account manager to complete your Prime Issuance setup process. Prime Trust has enabled the Card Issuance feature flag for your Organization’s sandbox environment. Once integration is complete, Prime Trust will enable issuance on production. You've completed the API setup process and have an integrator user account that can generate a JWT for API access. Your target customers for card issuance are based in the United States.

Decisions

Virtual or physical cards

If you want to issue physical cards, you can choose either the Standard or Custom package.

Standard package You can choose from seven card colors and add two logos to the card.

standard

Turn-around time is one week.

Primary and Secondary logos must be a .png file with a transparent background and a minimum size of 168 x 132 pixels (14mm x 11mm at 300 DPI).

Premium package

You can specify a custom design.

Turn-around time is six weeks (requires approval from the printer, bank, and card networks).

Custom design with the following specifications

  • Spec 1
  • Spec 2

iFrame Card Art

Option 1: Choose from standard card art.

Frame card art, simple design

iFrame card art, curved design

iFrame card art, pattern design

Option 2: Generate your own card art with the following specifications (if Premium package was selected this could be the same as the physical design): Spec 1: The minimum size for the card is 238 x 150 px at 72 DPI, but it can be scaled (proportionally or at @2x / @3x ) to any size to fit multiple devices.

Spec 1: The minimum size for the card is 238 x 150 px at 72 DPI, but it can be scaled (proportionally or at @2x / @3x ) to any size to fit multiple devices.

Submit wireframes of you web and mobile apps

Provide wireframes to Prime Trust support.

Integration steps

  1. Complete steps to provision a cardholder.
  2. Complete steps to verify the phone number and email address associated with the cardholder.
  • Optionally display the card to the cardholder.
  1. Optionally issue a physical card.
  2. Use the sandbox environment to test transactions.
  3. Once issued, you can view transactions and lock or unlock cards.

The following diagram shows the flow and API usage for card issuance.

Cardholder provisioning

Cardholder objects associate existing Prime Trust account and contact objects with the person to whom a debit card is issued. Cardholder objects hold the following data:

  • account-id - UUID associated with the cardholder’s Prime Trust account object
  • contact-id - UUID associated with the cardholder’s Prime Trust contact object
  • email - email address associated with the cardholder (can default to the Contact object email)
  • phone-number - phone number associated with the cardholder (can default to the Contact object phone number)
  • callback-url - optional

Cardholder restrictions:

  • Each cardholder has a verified custodial Account in Prime Trust
    • The cardholder has completed KYC requirements for the Account
    • Individual custodial accounts exist for each cardholder

Complete the following steps to provision a cardholder.

  1. Create a cardholder object using POST /v2/card-holders. Upon success, the system generates a cardholder object. After a cardholder is created, a cardholder verification object will be created automatically. An invitation email is sent out with the hash to access that cardholder verification object.
  2. Use GET /v2/card_holders/{card-holder-id}/sandbox in the sandbox environment to access the hash that will be found in the invitation email.

Cardholder verification

You can use either Card Issuance APIs or a pre-built Web UI for cardholder verification.

Cardholder verification using the APIs

Complete the following steps to verify cardholder phone number and email address. Use the card-holder-verification-id returned from the POST /v2/card-holders/ endpoint.

  1. Request email verification by using POST /v2/card-holder-verifications/[:card-holder-verification-id]/request-email-verification.
  2. Verify the email address by using POST /v2/card-holder-verifications/[:card-holder-verification-id]/verify-email. Pass in the email-otp number from the user.
  3. Request the text message with code by using POST /v2/card-holder-verifications/[:card-holder-verification-id]/request-phone-number-verification.
  4. Verify the phone-number by using POST /v2/card-holder-verifications/[:card-holder-verification-id]/verify-phone-number. Pass in the phone-number-otp number from the user. The final call returns a ‘card-display-token’ used for optionally displaying the card to the end-user.

Both verifications are now complete. Once completed, the cardholder verification object will be marked as fully verified and the virtual card will be issued.

The cardholder phone verification call provides a card-display-token used to display the card. The token is good for a one-time use. You can also call POST /v2/cards/resource-token to retrieve a new token.

The card-display-token is only returned when the cardholder verification is complete and you’ve opted to display the card to the end-user.

You can use the following iframe to display the card to the end user using the card-resource-token: https://<YOUR-PRIME-TRUST-ENVIRONMENT>/card-view?&resourceTokenHash=<card-display-token>

Testing verifications

The sandbox environment provides two GET methods to retrieve the email and phone codes:

  • Retrieve the email-otp number in the sandbox environment by using GET /v2/card-holder-verifications/[:card-holder-verification-id]/sandbox
  • Retrieve the phone-number-otp number in the sandbox environment by using GET /v2/card-holder-verifications/[:card-holder-verification-id]/sandbox

When testing, you can also verify the cardholder in the sandbox environment by calling PATCH /v2/card-holder-verifications/{hash}/sandbox with the following payload.

{
"data": {
"type": "card-holder-verifications",
"attributes": {
"phone-number-verified": true,
"email-verified": true
}
}
}

Cardholder verification using the web UI

You can enable a web interface to display the cardholder verification steps without directly using the API resources. Let your account manager know if you’d like to direct your end-users to a web page that enables the issuance flows.

Once a cardholder is provisioned, an email sent to the user contains a link to the web interface.

  1. The first verification step will ask the user to confirm their email address.
  2. The next verification step enables entry of the email confirmation.
  3. The web interface displays a confirmation message upon success.
  4. The next step asks for phone confirmation.
  5. The user enters the phone confirmation code. The web interface displays a confirmation message upon success. You can optionally display the card by requesting your account manager to enable this option.

Display the card

Once the card has been issued you can use our Card View widget (iFrame) to display the card to the cardholder.

The widget iframe can be bootstrapped onto your own website using a combination of adding a JavaScript tag to your website and calling a few JavaScript functions. These tools will then create an iframe that loads the widget.

Prime Trust makes available script code for Sandbox and Production environments.

<script type="text/javascript" src="https://bootstrapper.primetrust-cdn.com/bootstrap.js" defer></script> <script type="text/javascript" src="https://sandbox.bootstrapper.primetrust-cdn.com/bootstrap.js" defer></script>

You can place this script tag in your <head> or before your </body> tag. It's preferable to use the defer or async tag to make sure that it will not impact loading code.

Once you've included the script on your website, you'll need to create the code that will bootstrap this application and render the iframe.

The code will be available through the variables window.PrimeTrustEmbeds or window.pt.

If using Async loading, there will be a few options for listening for it to be ready.

window.onPrimeTrustEmbedsReady, and window.onBootstrapReady are specific to this library, while window.primeTrustReady will trigger when all Prime Trust scripts are finished loading (if you are using multiple options; otherwise it will run at the same time as the other two).

All can be set to a function, accepting one argument.

primeTrustReady uses the pt object (the combined object of all scripts), the other two use PrimeTrustEmbeds which is just the object from this script.

If the launched application is closed without completion (such as in using a modal and the user closes it), each launch function returns a function to remove the event listeners

Example script for card display widget iframe.

<script
type="text/javascript"
src="https://bootstrapper.primetrust-cdn.com/bootstrap.js"
defer
></script>
<script type="text/javascript">
console.log("[primetrust] 1. Loading Prime Trust Embedding API");
window.primeTrustReady = function (pt) {
console.log("[primetrust] 2. Loading embedded account creation...");
pt.launchCardView({
target: document.getElementById("main"),
// returned from `POST /v2/cards/{card-id}/resource-token`
token: "TOKEN",
//hideCardToggle optional, "true" hides the card details toggle switch
hideCardToggle: "true",
events: {
loaded: function () {
console.log("[primetrust] 3. Embedded company creation loaded!");
},
onDetailsShown: function (isShown) {
console.log(
"[primetrust] 4. Card Details have been: ",
isShown ? "shown" : "hidden"
);
},
},
});
// example functions to call with buttons
function onShowButtonClick() {
pt.showCardDetails();
}
function onHideButtonClick() {
pt.hideCardDetails();
}
function onCheckButtonClick() {
pt.checkCardDetailsVisible();
}
};
</script>

In the example script, the following functions are available:

  • showCardDetails, displays card details (if enabled)
  • hideCardDetails, hides card details (if enabled)
  • checkCardDetailsVisible, checks if the display of card details is enabled

Card management

Card objects represent the card used by cardholders to process debit transactions over the MasterCard network. Cards are by default issued as virtual but can also be issued as physical cards. Card objects hold the following data:

  • type: the object type, value “cards”
  • id: UUID for the card object generated by the system
  • activated-at: date-time card was activated
  • card-holder-id: UUID for the associated cardholder object
  • created-at: creation date-time for the object
  • issued-at: date-time the card was issued
  • last-four: last four digits of the card
  • name-on-card: name of the cardholder
  • physical-card-status: indicates the physical card status
    • available
    • ordered
    • received
  • shipped-at: date-time for when a physical card was shipped to the cardholder
  • status: card status; values can be
  • updated-at: date-time for when card information was last updated

Use the following endpoints to retrieve cards:

  • List card objects: GET /v2/cards
  • Retrieve a card object: GET /v2/cards/{card-id}

Physical card issuance

Cards are issued as virtual by default. If you want to request a physical card, use POST /v2/cards/{card-id}/request-physical.

Physical card activation

Physical cards can be activated using POST /v2/cards/:id/activate-physical. When performing sandbox testing, you can use the value 000000 for the activation code.

Lock and unlock cards

Use the following endpoints to manage cards:

  • Lock a card: POST /v2/cards/{card-id}/lock
  • Unlock a card: POST/ v2/cards/{card-id}/unlock

Reissue cards

Card reissue enables the customer to keep the existing card number and only updates the CVV and expiration for the card. Cards by default are automatically reissued three months before the card's expiry. Use POST /v2/cards/{card-id}/reissue to reissue.

Card transactions and testing

The card transaction object stores the following information:

  • type: object type, value of “cash-transactions”
  • id: UUID associated with the transaction object
  • card-id: UUID associated with the ‘card’ object
  • amount: USD amount of the transaction
  • type: transaction type, can be:
    • "authorization": pending state indicating that the cardholder can fund the transaction
    • "capture": processed state, indicates that the transaction has been approved for processing
  • description: description for the transaction

Complete these steps to test card transactions in the sandbox environment.

  1. Fund the account using POST /v2/accounts/{{accounts-id}}/sandbox/fund.
  2. Create an authorization transaction of $20 using POST /v2/card-transactions/sandbox.
  3. Update the transaction to capture using PATCH /v2/card-transactions/{card-transactions-id}/sandbox.

Card transaction settlement flow

Prime Issuance supports the following types of transaction states:

  • auth: a hold is placed on the account during authorization
  • capture: removes holds and take the money out of the custodial account
  • auth and capture: takes the money out of the custodial account
  • refund: refunds the money for a specific, previously captured transaction
  • auth reversal: removes the hold placed due to a previously received auth

Appendix A: Prime Issuance APIs overview

Prime Issuance makes available the following API resources for card issuance integration.

CardHolders resource

Creates and manages cardholder information (tied to existing account and contact objects).

Cardholder endpoints:

  • List card holders’ information based on Account, Contact, Cardholder Verification, or Cards: GET /v2/card-holders
  • Retrieve cardholder information for a given account-id and contact-id: POST /v2/card-holders
  • Retrieve cardholder information for a given card-holder-id: GET /v2/card-holders/{card-holder-id}
  • Retrieve a cardholder email and phone number for a given card-holder-id (sandbox): GET /v2/card-holders/{card-holder-id}/sandbox

Card Holder Verifications resource

Manages the cardholder verification process and provisions virtual cards at the completion of the verification process. For authenticated calls, you can use the verification-id from the Cardholder resource as the {hash} value for the following endpoints. Otherwise use a hash for non-authenticated calls.

Card Holder Verifications endpoints:

  • Retrieve verified email and phone numbers: GET/v2/card-holder-verifications/{hash}
  • Update verified email and phone number: PATCH/v2/card-holder-verifications/{hash}
  • Retrieve a cardholder verification object (sandbox): GET/v2/card-holder-verifications/{hash}/sandbox
  • Request an email verification: POST/v2/card-holder-verifications/{hash}/request-email-verification
  • Request verified email: POST/v2/card-holder-verifications/{hash}/verify-email
  • Request a phone number verification: POST/v2/card-holder-verifications/{hash}/request-phone-number-verification
  • Request verified phone number: POST/v2/card-holder-verifications/{hash}/verify-phone-number

Cards resource

Displays cards, locks and unlocks cards, and provisions physical cards.

Cards endpoints:

  • List card objects: GET /v2/cards
  • Retrieve a card object: GET /v2/cards/{card-id}
  • Issue physical card: /v2/cards/{card-id}/request-physical Lock a card: POST /v2/cards/{card-id}/lock`
  • Unlock a card: POST /v2/cards/{card-id}/unlock
  • Reissue physical card: POST /v2/cards/{card-id}/reissue
  • Activate physical card: POST /v2/cards/{card-id}/activate-physical
  • Sandbox update physical card status: POST /v2/cards/{card-id}/sandbox
  • Retrieve a card resource token used to display the card: POST /v2/cards/{card-id}/resource-token
  • Display a card (if enabled): GET /v2/cards/{hash}/display

Card Transactions resource

Sandbox transaction testing and retrieval of production transactions.

Card Transaction endpoints:

  • Process test transactions: POST/v2/card-transactions/sandbox
  • Update a test transaction: PATCH/v2/card-transactions/{card-transactions-id}/sandbox
  • List all card transaction objects: GET/v2/card-transactions
  • Retrieve card transaction objects for a single card: GET/v2/card-transactions/{card-transaction-id} Can retrieve the associated `card’ object, the ‘transaction’ object, or the ‘cardholder’ object
Last updated on