Skip to content
Last updated

Introduction

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

Card prerequisites

Cards webhooks

Subscribe to the following webhook events related to cards:

Event NameDescription
CARD_AUTHORIZATIONA customer made a transaction with their card and an authorization reservation has been created on the connected account.
CARD_AUTHORIZATION_DECLINE_V2A customer's card transaction was declined. See the list below for a full list of reasons.
CARD_AUTHORIZATION_RESOLUTIONA 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_EVENTThe 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_PENDINGA fraud case was recorded that requires the customer's immediate response.
CARD_FRAUD_CASE_TIMEOUTA customer did not respond in time to an open fraud case.
CARD_TOKEN_LIFECYCLEA push provisioning token was created or updated for a customer's card. Possible status values:
    - ACTIVE - INACTIVE - DEACTIVATED - SUSPENDED
SCA_CHALLENGEA 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

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.

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 card for a customer.

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.

On Sandbox, a given card can only be replaced once.

Card reason values

Specify the appropriate reason in your request to trigger the right replacement process:

  • Reissue a card that will soon expire: EXPIRES_SOON
  • Replace a damaged card (physical cards only): DEFECTIVE_CARD, CARDHOLDER_REQUEST (Deprecated)
  • Report a card as lost or stolen and request a replacement (physical cards only): LOST, STOLEN, COUNTERFEIT_PLASTIC, PREVENTIVE_BLOCK, ONLINE_TRANSACTION_FRAUD

For the reissue or replace flows:

  • The new card will have the same card number, but it will have a new CVV and expiry date.
  • Once you make this request, the card's status will change to PROCESSING, then ACTIVE or BLOCKED depending on the card's status prior to ordering. The value of the new_card_ordered property on the card resource will change to true.
  • The customer can still use the old card until they activate the new one. Once they do so, the old one will no longer be authorized and the value of new_card_ordered will change to false.

For the lost/stolen flow:

  • The new card will have a different card number.
  • The old card will stop working immediately upon acceptance of the API request. This action cannot be undone.
  • 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.

Accepted card statuses

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

  • Reissue: ACTIVE, INACTIVE
  • Replace and Lost/Stolen: ACTIVE, INACTIVE, BLOCKED, BLOCKED_BY_SOLARIS

You can only use this endpoint for physical cards.

How to report a card as lost or stolen

Use the POST Replace a card endpoint to report a card as lost or stolen. See the section above for detailed instructions.

The POST Report a card as lost or stolen is deprecated. Please use POST Replace a card instead.

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.

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:

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.

note

The maximum length for a cardholder's name is 21 characters. All other characters will be truncated.

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:

Address lineRelevant Solaris person attributesMaximum length
Line 1person.first_name + " " + person.last_name40 (length of both values combined and a single whitespace character)
Line 2person.address.line_1 + " " + person.address.line_240 (length of both values combined and a single whitespace character)
Line 3person.address.postal_code + " " + person.address.city9 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 lineRelevant Solaris business/person attributesMax length
Line 1business.name40
Line 2person.first_name + " " + person.last_name40 (length of both values combined and a single whitespace character)
Line 3business.address.line_1 + " " + business.address.line_240 (length of both values combined and a single whitespace character)
Line 4business.address.postal_code + " " + business.address.city9 for the postal code, 25 for the city name

Appendix I: Card types

Solaris does not issue physical cards for card resources with the VIRTUAL prefix.

Customer TypePhysical Card TypeVirtual Card Type
Person
    - MASTERCARD_DEBIT - VISA_DEBIT
    - VIRTUAL_MASTERCARD_DEBIT - VIRTUAL_VISA_DEBIT
Business
    - MASTERCARD_BUSINESS_DEBIT - VISA_BUSINESS_DEBIT
    - VIRTUAL_MASTERCARD_BUSINESS_DEBIT - VIRTUAL_VISA_BUSINESS_DEBIT
Freelancer
    - MASTERCARD_BUSINESS_DEBIT - VISA_BUSINESS_DEBIT
    - VIRTUAL_MASTERCARD_FREELANCE_DEBIT - VIRTUAL_VISA_FREELANCE_DEBIT

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.

StatusDescription
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.
CLOSEDThe customer closed this card, and now it can no longer be used. A new card must be issued.
CLOSED_BY_SOLARISSolaris closed this card, and now it can no longer be used. A new card must be issued.
COUNTERFEIT_CARDThe card was flagged as a counterfeit.
FRAUDThe card was flagged for fraudulent activity.
INACTIVEInitial status after Solaris executes the card creation request.
LOSTThe customer reported the card as lost.
NEVER_RECEIVEDThe customer reported that they never received the card.
PROCESSINGInitial status after Solaris receives the card creation request.
STOLENThe customer reported the card as stolen.

Appendix III: pos_entry_mode values

ValueDescription
CHIPThe customer conducted the transaction using the chip on the card.
CONTACTLESSThe customer conducted the transaction using the NFC module on the card.
CREDENTIAL_ON_FILEThe customer was charged by a merchant who already had their credit card information on file (e.g., for recurring transactions).
ECOMMERCEThe customer conducted the transaction with an e-commerce merchant.
MAG_STRIPEThe customer conducted the transaction using the magnetic stripe on the card.
MANUAL_PAN_ENTRYThe 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.
UNKNOWNThe POS entry mode data is unavailable.

Appendix IV: Transaction types

EnumDescription
AFTAccount Funding Transaction (AFT). Used to fund another account for purposes such as topping up prepaid card accounts, P2P money transfers, and topping up third-party digital wallets.
CASH_ATMATM cash withdrawal.
CASH_ATM_REVERSALReversal of an ATM cash withdrawal. Reservation canceled.
CASH_MANUALCash withdrawal via a bank counter.
CASH_MANUAL_REVERSALReversal of a cash withdrawal via a bank counter.
CREDIT_PRESENTMENTTypically used for refund transactions.
DEBIT_PRESENTMENTTypically used for non-authorized transactions.
DISPUTE_TRANSACTIONChargeback
FORCE_POST_TRANSACTIONManually settled transaction.
INQUIRYCard validation by Cards Smart Agent
OCTOriginal credit transfer.
PURCHASEE-commerce or POS transaction for the purchase of goods or services.
PURCHASE_REVERSALReversal of a purchase transaction. Reservation for the purchase of goods or services canceled

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 reasonPre-approved text
3DS_FAILEDWe could not approve your transaction because the merchant did not provide correct authentication information. Please try again.
AUTHENTICATION_REQUIREDFailed online authentication. Please try again.
CARD_BLOCKEDSomething went wrong. Contact us for further details.
CARD_EXPIREDThis card has expired. Please use your replacement card. If you have not yet received one, then please contact customer support.
CARD_INACTIVECard not active. Please activate your card and try again.
CARD_LOSTThe card was reported as lost. If you have not received a replacement card, please contact customer support.
CARD_STOLENThe card was reported as stolen. If you have not received a replacement card, please contact customer support.
EXPIRY_DATE_INVALIDIncorrect card details provided. Please try again.
FRAUD_SUSPECTEDSomething went wrong. Contact us for further details.
INSUFFICIENT_FUNDSBalance is too low. Top up your account and try again.
INVALID_CARD_DETAILSInvalid card details were provided. Please double-check your card details and ensure that your card is not blocked and try again.
INVALID_PIN_BLOCKEDCard is blocked due to incorrect PIN attempts. Please reset the PIN and try again.
LIST_CONTROLSpending control violated. Please review the set controls and try again.
PIN_INCORRECTIncorrect PIN entered. Please try again.
SCA_REQUIREDAuthentication is required for this transaction. If the declined transaction was contactless, then the merchant likely does not support the use of an online PIN. Therefore, you must use an alternate payment method that supports SCA, such as chip & PIN. If the original transaction declined was initiated remotely, then advise the customer to retry the transaction, as the merchant may have had a technical issue when processing the original authorization.
SPENDING_LIMITSpending limit exceeded. Please review the set limits and try again.
UNKNOWNThe payment was declined for an unclear reason. Please try to make a purchase at a different merchant. If payment still fails, then please order a replacement card.
UNSUPPORTED_FUNCTIONThe operation attempted with your card is not supported.

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 reasonPre-approved message
3DS_FAILEDWe could not approve your transaction because the merchant did not provide correct authentication information. Please try again.
ACCOUNT_CLOSEDSomething went wrong. Please contact us for further details.
ACCOUNT_LIMIT_REACHEDAccount limit reached. Please contact us for further details.
AUTHENTICATION_REQUIREDFailed online authentication. Please try again.
CARD_BLOCKEDSomething went wrong. Please contact us for further details.
CARD_INACTIVEThis card is not active. Please activate your card and try again.
CARD_NOT_PRESENT_AMOUNT_LIMIT_REACHED_DAILYDaily card limit exceeded. Please review the card limits and try again.
CARD_NOT_PRESENT_AMOUNT_LIMIT_REACHED_MONTHLYMonthly card limit exceeded. Please review the card limits and try again.
CARD_NOT_PRESENT_USE_LIMIT_REACHED_DAILYDaily card limit exceeded. Please review the card limits and try again.
CARD_NOT_PRESENT_USE_LIMIT_REACHED_MONTHLYMonthly card limit exceeded. Please review the card limits and try again.
CARD_PRESENT_AMOUNT_LIMIT_REACHED_DAILYDaily card limit exceeded. Please review the card limits and try again.
CARD_PRESENT_AMOUNT_LIMIT_REACHED_MONTHLYMonthly card limit exceeded. Please review the card limits and try again.
CARD_PRESENT_USE_LIMIT_REACHED_DAILYDaily card limit exceeded. Please review the card limits and try again.
CARD_PRESENT_USE_LIMIT_REACHED_MONTHLYMonthly card limit exceeded. Please review the card limits and try again.
CASH_ADVANCE_AMOUNT_LIMIT_REACHED_DAILYThe daily limit for cash withdrawals has been reached. Please contact us for further details.
CASH_ADVANCE_AMOUNT_LIMIT_REACHED_MONTHLYThe monthly limit for cash withdrawals has been reached. Please contact us for further details.
CONTACT_BANKSomething went wrong. Please contact us for further details.
CVV_INCORRECTIncorrect card details provided. Please try again.
DUPLICATE_TRASACTIONThere was an issue with the merchant terminal. Please try again.
EXPIRY_DATE_INVALIDIncorrect card details provided. Please try again.
FRAUD_SUSPECTEDSomething went wrong. Please contact us for further details.
INSUFFICIENT_FUNDSBalance is too low. Please top up your account and try again.
INVALID_PIN_BLOCKEDCard is blocked due to incorrect PIN attempts. Please reset the PIN and try again.
PIN_ENTRY_TIMEOUTThere was an issue with the merchant terminal. Please try again.
PIN_INCORRECTIncorrect PIN entered. Please try again.
REPLACEMENT_CARD_ACTIVATEDYou 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.
RETRY_WITH_CHIP_AND_PINWe encountered a problem while trying to approve your transaction. Please insert the card in the merchant terminal and try again.
SCA_REQUIREDAuthentication is required for this transaction.
TERMINAL_ERRORThere 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: pos_entry_mode 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.
    • wallet_type: The name of the digital wallet.
    • device_pan: Reference to the device's token in that wallet.

Appendix VIII: loss_reason enum values

This tables describes values for the POST Report a card as lost/stolen, which is deprecated. Please use the POST Replace a card endpoint to report a card as lost/stolen instead.

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

EnumDescription
COUNTERFEIT_PLASTICUse when the card was cloned or counterfeited.
HOME_INVASIONUse when the customer has provided a police report confirming a home invasion.
LEFT_AT_MERCHANTUse when the customer forgot the card at a merchant.
LOSTUse when the customer lost the card outside of their home.
MAIL_ORDERUse in case of fraud related to email scams, PAN phishing, or other mail-related security data/quantities.
MAILBOX_THEFTUse when the customer has provided a police report confirming mailbox theft.
MISSING_AT_HOMEUse when the customer lost the card at home.
PICK_POCKETUse when the customer has provided a police report confirming pickpocketing.
PREVENTIVE_BLOCKUse when the cardholder is not sure whether the card has been 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

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

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.)
    3. The customer reports the card as lost/stolen.
      • Your solution calls POST Replace a card, supplying one of the lost/stolen values for the reason property.
      • 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, supplying one of the replace values for the reason property. However, 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

Card status flow: Reported as lost or 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 Replace a card, supplying one of the lost/stolen values for the reason property.
    • 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 Replace a card, supplying one of the lost/stolen values for the reason property.
    • 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

Card status flow:

  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:
  4. If the customer orders a replacement card after activating it:

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:

loss_reason valueResulting card status
COUNTERFEIT_PLASTICCOUNTERFEIT_CARD
HOME_INVASIONSTOLEN
LEFT_AT_MERCHANTLOST
LOSTLOST
MAIL_ORDERFRAUD
MAILBOX_THEFTNEVER_RECEIVED
MISSING_AT_HOMELOST
PICK_POCKETSTOLEN
PREVENTIVE_BLOCKCOUNTERFEIT_CARD
SUSPECTED_MERCHANT_FRAUDFRAUD