Create Card

Endpoint

POST/api/v1/merchant/cards/

Used to create virtual and physical cards.

Card numbers, CVV, and expiration will be available immediately upon creation for both virtual and physical cards.

• Configure cardType = physical if there is any chance you will want to ship out a physical card for the cardholder.
• spendLimit works for Standard Authorization only. It is the opening balance of the card. Set an amount equivalent to the initial availableCredit on the Retrieve Card endpoint.

Request Body

{
  "sumsubApplicantId": "appl_abc123xyz",
  "cardType": "physical",
  "spendLimit": 1000.00,
  "customerType": "Consumer",
  "preferredCardName": "My Card",
  "kyc": {
    "firstName": "John",
    "lastName": "Doe",
    "dob": "1990-01-01",
    "residentialAddress": {
      "idDocumentType": "passport",
      "idDocumentNumber": "123456789",
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "New York",
      "country": "USA",
      "postalCode": "10001"
    }
  },
  "meta": {
    "id": "unique-user-id",
    "otpPhoneNumber": {
      "dialCode": 1,
      "phoneNumber": "1234567890"
    },
    "email": "user@example.com"
  }
}

Body Parameters

Card Details

Name	Type	Required	Description
sumsubApplicantId	string	✅	ID of the Sumsub applicant. Used to confirm the profile is KYC verified. Also used to cross-check submitted KYC.
cardType	string	✅	Specifies the type of card to create (physical or virtual).
preferredCardName	string	✅	Sets the name of the card.
spendLimit	float	❌	Sets the maximum spending limit for this card (≥ 0).
customerType	string	✅	Specifies if the cardholder is an individual (Consumer) or a business (Business).
kyc	object	✅	KYC Object
expiryDate	date \| null	❌	Expiry date (YYYY-MM-DD). Must be at least 1 month from creation. Defaults to 3 years if not specified.
preferredCardName	string	✅	Name printed on the physical card (≤ 27 chars). Unsupported characters: ;:!?<>~\%@{} |[]”_.
meta	object	✅	Supplementary data about the cardholder, used to identify the user in card system.
cardDesign	string	❌	The ID of the approved card design artwork. Retrieved from GET /card-design/.

KYC (Consumer)

Name	Type	Required	Description
firstName	string	✅	Cardholder’s first name (≤ 20 chars).
lastName	string	✅	Cardholder’s last name (≤ 20 chars).
dob	date	✅	Cardholder’s date of birth (YYYY-MM-DD).
residentialAddress	object	✅	Registered address details.

Residential Address

Name	Type	Required	Description
idDocumentType	string	✅	Government-issued ID type (passport, national ID, etc.).
idDocumentNumber	string	✅	ID number (≤ 255 chars).
line1	string	✅	Address line 1 (≤ 255 chars).
line2	string	✅	Address line 2 (≤ 255 chars).
city	string	✅	City or district (≤ 255 chars).
country	string	✅	Three-letter country code (ISO 3166-1 alpha-3).
postalCode	string	❌	Postal code (if applicable).

KYC (Business)

Name	Type	Required	Description
fullName	string	✅	Full legal name of the business.
entityType	string	✅	Type of entity (personal or company).
businessRegistrationNumber	string	✅	Legal business registration number.
businessOperationAddress	object	✅	Business operation address details.

Business Operation Address

Name	Type	Required	Description
line1	string	✅	Address line 1.
line2	string	✅	Address line 2.
city	string	✅	City or district.
country	string	✅	Three-letter country code (ISO 3166-1 alpha-3).
postalCode	string	❌	Postal code.

Meta Object

Name	Type	Required	Description
otpPhoneNumber	object	✅	Cardholder’s phone number for authentication (3DS, wallet verification).
id	string	✅	Unique identifier for the cardholder in your system.
email	string | null	❌	Cardholder’s email for authentication. Recommended for a seamless experience.

Example Response

{
    "id": "a1af0838-0b47-42bd-9484-6ee115d0dba1",
    "currency": "USD",
    "lastFour": "7958",
    "externalCustomerId": "unique-user-id",
    "cardholderName": "John Doe",
    "cardName": "Card 1",
    "cardDesign": "a6d8a4d1-abcf-4af3-888e-7fdbf3721497",
    "cardType": "virtual",
    "status": "ACTIVE",
    "created": "2025-06-16T23:07:22+0000"
}

Response Codes

Status Code	Description
201 Created	Card created successfully.
400 Bad Request	Invalid request parameters.
401 Unauthorized	Authentication failed.
500 Internal Server Error	Server error.