The article includes some pointers on how clients can create and manage linked cards with shared balances. After reading, you should be able to understand:

Cardholder Creation without KYC
Cardholder Creation with KYC
How to retrieve Linked Accounts
How to retrieve Transactions and Authorizations for Linked Accounts
The expected funds flow for Linked Cards

Overview:

The Linked Account feature with our Card Issuing Product allows clients to create two or more cardholders that share a common balance. Shared balance cards allow for two separate and distinct cardholders to use separate cards with different card numbers to access funds from the same balance. The secondary card must be created using the primary card’s account ID to link them. One account ID may have multiple secondary cards linked to it, but a secondary card may not be the primary account for a new card creation.

Cardholder Creation without KYC

Create Primary Cardholder
1. POST Create Cardholder
  1. Linked Account ID = Blank
2. The response should return:
  1. Processor_reference - String - Reference to the account on the processors system
3. Use GET Get Account By Processor Reference to return & store:
  1. Account ID
Create Physical Card with Linked Balance
1. POST Create Cardholder
  1. Linked Account ID = Account ID returned above

Note: The primary cardholder created in step one can have a maximum of 5 cards linked to it. The secondary cardholder in step b cannot be used as the primary card in any other relationships. To create two different types of cards (Virtual vs Physical), the subprogram code can be different, but a default option is used if left blank.

Cardholder Creation with KYC

Initiate KYC for Primary Cardholder
1. POST Create Cardholder
  1. Linked Account ID = Blank

Once Initiated, the KYC review will be submitted. Some cases may be approved immediately, while others may need a manual doc verification review stage to authenticate them. Once authenticated, a cardholder will be created.

The response should return:

KYC Result ID
Use GET Get KYC Result By ID
1. When the KYC Is approved, then the Response will return: “Cardholder - Object - The cardholder created during this KYC Transaction.”
2. Receiving a response on a KYC entry may take days or weeks.
Using Cardholder ID, call GET Get Cardholder Details to return & store:
1. Account ID
Create Secondary Card with Linked Balance
1. POST Create Cardholder
  1. Linked Account ID = Account ID returned above

How to retrieve Linked Accounts

There are many permutations that a client can create in linking and associated accounts. Given the potential need for each client to have their own relationship between cards, the client is responsible for storing and managing the relationships between their primary and secondary card accounts. When the Get Cardholder Details endpoint is queried for a “secondary” cardholder ID, the response will return the primary account ID to confirm that the cardholder creation request was successful, but we do not provide any other endpoints to retrieve relationships.

How to return the primary account ID linked to the secondary account with the secondary Cardholder ID

Use GET Get Cardholder Details
1. Response will return the “Linked Account ID” if the Cardholder was created with a Linked Account ID value. The Linked Account ID reflects the Primary Account ID that shares the balance with this Cardholder’s Account.

Display the balance for the card

GET Get Account Balance
1. Use Account ID to return the settled and available balance

Note: This balance should be the same for any cards that are linked to the same primary card.

Display the transactions for the cards

GET Get Account Authorizations
1. Use account ID to return current authorizations created under that account
GET Get Account Transactions
1. Use account ID to return the current transactions and adjustments created under that account

Note: There are a few different things to note when retrieving transactions to populate a cardholder transaction history for example. There are a few types of transaction types:

Authorization - The first stage of a typical e-commerce or point of sale transaction. At time of purchase, an authorization hold is applied to the balance on the card and is reflected in real time with an authorization. Most of the time, an authorization will settle and the debit will become permanent; sometimes, however, the authorization will not settle in which case it will be ‘purged’ (or removed) based on standard rules at the processor. When the authorization is purged, the amount that was held for the settlement is released and credited back to the available balance.
Settlement - A settled transaction reflects a permanent debit to the card balance that can only be removed through a reversal or refund credit transaction. Settlements reflect a real-money movement with the network and occur through batch processing.
Adjustment - Value loads or applicable fees are examples of internal adjustments that are done to support the needs of the program. These adjustments typically have unique fee types to differentiate them from other acquiring transactions.

The expected funds flow for Linked Cards

There will be one shared balance that will be credited or debited by transactions on any of the linked accounts. Either the primary or the secondary account can receive credit transactions that increase the balance (ex. value loads or direct deposits); likewise, the cards associated to the primary and secondary accounts can be used to initiate debit transactions from the same funding source.

Presently, since both the primary and secondary accounts are linked to unique cardholders, each will be assigned a Direct Deposit Account and can receive incoming EFTs that credit the same balance, should DDAs be enabled on the program.