Customers and onboarding

Register the customer#

Shell

curl -X POST https://sandbox.a2ainstapay.com/v1/customers \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{"type":"business","external_ref":"merchant-2001","email":"owner@example.com","mobile_number":"+16465550123","prefill":{"legal_name":"Seaside Bakery LLC","trading_name":"Seaside Bakery"}}'

Field	Notes
`type`	`individual` for a consumer, `business` for a merchant
`external_ref`	Your own reference, unique in your workspace, up to 64 characters
`email`, `mobile_number`	The mobile number is a US number in E.164 format. A number can hold one account of each type
`prefill`	Optional values to start the screens with: `first_name` and `last_name`, or `legal_name` and `trading_name`

The response has verification.status created and an onboarding_session. Open it with the SDK.

What the customer does on the hosted screens#

Step	Consumer	Merchant
Mobile check	One-time code to the mobile number	One-time code to the mobile number
Details	Name, date of birth (18 or over), residential address, SSN or ITIN	Legal and trading name, EIN, entity type, industry, registered address, website, expected volume and average ticket
People		Every owner of 25% or more and one control person, with a certification that the information is complete
Documents	Digital Account Terms, E-SIGN Consent, Privacy Notice, Customer Identification Notice	Merchant Services Agreement, Acceptable Use Policy, Privacy Notice, E-SIGN Consent
PIN	A six-digit PIN that is not a simple sequence	A six-digit PIN for the business's authorized user

Full SSNs and EINs are used for the checks and are not kept. A business in a prohibited industry is refused at once, before any personal details are collected.

Verification outcomes#

Status	Meaning	What to do
`pending`	Checks are running	Show "checking your details"
`approved`	The Digital Account is open; `account_id` is set and `account.created` follows	Continue to bank linking
`in_review`	The compliance team is reviewing, for example a possible sanctions match or a recent SIM swap	Tell the customer you will let them know; wait for the webhook
`rejected`	The account cannot be opened	Show a neutral message. A new application is possible after `verification.retry_available_at`

Each change raises customer.verification.updated. For merchants, GET /v1/customers/{id}/owners lists the owners and their own outcomes.

If the customer leaves before finishing#

The session expires, and the customer stays created. Create a new session to let them continue:

Shell

curl -X POST https://sandbox.a2ainstapay.com/v1/sessions -H "Authorization: Bearer $A2A_ACCESS_TOKEN" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"flow":"onboarding","customer_id":"cus_..."}'

After onboarding#

Need	Flow or endpoint
The customer forgot their PIN	`POST /v1/sessions` with `flow: pin_reset`
New e-mail, mobile number or address	`flow: contact_change`. A new address re-verifies the customer
Updated customer documents	`flow: terms_acceptance` when `GET /v1/customers/{id}/documents` shows `pending_acceptance`
PIN locked after ten wrong attempts	`customer.pin_locked`; it unlocks after an hour, or with a PIN reset
Close the account	`POST /v1/customers/{id}/close`; any balance is paid to the verified linked account

Questions about this page? Contact developer support.