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:
Cards webhooks
Subscribe to the following webhook events related to cards:
Event Name | Description |
---|---|
CARD_AUTHORIZATION |
A customer made a transaction with their card and an authorization reservation has been created on the connected account. |
CARD_AUTHORIZATION_DECLINE_V2 |
A customer's card transaction was declined. See the list below for a full list of reasons. |
CARD_AUTHORIZATION_RESOLUTION |
A card reservation was cancelled, expired, or converted to a booking. You do not have to send a push notification to the customer for this webhook. |
CARD_LIFECYCLE_EVENT |
The status of a customer's card has changed. See the list below for a list of card status values and messages to display to the customer. |
CARD_FRAUD_CASE_PENDING |
A fraud case was recorded that requires the customer's immediate response. |
CARD_FRAUD_CASE_TIMEOUT |
A customer did not respond in time to an open fraud case. |
CARD_TOKEN_LIFECYCLE |
A push provisioning token was created or updated for a customer's card. Possible status values:
|
SCA_CHALLENGE |
A customer made a transaction or performed an action (e.g., adding a card to a mobile wallet like Google or Apple Pay) that requires two-factor authentication. The generation of authentication challenges depends on risk criteria that cannot be disclosed. |
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:
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
.
note
If the card has the status BLOCKED_BY_SOLARIS
, then you cannot unblock it
yourself using the API. In this case, please contact Solaris customer
support.
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.
note
You can only use this endpoint for physical cards.
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
totrue
. -
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.
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.
Important
By default, virtual cards can only be used for online transactions. To make in-store purchases with a virtual card, customers must tokenize the virtual card. Read the next section to learn more.
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:
âäàáãåçñ¢.(+|&éêëèíîïìß!*)-/ÂÄÀÁÃÅÇÑ,%_?`
øÉÊËÈÍÎÏÌ:#@'="Øabcdefghiýjklmnopqrstuvwxyz¡¿Ý®©
´ABCDEFGHIôöòóõJKLMNOPQRûüùúÿ÷STUVWXYZÔÖÒÓÕ0123456789ÛÜÙÚ
Cardholder name generation
Solaris generates the cardholder's name by combining the first_name
and
last_name
attributes from their related person
resource, separated by a
whitespace. Example: person.first_name + " " + person.last_name
You may determine whether or not the cardholder's name should be printed in the main text section of the carrier letter.
note
The maximum length for a cardholder's name is 40 characters. All other characters will be truncated.
Cardholder shipping address generation
This section describes how Solaris generates the shipping address on the carrier envelope.
The 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:
Address line | Relevant Solaris person attributes | Maximum length |
---|---|---|
Line 1 | person.first_name + " " + person.last_name |
40 (length of both values combined and a single whitespace character) |
Line 2 | person.address.line_1 + " " + person.address.line_2 |
40 (length of both values combined and a single whitespace character) |
Line 3 | person.address.postal_code + " " + person.address.city |
9 for the postal code, 25 for the city name |
Line 4 | (not used) | (not used) |
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:
Address line | Relevant Solaris business/person attributes | Max length |
---|---|---|
Line 1 | business.name |
40 |
Line 2 | person.first_name + " " + person.last_name |
40 (length of both values combined and a single whitespace character) |
Line 3 | business.address.line_1 + " " + business.address.line_2 |
40 (length of both values combined and a single whitespace character) |
Line 4 | business.address.postal_code + " " + business.address.city |
9 for the postal code, 25 for the city name |
Appendix I: Card types
note
Solaris does not issue physical cards for card resources
with the VIRTUAL
prefix.
Customer Type | Physical Card Type | Virtual Card Type |
---|---|---|
Person |
|
|
Business |
|
|
Freelancer |
|
|
Appendix II: Card status values
Note
When a card is closed, its status cannot be changed. Only Solaris can set
initial statuses and _BY_SOLARIS
statuses.
Status | Description |
---|---|
ACTIVE |
(Temporary) Card has been issued and can be fully used. |
ACTIVATION_BLOCKED_BY_SOLARIS |
(Temporary) Card is blocked by us due to excessive failed token activation attempts. Contact Solaris customer support for assistance. |
BLOCKED |
(Temporary) Card is blocked, but can be unblocked by the customer. |
BLOCKED_BY_SOLARIS |
(Temporary) Solaris blocked the card, and it currently cannot be used. The customer cannot unblock this card. Contact Solaris customer support for assistance. |
CLOSED |
The customer closed this card, and now it can no longer be used. A new card must be issued. |
CLOSED_BY_SOLARIS |
Solaris closed this card, and now it can no longer be used. A new card must be issued. |
COUNTERFEIT_CARD |
The card was flagged as a counterfeit. |
FRAUD |
The card was flagged for fraudulent activity. |
INACTIVE |
Initial status after Solaris executes the card creation request. |
LOST |
The customer reported the card as lost. |
NEVER_RECEIVED |
The customer reported that they never received the card. |
PROCESSING |
Initial status after Solaris receives the card creation request. |
STOLEN |
The customer reported the card as stolen. |
Appendix III: pos_entry_mode values
Value | Description |
---|---|
CHIP |
The customer conducted the transaction using the chip on the card. |
CONTACTLESS |
The customer conducted the transaction using the NFC module on the card. |
CREDENTIAL_ON_FILE |
The customer was charged by a merchant who already had their credit card information on file (e.g., for recurring transactions). |
ECOMMERCE |
The customer conducted the transaction with an e-commerce merchant. |
MAG_STRIPE |
The customer conducted the transaction using the magnetic stripe on the card. |
CARD_NOT_PRESENT |
The customer conducted the transaction by submitting the card details without using the physical card itself. This usually occurs in the context of e-commerce purchases. |
MANUAL_PAN_ENTRY |
The merchant entered the card details manually. This may occur if the terminal could not read the card details when it was placed on the PIN pad or swiped via the magnetic stripe, or while processing a CNP (Card not present) transaction. |
UNKNOWN |
The POS entry mode data is unavailable. |
Appendix IV: Transaction types
Enum | Description |
---|---|
CASH_ATM and CASH_MANUAL |
Funds withdrawal |
CASH_ATM_REVERSAL and CASH_MANUAL_REVERSAL |
Reservation canceled |
PURCHASE |
Goods or services purchase |
PURCHASE_REVERSAL |
Reservation for the purchase of goods or services canceled |
OCT |
Original credit transfer |
CREDIT_PRESENTMENT |
Typically used for refund transactions |
DEBIT_PRESENTMENT |
Typically used for non-authorized transactions |
FORCE_POST_TRANSACTION |
Manually settled transaction |
DISPUTE_TRANSACTION |
Chargeback |
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:
Decline Reason | Pre-Approved Text |
---|---|
3DS_FAILED |
We could not approve your transaction because the merchant did not provide correct authentication information. Please try again. |
ACCOUNT_CLOSED |
Something went wrong. Contact us for further details. |
ACCOUNT_LIMIT_REACHED |
Account limit reached. Please contact us for further details. |
AUTHENTICATION_REQUIRED |
Failed online authentication. Please try again. |
CARD_BLOCKED |
Something went wrong. Contact us for further details. |
CARD_EXPIRED |
This card has expired. Please use your replacement card. If you have not yet received one, then please contact customer support. |
CARD_INACTIVE |
Card not active. Please activate your card and try again. |
CARD_NOT_PRESENT_AMOUNT_LIMIT_REACHED_DAILY |
Daily card limit exceeded. Please review the card limits and try again. |
CARD_NOT_PRESENT_AMOUNT_LIMIT_REACHED_MONTHLY |
Monthly card limit exceeded. Please review the card limits and try again. |
CARD_NOT_PRESENT_USE_LIMIT_REACHED_DAILY |
Daily card limit exceeded. Please review the card limits and try again. |
CARD_NOT_PRESENT_USE_LIMIT_REACHED_MONTHLY |
Monthly card limit exceeded. Please review the card limits and try again. |
CARD_PRESENT_AMOUNT_LIMIT_REACHED_DAILY |
Daily card limit exceeded. Please review the card limits and try again. |
CARD_PRESENT_AMOUNT_LIMIT_REACHED_MONTHLY |
Monthly card limit exceeded. Please review the card limits and try again. |
CARD_PRESENT_USE_LIMIT_REACHED_DAILY |
Daily card limit exceeded. Please review the card limits and try again. |
CARD_PRESENT_USE_LIMIT_REACHED_MONTHLY |
Monthly card limit exceeded. Please review the card limits and try again. |
CASH_ADVANCE_AMOUNT_LIMIT_REACHED_DAILY |
Daily limit for Cash withdrawals has been reached. Contact us for further details. |
CASH_ADVANCE_AMOUNT_LIMIT_REACHED_MONTHLY |
Monthly limit for Cash withdrawals has been reached. Contact us for further details. |
CONTACT_BANK |
Something went wrong. Contact us for further details. |
CVV_INCORRECT |
Incorrect card details provided. Please try again. |
DUPLICATE_TRASACTION |
There was an issue with the merchant terminal. Please try again. |
EXPIRY_DATE_INVALID |
Incorrect card details provided. Please try again. |
FRAUD_SUSPECTED |
Something went wrong. Contact us for further details. |
INSUFFICIENT_FUNDS |
Balance is too low. Top up your account and try again. |
INVALID_PIN_BLOCKED |
Card is blocked due to incorrect PIN attempts. Please reset the PIN and try again. |
PIN_INCORRECT |
Incorrect PIN entered. Please try again. |
PIN_ENTRY_TIMEOUT |
There was an issue with the merchant terminal. Please try again. |
RETRY_WITH_CHIP_AND_PIN |
We encountered a problem while trying to approve your transaction. Please try again inserting the card in the merchant terminal. |
SCA_REQUIRED |
Authentication is required for this transaction. |
TERMINAL_ERROR |
There was an issue with the merchant terminal. Please try again. |
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:
Decline reason | Pre-approved message |
---|---|
3DS_FAILED | We could not approve your transaction because the merchant did not provide correct authentication information. Please try again. |
ACCOUNT_CLOSED | Something went wrong. Please contact us for further details. |
ACCOUNTLIMITREACHED | Account limit reached. Please contact us for further details. |
AUTHENTICATION_REQUIRED | Failed online authentication. Please try again. |
CARD_BLOCKED | Something went wrong. Please contact us for further details. |
CARD_INACTIVE | This card is not active. Please activate your card and try again. |
CARDNOTPRESENTAMOUNTLIMITREACHEDDAILY | Daily card limit exceeded. Please review the card limits and try again. |
CARDNOTPRESENTAMOUNTLIMITREACHEDMONTHLY | Monthly card limit exceeded. Please review the card limits and try again. |
CARDNOTPRESENTUSELIMITREACHEDDAILY | Daily card limit exceeded. Please review the card limits and try again. |
CARDNOTPRESENTUSELIMITREACHEDMONTHLY | Monthly card limit exceeded. Please review the card limits and try again. |
CARDPRESENTAMOUNTLIMITREACHED_DAILY | Daily card limit exceeded. Please review the card limits and try again. |
CARDPRESENTAMOUNTLIMITREACHED_MONTHLY | Monthly card limit exceeded. Please review the card limits and try again. |
CARDPRESENTUSELIMITREACHED_DAILY | Daily card limit exceeded. Please review the card limits and try again. |
CARDPRESENTUSELIMITREACHED_MONTHLY | Monthly card limit exceeded. Please review the card limits and try again. |
CASHADVANCEAMOUNTLIMITREACHED_DAILY | The daily limit for cash withdrawals has been reached. Please contact us for further details. |
CASHADVANCEAMOUNTLIMITREACHED_MONTHLY | The monthly limit for cash withdrawals has been reached. Please contact us for further details. |
CONTACT_BANK | Something went wrong. Please contact us for further details. |
CVV_INCORRECT | Incorrect card details provided. Please try again. |
DUPLICATE_TRASACTION | There was an issue with the merchant terminal. Please try again. |
EXPIRYDATEINVALID | Incorrect card details provided. Please try again. |
FRAUD_SUSPECTED | Something went wrong. Please contact us for further details. |
INSUFFICIENT_FUNDS | Balance is too low. Please top up your account and try again. |
INVALIDPINBLOCKED | Card is blocked due to incorrect PIN attempts. Please reset the PIN and try again. |
PINENTRYTIMEOUT | There was an issue with the merchant terminal. Please try again. |
PIN_INCORRECT | Incorrect PIN entered. Please try again. |
REPLACEMENTCARDACTIVATED | You reordered and activated a card with the same PAN, but the CVV and expiry date have changed with the new card. You either used the old card or the unactivated new one in an online transaction. In the latter case, please contact the merchant to update your CVV and expiry date on their file. |
RETRYWITHCHIPANDPIN | We encountered a problem while trying to approve your transaction. Please insert the card in the merchant terminal and try again. |
SCA_REQUIRED | Authentication is required for this transaction. |
TERMINAL_ERROR | There was an issue with the merchant terminal. Please try again. |
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.