# Cards servicing ## Create a card - [POST /v1/persons/{person_id}/accounts/{account_id}/cards](https://docs.solarisgroup.com/api-reference/digital-banking/cards/cards-servicing/paths/~1v1~1persons~1%7Bperson_id%7D~1accounts~1%7Baccount_id%7D~1cards/post.md): Creates a card in the name of the person specified in the request URL and attaches it to the given account. Please note the following: * The cardholder name (i.e., the value of ) is automatically generated. You must enter a value as close to the cardholder's actual name as possible. * The value of and may not exceed 21 characters. * You must enter a between the cardholder's first and last name(s). Example: * You may only use the following characters in the value of and : . Please convert accented characters to their non-accented equivalents (e.g., converting to , to ). * Card activation requests are blocked for the first 24 hours after card creation. In order to test on with immediate activation, please include the string within the property. See the request example on the right for information on how to use it. You can set an encrypted PIN for the card by completing the below steps: 1. In your backend, retrieve the encryption key in JWK format with the and make it available to the customer's device. 2. On the customer's device, collect the customer's desired PIN through a text input in your frontend and store it as a string containing a JSON-formatted object . 3. On the customer's device, parse the received encryption key JWK from the first step (you may want to use a suitable library of your choice, e.g., JOSESwift for iOS or Nimbus JOSE for Android). 4. On the customer's device, encrypt the string containing the new PIN from step 2 into a JWE using the previously received encryption key and the following properties: 1. Algorithm: . 2. Encryption method: . 3. Key ID: property from the encryption key JWK. 5. On the customer's device, generate the compact serialization of the JWE created in the previous step—this will be used as the parameter. 6. The property from is the in the request. 7. Call this endpoint from your backend. ## List all cards for a person - [GET /v1/persons/{person_id}/cards](https://docs.solarisgroup.com/api-reference/digital-banking/cards/cards-servicing/paths/~1v1~1persons~1%7Bperson_id%7D~1cards/get.md): Returns all cards associated with the person provided in the request URL ## List all cards for a business - [GET /v1/businesses/{business_id}/cards](https://docs.solarisgroup.com/api-reference/digital-banking/cards/cards-servicing/paths/~1v1~1businesses~1%7Bbusiness_id%7D~1cards/get.md): Returns all cards associated with the business specified in the request URL. ## List all cards for an account - [GET /v1/accounts/{account_id}/cards](https://docs.solarisgroup.com/api-reference/digital-banking/cards/cards-servicing/paths/~1v1~1accounts~1%7Baccount_id%7D~1cards/get.md): Returns all cards associated with the cardAccount specified in the request URL. ## Show a card - [GET /v1/cards/{id}](https://docs.solarisgroup.com/api-reference/digital-banking/cards/cards-servicing/paths/~1v1~1cards~1%7Bid%7D/get.md): Returns information about the card specified in the request URL. ## List all cards - [GET /v1/cards](https://docs.solarisgroup.com/api-reference/digital-banking/cards/cards-servicing/paths/~1v1~1cards/get.md): Returns all cards associated with partner. ## Activate a card - [POST /v1/cards/{card_account_id}/activate](https://docs.solarisgroup.com/api-reference/digital-banking/cards/cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1activate/post.md): Activates the card with the ID specified in the request URL. Please note the following : The must have a status value of or (if activating a replacement card). The to which the card is tied must have a blocking_status value of . You can also include in the request the and . These are optional parameters you can collect from the cardholder upon receipt of their card in the mail, to ensure they are activating the right card. You can then verify both parameters against the card details you have on file for the customer, before sending the activation request to Solaris. Solaris will then perform a validation of both parameters before accepting the request. : Card activation requests are blocked for the first 24 hours after card creation. In order to test on with immediate activation, please include the string WITHSTATICTOKEN within the property when creating a card. ## Block a card - [POST /v1/cards/{card_account_id}/block](https://docs.solarisgroup.com/api-reference/digital-banking/cards/cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1block/post.md): Blocks the card with the ID specified in the request URL. Note that the card must have a status value of in order to be blocked. ## Unblock a card - [POST /v1/cards/{card_account_id}/unblock](https://docs.solarisgroup.com/api-reference/digital-banking/cards/cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1unblock/post.md): Unblocks the card specified in the request URL. Please note that the card must have the status of in order for you to unblock it with this method. If the card has the status , then you cannot unblock it with this method. ## Replace a card - [POST /v1/cards/{card_account_id}/replace](https://docs.solarisgroup.com/api-reference/digital-banking/cards/cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1replace/post.md): Issues a replacement for the card specified in the request URL. Specify the appropriate in your request to trigger the right replacement process: a card expiring soon: a damaged card (physical card only): , (Deprecated) Report a card as and request a replacement (physical cards only): , , , , Please note the following: For the or 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 , then or depending on the card's status prior to ordering. The value of the property on the card resource will change to . 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 will change to . For the 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. Accepted card statuses: : , and : , , , Please note that on a given card can only be replaced once. ## Close a card - [POST /v1/cards/{card_account_id}/close](https://docs.solarisgroup.com/api-reference/digital-banking/cards/cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1close/post.md): Closes the card with the ID specified in the request URL. In order to be closed, the card must have one of the following statuses: ## Create a secure view for card details - [POST /v1/cards/{id}/virtual_card_requests](https://docs.solarisgroup.com/api-reference/digital-banking/cards/cards-servicing/paths/~1v1~1cards~1%7Bid%7D~1virtual_card_requests/post.md): Retrieves the card number, expiry date, and CVV for the card specified in the request URL. The response is encrypted; your customer must decrypt it using a bound device. Please note the following prerequisites: * Your customer's device must have a supported operating system (Android: 4.3 or higher; iOS: iPhone 5 or newer, not jailbroken or rooted). * The customer must have already verified their device using the device binding process. You will need to supply the in this request. > > > You may only make clean PAN details available in the device's ## (Deprecated) Report a card as lost or stolen (deprecated) - [POST /v1/cards/{card_account_id}/lost_stolen_incidents](https://docs.solarisgroup.com/api-reference/digital-banking/cards/cards-servicing/paths/~1v1~1cards~1%7Bcard_account_id%7D~1lost_stolen_incidents/post.md): Please use the POST Replace a card endpoint instead. Read the endpoint summary to learn how to use the endpoint for the lost/stolen use case. Reports the card specified in the request URL as lost or stolen. The card will be immediately blacklisted. Please note the following: Please note that cards can only be reported lost or stolen without requesting a replacement. The of the card must only be one of the following values: , , , or . Only use this endpoint in the event that the card is lost or stolen or if the card details have been compromised. If a physical card is damaged, please use the endpoint. You can order a replacement card in the same API call by setting the value of to . When a card has been reported as lost or stolen, it immediately stops working. This action cannot be undone. If the customer has added their card to Google Pay or Apple Pay, reports it lost or stolen, and requests a replacement at the same time, then the lost/stolen card will continue to work. If the cardholder believes that their card and phone were both compromised, then you should not order them a replacement card in the same API call. Instead, use the endpoint to order them a new one. For you must set the value of to .