Why can't I create a virtual account?

Virtual-account creation checks three gates in this order, and each returns a distinct code naming what to do. Fix the first one you hit, then retry.

1. 400 endorsement_required

The currency's endorsement was never requested. Enrollment is explicit: a customer without endo_usd is never reviewed for USD at all.

curl -s -X PATCH $BASE/api/customers/cus_... \
  -H "Api-Key: $KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"endorsements": ["endo_usd"]}'

If the customer is missing the profile fields endo_usd needs, this PATCH returns 422 endorsement_profile_required instead. For an individual, send email and phone, already on the customer or in the same request. For a business, send email. Tax data is not needed to request the endorsement, but the review asks for it in the missing bucket, so send tax_id, and tax_residence_country for an individual, as well.

2. 400 endorsement_not_approved

It was requested, but it is not approved. The message names the current status, and the customer's endorsements[].requirements buckets name everything still outstanding.

• compliance_review in missing: the customer was never submitted. Call POST /api/customers/{customer_id}/verifications. A 422 verification_incomplete from that call names exactly what is still owed.
• Other missing items: supply them with a PATCH. Before the first submission, submit afterwards. After it, the PATCH resubmits by itself.
• pending: the review is running. Wait for endorsement.approved.
• issues: see Verification needs more information.

3. 400 customer_name_required

The customer has no name on file, and the name becomes the account holder name on the account. Names are optional at creation, and an individual's are usually read from the identity document at submit, but a nameless customer cannot reach the banking rail. PATCH in first_name and last_name, or legal_name for a business.

Checking before you call

A customer's readiness is visible before you attempt creation:

curl -s $BASE/api/customers/cus_... -H "Api-Key: $KEY"

If the endo_usd entry in endorsements reads approved and the customer has a name, all three gates pass.

For the refusals that depend on the request body rather than the customer, such as unsupported_corridor, rail_unavailable, and virtual_account_exists, see Errors.