Overview
Cards are virtual. Each card belongs to a cardholder and spends from a card balance. A card balance belongs to a funding owner: an individual, or a business.
Terms used in these pages:
- Customer (
cus_): an individual or a business you created with the Customers API, or an employee you added as a cardholder. - Enrolment: opening the card program for an individual or a business. It runs after their KYC or KYB is complete.
- Cardholder: a person who holds cards. An enrolled individual is their own cardholder. A business’s cardholders are its employees, plus its main beneficial owner, who is added automatically.
- Funding owner: the individual or business whose card balance a card spends.
- Card balance: the funds the cards can spend. You fund it with stablecoin deposits.
- Deposit instructions: the address, chain and token to send stablecoins to, to fund a card balance.
From a new customer to their first card
1
Create the customer and complete KYC or KYB
With the Customers API.
2
Record their acceptance of the card terms
Show the customer Endl’s card terms and record their acceptance. See
Card terms and the acceptance token.
3
Enrol them
POST /api/v0/cards/{customerId}/enrollment.
Poll GET /api/v0/cards/{customerId}/enrollment
until status is active.4
For a business, add employees as cardholders
POST /api/v0/customer/{businessId}/card-users.
Poll each cardholder until status is active.5
Fund the card balance
Send stablecoins to the deposit address,
or deposit from the customer’s Endl wallet.
6
Issue a card
7
Show the card details when the cardholder needs them
Conventions
The card API follows the same rules as the rest of the Endl API.Base URL and headers
Path parameters
On card routes, a business’s
customerId covers all of its employees’ cards. For
example, GET /api/v0/cards/{businessId} lists every employee’s cards, and you can
freeze an employee’s card through either the employee’s or the business’s id.
IDs
crd_, ctx_, cdp_ and cwd_ ids are the prefix plus 20 letters and digits, for
example crd_4fT9kQ2wE8rT5yU1iO7p.
Money
Amounts are a Money object: a decimal string and a currency code. Card amounts are in USD. In requests, sendUSD with at most 2 decimal places.
Money object
Fee object
Endl fees appear in thefees list of transactions, deposits and withdrawals.
Chains and tokens
On the sandbox, a wallet’s balance also lists other test USDC and USDT tokens, and other chains. Only
USDCR on base_sepolia funds the card balance.
There is no bridging. Funds move on one chain.
Time
Timestamps are ISO-8601, in UTC, for example2026-11-02T09:12:03Z.
Idempotency
Send anIdempotency-Key header on every request that creates something:
enrolments, cards, single-use cards, deposits and withdrawals.
- The key is 1 to 64 characters. Use a new random value (for example a UUID) for each new operation.
- A repeat with the same key and the same body returns the first result and creates nothing new.
- The same key with a different body returns
409 ERRCRD_1029. - A missing or too long key returns
400 ERRCRD_1016withfield: "Idempotency-Key".
- Enrolment is idempotent by customer. The key is required but not replayed: a repeat POST for a customer who already applied returns their current enrolment.
- Adding a cardholder doesn’t use the key. A repeat with the same email returns
400 ERRCRD_1010. If you lost the response, find the cardholder in the cardholder list.
Pagination
List endpoints return one page at a time, newest first.
The response holds the items, plus:
The cardholder list takes
cursor only, with a fixed page size of 20.
Responses
- A successful response is the object itself:
201when something is created,202when the result comes later,200otherwise. - An error uses the standard Endl error body, with an
ERRCRD_code inerrors[].code. See Card errors.
Forward compatibility
Ignore fields and enum values you don’t recognise. Endl adds new fields and new enum values without changingApi-Version. Values marked reserved aren’t sent yet.
Enrolment
Enrolment opens the card program for an individual or a business. The customer’s KYC (individual) or KYB (business) must be complete first.- Individuals and businesses only. Employees aren’t enrolled. Add them as cardholders of an enrolled business.
- Asynchronous. The POST answers
202with the enrolment, usuallypending. Poll the GET until the status is final. Businesses are reviewed by Endl first, so they take longer. - Safe to repeat. If the customer has already applied, the POST returns the current
enrolment with
200and starts nothing new. - One card account per person. An individual who is already a business’s
cardholder can’t enrol on their own (
409 ERRCRD_1034).
Card terms and the acceptance token
Before you enrol a customer, they must accept Endl’s card terms and conditions in your product. Endl shares the card terms document and its current version with you during onboarding. There is no API to fetch it. When the customer accepts, generate a new UUID (version 4) and keep it with your record of the acceptance. Send it asacceptanceToken when you
enrol the customer. Endl records the acceptance
under that token.
- Each token records one acceptance. A token that was already used returns
409 ERRCRD_1037. Capture a fresh acceptance and send a new token. - This acceptance is separate from the platform terms the customer accepts when you
create them (for example through
POST /api/v0/terms/links). Don’t reuse a token from that flow. - Keep your own record of the acceptance, such as when it happened and which terms version the customer saw. Endl stores the token and the terms version.
- The acceptance is recorded only when the enrolment is submitted. If the enrolment request is refused, nothing is recorded and you can send the same token again.
Business owner
When a business enrols, its main beneficial owner (the one with the largest ownership share) becomes one of its cardholders automatically.- The owner gets a
cus_id and appears in the business’s cardholder list. Don’t add them again. - Their cardholder status is
pendinguntil they are approved, thenactive. - If the owner’s email matches one of your individual customers who has no card account, that customer becomes the business’s cardholder. They can then no longer enrol on their own.
- The owner needs an email of their own, different from the business’s email, and
must not already hold cards. Otherwise the business’s enrolment ends
rejectedwith reasonERRCRD_1040. Correct the owner’s details, then enrol again. - The owner can’t be removed as a cardholder.