Sign in
latestOpenAPI 3.0.12026-08-104068226.2 KB

a772504dcc9e

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 a 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. The kid property from GET /v1/cards/pin_keys/latest is the kid in the request.
  7. Call this endpoint from your backend.
post/v1/persons/{person_id}/accounts/{account_id}/cards

Path parameters

person_idstring required

Solaris UID for person

account_idstring required

Solaris UID for account

Request body

line_1string required

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_2string

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'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' required

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

business_idstring

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

referencestring

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

shipping_priority'0' | '1' | '2' | '3' | '4' | '5' | '6'

Shipping priority to assign to the card.

encrypted_pinstring

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

key_idstring

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

Example request

{
  "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

Successful creation

idstring

ID of the card.

statusstring

Current state of the created card

Example response

{
  "id": "8febdba4912a747808ccc6f95f82bbb4mcrd",
  "status": "PROCESSING"
}