ROOKDocs
Sign In
5 min read•Updated August 2026

Partner Onboarding & Wallets

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

PATCH the wallet entity to correct PII. Send 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.

Was this page helpful?