Personal Cards

Cards are an important part of many FinTechs’ business with their customers. They come in many varieties: physical or virtual, debit or credit, and in multiple different products that define the card’s use: transaction limits, when fees are charged, rewards programs, and so on.

The Cards API creates and manages cards for your customers over the entire life of a card, from issuing a card through card activation, management, and termination.

A Card’s Life

A card handled in the Synctera platform has many parts of its life:

Requesting card issuance, when a FinTech presents a card issuance request for a customer who’s passed Know Your Customer (KYC), an account belonging to the customer, and a card type the customer has asked for. This request goes to Synctera’s card vendor, who will issue the specified card. Note that each account is limited to a single physical card and up to nine active virtual cards. Refer to Issue Card
Presenting the card to the customer, when the customer gets a physical card delivered to them, or information about the card is digitally presented to the customer through a secure channel.
Activating the card, which happens automatically for a virtual card. A physical card requires the customer to give the FinTech information to show that they received the card. The FinTech passes that information through Synctera to our card vendor to activate the card so the customer can start using the card. The customer also sets a personal identification number (PIN) for the card to complete activation.
Monitoring the card, when the FinTech is alerted for any irregularities in card use.
Managing the card, when the FinTech responds to customer activity, requests, and inquiries, and to any security alerts that come back through monitoring. The Fintech makes changes to the card data and status when appropriate.
Reissuing the card, when a new card is issued due to expiration, card damage, loss, card theft, or other situation, and the FinTech requests a new card to replace it. The existing card is either immediately terminated or terminated when the new card is activated, depending on the reissuance reason.
Suspending the card, when suspicious activity has been identified, but not confirmed as fraud; when the customer reports their card as lost but requests additional time to attempt to locate their card; or other situations that warrant temporarily blocking use of the card.
Terminating the card, when the customer asks to close the card account or when card misuse or theft mandates account termination with no replacement request. The FinTech disables the card.

The Cards API endpoints handle the card as it moves through these stages.

%%{init: {"fontFamily": "sans-serif"}}%%
stateDiagram-v2
    request : Request card
    physical : Physical card
    virtual : Virtual card
    deliver : Deliver to customer
    present : Present digitally<br>to customer
    activate : Activate card
    monitor : Monitor card
    manage : Manage card
    reissue : Reissue card
    suspend : Suspend card
    terminate : Terminate card
    request --> physical
    request --> virtual
	virtual --> present
	physical --> deliver
	deliver --> activate
	present --> monitor
	activate --> monitor
	monitor --> manage
	manage --> reissue
	manage --> suspend
	manage --> terminate

Card Activation Methods

There are 3 methods for activating cards:

Activation widget.
POST /cards/activate request with a barcode. Refer to Activate Card
PATCH /cards/{card_id} request . Refer to Update Card

Typically upon activating a card the user should be prompted to set a PIN on the card. Even virtual cards when used with digital wallets can be prompted for a PIN at a merchant POS.
If no PIN is set on a card and a merchant POS requests a PIN, the purchase will be impossible to complete successfully.

Activation Widget

For cards that have the full PAN and CVV printed on them, the customer who receives the card logs into the FinTech app (which uses our widgets described below), selects the option to activate a card, and enters those values to prove that they received the card. These values go to Synctera’s card vendor for card activation.

Barcode Activation

For cards that don’t have the PAN and CVV printed on them (or just have a partial PAN), the card issuer generates a unique barcode value for the card and gives that value to the card fulfillment vendor printing the card. The card printer encodes the barcode string into a code 128 barcode printed on the card or card carrier.

The customer receiving the card uses the FinTech app’s section for card activation and scans the barcode. The FinTech converts the barcode back into the string and sends that to the POST /cards/activate endpoint which authenticates card activation through our card vendor.

PATCH Request

Depending on the risk appetite and alternative means of verifying the cardholder has the card in hand, integrators can optionally choose to activate cards using the PATCH /cards/{card_id} endpoint.

This doesn't require any proof that the customer has the card in hand, so it's up to the integrator to perform any required due diligence to verify and authenticate the user.

Handling Sensitive Card Information

Some card data such as the PAN, CVV, expiration date (EXP) and PIN are sensitive and should be guarded from exposure to anyone except the authorized card holder. This data is exposed not only during card activation, but over the life of the card when the card customer wants to view their card data.

To secure sensitive card information, the Payment Card Industry (PCI) Data Security Standard defines steps that must be followed when sending and receiving sensitive information. Your sponsor bank and credit card network require PCI compliance in your application when you handle card business with customers. Getting PCI compliance certification is an involved and expensive process.

To provide PCI compliance without you having to go through the compliance process, we provide pre-built widgets and a library that are certified PCI-compliant. These widgets and the library are created by our card vendor, adapted by Synctera to work in our platform, and run within your application to send and receive sensitive data directly between your application and our card vendor.

If you are PCI-certified, we also provide direct API access to manage your customers PIN. When your fintech onboards with Synctera, access to the API will be granted upon confirmation of your PCI-certification.

Initial Card Setup–

Synctera provides two PCI-compliant widgets that let your customers activate cards and set up an initial PIN:

The Activate Card Widget collects the PAN and CVV from your customer when they activate a card and then securely sends those values to our card vendor. The widget then asks the customer to set a PIN, which it also sends to the card vendor.
The Set PIN Widget lets a customer set a card’s PIN and then securely transmits it to our card vendor. This is useful for a barcode-activated card or when a customer wants to reset a PIN.

These widgets each display within an HTML iframe element and connect to the card vendor using a single-use token granted for each transaction.

If you are PCI-certified the Card PIN API can be used to manage your customer PIN directly.

Displaying Sensitive Card Data

Once a card is active, your customers will want to view information about their cards that includes sensitive card data such as the PAN and CVV. See the Card Widgets guide for more details.

Resetting PIN Tries

If someone incorrectly enters a card’s PIN too many times in a short time period (typically at an ATM or point-of-sale device), our card vendor suspends the card. The card status is set to SUSPENDED, and the card owner will most likely contact your FinTech for assistance.

There are several courses of action to take if this occurs:

If you determine that fraud occurred on the card, you should reissue the card. This resets the PIN tries on the new card.
If the customer has forgotten their PIN, they can reset it using the PIN widget in your app. You must update the status of the card from SUSPENDED to ACTIVE so your customer can use the card again.
If the customer remembers their PIN correctly, then you update the status of the card from SUSPENDED to ACTIVE so the customer can use the card again.

Note that you can handle status update and card reissuance through the Synctera dashboard if a customer service rep is working with the customer, or you can handle it through the Cards API endpoints if you have your own customer service mechanisms.

Card Reissuance Scenarios

A card may be reissued for many reasons. The card may have expired, the name on the card may need to be changed, or a physical card may be lost or stolen. Each of these scenarios is handled a bit differently to provide the best transition from the existing card to its replacement. These reissuance reasons are defined in the Cards API when you request issuing a replacement card:

EXPIRATION: A card is going to expire soon. A new expiration date and CVV are assigned to the replacement card while the PAN remains the same. The old card remains active until the new card is activated or until the expiration date arrives. An expiration reissuance must be requested prior to the actual expiration date. To retrieve cards that are about to expire, you can use the List Cards endpoint - you can sort cards by expiration date with the expiration_date sort argument or filter cards with the expires_before filter. From there, you can choose how you want to automate the reissuance. You could, for example, create a background job that reissues cards without any user interaction, or prompt the user to go through a reissuance flow, where they confirm the card shipping address, etc.
LOST: The customer has reported the card as lost. The lost card is immediately terminated. The replacement card has a new PAN, CVV, and expiration date, but keeps the same PIN.
STOLEN: The customer has reported the card as stolen. The stolen card is immediately terminated. The replacement card has a new PAN, CVV, and expiration date, but keeps the same PIN.
DAMAGED: The customer requests a new card to replace a damaged card. A new expiration date and CVV are assigned to the replacement card while the PAN remains the same. The old card remains active until the new card is activated or until the expiration date arrives.
APPEARANCE: The customer requests a new card with a different appearance, for example changing the name printed on the card or changing the card's custom image. A new expiration date and CVV are assigned to the replacement card while the PAN remains the same. The old card remains active until the new card is activated or until the expiration date arrives.
PRODUCT_CHANGE: The customer requests converting a card to a different card product (within the same card program), for example a virtual card to a physical card or a standard physical card to a physical card with a custom image. A new expiration date and CVV are assigned to the replacement card while the PAN remains the same. The old card remains active until the new card is activated or until the expiration date arrives.
PROGRAM_CHANGE: The customer requests converting a card to a different program, specifically debit card to a smart card. A new expiration date and CVV are assigned to the replacement card while the PAN remains the same. The old card remains active until the new card is activated or until the expiration date arrives.

In all of these cases, the Synctera platform automatically terminates the old card when it is time for termination. Also, where relevant, Digital wallet tokens are updated automatically, i.e. cardholders to not need to add the new card to the wallet. If the card is already on-file with merchants, cardholders do not need to worry about updating their card-on-file as it is automatically updated.

Cards API Objects

The Cards API works with two primary objects.

The Card Product Object

A card product is a defined set of card features that you can offer to your customers. A card product may define charge limits, foreign transaction fees, reward programs, and other important agreements between you and a customer for card use. When your FinTech onboards with Synctera and works out an agreement with a sponsor bank, if you’re going to use cards, your agreement includes a set of defined card products you can offer to your customers.

When we set you up in the Synctera platform, we create a set of Cards API objects, one for each of your card products. Each card product object contains:

The card product ID, unique to the card product
The card product name.
The card product form: whether it’s physical or virtual
Active/inactive status, whether the card product is still active or not. Inactive card products can’t be used to request card issuance.

When you request a card issuance, you specify a card product by ID so that you and the card issuer know the terms under which the card is issued.

The Card Object

The card object is the Card API’s principal object. Each object defines and tracks a card from issuance request through activation, management, and eventual end of life.

A card object has a set of attributes that vary depending on whether the card is virtual or physical. A physical card has to contain information about shipping such as address and shipping status, and for activation of a physical card such as the barcode used for validation.

Common Attributes

Physical and virtual card objects both have these common attributes:

Card ID specifies this card object.
Creation time specifies the date and time when this card was requested to be issued.
Last modified time specifies the date and time when this card object was last modified, whether modified by the integrator or the Synctera platform.
Form specifies whether the card is physical or virtual.
Account, customer, and card product IDs specify the customer, their account, and the card product associated with the card.
Embossed name is the exact name on the card: embossed in the card if physical, just associated with the card if virtual.
Last four provides the last four digits of the card’s PAN.
Expiration month, year, and time specify at least the standard month and year of expiration and may optionally specify a specific day and time.
Network specifies the credit card network that handles the card’s transactions, currently Mastercard.
Reissue from, to, and reason provide card reissue information if this is a reissued card: the ID of the card being reissued, the card ID of the replacement (this card), and a reason for the reissuance.
Metadata is an optional array of key-value pairs providing additional information about the card.
Type specifies whether this is a credit or debit card. It may currently only specify a debit card.
Status specifies multiple aspects of a card’s current status:
- Card status specifies the card’s current stage of life. The platform may set this value as it detects card changes, such as when a card becomes activated. You may also set this status when you find it appropriate.
  - Active: The card is available for full use.
  - Unactivated: The card hasn’t been activated yet and can’t be used.
  - Suspended: The card is suspended and can’t be used again until returned to active status.
  - Terminated: The card may no longer be used.
- Status reason specifies a code for a defined set of reasons why a card’s status changed.
- Memo provides your FinTech the option to enter additional details about status change.

Physical Card Attributes

A physical card object has some additional attributes:

Card fulfillment status reports whether the card has been issued, ordered, rejected, reordered, or shipped.
Shipping provides information about how and where the card should be shipped:
- Address provides the address to which the card was mailed. If not specified on the issuance request, this defaults to the customer’s shipping address.
- Care of line is the name of the person who will receive the package on behalf of the recipient. This value is generally used when mailing the card to a location other than the customer’s shipping address.
- Is expedited fulfillment requests expedited printing of the card by the card fulfillment vendor. Additional fees apply.
- Method specifies the shipping method and whether or not it’s expedited. If this value is not provided, it defaults to LOCAL_MAIL. Additional fees apply for all other methods.
- Recipient name specifies who should receive the card, often used for signature purposes. If not provided, it defaults to the customer’s name. This isn’t the same as the entity specified as “care of,” which is just used as part of the address.
Tracking number provides a number used to track a card’s shipment through the carrier.
Is PIN set specifies whether the PIN has been set for the card or not.

The Synctera platform receives information from the card issuer about shipping status and fills in attributes with received information so you can check on a card’s shipping status by looking at the card object.

Endpoints

The Cards API offers endpoints that handle different aspects of card creation and management.

Card Products

These endpoints provide card product information:

List Card Products returns an array of card product objects set up for you when your FinTech onboarded with Synctera. Each object provides a card product ID and card form with optional active/inactive status and card product name.
Get Details About a Card Product returns a card product object for a single card product.

Card Creation

These endpoints create an active card for a customer:

Issue a Card requests a card for a customer using one of the customer’s accounts and specifying a card product. If a request to this endpoint specifies that this is a card reissuance, the endpoint handles terminating the replaced card.
Activate a Card requests the card vendor to activate a physical card using the activation barcode provided by the customer.

Card Management

These endpoints manage a card once it’s issued:

List Cards returns an array of card objects representing cards you’ve issued. You can specify query parameters that include customer, account, embossed name, last four digits of the PAN, expiration date, card type, brand, form, card product, and the postal code of the user. Refer to List Cards
Get Card returns a single card object specified by card ID so that you can examine card attributes. Refer to Get Card
Update Card revises a card object’s attributes, limited to attributes that can change over the life of a card. This includes card status, status reason, and metadata stored in the memo attribute. Refer to Update Card
List Card Changes returns an array of any changes made to a card object’s card status or fulfillment status made either by you or by the Synctera platform. Each change in the array reports the type of change (card or fulfillment), how the change was submitted, optional memo metadata, both the old and new status (card or fulfillment), and the ID of the admin who made the change (if made in the Synctera admin system) and the time the change occurred. Refer to List Card Changes

Data Security Through Widgets

These endpoints provide tokens and connection information for Synctera’s PCI-compliant widgets:

Get Card Widget URL returns a URL used by the Synctera Activate Card and Set PIN widgets.
Get a Client Token returns a short-term token for use by the syntera.js client library to retrieve sensitive data for display.

A Typical Card Workflow

This workflow is an example of steps covering a card’s life from creation to deactivation. For this example, the card we work with is a physical debit card that activates through a barcode activation value.

Setup: To create a card, you need a customer that has passed KYC verification and an account that belongs to the customer.

Requesting Card Issuance

You offer a card product to a customer who you think is a promising card candidate.
To review the card products available through your FinTech, request a list of them through a request to List Card Products and note the card product ID of the product you want to offer.
The customer signs up for your card product and accepts the card disclosure. Disclosure to the customer is generally handled as part of your account onboarding process, but in some cases may be a separate process.
You request a card issuance through Issue a Card.
You specify the customer, the account, the card product, a name to emboss on the card, and optionally provide shipping information for the new card. The endpoint returns the card object, including the card object ID.
To check on card issuance status, you regularly request List Card Changes to return the card change history of the card object where you can look for new changes.
Each change reports shipping and card status changes, so you know when a card was ordered, issued, shipped, or even rejected so you can take action if necessary.

📘
For customers who have specified a chosen name, you can overwrite the default embossed first and last name by explicitly setting embossed_name with your customer's chosen and last name.

%%{init: {"fontFamily": "sans-serif"}}%%
sequenceDiagram
FinTech->>Customer: Offer card product
Customer->>FinTech: Sign me up
FinTech->>Synctera Platform: "Issue a Card"
FinTech->>Synctera Platform: Check card status: "List Card Changes"

Activating a Card

Your customer receives the card, logs into your app to activate the card, and uses their cell phone camera to scan the QR code.
Your app translates the QR code into a barcode value.
You use Activate Card to supply the barcode value and request card activation.
The Cards API requests card activation through the card vendor..
You use the Set PIN widget in your app to ask the customer to set a PIN for the card, which they do.
The Set PIN widget sends the PIN value to the card vendor.
The card vendor activates the card and notifies the Synctera platform.
The Synctera platform sets the corresponding card object’s status to ACTIVE.

%%{init: {"fontFamily": "sans-serif"}}%%
sequenceDiagram
Customer->>FinTech: Scan QR code on card
FinTech->>FinTech: Translate QR code to barcode value
FinTech->>Synctera Platform: Send barcode value:<br>"Activate Card"
Synctera Platform->>Card Vendor: Activate  card
Customer->>FinTech: Set PIN through widget
FinTech->>Card Vendor: Widget sends PIN setting
Card Vendor->>Card Vendor: Activate card
Card Vendor->>Synctera Platform: Card is active
Synctera Platform->>Synctera Platform: Card status: ACTIVE

Reissuing a Card

Your customer reports that they lost the card.
You request a card reissuance through Issue a Card. You provide all the information you did when you issued the lost card, and also specify a reason for reissuance and the card ID of the lost card as the card being replaced. (Note that you can also use the Synctera dashboard to perform this task.)
The Synctera platform immediately terminates the lost card with the card vendor and sets the card’s status to TERMINATED.
The new card is issued and activated just as the lost card was, except for the PIN which is retained from the lost card.

%%{init: {"fontFamily": "sans-serif"}}%%
sequenceDiagram
Customer->>FinTech: I lost my card
FinTech->>Synctera Platform: "Issue a Card"<br>to replace lost card
Synctera Platform->>Card Vendor: Terminate card
Card Vendor->>Card Vendor: Terminate card
Synctera Platform->>Synctera Platform: Set card to "TERMINATED"
Synctera Platform->>Card Vendor: Issue new card
Card Vendor->>Customer: Issue new card with old PIN

Cancelling a Card

The customer cancels the card.
You use Update Card to change the card’s status to TERMINATED. (Note that you can also use the Synctera dashboard to perform this task.)
The Synctera platform notifies the card vendor of termination.
The card vendor terminates the card.

%%{init: {"fontFamily": "sans-serif"}}%%
sequenceDiagram
Customer->>FinTech: Cancel my card
FinTech->>Synctera Platform: "Update Card" to<BR>TERMINATED status
Synctera Platform->>Card Vendor: Terminate card
Card Vendor->>Card Vendor: Terminate card

A Card’s Life

Card Activation Methods

Activation Widget

Barcode Activation

PATCH Request

Handling Sensitive Card Information

Initial Card Setup–

Displaying Sensitive Card Data

Resetting PIN Tries

Card Reissuance Scenarios

Cards API Objects

The Card Product Object

The Card Object

Common Attributes

Physical Card Attributes

Endpoints

Card Products

Card Creation

Card Management

Data Security Through Widgets

A Typical Card Workflow

Requesting Card Issuance

📘For customers who have specified a chosen name, you can overwrite the default embossed first and last name by explicitly setting embossed_name with your customer's chosen and last name.

Activating a Card

Reissuing a Card

Cancelling a Card

📘
For customers who have specified a chosen name, you can overwrite the default embossed first and last name by explicitly setting embossed_name with your customer's chosen and last name.