> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endl.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Issue single-use card
> Issues a scoped, single-use virtual card to an active cardholder.
**Card details come back once, in `encryptedCard`, and there is no endpoint to fetch them again.** A retry with the same `Idempotency-Key` returns `409 ERRCRD_1008` with no details. Decrypt and use the card straight away — see [Card details encryption](/api-reference/cards/encryption).
The business needs a registered RSA public key before any card can be issued; without one this fails with `400 ERRCRD_1004`.
`lifetimeLimitCents` comes back as the amount plus the buffer, rounded up.
## OpenAPI
````yaml api-reference/endl-cards-api.json POST /api/v0/customer/{businessId}/card-users/{cardholderId}/cards/scoped
openapi: 3.1.0
info:
title: Endl Cards API
version: '0'
description: >-
Issue single-use virtual cards to cardholders under a business customer.
Three endpoints under `/api/v0/customer`. The key must carry the **`cards`**
permission, and the business customer must be enabled for cards.
**Card details are returned once, encrypted to your own RSA public key** —
see [Card details encryption](/api-reference/cards/encryption).
servers:
- url: https://api-sandbox.endl.io
description: Sandbox
security:
- apiKey: []
paths:
/api/v0/customer/{businessId}/card-users/{cardholderId}/cards/scoped:
post:
tags:
- Cards
summary: Issue single-use card
description: >-
Issues a scoped, single-use virtual card to an active cardholder.
**Card details come back once, in `encryptedCard`, and there is no
endpoint to fetch them again.** A retry with the same `Idempotency-Key`
returns `409 ERRCRD_1008` with no details. Decrypt and use the card
straight away — see [Card details
encryption](/api-reference/cards/encryption).
The business needs a registered RSA public key before any card can be
issued; without one this fails with `400 ERRCRD_1004`.
`lifetimeLimitCents` comes back as the amount plus the buffer, rounded
up.
parameters:
- $ref: '#/components/parameters/ApiVersion'
- $ref: '#/components/parameters/BusinessId'
- name: cardholderId
in: path
required: true
schema:
type: string
description: An **active** cardholder of that business, `cus_…`.
example: cus_6OzDYZWl5Aim37RwvZfZ
- name: Idempotency-Key
in: header
required: false
schema:
type: string
minLength: 1
maxLength: 64
description: >-
1–64 characters. **A retry with the same key never creates a second
card.**
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- amountInUSDCents
properties:
amountInUSDCents:
type: integer
description: 1 – 10,000,000. Whole numbers only.
bufferPercentage:
type: integer
description: 0 – 20. Defaults to 20.
expiresAt:
type: string
description: >-
ISO-8601 with offset. Must be in the future and no more than
365 days out.
allowedMccs:
type: array
items:
type: string
description: Non-empty, unique 4-digit codes.
allowedMerchants:
type: array
items:
type: string
description: Non-empty, at most 25 unique names, 1–64 characters each.
displayName:
type: string
description: >-
At most 26 characters — letters, digits, spaces, `.` and
`-`, with at least one letter.
purpose:
type: string
description: At most 255 characters.
example:
amountInUSDCents: 4299
bufferPercentage: 10
expiresAt: '2026-10-01T00:00:00Z'
allowedMccs:
- '5411'
allowedMerchants:
- Amazon
displayName: Agent card
purpose: order 8841
responses:
'201':
description: The card, with its details encrypted in `encryptedCard`.
content:
application/json:
example:
cardId: 6eab027d-1c2e-4f0a-9b1d-3c5e7a9f0b12
cardholderId: cus_6OzDYZWl5Aim37RwvZfZ
status: active
last4: '2464'
expiryMonth: '12'
expiryYear: '2030'
scope:
amountInUSDCents: 4299
lifetimeLimitCents: 4729
bufferPercentage: 10
expiresAt: '2026-10-01T00:00:00Z'
allowedMccs:
- '5411'
allowedMerchants:
- Amazon
cardType: consumer
purpose: order 8841
spentAt: null
encryptedCard:
alg: RSA-OAEP-256+A256GCM
keyId: my-card-key
encryptedKey: kD3n…==
iv: nV7kuhxhBtvq9s1Z
ciphertext: 5u7fkhvc9cKI…
tag: XuMrbHy9vx3oQ2cR1ZpA8w==
aad: 6eab027d-1c2e-4f0a-9b1d-3c5e7a9f0b12
schema:
type: object
properties:
cardId:
type: string
format: uuid
description: The card. Also `encryptedCard.aad`.
cardholderId:
type: string
description: Echo of the path.
status:
type: string
description: '`active`.'
last4:
type: string
description: Last four digits.
expiryMonth:
type: string
description: '`MM`.'
expiryYear:
type: string
description: '`YYYY`.'
scope:
type: object
description: The spend scope as applied.
encryptedCard:
type: object
description: >-
The card number, CVV and expiry — **returned once,
encrypted to your RSA public key**.
properties:
alg:
type: string
description: '`RSA-OAEP-256+A256GCM`.'
keyId:
type: string
description: The partner key it was encrypted to.
encryptedKey:
type: string
description: base64. AES-256 key wrapped with RSA-OAEP-SHA256.
iv:
type: string
description: base64. 12-byte GCM nonce.
ciphertext:
type: string
description: >-
base64. Encrypted
`{"pan","cvv","expiryMonth","expiryYear"}`.
tag:
type: string
description: base64. 16-byte GCM tag.
aad:
type: string
description: >-
Equals `cardId`. Bind the payload to the card by
checking this.
'400':
description: >-
`ERRCRD_1000` not a business · `ERRCRD_1001` business not enabled
for cards · `ERRCRD_1003` cardholder not active · **`ERRCRD_1004` no
card encryption key registered** · `ERRCRD_1005` a field broke a
rule, bad `Idempotency-Key`, invalid JSON · `ERRCRD_1006` card
cannot be issued with these parameters.
content:
application/json:
example:
code: 400
message: amountInUSDCents must be an integer from 1 to 10000000
status: ERROR
data: null
errors:
- code: ERRCRD_1005
message: amountInUSDCents must be an integer from 1 to 10000000
field: null
'401':
description: Missing or invalid `Api-Key`.
content:
application/json:
example:
code: 401
message: Partner API key required
status: ERROR
data: null
errors:
- code: ERRCORE_1004
message: Partner API key required
field: null
'403':
description: >-
`ERRCRD_1007` cards cannot be issued to this cardholder ·
`ERRCORE_1005` another partner's business, or the key lacks `cards`.
content:
application/json:
example:
code: 403
message: Card issuing not available
status: ERROR
data: null
errors:
- code: ERRCRD_1007
message: Card issuing not available
field: null
'404':
description: >-
`ERRCRD_1002` cardholder not found under this business ·
`ERRREF_1001` unknown `businessId`.
content:
application/json:
example:
code: 404
message: Cardholder not found
status: ERROR
data: null
errors:
- code: ERRCRD_1002
message: Cardholder not found
field: null
'409':
description: >-
A card was already issued for this `Idempotency-Key`. **The details
are not returned again.**
content:
application/json:
example:
code: 409
message: Card already issued
status: ERROR
data: null
errors:
- code: ERRCRD_1008
message: Card already issued
field: null
'502':
description: Card service unavailable. **Retry with the same `Idempotency-Key`.**
content:
application/json:
example:
code: 502
message: Card issuing temporarily unavailable
status: ERROR
data: null
errors:
- code: ERRCRD_1009
message: Card issuing temporarily unavailable
field: null
components:
parameters:
ApiVersion:
name: Api-Version
in: header
required: true
description: >-
The API version this request targets. `2026-09.1`. See
[Versioning](/api-reference/versioning).
schema:
type: string
pattern: ^\d{4}-\d{2}\.\d+$
default: 2026-09.1
example: 2026-09.1
BusinessId:
name: businessId
in: path
required: true
schema:
type: string
description: Your **business** customer, `cus_…`, enabled for cards.
example: cus_HUCgMg1iqWb379FMNvaJ
securitySchemes:
apiKey:
type: apiKey
in: header
name: Api-Key
description: Partner API key. Must carry the `cards` permission.
````