# 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](/guides/cards#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](/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). Please 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 the [list below](#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 the [list below](#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.  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](#cardholder-name-and-address-generation).
- `type`: The card type. View [here](#appendix-i-card-types) 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 SIA. The API will respond with the ID of the card and the status of `PROCESSING`.


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

[Click here to view the 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 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:**


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

[Click here to view the 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, you can activate the card using the following endpoint:

**Request URL:**


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

[Click here to view the 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 wallet, implement the relevant endpoints in the [Card Push Provisioning guide](/guides/cards/push-provisioning).

### How to block/unblock a card

Use [POST Block a card](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1block/post) to block a customer's debit card. As a prerequisite,
the card must have a `status` of `ACTIVE`.

Use [POST Unblock a card](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1unblock/post) 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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1replace/post) 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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1persons~1%7Bperson_id%7D~1accounts~1%7Baccount_id%7D~1cards/post).


#### 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](/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 or stolen. See the section above for detailed instructions.

The [POST Report a card as lost or stolen](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1replace/post) is **deprecated.** Please use POST Replace a card instead.

### Cards API reference

[Click here to see 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. 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 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/#tag/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. |
| `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. |
| `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_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. |
| `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. |
| `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/#tag/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. 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_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 X: 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 tables describes values for the [POST Report a card as lost/stolen](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1lost_stolen_incidents/post), which is **deprecated.** Please 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](#how-to-report-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](/assets/status-flow-create-activate.4d20bc8bff0f1a5ba15f46feb4ed56b5a5c82659518b3a27178d8881a237e5ca.aebdbb0d.svg)

1. Your solution calls [POST Create a card](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1persons~1%7Bperson_id%7D~1accounts~1%7Baccount_id%7D~1cards/post) 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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1activate/post).
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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1close/post). The card's status transitions to **CLOSED.** This status is final.


### Card status flow: Card blocking

![Card status flow: Card blocking](/assets/status-flow-blocking.fbcb54763b45a419dd31d6238f6d861d6a3ca5213b1bd67b39300adbd50a8bd5.aebdbb0d.svg)

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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1unblock/post).
    - The card's status transitions back to **ACTIVE.**
  3. The customer reports the card as lost/stolen.
    - Your solution calls [POST Replace a card](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1replace/post), supplying one of the [lost/stolen values](/guides/cards/creation-and-servicing/#card-reason-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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1activate/post). 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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1replace/post), supplying one of the [replace values](/guides/cards/creation-and-servicing/#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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1close/post).
    - 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](/assets/status-flow-lost-stolen.6eff429c84e4f3f32ca678ac7e2b7d77b44c009d462b47cc186bc7dafc482f06.aebdbb0d.svg)

1. Your solution calls [POST Create a card](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1persons~1%7Bperson_id%7D~1accounts~1%7Baccount_id%7D~1cards/post) 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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1replace/post), supplying one of the [lost/stolen values](/guides/cards/creation-and-servicing/#card-reason-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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1activate/post). 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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1replace/post), supplying one of the [lost/stolen values](/guides/cards/creation-and-servicing/#card-reason-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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1activate/post). 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: ](/assets/status-flow-replace.0f43e7a17aa00d0248283ad3efedfc79381e7ea00e189696a04003099835e2d3.aebdbb0d.svg)

1. Your solution calls [POST Create a card](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1persons~1%7Bperson_id%7D~1accounts~1%7Baccount_id%7D~1cards/post) 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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1replace/post), supplying one of the [reissue or replace values](/guides/cards/creation-and-servicing/#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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1activate/post).
  - 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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1replace/post), supplying one of the [reissue or replace values](/guides/cards/creation-and-servicing/#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](/api-reference/digital-banking/cards/#tag/Cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1activate/post).
  - 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` |