Card creation & servicing

Introduction

This page explains everything related to issuing and managing debit cards for your customers.

Card prerequisites

• Please read the PCI compliance and sensitive information section on the cards overview page.
• Solaris debit cards must always be tied to Solaris bank accounts. Please follow the Get started guide and implement the customer onboarding flow for Digital Banking & Cards. This guide also includes instructions for issuing cards to your customers once you have onboarded them.

• Your customers cannot make card transactions without two-factor authentication (2FA). Please ensure that you have implemented the following mandatory features before continuing:

  • 3DS
  • Device binding
  • Change request process
  • Strong Customer Authentication

Cards webhooks

Subscribe to the following webhook events related to cards:

Cards servicing endpoints

This section describes how to perform common cards-related operations using Solaris' API:

How to issue a card

You can issue cards to your customers by calling the following endpoints:

POST Create a card

This endpoint initiates the card creation process for the customer. Include the account_id along with the person_id in the request URL. Additionally, include the following properties in the request body:

• line_1: The cardholder's name which will be printed on the card. Pay attention to the special rules governing card names mentioned here.
• type: The card type. View here a list of possible card types for each customer segment.

Request URL:

POST /v1/persons/{person_id}/accounts/{account_id}/cards

Response example:

A card will be created in the system, and Solaris will issue a card creation request with SIA. The API will respond with the ID of the card and the status of PROCESSING.

{
  "id": "8febdba4912a747808ccc6f95f82aaa4",
  "status": "PROCESSING"
}

Click here to view the full API reference.

GET Retrieve card details

Before you can activate the card, make the following API call to retrieve the details of the card. The status must have the value of INACTIVE. The status change may take a few seconds after the initial POST Create card request, as Solaris submits card creation requests asynchronously to SIA.

The API will respond with the card details when the status changes to INACTIVE. Until then, the response will look the same as the one from the previous call.

Request URL:

GET /v1/cards/{card_id}

Click here to view the full API reference.

POST Activate a card

Once the card is INACTIVE and you have retrieved the details using the previous API call, you can activate the card using the following endpoint:

Request URL:

POST /v1/cards/{card_id}/activate

Click here to view the full API reference.

Card push provisioning

If your customer wants to use their card in a digital wallet, such as Google Pay, Apple Pay, or Samsung Pay wallet, implement the relevant endpoints in the Card Push Provisioning guide.

How to block/unblock a card

Use POST Block a card to block a customer's debit card. As a prerequisite, the card must have a status of ACTIVE.

Use POST Unblock a card to unblock a card. It must have a status of BLOCKED.

How to replace a card

Use POST Replace a card to order a new debit card for a customer.

Please only use this endpoint in the event of physical damage to the card. If the card is lost or stolen, please use the dedicated endpoint.

The new card will retain the card number from the old one, but it will have a new CVV and expiry date.

As a prerequisite, the card must have one of the following statuses:

• ACTIVE
• BLOCKED
• BLOCKED_BY_SOLARIS

When you call this endpoint, the card's new_card_ordered value will change to true and the status will remain ACTIVE. The customer will still be able to use the old card until the replacement arrives. When the customer activates the replacement, then the value of new_card_ordered will return to false and they can start using it right away.

How to report a card as lost or stolen

Use POST Report a card as lost or stolen if a customer reports their card as lost or stolen.

Please note the following behavior for this endpoint:

• When a card is reported as lost or stolen, it immediately stops working. You cannot undo this action.
• In the API call, you can request a replacement for the lost or stolen card by setting the value of order_replacement to true.

• Note that lost or stolen cards that had been added to Apple Pay or Google Pay wallets can still be used for purchases using those wallets.

  • If your customer believes that their card and phone were compromised, then you should call this endpoint without requesting a replacement card. Instead, order a replacement separately using POST Create a card.
• Please only use this endpoint in the event that the card was lost or stolen. If the card was damaged, then please use POST Replace a card.
• This endpoint only works with physical cards.

See the appendix below for a description of each loss_reason value.

The card's status will change based on the loss_reason provided by the customer. See the appendix below for a mapping of loss_reason values to the resulting card status values.

Cards API reference

Click here to see the full cards API reference.

Types of cards

Solaris allows you to create physical and virtual cards for your customers. Additionally, your customers can opt to tokenize their cards (i.e., add them to a Google Pay or Apple Pay wallet).

Virtual cards

Virtual cards are fully functioning Solaris payment cards that are not physically produced. Customers can use virtual cards immediately after they are generated. They can also replace virtual cards at regular intervals, e.g., after every transaction or every X number of minutes.

To use virtual cards in your solution, you must implement device binding.

To create a virtual card for a customer, call the POST Create a card endpoint and specify a virtual type in the request body.

To view the virtual card's details, call the POST Create secure view endpoint. The API will return the encrypted card details, which the customer's device must decrypt with a device signature.

You can create up to five virtual cards per customer.

Cardholder name and address generation

Overview

When Solaris provides cardholder name and address information to the card manufacturer to print and ship debit cards, it draws this information from various attributes stored on the cardholder's person and/or business resources. These details will be printed on the card.

Therefore, you must restrict the customer's input during the onboarding process to the set of supported characters listed below. Any non-supported characters will be replaced with ? once Solaris sends the address to the card manufacturer.

Supported characters

Solaris' card manufacturer only supports the characters listed below. Please ensure that your solution validates all text inputs using the following character set:

ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 -/

Please convert accented characters to their non-accented equivalents (e.g., converting Ö to OE, É to E).

You may determine whether or not the cardholder's name should be printed in the main text section of the carrier letter.

Cardholder shipping address generation

The customer's shipping address will be printed in the address section of the carrier letter. If the addressee of the carrier envelope has two lines in their address (i.e., values for both address.line_1 and address.line_2 in their person resource), then the two lines will be combined before the card is sent to the production facility.

Person and freelancer cards

For persons and freelancers, the card will be shipped to the address stored in the related person resource.

The table below explains which person values Solaris uses to address the shipping envelope:

Business cards

For businesses, the card will be shipped to the address of the associated business (i.e., the address stored on the business resource).

The table below explains which business and person values Solaris uses to address the shipping envelope:

Appendix I: Card types

Appendix II: Card status values

Appendix III: pos_entry_mode values

Appendix IV: Transaction types

Appendix V: Transaction declined reasons (V2)

Below is a table of possible decline reasons and pre-approved messages for the CARD_AUTHORIZATION_DECLINE_V2 webhook event:

Appendix VI: Transaction declined reasons (Legacy V1)

Below is a table of possible decline reasons and pre-approved messages for the CARD_AUTHORIZATION_DECLINE (legacy) webhook event:

Appendix VII: Card metadata values

• cards: Sub-object containing metadata related to the card payment.

  • card_id: Solaris ID of the card used for conducting the payment.

  • merchant: Sub-object containing information about the merchant where the customer made the card payment.

    • id: ID provided by the merchant.
    • country_code: Two-letter country code for the country where the merchant is based.
    • category_code: The merchant's Merchant Category Code (MCC).
    • post_code: Post code where the merchant is based.
    • state: State where the merchant is based.
    • street_address: Street address where the merchant is based.
    • name: The merchant's name.
    • town: Town where the merchant is based.

  • original_amount: The original amount of the transaction.

    • currency: The currency in which the transaction was conducted.
    • value: The value of the transaction.
    • fx_rate: The foreign exchange rate that was applied to the transaction.
    • fx_markup: The difference in the exchange rate between VISA/MasterCard and the ECB.
    • issuer_fee: The foreign exchange fee charged by the card issuer.
  • pos_entry_mode: The point-of-sale (POS) method used for the transaction. See Appendix X: posentrymode values for the full list.
  • trace_id: ID of the related transaction received from the merchant.
  • transaction_date: Date when the card payment was made.
  • transaction_time: Time when the card payment was made.
  • transaction_type: The type of card transaction. See Appendix IV: Transaction types for the full list.
  • auth_code: Authorization code for the card payment.
  • terminal_id: ID of the terminal used for the card payment.
  • acquirer_id: The ID of the merchant's acquiring bank or institution.

Appendix VIII: loss_reason enum values

The table below explains each possible value for the loss_reason property when reporting a card as lost or stolen:

Appendix IX: Card status transition flows

The following diagrams depict how a card's status value changes based on various scenarios related to card servicing.

Card status flow: Create & activate card

1. Your solution calls POST Create a card to order a new card for a customer. The card has the initial status value of PROCESSING.
2. Solaris processes the card creation request and mails the card to the customer. The card's status transitions to INACTIVE.
3. The customer receives the card in the mail and activates their card in your frontend. Your solution calls POST Activate a card.
4. Solaris processes the card activation request. The card's status transitions to ACTIVE.
5. If the customer wishes to close their card, then they follow the steps in your frontend. Your solution then calls POST Close a card. The card's status transitions to CLOSED. This status is final.

Card status flow: Card blocking

1. The customer has already ordered and activated their card. It has a status of ACTIVE.
2. An event occurs that results in the card being blocked. This transitions the card's status to BLOCKED or BLOCKED_BY_SOLARIS (depending on the event).

3. One of the following events occurs:

   1. Solaris unblocks the card.

      • The card's status transitions back to ACTIVE.

   2. You unblock the card, or the customer unblocks it in your frontend. (This is only possible if the status is BLOCKED.)

      • Your solution calls POST Unblock a card.
      • The card's status transitions back to ACTIVE.

   3. The customer reports the card as lost/stolen.

      • Your solution calls POST Report a card as lost or stolen.
      • If you order a replacement card, then the card's status will transition to INACTIVE. Then, when the customer receives and activates the replacement, your solution calls POST Activate a card. Then, the card's status transitions to ACTIVE.
      • If you don't order a replacement, then the card's status transitions to CLOSED_BY_SOLARIS. This status is final.

   4. The customer orders a replacement card.

      • Your solution calls POST Replace a card, but this will result in an error, as this is an invalid action.

   5. You close the card, or the customer closes it in your frontend. (This is only possible if the status is BLOCKED.)

      • Your solution calls POST Close a card.
      • The card's status transitions to CLOSED. This status is final.

Card status flow: Reported as lost/stolen

1. Your solution calls POST Create a card to order a new card for a customer. The card has the initial status value of PROCESSING.
2. Solaris processes the card creation request and mails the card to the customer. The card's status transitions to INACTIVE.

3. If the customer reports the card as lost/stolen prior to activating it:

   • Your solution calls POST Report a card as lost or stolen.
   • If you order a replacement card, then the card's status will remain INACTIVE. Then, when the customer receives and activates the replacement, your solution calls POST Activate a card. Then, the card's status transitions to ACTIVE.
   • If you don't order a replacement, then the card's status transitions to CLOSED_BY_SOLARIS. This status is final.

4. If the customer reports the card as lost/stolen after activating it:

   • Your solution calls POST Report a card as lost or stolen.
   • If you order a replacement card, then the card's status will transition to STOLEN. Then, when the customer receives and activates the replacement, your solution calls POST Activate a card. Then, the card's status transitions to ACTIVE.
   • If you don't order a replacement, then the card's status transitions to CLOSED_BY_SOLARIS. This status is final.

Card status flow: Card replacement

1. Your solution calls POST Create a card to order a new card for a customer. The card has the initial status value of PROCESSING.
2. Solaris processes the card creation request and mails the card to the customer. The card's status transitions to INACTIVE.

3. If the customer orders a replacement card prior to activating it:

   • Your solution calls POST Replace a card.
   • The card's status remains INACTIVE.
   • When the customer receives and activates the replacement in your frontend, your solution calls POST Activate a card.
   • The card's status transitions to ACTIVE.

4. If the customer orders a replacement card after activating it:

   • Your solution calls POST Replace a card.
   • The card's status remains ACTIVE.
   • When the customer receives and activates the replacement in your frontend, your solution calls POST Activate a card.
   • The card's status remains ACTIVE.

Appendix X: Lost/stolen status transitions

When a customer reports a card as lost or stolen, the card status changes based on the provided loss_reason. This table explains which card status results from each possible loss_reason: