Card creation & servicing

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 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:
  • ACTIVE
  • INACTIVE
  • DEACTIVATED
  • SUSPENDED
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 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.

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

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.