Card creation & servicing (1.0)

Download OpenAPI specification:Download

Cards servicing

Create a card

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 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 endpoint from your backend.

Request
Security:
path Parameters
person_id
required
string

Solaris UID for person

account_id
required
string

Solaris UID for account

Request Body schema: application/json
line_1
required
string

The cardholder's name as it should be printed on the card. Please note the guidelines for this field as written in the method description above.

line_2
string

An additional field to print another line of text on the card. Can be used for a variety of use cases to fit your business needs. Please note the guidelines for this field as written in the method description above.

type
required
string (Solaris-Enums-CardType)

The type of the card. Note The following enum list is not exhaustive but only indicative of some possible values.

Enum: "MASTERCARD_DEBIT" "MASTERCARD_BUSINESS_DEBIT" "VIRTUAL_MASTERCARD_DEBIT" "VIRTUAL_MASTERCARD_BUSINESS_DEBIT" "VIRTUAL_MASTERCARD_FREELANCE_DEBIT" "VISA_DEBIT" "VISA_BUSINESS_DEBIT" "VIRTUAL_VISA_DEBIT" "VIRTUAL_VISA_BUSINESS_DEBIT" "VIRTUAL_VISA_FREELANCE_DEBIT" "VISA_CREDIT" "VIRTUAL_VISA_CREDIT" "VISA_BUSINESS_CREDIT" "VIRTUAL_VISA_BUSINESS_CREDIT"
business_id
string

(For business cards) ID of the business with which to associate the card.

reference
string

A unique reference for the card. This field is mandatory, and the API will check it for uniqueness.

shipping_priority
string

Shipping priority to assign to the card.

Enum: "0" "1" "2" "3" "4" "5" "6"
encrypted_pin
string

The encrypted PIN value (JWE in compact serialization). See the description of this method for instructions on how to produce this value.

key_id
string

Solaris' public RSA key ID. Returned as the kid property by the GET /v1/cards/pin_keys/latest endpoint.

Responses
201

Successful creation

400

Validation error.

403

You are not authorized to perform this action.

404

The resource could not be found.

500

Internal server error.

default

Unexpected error

post/v1/persons/{person_id}/accounts/{account_id}/cards
Request samples
application/json
{
  • "line_1": "MICHAEL WITHSTATICTOKEN/MUSTERMANN",
  • "line_2": "TEST COMPANY GMBH",
  • "type": "MASTERCARD_BUSINESS_DEBIT",
  • "business_id": "52e6a9b8a559d842ed7d8901b0e1bf4bcbiz",
  • "reference": "61a50bf05278217a57e5ad15ed259e44",
  • "shipping_priority": "0",
  • "encrypted_pin": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwia2lkIjoiN2FkOTFjYWQtODU0NC00ZmQyLWJlNDgtNDcyOTU3MGEzOTRhIn0.bDPrZvlJ9slqZ9WDy_PDCZrKCvFyLanAeDItyDFdaiRvQbsTdoDE5Y-etWN--y25HkMKzpbC0CIJHdN7kLa225Ax2O6SPaxDkGGNSQPKzkxXmimpv9zaRYNCVQ67KdVTK6WOVLjOVRBKZDba9zvzfKvXlBYqj51WyQR_yvxrXTPftX3IQkDo8RjdaB6tr9HugdimbqOiMgiNSOHAn0G-Zi6tkwL0TLlA5_8xzUec40vaBvEoTBc_OZjZy7s7ebKzS8Hhg6NF9CemeMIEwes8ZzO1s1385PCxLhce0KEekVUoCjrLP9QhoYSjQUTUNrxkn4h0ZnicF5ycbW36Ivt8mQ.sAtSq_rfcxxlQiQc2qZ0Kg.bW53DScq6C8vnqD620Lnuw.MYGA-87sfGrFupu2FqC3Ick_EvwCA5vO2tPktS1yJPg",
  • "key_id": "7ad91cad-8544-4fd2-be48-4729570a394a"
}
Response samples
application/json
{
  • "id": "8febdba4912a747808ccc6f95f82bbb4mcrd",
  • "status": "PROCESSING"
}

List all cards for a person

Returns all cards associated with the person provided in the request URL

Request
Security:
path Parameters
person_id
required
string
query Parameters
filter[status]
string

Filter the results by the card status

page[number]
integer
Default: 1

Page number to return

page[size]
integer
Default: 10

The number of results per page to return

Responses
200

Successful result of the operation

400

Invalid request.

403

You are not authorized to perform this action.

404

The resource could not be found.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/cards
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/cards?filter%5Bstatus%5D=string&page%5Bnumber%5D=1&page%5Bsize%5D=10'
Response samples
application/json
[
  • {
    }
]

List all cards for a business

Returns all cards associated with the business specified in the request URL.

Request
Security:
path Parameters
business_id
required
string
query Parameters
page[number]
integer
Default: 1

The number of results pages to return.

page[size]
integer
Default: 10

The size of each page in the response.

Responses
200

Successful result of the operation

400

Invalid request.

403

You are not authorized to perform this action.

404

The resource could not be found.

500

Internal server error.

default

Unexpected error

get/v1/businesses/{business_id}/cards
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/businesses/{business_id}/cards?page%5Bnumber%5D=1&page%5Bsize%5D=10'
Response samples
application/json
[
  • {
    }
]

List all cards for an account

Returns all cards associated with the cardAccount specified in the request URL.

Request
Security:
path Parameters
account_id
required
string

Solaris UID for account

query Parameters
page[number]
integer
Default: 1

The number of results pages to return.

page[size]
integer
Default: 10

The size of each page in the response.

Responses
200

Successful result of the operation

400

Validation error.

403

You are not authorized to perform this action.

404

The resource could not be found.

500

Internal server error.

default

Unexpected error

get/v1/accounts/{account_id}/cards
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/accounts/{account_id}/cards?page%5Bnumber%5D=1&page%5Bsize%5D=10'
Response samples
application/json
[
  • {
    }
]

Show a card

Returns information about the card specified in the request URL.

Request
Security:
path Parameters
id
required
string
Responses
200

Successful result of the operation

400

Invalid request.

403

You are not authorized to perform this action.

404

The resource could not be found.

500

Internal server error.

default

Unexpected error

get/v1/cards/{id}
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/cards/{id}'
Response samples
application/json
{
  • "id": "8febdba4912a747808ccc6f95f82bbb4",
  • "status": "ACTIVE",
  • "reference": "87285d83-ab15-4906-af87-5763801d9e43",
  • "type": "MASTERCARD_DEBIT",
  • "expiration_date": "2020-12-30",
  • "new_card_ordered": false,
  • "person_id": "5af2ea4271038d5c53e68ccbf4fe43b3cper",
  • "account_id": "a5844f601567db9b59b3531245a58e96cacc",
  • "business_id": "52e6a9b8a559d842ed7d8901b0e1bf4bcbiz",
  • "representation": {
    },
  • "creation_date": "2022-05-01",
  • "sia_account_number": "500001650679"
}

List all cards

Returns all cards associated with partner.

Request
Security:
query Parameters
filter[business_id]
string

Filter the results by the ID of the business associated with the card.

filter[person_id]
string

Filter the results by the ID of the person associated with the card.

filter[person_uid]
string
Deprecated

Filter the results by the ID of the person associated with the card.

filter[account_id]
string

Filter on account id

filter[account_uid]
string
Deprecated

Filter on account id

filter[status]
string

Filter the results by the card status

filter[type]
string

Filter the results by the card type.

filter[masked_pan]
string

Filter the results by the card's masked PAN.

filter[line_1]
string

Filter the cards by the value of their address line 1.

filter[sia_account_number]
string

Filter the results by the SIA account number.

page[number]
integer
Default: 1

The number of results pages to return.

page[size]
integer
Default: 10

The size of each page in the response.

Responses
200

Successful result of the operation

400

Invalid request.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/cards
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/cards?filter%5Bbusiness_id%5D=string&filter%5Bperson_id%5D=string&filter%5Bperson_uid%5D=string&filter%5Baccount_id%5D=string&filter%5Baccount_uid%5D=string&filter%5Bstatus%5D=string&filter%5Btype%5D=string&filter%5Bmasked_pan%5D=string&filter%5Bline_1%5D=string&filter%5Bsia_account_number%5D=string&page%5Bnumber%5D=1&page%5Bsize%5D=10'
Response samples
application/json
[
  • {
    }
]

Activate a card

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.

Request
Security:
path Parameters
card_account_id
required
string
Request Body schema: application/json
pan_last_4_digit
string

The last 4 digits of the card's PAN.

expiry_date
string

The card expiry date. Format should be mm/yy.

Responses
200

Successful result of the operation

400

Invalid request.

403

You are not authorized to perform this action.

404

The resource could not be found.

500

Internal server error.

default

Unexpected error

post/v1/cards/{card_account_id}/activate
Request samples
application/json
{
  • "pan_last_4_digit": "2314",
  • "expiry_date": "01/23"
}
Response samples
application/json
[
  • {
    }
]

Block a card

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.

Request
Security:
path Parameters
card_account_id
required
string
Responses
200

Successful result of the operation

400

Invalid request.

403

You are not authorized to perform this action.

404

The resource could not be found.

500

Internal server error.

default

Unexpected error

post/v1/cards/{card_account_id}/block
Request samples
curl -i -X POST \
  'https://api.solaris-sandbox.de/v1/cards/{card_account_id}/block'
Response samples
application/json
{
  • "expiration_date": "2020-12-30",
  • "new_card_ordered": false,
  • "person_id": "6dceb838ea04090aaa4277c7ea8a1c78cper",
  • "account_id": "6cbac416a5d91aaf5e6bc9ee15d58799cacc",
  • "business_id": "52e6a9b8a559d842ed7d8901b0e1bf4bcbiz",
  • "sia_account_number": "500000001103",
  • "creation_date": "2022-05-01",
  • "id": "2b890724292e287935420a2ca13ae7f9mcrd",
  • "status": "ACTIVE",
  • "reference": "b92b6840d6345b11f29b598c10bae770",
  • "type": "MASTERCARD_DEBIT",
  • "representation": {
    }
}

Unblock a card

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.

Request
Security:
path Parameters
card_account_id
required
string
Responses
200

Successful result of the operation

400

Invalid request.

403

You are not authorized to perform this action.

404

The resource could not be found.

500

Internal server error.

default

Unexpected error

post/v1/cards/{card_account_id}/unblock
Request samples
curl -i -X POST \
  'https://api.solaris-sandbox.de/v1/cards/{card_account_id}/unblock'
Response samples
application/json
{
  • "expiration_date": "2020-12-30",
  • "new_card_ordered": false,
  • "person_id": "6dceb838ea04090aaa4277c7ea8a1c78cper",
  • "account_id": "6cbac416a5d91aaf5e6bc9ee15d58799cacc",
  • "business_id": "52e6a9b8a559d842ed7d8901b0e1bf4bcbiz",
  • "sia_account_number": "500000001103",
  • "creation_date": "2022-05-01",
  • "id": "2b890724292e287935420a2ca13ae7f9mcrd",
  • "status": "ACTIVE",
  • "reference": "b92b6840d6345b11f29b598c10bae770",
  • "type": "MASTERCARD_DEBIT",
  • "representation": {
    }
}

Replace a card

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.

Request
Security:
path Parameters
card_account_id
required
string
Request Body schema: application/json
line_1
string

The name to print on the new card. For Replace flow only.

line_2
string

Additional optional embossing line. For Replace flow only.

reason
string
Default: "CARDHOLDER_REQUEST"

The reason why the customer is requesting a replacement card.

Enum: "CARDHOLDER_REQUEST" "COUNTERFEIT_PLASTIC" "DEFECTIVE_CARD" "EXPIRES_SOON" "LOST" "ONLINE_TRANSACTION_FRAUD" "PREVENTIVE_BLOCK" "STOLEN" "SUSPECTED_MERCHANT_FRAUD"
reference
string
Default: "718578ca-fb20-4c3e-9f07-c86b21711b2f"

Randomly generated UUID that acts as an idempotency key.

retain_pin
boolean

Indicates whether or not the new card should use the same PIN as the old one. For Replace and Reissue flows, default is true. For Lost/Stolen, default is false.

reported_at
string <date-time>

For Lost/Stolen flow only. Timestamp from when the card was reported (ISO 8601 format).

Responses
200

Successful result of the operation

400

Invalid request.

403

You are not authorized to perform this action.

404

The resource could not be found.

500

Internal server error.

default

Unexpected error

post/v1/cards/{id}/replace
Request samples
application/json
{
  • "line_1": "JOHN/DOE",
  • "line_2": "TEST GMBH",
  • "reason": "DEFECTIVE_CARD",
  • "reference": "7dc5377e-b90b-3401-b9a5-5dd094893e28",
  • "retain_pin": true,
  • "reported_at": "2020-01-13T09:56:24.000Z"
}
Response samples
application/json
{
  • "id": "2b890724292e287935420a2ca13ae7f9mcrd",
  • "status": "PROCESSING"
}

(Deprecated) Report a card as lost or stolenDeprecated

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.

Request
Security:
path Parameters
card_account_id
required
string
Request Body schema: application/json
loss_reason
required
string

The customer's reason for reporting the card as lost or stolen.

Enum: "COUNTERFEIT_PLASTIC" "HOME_INVASION" "LEFT_AT_MERCHANT" "LOST" "MAIL_ORDER" "MAILBOX_THEFT" "MISSING_AT_HOME" "PICK_POCKET" "PREVENTIVE_BLOCK" "SUSPECTED_MERCHANT_FRAUD"
lost_at
required
string <date-time>

Timestamp from when the card was lost (ISO 8601 format).

order_replacement
boolean

Boolean to indicate whether or not to order the customer a replacement card in the same API request. Note that you can set this to false and order the customer a new card in a separate API call, e.g., if they lost a tokenized card.

retain_pin
boolean

(If ordering a replacement card right away) Boolean to indicate whether the new card should retain the same PIN.

Responses
200

Successful result of the operation

400

Invalid request.

403

You are not authorized to perform this action.

404

The resource could not be found.

500

Internal server error.

default

Unexpected error

post/v1/cards/{card_account_id}/lost_stolen_incidents
Request samples
application/json
{
  • "loss_reason": "HOME_INVASION",
  • "lost_at": "2020-01-13T09:56:24.000Z",
  • "order_replacement": false,
  • "retain_pin": false
}
Response samples
application/json
[
  • {
    }
]

Close a card

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

Request
Security:
path Parameters
card_account_id
required
string
Responses
200

Successful result of the operation

400

Invalid request.

403

You are not authorized to perform this action.

404

The resource could not be found.

500

Internal server error.

default

Unexpected error

post/v1/cards/{card_account_id}/close
Request samples
curl -i -X POST \
  'https://api.solaris-sandbox.de/v1/cards/{card_account_id}/close'
Response samples
application/json
[
  • {
    }
]

Create a secure view for card details

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.

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.

Request
Security:
path Parameters
id
required
string
Request Body schema: application/json

The content of the request

device_id
required
string

ID of the customer's bound device.

device_data
string

Encoded device fingerprint generated using the Seon SDK. See the device monitoring guide for more information about generating this value.

signature
required
string

The device signature obtained during the device binding process. The signature must be generated using the device's unrestricted key.
Follow these steps to generate the key:

  1. Generate the RSA key pair. This results in an rsa_key.
  2. Create a JWK JSON representation of the public part of the rsa_key. This results in a jwk_key.
  3. Generate a single string from the jwk_key representation of the public part of the rsa_key using the following steps:
    1. Sort every key/value pair alphabetically by the key.
    2. Combine the key and value of every key/value pair using : as the delimiter, e.g., alg:RS256.
    3. Join every key/value pair to a single string using ; as the delimiter, e.g, alg:RS256;...;e:AQAB.
    4. This results in a key_string, whose format resembles this: alg:RS256;e:AQAB;kid:0016E6D1...35E6;kty:RSA;n:qp7...Q;use:enc
  4. Sign the key_string using the device's unrestricted key. This results in the signed_key. Read more about how to create an unrestricted key for use in device binding here.
  5. Hex-encode encode the signed_key to get the signature.

required
object

JSON Web Key (JWK) data that will be used to encrypt the card details. Click here to learn more about this algorithm.

required
object

JSON Web Encryption attributes.

Responses
200

Successful result of the operation

400

Validation error.

403

You are not authorized to perform this action.

404

The resource could not be found.

500

Internal server error.

default

Unexpected error

post/v1/cards/{id}/virtual_card_requests
Request samples
application/json
{
  • "device_id": "ZtzhX7M96stcA2LzDpX1Lg8dev",
  • "device_data": "Web;179ac83968ab42f79e960c1753a4078fdcon;jVl14emA+OcyALb9F+CMFg==;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",
  • "signature": "556F4558783743346570744B674D3838454E3444334F627141394E696735726B3946593739356B413353337359767A34756F387977754D2F4658536134327A41394454716D3337616570764335346A477276744579376246514B546C79465A6A7A532F577545722B4946644A4A2F674953784E7A715451765A3077432B39486E6F4B7A36447050725537695657476A626B3057366549746363312F577654742F39594D4B726B7541506E49426B4A74426B737254687867562B3169636155582B432B426F41696A64544A314D773774624F70556F4C686257392F496936773235744472494E33564A6166446E6F634E523438335469595568382B70343946703473395971434872503270395959616B513155795673444635504B45596B75784A2F7A797933334779686732744D5473435238476B7959657648372F31733532472B6C73573048754F597A4C364E324954426B6C666D413D3D0D0A",
  • "jwk": {
    },
  • "jwe": {
    }
}
Response samples
application/json
{
  • "data": "W2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awaW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awaW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awaW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awaW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awaW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awa"
}

Encrypted PIN Change

Retrieve latest public key

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.

Request
Security:
Responses
200

The public key was fetched successfully.

401

Invalid/missing OAuth token.

403

Unauthorized action.

404

The card could not be found.

500

Internal server error.

get/v1/cards/pin_keys/latest
Request samples
curl -i -X GET \
  https://api.solaris-sandbox.de/v1/cards/pin_keys/latest
Response samples
application/json
{
  • "kid": "0dce6f4d-b5d0-4c7b-a7d8-cfe231a1f385",
  • "kty": "RSA",
  • "use": "enc",
  • "alg": "RS256",
  • "n": "ielfymjYSKEeeai7pFBhJrr0aR-B5_T0snVgQSm8K-SsFv3MFofkeWxWT3PCBId8kovdI-gfKabCyhuQDaYbXP1opyEkB9-gyG4zqmWoW9ddmWo-wxaW08KiruNl09IjWJR0w93tM0i8Pn2qpCSM3h0CdgfO9-VjLn1BpYFKjuJ1apZQ3TG1YYIfGSymghUl0JWLu0s5J2BrvEz91E0K4aF-VY4oSnlrTilq3FrCOgF8IopUvqJWIsz-hKagNAP1K4AXoSVX7Kc4MxUcZEIlkeMKj05YF3zoFhOzfQCa5kcYdPFNlEOpuZwuMidYw8LNBFdvV4VeKYUXZrvaW-SKUQ",
  • "e": "AQAB"
}

(Deprecated) Retrieve latest public keyDeprecated

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.

Request
Security:
path Parameters
card_account_id
required
string

Unique identifier of the card whose PIN you wish to change.

Example: 1fe8caa4bf1f49d87b2d63c14bb565f0mcrd
Responses
200

The public key was fetched successfully.

401

Invalid/missing OAuth token.

403

Unauthorized action.

404

The card could not be found.

500

Internal server error.

get/v1/cards/{card_account_id}/pin_keys/latest
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/cards/{card_account_id}/pin_keys/latest'
Response samples
application/json
{
  • "kid": "0dce6f4d-b5d0-4c7b-a7d8-cfe231a1f385",
  • "kty": "RSA",
  • "use": "enc",
  • "alg": "RS256",
  • "n": "ielfymjYSKEeeai7pFBhJrr0aR-B5_T0snVgQSm8K-SsFv3MFofkeWxWT3PCBId8kovdI-gfKabCyhuQDaYbXP1opyEkB9-gyG4zqmWoW9ddmWo-wxaW08KiruNl09IjWJR0w93tM0i8Pn2qpCSM3h0CdgfO9-VjLn1BpYFKjuJ1apZQ3TG1YYIfGSymghUl0JWLu0s5J2BrvEz91E0K4aF-VY4oSnlrTilq3FrCOgF8IopUvqJWIsz-hKagNAP1K4AXoSVX7Kc4MxUcZEIlkeMKj05YF3zoFhOzfQCa5kcYdPFNlEOpuZwuMidYw8LNBFdvV4VeKYUXZrvaW-SKUQ",
  • "e": "AQAB"
}

Change card PIN

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": "<NEW_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.
Request
Security:
path Parameters
card_account_id
required
string

Unique identifier of the card whose PIN you wish to change.

Example: 1fe8caa4bf1f49d87b2d63c14bb565f0mcrd
Request Body schema: application/json
device_id
required
string

ID of the customer's previously bound device.

device_data
string

Encoded device fingerprint generated using the Seon SDK. See the device monitoring guide for more information about generating this value.

encrypted_pin
required
string

The encrypted PIN value (JWE in compact serialization). See the description of this method for instructions on how to produce this value.

key_id
required
string

Solaris' public RSA key ID. Returned as the kid property by the GET Retrieve latest public key endpoint.

signature
required
string

The signature of the encrypted_pin created with the device binding key.

Responses
200

The card's PIN was successfully changed.

400

Validation error.

403

Unauthorized action.

404

The card could not be found.

500

Internal server error.

post/v1/cards/{card_account_id}/pin_update_requests
Request samples
application/json
{
  • "encrypted_pin": "Web;179ac83968ab42f79e960c1753a4078fdcon;jVl14emA+OcyALb9F+CMFg==;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",
  • "key_id": "0dce6f4d-b5d0-4c7b-a7d8-cfe231a1f385",
  • "device_id": "d3768ef3-b26b-4746-9ee0-94f527184830",
  • "device_data": "Web;179ac83968ab42f79e960c1753a4078fdcon;jVl14emA+OcyALb9F+CMFg==;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",
  • "signature": "3045022100ef4f8ede9999e1338a2af0ecd5c183c306fc1d134302895aa813bd0434b0a5d90220567e1c5d16d6be0f3a8553fcfdd765e8fefb169532fbf6932d96075358b46328"
}
Response samples
application/json
{
  • "errors": [
    ]
}

Change card PIN with Change Request

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": "<NEW_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.
Request
Security:
path Parameters
card_account_id
required
string

Unique identifier of the card whose PIN you wish to change.

Example: 1fe8caa4bf1f49d87b2d63c14bb565f0mcrd
Request Body schema: application/json
encrypted_pin
required
string

The encrypted PIN value (JWE in compact serialization). See the description of this method for instructions on how to produce this value.

key_id
required
string

Solaris' public RSA key ID. Returned as the kid property by the GET Retrieve latest public key endpoint.

Responses
200

The request was accepted, and now the customer must confirm the change request.

400

Validation error.

403

Unauthorized action.

404

The card could not be found.

500

Internal server error.

post/v1/cards/{card_account_id}/sca_pin_update_requests
Request samples
application/json
{
  • "encrypted_pin": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwia2lkIjoiN2FkOTFjYWQtODU0NC00ZmQyLWJlNDgtNDcyOTU3MGEzOTRhIn0.bDPrZvlJ9slqZ9WDy_PDCZrKCvFyLanAeDItyDFdaiRvQbsTdoDE5Y-etWN--y25HkMKzpbC0CIJHdN7kLa225Ax2O6SPaxDkGGNSQPKzkxXmimpv9zaRYNCVQ67KdVTK6WOVLjOVRBKZDba9zvzfKvXlBYqj51WyQR_yvxrXTPftX3IQkDo8RjdaB6tr9HugdimbqOiMgiNSOHAn0G-Zi6tkwL0TLlA5_8xzUec40vaBvEoTBc_OZjZy7s7ebKzS8Hhg6NF9CemeMIEwes8ZzO1s1385PCxLhce0KEekVUoCjrLP9QhoYSjQUTUNrxkn4h0ZnicF5ycbW36Ivt8mQ.sAtSq_rfcxxlQiQc2qZ0Kg.bW53DScq6C8vnqD620Lnuw.MYGA-87sfGrFupu2FqC3Ick_EvwCA5vO2tPktS1yJPg",
  • "key_id": "7ad91cad-8544-4fd2-be48-4729570a394a"
}
Response samples
application/json
{
  • "id": "d6c778822b2d7bd3b778935bcfd0d1d3csc",
  • "status": "CONFIRMATION_REQUIRED",
  • "updated_at": "2022-04-21T13:59:52+00:00",
  • "url": "https://example.com/authorize"
}

Card spending controls

Create card controls list

Creates a card controls list and applies it to all cards defined in the scope and scope_id of the request.

Request
Security:
Request Body schema: application/json
scope
required
string (Scope)

The scope of the card spending control.

Enum: "CARD" "CARDHOLDER" "ACCOUNT" "BUSINESS" "PARTNER" "PARTNER_CARDS" "BUSINESS_CARDS" "ACCOUNT_CARDS" "CARDHOLDER_CARDS" "NON_BUSINESS_CARDS" "PARTNER_CARDHOLDERS"
scope_id
required
string

ID of the resource that corresponds with the scope. For example, if the scope is PARTNER, then the scope_id would be your partner ID. For business, it would be the business ID.

idempotency_key
required
string <uuid>

A randomly generated UUID which the server uses to recognize subsequent retries of the same request.

object (ListRule)
object (ListRule)
Responses
201

The card controls list was successfully created.

208

The card controls list has already been created.

400

Validation failed for the card controls list, or the provided partner identifier is invalid.

403

You are not authorized to perform this action.

404

The card controls list could not be found.

500

Internal server error.

post/v1/card_controls/lists
Request samples
application/json
{
  • "scope": "CARD",
  • "scope_id": "54e06604b0cf825810bec508cc1f2dc7mcrd",
  • "idempotency_key": "504f6816-f7b5-4965-bc35-69acadc9f5c7",
  • "inclusion": {
    },
  • "exclusion": {
    }
}
Response samples
application/json
{
  • "id": "7a911b90-0109-11ec-9a03-0242ac130003",
  • "scope": "CARD",
  • "scope_id": "54e06604b0cf825810bec508cc1f2dc7mcrd",
  • "origin": "SOLARISBANK",
  • "idempotency_key": "504f6816-f7b5-4965-bc35-69acadc9f5c7",
  • "inclusion": {
    },
  • "exclusion": {
    }
}

Index card controls lists

Returns an array containing all active card controls lists in place for your customers.

Request
Security:
query Parameters
filter[scope]
required
string (Scope)

Filter the results by the type of scope.

Enum: "CARD" "CARDHOLDER" "ACCOUNT" "BUSINESS" "PARTNER" "PARTNER_CARDS" "BUSINESS_CARDS" "ACCOUNT_CARDS" "CARDHOLDER_CARDS" "NON_BUSINESS_CARDS" "PARTNER_CARDHOLDERS"
filter[scope_id]
string

Filter the results by a specific scope (e.g., the ID of an account or the person ID of a cardholder).

include_related
boolean

Using this filter, the API will return all card controls lists that were defined at the ACCOUNT, BUSINESS, or PARTNER level that apply to a specific card. You can only use this filter in combination with the scope and scope_id filters. The scope must be set to CARD and the scope_id must be set to a card ID.

Responses
200

Successful result of the operation

400

Request validation failed.

403

You are not authorized to perform this action.

500

Internal server error.

get/v1/card_controls/lists
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/card_controls/lists?filter%5Bscope%5D=CARD&filter%5Bscope_id%5D=string&include_related=true'
Response samples
application/json
[
  • {
    }
]

Retrieve a card controls list

Returns the card controls list with the ID specified in the request URL.

Request
Security:
path Parameters
id
required
string

ID of the card controls list to retrieve.

Responses
200

The operation was successful.

400

Partner identifier is invalid

403

You are not authorized to perform this action.

404

The card controls list could not be found.

500

Internal server error.

get/v1/card_controls/lists/{id}
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/card_controls/lists/{id}'
Response samples
application/json
{
  • "id": "7a911b90-0109-11ec-9a03-0242ac130003",
  • "scope": "CARD",
  • "scope_id": "54e06604b0cf825810bec508cc1f2dc7mcrd",
  • "origin": "SOLARISBANK",
  • "idempotency_key": "504f6816-f7b5-4965-bc35-69acadc9f5c7",
  • "inclusion": {
    },
  • "exclusion": {
    }
}

Delete card controls list

Deletes the card controls list specified in the request URL.

Request
Security:
path Parameters
id
required
string

ID of the card controls list to delete.

Responses
204

No Content

400

Partner identifier is invalid

403

You are not authorized to perform this action.

404

Card controls list not found

500

Internal server error.

delete/v1/card_controls/lists/{id}
Request samples
curl -i -X DELETE \
  'https://api.solaris-sandbox.de/v1/card_controls/lists/{id}'
Response samples
application/json
[
  • {
    }
]

Create card spending limit control

Creates a card spending limit control and applies it to all cards defined in the scope and scope_id of the request.

Request
Security:
Request Body schema: application/json
scope
required
string (Scope)

The scope of the card spending control.

Enum: "CARD" "CARDHOLDER" "ACCOUNT" "BUSINESS" "PARTNER" "PARTNER_CARDS" "BUSINESS_CARDS" "ACCOUNT_CARDS" "CARDHOLDER_CARDS" "NON_BUSINESS_CARDS" "PARTNER_CARDHOLDERS"
scope_id
required
string

ID of the resource that corresponds with the scope. For example, if the scope is PARTNER, then the scope_id would be your partner ID. For business, it would be the business ID.

idempotency_key
required
string <uuid>

A randomly generated UUID which the server uses to recognize subsequent retries of the same request.

required
object (SpendingLimitRule)

Amount or count limit - only one could be used.

Responses
201

The card spending limit control was successfully created.

208

The card spending limit control has already been created.

400

The request validation failed.

403

You are not authorized to perform this action.

500

Internal server error.

post/v1/card_controls/spending_limits
Request samples
application/json
{
  • "scope": "CARD",
  • "scope_id": "54e06604b0cf825810bec508cc1f2dc7mcrd",
  • "idempotency_key": "504f6816-f7b5-4965-bc35-69acadc9f5c7",
  • "limit": {
    }
}
Response samples
application/json
{
  • "id": "7a911b90-0109-11ec-9a03-0242ac130003",
  • "scope": "CARD",
  • "scope_id": "54e06604b0cf825810bec508cc1f2dc7mcrd",
  • "origin": "SOLARISBANK",
  • "idempotency_key": "504f6816-f7b5-4965-bc35-69acadc9f5c7",
  • "limit": {
    }
}

Index card spending limit controls

Returns all active card spending limit controls.

Request
Security:
query Parameters
filter[scope]
required
string (Scope)

Filter the results by the type of scope.

Enum: "CARD" "CARDHOLDER" "ACCOUNT" "BUSINESS" "PARTNER" "PARTNER_CARDS" "BUSINESS_CARDS" "ACCOUNT_CARDS" "CARDHOLDER_CARDS" "NON_BUSINESS_CARDS" "PARTNER_CARDHOLDERS"
filter[scope_id]
string

Filter the results by a specific scope (e.g., the ID of an account or the person ID of a cardholder).

include_related
boolean

Using this filter, the API will return all card spending limit controls that were defined at the ACCOUNT, BUSINESS, or PARTNER level that apply to a specific card. You can only use this filter in combination with the scope and scope_id filters. The scope must be set to CARD and the scope_id must be set to a card ID.

Responses
200

Successful result of the operation

400

The request validation failed.

403

You are not authorized to perform this action.

500

Internal server error.

get/v1/card_controls/spending_limits
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/card_controls/spending_limits?filter%5Bscope%5D=CARD&filter%5Bscope_id%5D=string&include_related=true'
Response samples
application/json
[
  • {
    }
]

Retrieve a card spending limit control

Returns information about the card spending limit control specified in the request URL.

Request
Security:
path Parameters
id
required
string

ID of the card spending limit control.

Responses
200

Successful result of the operation

400

The supplied partner identifier is invalid.

403

You are not authorized to perform this action.

404

The card spending limit control could not be found.

500

Internal server error.

get/v1/card_controls/spending_limits/{id}
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/card_controls/spending_limits/{id}'
Response samples
application/json
{
  • "id": "7a911b90-0109-11ec-9a03-0242ac130003",
  • "scope": "CARD",
  • "scope_id": "54e06604b0cf825810bec508cc1f2dc7mcrd",
  • "origin": "SOLARISBANK",
  • "idempotency_key": "504f6816-f7b5-4965-bc35-69acadc9f5c7",
  • "limit": {
    },
  • "utilized_limit": {
    }
}

Delete card spending limit control

Deletes the card spending limit control specified in the request URL.

Request
Security:
path Parameters
id
required
string

ID of the card spending limit control to delete.

Responses
204

No Content

400

The supplied partner identifier is invalid.

403

You are not authorized to perform this action.

404

Card controls spending limit not found

500

Internal server error.

delete/v1/card_controls/spending_limits/{id}
Request samples
curl -i -X DELETE \
  'https://api.solaris-sandbox.de/v1/card_controls/spending_limits/{id}'
Response samples
application/json
[
  • {
    }
]

Create card spending limit control (V2)

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.

Request
Security:
Request Body schema: application/json
scope
required
string (Scope)

The scope of the card spending control.

Enum: "CARD" "CARDHOLDER" "ACCOUNT" "BUSINESS" "PARTNER" "PARTNER_CARDS" "BUSINESS_CARDS" "ACCOUNT_CARDS" "CARDHOLDER_CARDS" "NON_BUSINESS_CARDS" "PARTNER_CARDHOLDERS"
scope_id
required
string

ID of the resource that corresponds with the scope. For example, if the scope is PARTNER, then the scope_id would be your partner ID. For business, it would be the business ID.

idempotency_key
required
string <uuid>

A randomly generated UUID which the server uses to recognize subsequent retries of the same request.

required
object (SpendingLimitRuleV2)

Object containing the properties of the spending limit control. Note that you must set either amount or count; you cannot set both.

Responses
201

The card spending limit control was successfully created.

208

The card spending limit control has already been created.

400

The request validation failed.

403

You are not authorized to perform this action.

500

Internal server error.

post/v1/card_controls/spending_limits(use api-version-header to consume this endpoint)
Request samples
application/json
{
  • "scope": "CARD",
  • "scope_id": "54e06604b0cf825810bec508cc1f2dc7mcrd",
  • "idempotency_key": "504f6816-f7b5-4965-bc35-69acadc9f5c7",
  • "limit": {
    }
}
Response samples
application/json
{
  • "id": "7a911b90-0109-11ec-9a03-0242ac130003",
  • "scope": "CARD",
  • "scope_id": "54e06604b0cf825810bec508cc1f2dc7mcrd",
  • "origin": "SOLARISBANK",
  • "idempotency_key": "504f6816-f7b5-4965-bc35-69acadc9f5c7",
  • "limit": {
    }
}

Index card spending limit controls (V2)

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.

Request
Security:
query Parameters
filter[scope]
required
string (Scope)

Filter the results by the type of scope.

Enum: "CARD" "CARDHOLDER" "ACCOUNT" "BUSINESS" "PARTNER" "PARTNER_CARDS" "BUSINESS_CARDS" "ACCOUNT_CARDS" "CARDHOLDER_CARDS" "NON_BUSINESS_CARDS" "PARTNER_CARDHOLDERS"
filter[scope_id]
string

Filter the results by a specific scope (e.g., the ID of an account or the person ID of a cardholder).

include_related
boolean

Using this filter, the API will return all card spending limit controls that were defined at the ACCOUNT, BUSINESS, or PARTNER level that apply to a specific card. You can only use this filter in combination with the scope and scope_id filters. The scope must be set to CARD and the scope_id must be set to a card ID.

Responses
200

Successful result of the operation

400

The request validation failed.

403

You are not authorized to perform this action.

500

Internal server error.

get/v1/card_controls/spending_limits(use api-version-header to consume this endpoint)
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/card_controls/spending_limits(use%20api-version-header%20to%20consume%20this%20endpoint)?filter%5Bscope%5D=CARD&filter%5Bscope_id%5D=string&include_related=true'
Response samples
application/json
[
  • {
    }
]

Retrieve a card spending limit control (V2)

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.

Request
Security:
path Parameters
id
required
string

ID of the card spending limit control.

Responses
200

Successful result of the operation

400

The supplied partner identifier is invalid.

403

You are not authorized to perform this action.

404

The card spending limit control could not be found.

500

Internal server error.

get/v1/card_controls/spending_limits/{id}(use api-version-header to consume this endpoint)
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/card_controls/spending_limits/{id}(use%20api-version-header%20to%20consume%20this%20endpoint)'
Response samples
application/json
{
  • "id": "7a911b90-0109-11ec-9a03-0242ac130003",
  • "scope": "CARD",
  • "scope_id": "54e06604b0cf825810bec508cc1f2dc7mcrd",
  • "origin": "SOLARISBANK",
  • "idempotency_key": "504f6816-f7b5-4965-bc35-69acadc9f5c7",
  • "limit": {
    },
  • "utilized_limit": {
    }
}

Delete card spending limit control (V2)

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.

Request
Security:
path Parameters
id
required
string

ID of the card spending limit control to delete.

Responses
204

No Content

400

The supplied partner identifier is invalid.

403

You are not authorized to perform this action.

404

Card controls spending limit not found

500

Internal server error.

delete/v1/card_controls/spending_limits/{id}(use api-version-header to consume this endpoint)
Request samples
curl -i -X DELETE \
  'https://api.solaris-sandbox.de/v1/card_controls/spending_limits/{id}(use%20api-version-header%20to%20consume%20this%20endpoint)'
Response samples
application/json
[
  • {
    }
]

Card transactions

Allow a transaction that was marked as fraudulent

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.

Request
Security:
path Parameters
card_id
required
string
id
required
string
Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

404

The resource could not be found.

500

Internal server error.

default

Unexpected error

post/v1/cards/{card_id}/fraud_cases/{id}/whitelist
Request samples
curl -i -X POST \
  'https://api.solaris-sandbox.de/v1/cards/{card_id}/fraud_cases/{id}/whitelist'
Response samples
application/json
{
  • "id": "154dca58bb1b5c8701039fa6514ffc66frdcs",
  • "resolution": "WHITELISTED",
  • "whitelisted_until": "2020-05-05T11:54:26Z"
}

Confirm a fraud case

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.

Request
Security:
path Parameters
card_id
required
string
id
required
string
Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

404

The resource could not be found.

500

Internal server error.

default

Unexpected error

post/v1/cards/{card_id}/fraud_cases/{id}/confirm
Request samples
curl -i -X POST \
  'https://api.solaris-sandbox.de/v1/cards/{card_id}/fraud_cases/{id}/confirm'
Response samples
application/json
{
  • "id": "154dca58bb1b5c8701039fa6514ffc66frdcs",
  • "resolution": "CONFIRMED"
}

Decline 3DS authentication

This endpoint marks the 3DS authentication specified by the challenge_id in the request URL as declined. The challenge must not have already expired.

Request
Security:
path Parameters
challenge_id
required
string
Request Body schema: example
Schema not provided
Responses
202

The request was accepted and is being processed.

400

The challenge has already expired.

404

The resource could not be found.

500

Internal server error.

post/v1/cards/3ds/{challenge_id}/decline
Request samples
curl -i -X POST \
  'https://api.solaris-sandbox.de/v1/cards/3ds/{challenge_id}/decline' \
  -H 'Content-Type: example'
Response samples
application/json
{ }

Index card transactions

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.

Request
Security:
path Parameters
card_id
required
string <uuid>

ID of the card.

query Parameters
filter[card_transaction_id]
string

Filter the results by card transaction ID. (One value)

filter[created_at][min]
string <date-time>

Filter the results by the date/time when the transaction was created (from a given date/time value in UTC format).

filter[created_at][max]
string <date-time>

Filter the results by the date/time when the transaction was created (until a given date/time value in UTC format).

filter[partner_id]
string

Filter the results by partner ID.

filter[iban]
string

Filter the results by associated IBAN.

filter[transaction_key]
string

Filter the results by the transaction key.

filter[hashed_transaction_key]
string

Filter the results by the hashed transaction key.

filter[indicators]
string

Filter the results by transaction indicator.

Enum: "PREMATURELY_RESOLVED_RESERVATIONS_MATCHED" "RESERVED_LESS_THAN_SETTLED" "SETTLED_BUT_NOT_RESERVED_BEFORE"
filter[status]
string

Filter the results by transaction status.

Enum: "ACTIVE" "EXPIRED" "INITIATED" "PROCESSED" "RESOLVED" "REVERSED" "SETTLED"
filter[approval_code]
string

Filter the results by approval code.

filter[merchant_name]
string

Filter the results by merchant name.

filter[merchant_id]
string

Filter the results by merchant ID.

filter[core_banking_reservation_id]
string

Filter the results by core banking reservation ID.

filter[core_banking_transaction_id]
string

Filter the results by core banking transaction ID.

filter[amount]
integer

Filter the results by the amount deducted from the customer's account.

filter[transaction_amount]
integer

Filter the results by the transaction amount.

filter[declined]
boolean

Return only declined transactions.

page[number]
integer <int32>

Specifies the number of results pages to return.

page[size]
integer <int32>

Specifies the number of entries on each results page.

Responses
200

The operation was successful.

400

Request validation failed.

403

You are not authorized to perform this action.

404

Not Found.

500

Internal server error.

get/v1/cards/{card_id}/transactions
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/cards/{card_id}/transactions?filter%5Bcard_transaction_id%5D=string&filter%5Bcreated_at%5D%5Bmin%5D=2019-08-24T14%3A15%3A22Z&filter%5Bcreated_at%5D%5Bmax%5D=2019-08-24T14%3A15%3A22Z&filter%5Bpartner_id%5D=string&filter%5Biban%5D=string&filter%5Btransaction_key%5D=string&filter%5Bhashed_transaction_key%5D=string&filter%5Bindicators%5D=PREMATURELY_RESOLVED_RESERVATIONS_MATCHED&filter%5Bstatus%5D=ACTIVE&filter%5Bapproval_code%5D=string&filter%5Bmerchant_name%5D=string&filter%5Bmerchant_id%5D=string&filter%5Bcore_banking_reservation_id%5D=string&filter%5Bcore_banking_transaction_id%5D=string&filter%5Bamount%5D=0&filter%5Btransaction_amount%5D=0&filter%5Bdeclined%5D=true&page%5Bnumber%5D=0&page%5Bsize%5D=0'
Response samples
application/json
[
  • {
    }
]

Card transactions simulation

(Sandbox only) Create test fraud case

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.

Request
Security:
path Parameters
card_id
required
string
Responses
204

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

404

The resource could not be found.

500

Internal server error.

post/v1/cards/{card_id}/test_fraud_cases
Request samples
curl -i -X POST \
  'https://api.solaris-sandbox.de/v1/cards/{card_id}/test_fraud_cases'
Response samples
application/json
{
  • "id": "a95f2aaf-4e0c-4d49-8021-8a16a884ed86",
  • "status": "400",
  • "code": "build_pagination_headers_failure",
  • "title": "Failed to build pagination headers.",
  • "detail": "Cannot connect to database."
}

(Sandbox only) Create test 3DS transaction

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.

Request
Security:
path Parameters
card_id
required
string
Request Body schema: application/json
merchant_name
required
string

The name of the merchant.

purchase_currency
required
string

The currency used for the purchase.

purchase_amount
required
integer

The purchase amount (in Euro cents).

Responses
200

Successful result of the operation

400

Endpoint not available for production environment

404

The resource could not be found

500

Internal server error.

post/v1/cards/{card_id}/test_3ds_authentication
Request samples
application/json
{
  • "merchant_name": "Merchant Name",
  • "purchase_currency": "EUR",
  • "purchase_amount": 1000
}
Response samples
application/json
{
  • "html": "<html>...</html>"
}

(Beta, sandbox only) Simulate an authorization

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.

Request
Security:
path Parameters
card_id
required
string

ID of the card to use for the test transaction.

Request Body schema: application/json
type
required
string

The type of transaction.

Enum: "PURCHASE" "CASH_ATM" "OCT"
required
object

The amount of the card authorization.

transaction_currency
required
string

Currency code of the transaction.

pos_entry_mode
required
string

The POS entry mode used to complete the transaction.

Enum: "CHIP" "CONTACTLESS" "MAG_STRIPE" "MANUAL_PAN_ENTRY" "UNKNOWN"
merchant_category_code
required
string <integer>

The merchant category code (should be 4 digits).

acquirer_id
required
string <integer>

The acquirer ID (up to 6 digits).

approval_code
required
string <integer>

The approval code (should be 6 digits).

terminal_id
string <integer>

Terminal ID (should be 8 digits).

merchant_id
required
string <integer>

Merchant ID (should be 15 digits).

merchant_name
required
string

The merchant's name (up to 24 characters).

merchant_city
required
string

The merchant's city (up to 13 characters).

merchant_country
required
string <ISO 3166 alpha-2>

The merchant's country (ISO 3166 two-character code).

Responses
202

The operation was successful.

400

Bad Request

403

Forbidden

404

The resource could not be found.

500

Internal server error.

post/v1/cards/{card_id}/simulator/transactions/authorization
Request samples
application/json
{
  • "type": "PURCHASE",
  • "authorization": {
    },
  • "transaction_currency": "USD",
  • "pos_entry_mode": "CHIP",
  • "merchant_category_code": "5411",
  • "acquirer_id": "123456",
  • "approval_code": "053630",
  • "terminal_id": "12345678",
  • "merchant_id": "123456789101112",
  • "merchant_name": "Solarisbank AG",
  • "merchant_city": "Berlin",
  • "merchant_country": "DE"
}
Response samples
application/json
{
  • "transaction_key": "100000000142424"
}

(Beta, sandbox only) Simulate an unauthorized settlement

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.

Request
Security:
path Parameters
card_id
required
string

ID of the card to use for the test transaction.

Request Body schema: application/json
required
object

The type of settlement.

type
required
string

The type of transaction.

Enum: "OCT" "PURCHASE" "PURCHASE_REVERSAL" "CASH_ATM_REVERSAL" "CASH_MANUAL_REVERSAL" "CASH_ATM" "CASH_MANUAL" "CREDIT_PRESENTMENT" "DEBIT_PRESENTMENT" "FORCE_POST_TRANSACTION" "DISPUTE_TRANSACTION" "FRAUD_TRANSACTION"
pos_entry_mode
required
string

The POS entry mode used to complete the transaction.

Enum: "UNKNOWN" "MAG_STRIPE" "CHIP" "MANUAL_PAN_ENTRY" "CONTACTLESS" "CARD_NOT_PRESENT"
merchant_category_code
required
string <integer>

The merchant category code (should be 4 digits).

acquirer_id
required
string <integer>

The acquirer ID (up to 6 digits).

approval_code
required
string <integer>

The approval code (should be 6 digits).

terminal_id
required
string <integer>

Terminal ID (should be 10 digits).

merchant_id
required
string <integer>

Merchant ID (should be 15 digits).

merchant_name
required
string

The merchant's name (max 25 characters).

merchant_city
required
string

The merchant's city (max 13 characters).

merchant_country
required
string <ISO 3166 alpha-2>

The merchant's country (ISO 3166 two-character code).

Responses
202

The operation was successful.

400

Bad Request

403

Forbidden

404

The resource could not be found.

500

Internal server error.

post/v1/cards/{card_id}/simulator/transactions/settle
Request samples
application/json
{
  • "settlement": {
    },
  • "type": "OCT",
  • "pos_entry_mode": "UNKNOWN",
  • "merchant_category_code": "5411",
  • "acquirer_id": "123456",
  • "approval_code": "053630",
  • "terminal_id": "1234567890",
  • "merchant_id": "123456789101112",
  • "merchant_name": "Solarisbank AG",
  • "merchant_city": "Berlin",
  • "merchant_country": "DE"
}
Response samples
application/json
{
  • "transaction_key": "100000000142424"
}

(Beta, sandbox only) Simulate the settlement of an authorization

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.

Request
Security:
path Parameters
card_id
required
string

ID of the card to use for the test transaction.

transaction_key
required
string

transaction_key of the card transaction.

Request Body schema: application/json
required
object

The type of settlement.

Responses
202

The operation was successful.

400

Bad Request

403

Forbidden

404

The resource could not be found.

500

Internal server error.

post/v1/cards/{card_id}/simulator/transactions/{transaction_key}/settle
Request samples
application/json
{
  • "settlement": {
    }
}
Response samples
application/json
{
  • "transaction_key": "100000000142424"
}

(Beta, sandbox only) Simulate an expired card authorization

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.

Request
Security:
path Parameters
transaction_key
required
string

transaction_key of the card transaction to mark as expired.

Responses
202

The operation was successful.

400

Bad Request

403

Forbidden

404

The resource could not be found.

500

Internal server error.

post/v1/cards/simulator/authorization/{transaction_key}/expire
Request samples
curl -i -X POST \
  'https://api.solaris-sandbox.de/v1/cards/simulator/authorization/{transaction_key}/expire'
Response samples
application/json
[
  • {
    }
]

Card Delivery Tracking API

Retrieve card tracking information

Returns tracking information for the card with the ID specified in the request URL.

Request
Security:
path Parameters
cardId
required
string

ID of the card account.

Example: 1fe8caa4bf1f49d87b2d63c14bb565f0mcrd
Responses
200

Card tracking data was fetched successfully.

400

Validation error.

401

Invalid/missing OAuth token.

403

Unauthorized action.

500

Internal server error.

get/v1/cards/{cardId}/delivery_trackings
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/cards/{cardId}/delivery_trackings'
Response samples
application/json
[
  • {
    },
  • {
    }
]