# 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/_spec/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 ) 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 . ## 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 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 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 . 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. 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 parameter. Note that you must use the 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 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 . 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: 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. 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 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 and 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 and 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 and of the request. This endpoint replaces the old version. However, please note that you have to set the header to the version you want (e.g., ). 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. This endpoint replaces the old version. However, please note that you have to set the header to the version you want (e.g., ). If you do not specify an , 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. This endpoint replaces the old version. However, please note that you have to set the header to the version you want (e.g., ). If you do not specify an , 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.. This endpoint replaces the old version. However, please note that you have to set the header to the version you want (e.g., ). If you do not specify an , 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 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 ### (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 on CARD_AUTHORIZATION or CARD_AUTHORIZATION_DECLINE_V2 (depending on whether the test transaction should be approved or declined). The API returns a corresponding with the created transaction. You can query info about the transaction using GET Index account bookings or GET Index reservations. Please the following: This is a The account associated with the card specified in must have an ### (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 that corresponds with the created transaction. You can query info about the transaction using GET Index account bookings or GET Index reservations. Please the following: The account associated with the card specified in must have an ### (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 and . The API returns a that corresponds with the created transaction. You can query info about the transaction using GET Index account bookings or GET Index reservations. Please the following: This is a The account associated with the card specified in must have an ### (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 . The API returns the response code and an empty response body. This is a ## 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.