Skip to main content
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 its id 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. Set type 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 has onboarding_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 outstanding requirements. Clear them item by item. Hop submits the account for review automatically; there is no submit call.
Youthe API callerHopautomaticBankpartner bank

Business account

  1. Identity
  2. 1You
  3. 2You
    Add the people behind the entity: at least one with is_signerPOST/accounts/{aid}/associated-persons aap_
  4. Open the group
  5. 3You
  6. 4Hop
    Raises the agreements the entity must signagr_
  7. Clear requirements
  8. 5You
    Read what is outstanding. This list drives everything that followsGET/virtual-account-groups/{gid} requirements[]
  9. 6You
    Accept the agreements, naming the signerPOST/{gid}/agreements/actions signer_id required
  10. 7You
  11. Review
  12. 8Hop
    Submits the entity once nothing is outstanding. No call from youunder_review
  13. 9Bank
    Verifies the entity and its people, then approves or asks for moreapproved · action_needed
  14. Go live
  15. 10Hop
    Enables the group. Virtual accounts can now be createdstatus: enabled
  16. 11You
  17. 12Bank
    Issues the bank details; the virtual account leaves pendingIBAN · account number

Individual account

  1. Identity
  2. 1You
  3. Open the group
  4. 2You
    Open the group. No associated persons are needed for an individualPOST/accounts/{aid}/virtual-account-groups vag_
  5. 3Hop
    Raises the agreements the person must signagr_
  6. Clear requirements
  7. 4You
  8. 5You
  9. 6You
  10. Review
  11. 7Hop
    Submits the person once nothing is outstanding. No call from youunder_review
  12. 8Bank
    Verifies the person, then approves or asks for moreapproved · action_needed
  13. Go live
  14. 9Hop
    Enables the group. Virtual accounts can now be createdstatus: enabled
  15. 10You
  16. 11Bank
    Issues the bank details; the virtual account leaves pendingIBAN · account number

What each requirement means

Everything after the group is opened is driven by the requirements 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.

Troubleshooting