​
Overview

USD accounts run on EU Rails (Fiat Republic) alongside EUR and GBP. To meet US banking requirements, an individual end user who needs to send or receive USD must complete an extra identity check: you supply a few additional profile fields and upload a government-issued ID, which the banking partner reviews. Once approved, the end user can hold USD fiat accounts and virtual accounts, and you can make USD payments on their behalf.
This applies to individual (KYC) end users only. Business (KYB) end users are verified through their standard onboarding — see End Users.

​
How USD verification works

1

Create the end user with the USD fields

On the individual create request, include the USD-required fields below (phone, nationality, identificationDocument). See End Users → Individual create.
2

Upload an identity document

Upload a clear scan or photo of the end user’s government-issued ID via the documents endpoint. See Uploading the document.
3

Wait for the banking partner's review

The partner reviews the document — typically 1–2 business days. Subscribe to Webhooks for the status change rather than polling.
4

Use USD

Once approved, assign the end user to USD fiat/virtual accounts and send USD payments.

​
Required end-user fields for USD

These fields are optional for EUR/GBP but required when the end user needs USD services:
​
phone
string
required
Max 20 characters.
​
nationality
string | string[]
required
2-letter ISO code, or an array of codes.
​
identificationDocument
object
required
{ type, number }. See the accepted type values below.
Already created the end user without these? Add them later with the update endpoint before uploading the document.

​
Accepted identity documents

DocumentidentificationDocument.typeNotes
Passport (recommended)PASSPORTClear photo page, not expired.
Driver’s licenceDRIVERS_LICENCEMust show full name and date of birth.
National ID cardNATIONAL_IDPhoto and personal details.
Work permitWORK_PERMITWhere applicable.

​
Uploading the document

Upload the ID against the end user as base64-encoded file data.
​
endUserId
string
required
The Balansas end user id (UUID) — the same id returned when you created the end user.
​
documentType
string
required
One of IDENTITY_VERIFICATION, identity, proof_of_address, other. Use IDENTITY_VERIFICATION for the USD identity check.
​
fileName
string
required
1–255 characters.
​
fileData
string
required
Base64-encoded file contents.
​
mimeType
string
required
One of application/pdf, image/jpeg, image/png.
The API validates the MIME type, the base64 encoding, the file name, and that the end user belongs to you. Everything about document quality is judged by the banking partner during review (see below).
Base64 inflates a file by roughly a third — keep the original file small (around 10 MB or less) so the request stays within limits.

Upload a verification document

Full request and response in the API Reference.

​
Document quality (what the reviewer checks)

The banking partner reviews the uploaded image. To get approved on the first try:

Do

  • High resolution, all text readable
  • Full document visible — all four corners
  • Valid, non-expired document
  • Colour image preferred
  • Name matches the end user’s profile

Avoid

  • Blurry or out-of-focus images
  • Cropped or partial documents
  • Glare or reflections hiding details
  • Edited or digitally altered images
  • Screenshots or photos of a screen

​
Document review outcomes

The banking partner reviews the uploaded document and reaches one of the outcomes below. These describe the document’s review state — they are not API status values. The end user’s own lifecycle is reported by end_user.status (pending_verification → active); subscribe to Webhooks for that transition rather than polling.
OutcomeMeaningAction
PendingDocument uploaded, awaiting the partner’s review (typically 1–2 business days).Wait for the webhook.
ApprovedVerified — USD services are enabled; the end user moves toward active.Start using USD.
RejectedDocument not accepted.Re-upload a corrected document.
Common rejection reasons: the document is expired, image quality is too low/blurry, the name doesn’t match the end user’s profile, the document type isn’t accepted, or the corners are cut off.

​
Errors

A bad upload fails fast with a 400 (invalid base64, unsupported mimeType, or a validation error on the fields above); an unknown or unowned endUserId returns 404. See Errors for the envelope and the Documents API reference for the full list.