# Card creation & servicing Version: 1.0 ## Servers Sandbox ``` https://api.solaris-sandbox.de ``` Production ``` https://api.solarisbank.de ``` ## Download OpenAPI description [Card creation & servicing](https://docs.solarisgroup.com/_bundle/api-reference/digital-banking/cards.yaml) ## 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 line_1) is not automatically generated. You must enter a value as close to the cardholder's actual name as possible. * The value of line_1 and line_2 may not exceed 21 characters. * You must enter a / between the cardholder's first and last name(s). Example: ADAM AARON/SCHMIDT * You may only use the following characters in the value of line_1 and line_2: ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 -/.. Please convert accented characters to their non-accented equivalents (e.g., converting Ö to OE, É to E). * Card activation requests are blocked for the first 24 hours after card creation. In order to test on Sandbox with immediate activation, please include the string WITHSTATICTOKEN within the line_1 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 GET Retrieve latest public key method 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 {"pin": ""}. 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: RSA-OAEP-256. 2. Encryption method: A256CBC-HS512. 3. Key ID: kid 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 encrypted_pin parameter. 6. The kid property from GET /v1/cards/pin_keys/latest is the kid 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 preconditions: The card must have a status value of ACTIVE or INACTIVE (if activating a replacement card). The account to which the card is tied must have a blocking_status value of NO_BLOCK. You can also include in the request the pan_last_4_digit and expiry_date. 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. Note: Card activation requests are blocked for the first 24 hours after card creation. In order to test on Sandbox with immediate activation, please include the string WITHSTATICTOKEN within the line_1 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 ACTIVE 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 BLOCKED in order for you to unblock it with this method. If the card has the status BLOCKED_BY_SOLARIS, 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 reason in your request to trigger the right replacement process: Reissue a card expiring soon: EXPIRES_SOON Replace a damaged card (physical card 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 Please note the following: 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. Accepted card statuses: Reissue: ACTIVE, INACTIVE Replace and Lost/Stolen: ACTIVE, INACTIVE, BLOCKED, BLOCKED_BY_SOLARIS Please note that on Sandbox 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. Note: this action cannot be undone. In order to be closed, the card must have one of the following statuses: ACTIVE BLOCKED COUNTERFEIT_CARD FRAUD INACTIVE LOST NEVER_RECEIVED STOLEN ### 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 device_id in this request. > Warning > > Never store or log decrypted card details on a customer's device. This information may never leave the device. You may only make clean PAN details available in the device's temporary memory. ### (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): Note: This endpoint is deprecated. 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 virtual cards can only be reported lost or stolen without requesting a replacement. The status of the card must only be one of the following values: ACTIVE, INACTIVE, BLOCKED, or BLOCKED_BY_SOLARIS. 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 POST Replace a card endpoint. You can order a replacement card in the same API call by setting the value of order_replacement to true. 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 POST Create a card endpoint to order them a new one. For sandbox testing, you must set the value of lost_at to 2021-06-03T18:31:09+00:00. ## Encrypted PIN Change ### Retrieve latest public key - [GET /v1/cards/pin_keys/latest](https://docs.solarisgroup.com/api-reference/digital-banking/cards/encrypted-pin-change/solaris_cards_pin_service_get_pin_keys_aa.md): Returns the latest Solaris public RSA key in JWK format. Call this method every time before you call the POST Change card PIN method to ensure you have the latest key. See RFC7517 for more information on JWKs. ### Change card PIN - [POST /v1/cards/{card_account_id}/pin_update_requests](https://docs.solarisgroup.com/api-reference/digital-banking/cards/encrypted-pin-change/solaris_cards_pin_service_save_pin.md): Changes the PIN of the card specified in the request URL. Follow these instructions to use this endpoint: 1. In your backend, retrieve the encryption key in JWK format with the GET Retrieve latest public key method 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 string containing a JSON-formatted object {"pin": ""}. 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: RSA-OAEP-256 2. Encryption method: A256CBC-HS512 3. Key ID: kid 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 encrypted_pin parameter. 6. On the customer's device, sign the serialized JWE of the previous step using the cardholder's private key from their bound device — this is the signature parameter. Note that you must use the restricted key. 7. Transfer the values generated in the previous two steps (serialized JWE and created signature) to your backend. 8. Call this endpoint from your backend. ### Change card PIN with Change Request - [POST /v1/cards/{card_account_id}/sca_pin_update_requests](https://docs.solarisgroup.com/api-reference/digital-banking/cards/encrypted-pin-change/solaris_cards_sca_pin_service_save_pin.md): Changes the PIN of the card specified in the request URL using the Change Request process. Follow these instructions to use this endpoint: 1. Retrieve the encryption key in JWK format with the GET Retrieve latest public key method and make it available. 2. Collect the customer's desired PIN through a text input in your frontend and store it as string containing a JSON-formatted object {"pin": ""}. 3. 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. 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: RSA-OAEP-256 2. Encryption method: A256CBC-HS512 3. Key ID: kid 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 encrypted_pin parameter. 6. Call this endpoint from your backend. ### (Deprecated) Retrieve latest public key (deprecated) - [GET /v1/cards/{card_account_id}/pin_keys/latest](https://docs.solarisgroup.com/api-reference/digital-banking/cards/encrypted-pin-change/solaris_cards_pin_service_get_pin_keys.md): Deprecated endpoint. Returns the latest Solaris public RSA key in JWK format. Call this method every time before you call the POST Change card PIN method to ensure you have the latest key. See RFC7517 for more information on JWKs. ## Card spending controls ### Create card controls list - [POST /v1/card_controls/lists](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-spending-controls/createcardcontrollist.md): Creates a card controls list and applies it to all cards defined in the scope and scope_id of the request. ### Index card controls lists - [GET /v1/card_controls/lists](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-spending-controls/indexcardcontrollist.md): Returns an array containing all active card controls lists in place for your customers. ### Retrieve a card controls list - [GET /v1/card_controls/lists/{id}](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-spending-controls/showcardcontrollist.md): Returns the card controls list with the ID specified in the request URL. ### Delete card controls list - [DELETE /v1/card_controls/lists/{id}](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-spending-controls/deletecardcontrollist.md): Deletes the card controls list specified in the request URL. ### Create card spending limit control - [POST /v1/card_controls/spending_limits](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-spending-controls/createcardcontrolspendinglimit.md): Creates a card spending limit control and applies it to all cards defined in the scope and scope_id of the request. ### Index card spending limit controls - [GET /v1/card_controls/spending_limits](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-spending-controls/indexcardcontrolspendinglimit.md): Returns all active card spending limit controls. ### Retrieve a card spending limit control - [GET /v1/card_controls/spending_limits/{id}](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-spending-controls/showcardcontrolspendinglimit.md): Returns information about the card spending limit control specified in the request URL. ### Delete card spending limit control - [DELETE /v1/card_controls/spending_limits/{id}](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-spending-controls/deletecardcontrolspendinglimit.md): Deletes the card spending limit control specified in the request URL. ### Create card spending limit control (V2) - [POST /v1/card_controls/spending_limits(use api-version-header to consume this endpoint)](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-spending-controls/createcardcontrolspendinglimitv2.md): Creates a card spending limit control and applies it to all cards defined in the scope and scope_id of the request. Important This endpoint replaces the old version. However, please note that you have to set the Api-Version header to the version you want (e.g., 2024-01-01). If you do not specify a version, then the API will return the older version of the response. ### Index card spending limit controls (V2) - [GET /v1/card_controls/spending_limits(use api-version-header to consume this endpoint)](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-spending-controls/indexcardcontrolspendinglimitv2.md): Returns all active card spending limit controls. Important This endpoint replaces the old version. However, please note that you have to set the Api-Version header to the version you want (e.g., 2024-01-01). If you do not specify an Api-Version, then the API will return the older version of the response. ### Retrieve a card spending limit control (V2) - [GET /v1/card_controls/spending_limits/{id}(use api-version-header to consume this endpoint)](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-spending-controls/showcardcontrolspendinglimitv2.md): Returns information about the card spending limit control specified in the request URL. Important This endpoint replaces the old version. However, please note that you have to set the api-version header to the version you want (e.g., 2024-01-01). If you do not specify an api-version, then the API will return the older version of the response. ### Delete card spending limit control (V2) - [DELETE /v1/card_controls/spending_limits/{id}(use api-version-header to consume this endpoint)](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-spending-controls/deletecardcontrolspendinglimitv2.md): Deletes the card spending limit control specified in the request URL.. Important This endpoint replaces the old version. However, please note that you have to set the api-version header to the version you want (e.g., 2024-01-01). If you do not specify an api-version, then the API will return the older version of the response. ## Card transactions ### Allow a transaction that was marked as fraudulent - [POST /v1/cards/{card_id}/fraud_cases/{id}/whitelist](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-transactions/paths/~1v1~1cards~1%7Bcard_id%7D~1fraud_cases~1%7Bid%7D~1whitelist/post.md): This endpoint confirms that a transaction marked as fraudulent was not actually fraudulent (i.e., the customer confirms that they made the transaction themselves or is otherwise aware of the transaction). Once you call this endpoint, fraud monitoring will be disabled for the card specified in the request URL for 10 minutes, and the transaction can be attempted again. ### Confirm a fraud case - [POST /v1/cards/{card_id}/fraud_cases/{id}/confirm](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-transactions/paths/~1v1~1cards~1%7Bcard_id%7D~1fraud_cases~1%7Bid%7D~1confirm/post.md): This endpoint confirms to Solaris that a fraud case was indeed fraudulent. The card used to make the fraudulent transaction will be subsequently blocked. You should then redirect your customer to your customer support so that a replacement card can be issued. ### Decline 3DS authentication - [POST /v1/cards/3ds/{challenge_id}/decline](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-transactions/paths/~1v1~1cards~13ds~1%7Bchallenge_id%7D~1decline/post.md): This endpoint marks the 3DS authentication specified by the challenge_id in the request URL as declined. The challenge must not have already expired. ### Index card transactions - [GET /v1/cards/{card_id}/transactions](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-transactions/indexcardtransactions.md): Returns all card transactions associated with the card ID specified in the request URL. Use the filter parameters to narrow down the results according to your needs. ## Card transactions simulation ### (Sandbox only) Create test fraud case - [POST /v1/cards/{card_id}/test_fraud_cases](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-transactions-simulation/paths/~1v1~1cards~1%7Bcard_id%7D~1test_fraud_cases/post.md): This endpoint simulates a fraudulent transaction for the card specified in the request URL. The fraudulent transaction process will begin as a result. This endpoint is only available on Sandbox. ### (Sandbox only) Create test 3DS transaction - [POST /v1/cards/{card_id}/test_3ds_authentication](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-transactions-simulation/paths/~1v1~1cards~1%7Bcard_id%7D~1test_3ds_authentication/post.md): This endpoint simulates a test 3DS transaction for the card_id specified in the request URL. Calling this endpoint will begin the 3DS transaction process. The API will return a JSON schema containing the HTML for the 3DS challenge screen. This endpoint is only available on Sandbox. ### (Beta, sandbox only) Simulate an authorization - [POST /v1/cards/{card_id}/simulator/transactions/authorization](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-transactions-simulation/paths/~1v1~1cards~1%7Bcard_id%7D~1simulator~1transactions~1authorization/post.md): Creates a simulated card authorization for the purpose of testing approval & denial flows. Calling this endpoint will trigger a webhook notification on CARD_AUTHORIZATION or CARD_AUTHORIZATION_DECLINE_V2 (depending on whether the test transaction should be approved or declined). The API returns a transaction_key corresponding with the created transaction. You can query info about the transaction using GET Index account bookings or GET Index reservations. Please note the following: This is a beta endpoint. The account associated with the card specified in card_id must have an available balance. ### (Beta, sandbox only) Simulate an unauthorized settlement - [POST /v1/cards/{card_id}/simulator/transactions/settle](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-transactions-simulation/paths/~1v1~1cards~1%7Bcard_id%7D~1simulator~1transactions~1settle/post.md): Creates a simulated unauthorized settlement. The API returns a transaction_key that corresponds with the created transaction. You can query info about the transaction using GET Index account bookings or GET Index reservations. Please note the following: The account associated with the card specified in card_id must have an available balance. ### (Beta, sandbox only) Simulate the settlement of an authorization - [POST /v1/cards/{card_id}/simulator/transactions/{transaction_key}/settle](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-transactions-simulation/paths/~1v1~1cards~1%7Bcard_id%7D~1simulator~1transactions~1%7Btransaction_key%7D~1settle/post.md): Executes a test card authorization settlement for the given card_id and transaction_key. The API returns a transaction_key that corresponds with the created transaction. You can query info about the transaction using GET Index account bookings or GET Index reservations. Please note the following: This is a beta endpoint. The account associated with the card specified in card_id must have an available balance. ### (Beta, sandbox only) Simulate an expired card authorization - [POST /v1/cards/simulator/authorization/{transaction_key}/expire](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-transactions-simulation/paths/~1v1~1cards~1simulator~1authorization~1%7Btransaction_key%7D~1expire/post.md): Marks the card authorization as expired for the given transaction_key. The API returns the 202 (Accepted) response code and an empty response body. Note: This is a beta endpoint. ## Card Delivery Tracking API ### Retrieve card tracking information - [GET /v1/cards/{cardId}/delivery_trackings](https://docs.solarisgroup.com/api-reference/digital-banking/cards/card-delivery-tracking-api/solaris_cards_service_public_card_delivery_trackings.md): Returns tracking information for the card with the ID specified in the request URL.