Issuing cards for your users

This guide walks the whole journey for a program that issues cards to its end users — from inviting the user to a funded, ordered card. It spans three surfaces, so it’s easy to lose the thread; the diagram below shows who calls what. The flow has three variants, chosen by how you invite the user:

	Managed (`PREPAID_CARD_CUSTOMER` invite)	Default (invite with no `role`)	Cardholder on a corporate (`EMPLOYEE`, or a role set up for your program)
Use case	Program funds the card on the user’s behalf	User funds their own card via IBAN	A corporate holds the account; its employees — or the cardholders your program’s role names — hold cards on it
Funding	Program master account via Load / Unload	User’s assigned IBAN	The corporate’s own account — the card spends from it directly
Invite body	`role` + the funding `accountId`	`email` (plus whatever the role requires)	`role` + `corporateCustomerId` + `accountIds` + name
Who onboards the user	The user, in your app	The user, in your app	You, on the Management API (KYC)
Who orders the card	The user, or you	The user, or you	You, on the corporate’s account

Who calls what

Two things change the picture above. On a program that uses a client reference (users sign in through your identity provider) Orenda sends no invite email — the user signs in through your identity provider with the clientReference you supplied. For a cardholder on a corporate the onboarding is yours: you submit their KYC and order their card on the Management API; the cardholder signs in, accepts the legal agreements in-app, and uses the card. Both are called out in the steps below.

Step 1 — Invite the user

Invite the customer with one call to POST /v1/access-management/customer-invites. It creates the user and their application, and Orenda emails the user a temporary password. The invite body selects the funding model for the rest of the flow.

POST https://api.next.orenda.finance/v1/access-management/customer-invites?programId=<programId>
Authorization: Bearer <service user IdToken>

Managed (prepaid)
Default (IBAN)
Cardholder on a corporate

Name the role and the funding accountId — the program account the user draws against:

{
  "email": "jane@example.com",
  "role": "PREPAID_CARD_CUSTOMER",
  "accountId": "8f1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b4c"
}

An invite with no role — the user onboards as a customer with their own account:

{
  "email": "jane@example.com"
}

Name the role, the onboarded corporate and the account(s) the cardholder may reach. The role is EMPLOYEE, or a role set up for your program such as CONSUMER_CARDHOLDER. Send firstName and lastName — they are printed on the card. The API enforces them only when the role’s configuration asks for them, so do not rely on a 400 to catch a missing name. If your program uses a client reference, add the clientReference your identity provider will present:

{
  "email": "ada@example.com",
  "clientReference": "firebase-uid-of-ada",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "role": "CONSUMER_CARDHOLDER",
  "corporateCustomerId": "<corporate customerId>",
  "accountIds": ["<corporate accountId>"]
}

The cardholder gets no account of their own. See Cardholders on a corporate for the rules.

You get back data.applicationId — the user’s application, and their customerId.

Service users are exempt from the step-up; an operator must send a confirmation (passkey or TOTP) or the call returns 422 SCA_MISSING. Which user details are required depends on the role — send what you have, and a 400 names any field that’s missing. Full field reference: Invite a customer.

Step 2 — The user onboards (Customer API)

Everything from here until the card is the user acting with their own token on the Customer API. The user signs in with the temporary password from the invite email (changing it and setting up 2FA/passkey on first login), then moves through onboarding:

Accept legal agreements — fetch GET /v1/applications/{applicationId}/documents/legal, then submit POST /v1/applications/{applicationId}/documents/legal/accept
KYC — fetch the schema (GET /v1/applications/{applicationId}/kyc/schema) and submit answers (POST /v1/applications/{applicationId}/kyc)
Identity verification (Sumsub) — get a token (GET /v1/applications/{applicationId}/webtoken/sumsub) and run the SDK
Poll GET /v1/applications until onboarding completes

The build order for the user’s side, from sign-in through cards and payments, lives on the Customer API docs: Integration order for an invited user.

You don’t need to poll yourself: your program receives a webhook when the application is approved.

Program that uses a client reference
Cardholder on a corporate

There is no temporary password: the user signs in through your identity provider, and the clientReference from the invite is their identity. The onboarding steps are the same, driven by currentStep on GET /v1/applications.

The cardholder does not go through these steps in your app. You submit their KYC on the Management API — POST /v1/applications/{applicationId}/kyc with the applicationId from the invite. Once approved, the cardholder is provisioned automatically and no account is created for them; at first sign-in they accept the program’s legal agreements in-app. From then on their GET /v1/applications reports currentStep: CUSTOMER and the corporate’s customerId, which is what makes every customer-scoped endpoint return the corporate’s data, bounded to what they were granted.

Step 3 — Order the card

Once approved, the application carries the customerId, and the user’s primary account is created automatically (read its accountId). Order the card:

POST /v1/customers/{customerId}/accounts/{accountId}/cards

The user can order their own card on the Customer API, or you can order it on the Management API (POST …/cards) — see Card operations.

Cardholders on a corporate. For a user invited as an EMPLOYEE, or under a role your program defines (see Invite a customer), there is no account of their own: order the card on the corporate’s account and name the cardholder in the body — { "cardType": "VIRTUAL", "forCustomerId": "<cardholder customerId>" } — where the cardholder’s customerId is the applicationId the invite returned, and the path is the corporate’s customerId and one of the accountIds from the invite. The card is printed with the cardholder’s name and attributed to them, so among cardholders only they see it, and they see no other cardholder’s card. The cardholder must belong to the path corporate and the account must be one they were granted, else 400. You can order it as soon as the invite returns — before their KYC is complete. Whether the cardholder can also order a card themselves is set by the permissions on their role.The NEW_CARD_ADDED webhook for that card carries the corporate’s customerId and clientReference, not the cardholder’s — correlate the cardId with your own order response to know whose card it is.

Step 4 — Fund the card

Managed (prepaid)
Default (IBAN)
Cardholder on a corporate

Load funds onto the card from the program master account:

POST /v1/customers/{customerId}/accounts/{accountId}/balance

{ "amount": 100.00, "action": "LOAD" }

Use "action": "UNLOAD" to pull funds back to the master account.

Invite a customer

Create the user and their application with one invite call.

Card operations

Issue, status, limits, Load/Unload.

User-side walkthrough

The Customer API steps in full.

Webhooks

Get notified when the application is approved.

Get started

Oversight

Customer operations

Batch payments

Configuration

Who calls what

Step 1 — Invite the user

Step 2 — The user onboards (Customer API)

Step 3 — Order the card

Step 4 — Fund the card

Invite a customer

Card operations

User-side walkthrough

Webhooks

​Who calls what

​Step 1 — Invite the user

​Step 2 — The user onboards (Customer API)

​Step 3 — Order the card

​Step 4 — Fund the card

​Related

Invite a customer

Card operations

User-side walkthrough

Webhooks

Who calls what

Step 1 — Invite the user

Step 2 — The user onboards (Customer API)

Step 3 — Order the card

Step 4 — Fund the card

Related