Onboarding
Create a wallet entity, collect identity documents, submit an application, then open a wallet and issue a card.
The sequence is the same for persons and businesses. Business wallet entities also send a control person and beneficial owners.
Sequence
1. Wallet entity: POST /v1/wallet-entities with type PERSON or BUSINESS. The response includes id and verification. Poll GET /v1/wallet-entities/{wallet_entity_id} until verification.status is VERIFIED. If the check needs files, verification.status is IN_REVIEW or REJECTED with DOCUMENT_REQUIRED.
2. Identity documents: POST /v1/wallet-entities/{wallet_entity_id}/documents with a document_type. PUT the file bytes to the returned upload_url before upload_url_expires_at. GET /v1/wallet-entities/{wallet_entity_id}/documents/{document_id} until status is ACCEPTED (or REJECTED, then upload a replacement). For a business, add owners with POST /v1/wallet-entities/{wallet_entity_id}/beneficial-owners.
3. Application: POST /v1/applications with wallet_entity_id, product_id, requested_credit_limit, income, and consent flags. Read GET /v1/applications/{application_id} for status and kyc.
4. Application documents: When status is PENDING_DOCUMENTS, POST /v1/applications/{application_id}/documents and PUT the file to upload_url, then poll the application until status leaves PENDING_DOCUMENTS.
5. Wallet: When the application is APPROVED, decision has credit_limit and apr. POST /v1/wallets with wallet_entity_id, product_id, credit_limit from the decision, and application_id. Creating the wallet also creates its default financial account (kind CREDIT, purpose ISSUING, in the program default currency); it appears in financial_account_ids and emits financial_account.created.
6. Card: POST /v1/cards with wallet_id and form_factor (VIRTUAL or PHYSICAL). Physical cards require shipping. The card spends against the wallet's credit and spend limits. Card responses include last_four and expiry, never PAN or CVV. Display PAN in a PCI iframe. See Secure card display.
Wallet entity → documents → application → documents → wallet → card
POST PUT POST PUT POST POST
Person versus business
| Step | Person | Business |
|---|---|---|
| Create wallet entity | first_name, last_name, date_of_birth, ssn_last4 or government_id | legal_name, legal_type, tax_id, control_person |
| Extra people | Beneficial owners (create body or nested POST) | |
| Extra files | Government identity, proof of address | Articles, EIN letter, owner identity |
resubmit_for_verification: true so a new check runs on the updated data. PATCH an open application with status: WITHDRAWN to stop review, or send updated income / requested_credit_limit.
All of these operations are program-scoped: send X-Program-ID when the API key can access more than one program. Creating a wallet entity, application, document, or beneficial owner accepts an optional Idempotency-Key.