Start with whose account you are onboarding, then identify whether the virtual account holder is a business or an individual. Your customer model determines which account to use; the holder’s identity determines the verification requirements.
Choose your customer model
Direct customers
Use your existing account to open virtual accounts in your own name. Retrieve itsid with List Accounts, then set or complete your identity profile with Update Account.
Platform customers
Use Create Account to create one account per end customer, supplying that customer’s identity profile. For a business, you can include associated persons in the same request. If the end customer already has an account, reuse it. Their virtual accounts are opened in their name. To open virtual accounts for your platform itself, use your existing fee-collection account and your platform’s own identity profile.Identify the virtual account holder
Both customer models use the same identity types. Settype to business or individual when creating or updating the account’s identity profile. Once set, this identity type cannot be changed.
Business and individual describe the account holder’s identity. The virtual account group’s
type selects a service from List Group Types.
Accounts, groups and virtual accounts
An account stores the identity of the business or individual selected above. A virtual account group tracks that account’s onboarding requirements, approval, and activation for a group type. You can onboard the same account for multiple group types, with one group per type. Each group is onboarded and enabled separately. Repeating Create Virtual Account Group for the same account and type returns the existing group. A virtual account belongs to one group and provides bank details in the account holder’s name, with its own balance in one currency. Once the group hasonboarding_status: approved and status: enabled, you can create virtual accounts in its supported currencies, including multiple virtual accounts in the same currency.
Complete onboarding
Follow the business or individual flow below for the account you selected. If its identity profile and any associated persons are already complete, continue to Open the group. After you open the group, Get Virtual Account Group returns the outstandingrequirements. Clear them item by item. Hop submits the account for review automatically; there is no submit call.
Youthe API callerHopautomaticBankpartner bank
Business account
- Identity
- 1YouSet the account identity: legal name, registration number, incorporation date, registered addressPATCH/customers/{cid}/accounts/{aid}
- 2YouAdd the people behind the entity: at least one with
is_signerPOST/accounts/{aid}/associated-persons aap_ - Open the group
- 3YouOpen the group: safe to call before the identity is set, it just comes back with a requirementPOST/accounts/{aid}/virtual-account-groups vag_
- 4HopRaises the agreements the entity must signagr_
- Clear requirements
- 5YouRead what is outstanding. This list drives everything that followsGET/virtual-account-groups/{gid} requirements[]
- 6YouAccept the agreements, naming the signerPOST/{gid}/agreements/actions signer_id required
- 7YouUpload each requested document against its requirement keyPOST/{gid}/documents doc_
- Review
- 8HopSubmits the entity once nothing is outstanding. No call from youunder_review
- 9BankVerifies the entity and its people, then approves or asks for moreapproved · action_needed
- Go live
- 10HopEnables the group. Virtual accounts can now be createdstatus: enabled
- 11YouCreate a virtual account in the currency you needPOST/{gid}/virtual-accounts va_
- 12BankIssues the bank details; the virtual account leaves
pendingIBAN · account number
Individual account
- Identity
- 1YouSet the account identity: name, date of birth, nationality, address, tax residence and due-diligence answersPATCH/customers/{cid}/accounts/{aid}
- Open the group
- 2YouOpen the group. No associated persons are needed for an individualPOST/accounts/{aid}/virtual-account-groups vag_
- 3HopRaises the agreements the person must signagr_
- Clear requirements
- 4YouRead what is outstanding. For an individual this is profile fields and identity documentsGET/virtual-account-groups/{gid} requirements[]
- 5YouAccept the agreements: omit
signer_id, the person signs as themselvesPOST/{gid}/agreements/actions no signer_id - 6YouUpload each requested document against its requirement keyPOST/{gid}/documents doc_
- Review
- 7HopSubmits the person once nothing is outstanding. No call from youunder_review
- 8BankVerifies the person, then approves or asks for moreapproved · action_needed
- Go live
- 9HopEnables the group. Virtual accounts can now be createdstatus: enabled
- 10YouCreate a virtual account in the currency you needPOST/{gid}/virtual-accounts va_
- 11BankIssues the bank details; the virtual account leaves
pendingIBAN · account number
What each requirement means
Everything after the group is opened is driven by therequirements list on Get Virtual Account Group. Four kinds appear:
Saving an identity profile or an associated person resumes onboarding on its own, so poll the group rather than re-creating anything.