---
title: "Create a card"
method: POST
path: "/v1/persons/{person_id}/accounts/{account_id}/cards"
tags: ["Cards servicing"]
---

# Create a card

`POST /v1/persons/{person_id}/accounts/{account_id}/cards`

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](https://github.com/airsidemobile/JOSESwift) or [Nimbus JOSE for Android](https://connect2id.com/products/nimbus-jose-jwt)).
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.

## Path parameters

- `person_id` string, required
- `account_id` string, required

## Request body

- CardCreateRequest — The content of the card creation request
  - `line_1` string, 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_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` '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_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` '0' | '1' | '2' | '3' | '4' | '5' | '6' — Shipping priority to assign to the card.
  - `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.

## Response `201`

Successful creation

- CardCreateResponse
  - `id` string — ID of the card.
  - `status` string — Current state of the created card

## Other responses

- `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

---

[API](https://skmtc.net/solarisgroup/apis/card-creation-servicing.md) · [All operations](https://skmtc.net/solarisgroup/apis/card-creation-servicing/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/solarisgroup/card-creation-servicing/revisions/a772504dcc9e/schema)