# Card creation & servicing

## Introduction

This guide explains the process of issuing and managing debit cards for your customers.

## Card prerequisites

* Read the [PCI compliance and sensitive information](/guides/cards#pci-compliance-and-sensitive-information) section on the cards overview page.
* You must tie Solaris debit cards to Solaris bank accounts. Follow the [Get started guide](/guides/get-started) 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). Ensure that you have implemented the following **mandatory features** before continuing:
  * [3DS](/guides/cards/3ds)
  * [Device binding](/guides/authentication/device-binding/)
  * [Change request process](/guides/authentication/strong-customer-authentication/#change-request)
  * [Strong Customer Authentication](/guides/authentication/strong-customer-authentication)


### 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 [Appendix V](#appendix-v-transaction-declined-reasons-v2) 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 [Appendix II](#appendix-ii-card-status-values) 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. |


## Cards servicing endpoints

This section describes how to perform common cards-related operations using the Solaris API.

### 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 in [Cardholder name and address generation](#cardholder-name-and-address-generation).
* `type`: The card type. View [Appendix I](#appendix-i-card-types) for a list of possible card types for each customer segment.


**Request URL**


```shell
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 the processor. The API will respond with the ID of the card and the status of `PROCESSING`.


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

[View full API reference](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1persons~1%7Bperson_id%7D~1accounts~1%7Baccount_id%7D~1cards/post)

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

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**


```shell
GET /v1/cards/{card_id}
```

[View full API reference](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bid%7D/get)

#### POST Activate a card

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

**Request URL**


```shell
POST /v1/cards/{card_id}/activate
```

[View full API reference](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1activate/post)

### Card push provisioning

If your customer wants to use their card in a digital wallet, such as Google Pay, Apple Pay, or Samsung Pay, implement the relevant endpoints in the [Card Push Provisioning guide](/guides/cards/push-provisioning).

### 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`.

[View POST Block a card API reference](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1block/post)

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

[View POST Unblock a card API reference](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1unblock/post)

If the card has the status `BLOCKED_BY_SOLARIS`, you cannot unblock it yourself using the API. In this case, contact Solaris customer support.

### 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, the value of `new_card_ordered` will return to `false` and they can start using it right away.

[View POST Replace a card API reference](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1replace/post)

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

### 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** endpoint is **deprecated.** Use **POST Replace a card** instead.

### Cards API reference

[View the full cards API reference](/api-reference/digital-banking/cards/)

## 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](/guides/authentication/device-binding).

To create a virtual card for a customer, call the `POST Create a card` endpoint and specify a [virtual type](#appendix-i-card-types) 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.

## 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. Ensure that your solution validates all text inputs using the following character set:


```
ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 -/.
```

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

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. |
| `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 |
|  --- | --- |
| `AFT` | Account 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_ATM` | ATM cash withdrawal. |
| `CASH_ATM_REVERSAL` | Reversal of an ATM cash withdrawal. Reservation canceled. |
| `CASH_MANUAL` | Cash withdrawal via a bank counter. |
| `CASH_MANUAL_REVERSAL` | Reversal of a cash withdrawal via a bank counter. |
| `CREDIT_PRESENTMENT` | Typically used for refund transactions. |
| `DEBIT_PRESENTMENT` | Typically used for non-authorized transactions. |
| `DISPUTE_TRANSACTION` | Chargeback |
| `FORCE_POST_TRANSACTION` | Manually settled transaction. |
| `INQUIRY` | Card validation by [Cards Smart Agent](/guides/cards/cards-smart-agent). |
| `OCT` | Original credit transfer. |
| `PURCHASE` | E-commerce or POS transaction for the purchase of goods or services. |
| `PURCHASE_REVERSAL` | Reversal 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](/api-reference/onboarding/webhooks/webhook-events/paths/card_authorization_decline_v2/post) 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. |
| `AUTHENTICATION_REQUIRED` | Failed online authentication. Please try again. |
| `AML_REQUIREMENT_FAILED` | We were unable to process this payment. For your security, please contact your bank so we can help you complete your transaction. |
| `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_LOST` | The card was reported as lost. If you have not received a replacement card, please contact customer support. |
| `CARD_STOLEN` | The card was reported as stolen. If you have not received a replacement card, please contact customer support. |
| `DO_NOT_HONOUR` | We were unable to process this payment. For your security, please contact your bank so we can help you complete your transaction. |
| `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_CARD_DETAILS` | Invalid card details were provided. Please double-check your card details and ensure that your card is not blocked and try again. |
| `INVALID_FORMAT` | There was an issue with the merchant terminal. Please try again. |
| `INVALID_PIN_BLOCKED` | Card is blocked due to incorrect PIN attempts. Please reset the PIN and try again. |
| `LIST_CONTROL` | Spending control violated. Please review the set controls and try again. |
| `PIN_INCORRECT` | Incorrect PIN entered. Please try again. |
| `PIN_VALIDATION_FAILURE` | Cannot verify PIN. Please try different terminal. If the issue persist replace the card. |
| `POS_FAILURE` | Technical Error - Please wait a few minutes and try again. |
| `SCA_REQUIRED` | Authentication 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_LIMIT` | Spending limit exceeded. Please review the set limits and try again. |
| `SYSTEM_MALFUNCTION` | Technical Error - Please wait a few minutes and try again. |
| `TRANSACTION_NOT_ALLOWED` | Your card can not be used at this terminal type. |
| `UNKNOWN` | The 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_FUNCTION` | The 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)](/api-reference/onboarding/webhooks/webhook-events/paths/card_authorization_decline_v2/post) 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. |
| `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. Please contact us for further details. |
| `CARD_INACTIVE` | This card is 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` | The daily limit for cash withdrawals has been reached. Please contact us for further details. |
| `CASH_ADVANCE_AMOUNT_LIMIT_REACHED_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. |
| `EXPIRY_DATE_INVALID` | 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. |
| `INVALID_PIN_BLOCKED` | Card is blocked due to incorrect PIN attempts. Please reset the PIN and try again. |
| `PIN_ENTRY_TIMEOUT` | There was an issue with the merchant terminal. Please try again. |
| `PIN_INCORRECT` | Incorrect PIN entered. Please try again. |
| `REPLACEMENT_CARD_ACTIVATED` | You reordered and activated a card with the same PAN, but the CVV and expiry date have changed with the new card. |
| `RETRY_WITH_CHIP_AND_PIN` | 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 III: pos_entry_mode values](#appendix-iii-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](#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 table describes values for the **POST Report a card as lost/stolen** endpoint, which is **deprecated.** Use the [POST Replace a card](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1replace/post) 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.

| Enum | Description |
|  --- | --- |
| `COUNTERFEIT_PLASTIC` | Use when the card was cloned or counterfeited. |
| `HOME_INVASION` | Use when the customer has provided a police report confirming a home invasion. |
| `LEFT_AT_MERCHANT` | Use when the customer forgot the card at a merchant. |
| `LOST` | Use when the customer lost the card outside of their home. |
| `MAIL_ORDER` | Use in case of fraud related to email scams, PAN phishing, or other mail-related security data/quantities. |
| `MAILBOX_THEFT` | Use when the customer has provided a police report confirming mailbox theft. |
| `MISSING_AT_HOME` | Use when the customer lost the card at home. |
| `PICK_POCKET` | Use when the customer has provided a police report confirming pickpocketing. |
| `PREVENTIVE_BLOCK` | Use 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, 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**.)
    * 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 Replace a card**, supplying one of the [lost/stolen values](#card-reason-values) for the `reason` property.
    * If you order a **replacement card**, the card's status will transition to **INACTIVE**. Then, when the customer receives and activates the replacement, your solution calls **POST Activate a card**. The card's status transitions to **ACTIVE**.
    * If you **don't order** a replacement, 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](#card-reason-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](#card-reason-values) for the `reason` property.
  * If you order a **replacement card**, 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, 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](#card-reason-values) for the `reason` property.
  * If you order a **replacement card**, 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, the card's status transitions to **CLOSED_BY_SOLARIS**. This status is final.


### Card status flow: Card replacement

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**, supplying one of the [reissue or replace values](#card-reason-values) for the `reason` property.
  * 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**, supplying one of the [reissue or replace values](#card-reason-values) for the `reason` property.
  * 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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1replace/post), the card status changes based on the provided `loss_reason`. This table explains which card status results from each possible `loss_reason`:

| loss_reason value | Resulting card status |
|  --- | --- |
| `COUNTERFEIT_PLASTIC` | `COUNTERFEIT_CARD` |
| `HOME_INVASION` | `STOLEN` |
| `LEFT_AT_MERCHANT` | `LOST` |
| `LOST` | `LOST` |
| `MAIL_ORDER` | `FRAUD` |
| `MAILBOX_THEFT` | `NEVER_RECEIVED` |
| `MISSING_AT_HOME` | `LOST` |
| `PICK_POCKET` | `STOLEN` |
| `PREVENTIVE_BLOCK` | `COUNTERFEIT_CARD` |
| `SUSPECTED_MERCHANT_FRAUD` | `FRAUD` |