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

The Get started with Digital Banking & Cards guide covers the process for issuing cards from start to finish. Click the links below to see the instructions:

• Issue a card for a person
• Issue a card for a business

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 Replace 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.

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: