Search

Are you looking for test card numbers?

Would you like to contact support?

Issuin icon

Manage accounts

Create balance accounts and update an existing account holder resource.

After you create an account holder, you can update user information for KYC purposes, explicitly create balance accounts, or create multiple balance accounts for one account holder.

Update an account holder

You need to add information or update existing information for an accountHolder resource, most commonly during the KYC process.

Here is an example updating the address for accountHolders.id AHA1B2C3D4E5F6G7H8I9J0.

PATCH /accountHolders/{id} request
{
  "contact":{
    "address": {
      "city": "Amsterdam",
      "country": "NL",
      "stateOrProvince": "NH",
      "street": "89 Brannan Street",
      "street2": "Suite 601",
      "postalCode": "1020CD"
    }
  }
}

The response contains the updated accountHolder resource.

Response
{
  "id":"AHA1B2C3D4E5F6G7H8I9J0",
  "contact":{
    "address": {
      "city": "Amsterdam",
      "country": "NL",
      "stateOrProvince": "NH",
      "street": "89 Brannan Street",
      "street2": "Suite 601",
      "postalCode": "1020CD"
    }
    ...
  },
  ...
}

Multiple balance accounts for one account holder

In some scenarios, you may need multiple balance accounts for a single account holder. For example:

  • Multiple balance accounts under one account holder: A user requests additional cards to keep separate balances for their checking and savings accounts.
  • Multiple card holders under one parent account holder: A user requests additional cards with separate balances for their spouse or other family members.

Create balance accounts

A balance account is created automatically when you create an account holder. You can explicitly create balance accounts for more control over the process or create multiple balance accounts for one account holder.

To create a balance account, make a POST /balanceAccounts request providing:

  • accountHolderId: The ID of the accountHolder associated with this balance account.
  • description: A free-form text field.
  • reference: Your unique identifier for this balance account.

Here is an example for creating a new balance account for accountHolders.id AHA1B2C3D4E5F6G7H8I9J0.

POST /balanceAccounts request
{
  "balancePlatform": "YOUR_BALANCE_PLATFORM_ACCOUNT",
  "accountHolderId":"AHA1B2C3D4E5F6G7H8I9J0",
  "description":"{hint:Human-readable field description}S.Hopper - Main balance account{/hint}", 
  "reference":"{hint:Your unique identifier for this resource}myBalanceAccount_12345{/hint}" 
}

This returns the newly created balanceAccount resource.

Response
{
  "id":"BAB8B2C3D4E5F6G7H8D9J6GD4",
  "accountholderId":"AHA1B2C3D4E5F6G7H8I9J0",
  "description":"{hint:Human-readable field description}S.Hopper - Main balance account{/hint}", 
  "reference":"{hint:Your unique identifier for this resource}myBalanceAccount_12345{/hint}",
  "status":"active"
}

The balance account will have a zero initial balance. Before the user can use their card, you need to make sure the account has funds. For more information, refer to Manage funds.

Next steps