Issue Card
Provision a new virtual card.
Card creation is asynchronous. The response returns immediately with status: "CREATING"; the card is fully provisioned once you receive the CARD_CREATED webhook.
Optional header
X-Idempotency-Keystringheader1–64 characters matching [a-zA-Z0-9_-]. Retrying with the same key and the same body returns the original card (same cardId) and does not create a duplicate. The same key with a different body returns 409 Conflict. Successful responses are cached for 24 hours. Distinct from X-Nonce, which is one-time anti-replay and must be rotated on every retry. See Idempotency.
Body
cardBinIdstringbodyrequiredCard BIN ID — see GET /card-bins.
initialAmountintegerbodyrequiredInitial funding amount in cents. Minimum 100 ($1.00), maximum 4000000 ($40,000.00).
firstNamestringbodyCardholder's first name (max 25 chars; letters, spaces, apostrophes, hyphens). Required unless cardholderId is provided.
lastNamestringbodyCardholder's last name (max 25 chars; letters, spaces, apostrophes, hyphens). Required unless cardholderId is provided.
mobilePrefixstringbodyMobile prefix including +. Required when the BIN has mobile: true.
mobilestringbodyMobile number without prefix. Required when the BIN has mobile: true.
emailstringbodyEmail address. Required when the BIN has email: true.
pinstringbodyCard PIN — 4 digits, non-repeating. Only when BIN has supportPin: true.
billingAddressobjectbodyBilling address. Required when the BIN's issuingCountry is "US".
tagsarraybodyUp to 6 tags. Used for organising cards in your dashboard.
cardholderIdstringbodyKYC cardholder ID (kyc_…) returned by the KYC create endpoints. Required when the BIN has requireKycCardholder: true. The cardholder must be in APPROVED status.
When cardholderId is provided, the verified identity from KYC is used; firstName and lastName may be omitted. Each cardholder may back at most maxCardCount (default 2) cards.
Response
Returns the newly created card with status: "CREATING".
cardIdstringnamestringcardNumberstringstatusstringCREATING, FAILED, ENABLE, DISABLE, DELETING, DELETED, or EXPIRED.availableBalanceintegertotalConsumptionintegercardBinIdstringsupportPinbooleanbrandstringcardholderNamestringbillingAddressobjectcreatedAtintegerupdatedAtinteger{
"cardBinId": "v_123456",
"initialAmount": 10000,
"firstName": "John",
"lastName": "Doe",
"mobilePrefix": "+1",
"mobile": "2025550123",
"email": "[email protected]",
"pin": "1234",
"billingAddress": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "New York",
"state": "NY",
"country": "US",
"postalCode": "10001"
},
"tags": ["Marketing", "Q4-2024"],
"cardholderId": "kyc_8f3a9c2b1d4e5f6a"
}{
"code": 0,
"message": "SUCCESS",
"data": {
"cardId": "cid_1234567890",
"name": "C78AB1234",
"cardNumber": "555543******1234",
"status": "ENABLE",
"availableBalance": 10000,
"totalConsumption": 0,
"cardBinId": "v_123456",
"supportPin": true,
"brand": "VISA",
"cardholderName": "JOHN DOE",
"createdAt": 1640995200000,
"updatedAt": 1640995200000,
"billingAddress": {
"line1": "123 Main Street",
"line2": "Apt 4B",
"city": "New York",
"state": "NY",
"postalCode": "10001",
"country": "US"
}
}
}