Onboard User

If you wish to receive payments from users or send money on behalf of your users, you will need to onboard them first. These users will be unique to your business, so if they already have a checkbook.io account, or they visit Checkbook.io and sign up for an account, this will be a separate account that you are creating.

Create the user

To onboard these users, you will call POST /v3/user and supply a user_id for the user, and the user's name. The response from this API call will include the new user's API key and API secret. For additional further requests to onboard/send money on behalf of this user, you will use their API keys.

The interactive form allows you to test the API endpoint in our demo environment right from the reference page. Here's an example of a request:

curl --request POST \
  --url https://demo.checkbook.io/v3/user \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"user_id":"[email protected]","name":"James Bond"}'

And the corresponding response:

{
    "key":"92784091e84c48e7aab87d2e5141cb2d",
    "secret":"h8Yhlq0n4SuawATP649lh8byJtFTft",
    "user_id":"[email protected]"
}

For the user_idyou don't have to use an email address, you can use a custom identifier, for example, james_bond_007.

📘

Note

The previous request is for the demo environment. You will need to use either the sandbox endpoint if you want to create test users, or the production endpoint if you want to create real users.

Signing API requests

All future API request on behalf of this user will need to use for the Authorization header the keys returned by the call POST /v3/user. So for the example above, the Authorization header would look like this for the new user:

Authorization: 92784091e84c48e7aab87d2e5141cb2d:h8Yhlq0n4SuawATP649lh8byJtFTft

❗️

Save the API keys

Make sure to save the API keys in your database because you won't be able to retrieve them at a later time from our system.

Update user info

After onboarding the user, you will need to add their business information (or phone number if they are an individual). You'll add their info info by calling PUT /v3/user. We will need a first/last name, business name, address, tax id, and last 4 of their SSN.

The interactive form allows you to test the API endpoint in our demo environment right from the reference page. Here's an example of a request for updating the user date of birth:

curl --request PUT \
  --url https://demo.checkbook.io/v3/user \
  --header 'authorization: 92784091e84c48e7aab87d2e5141cb2d:h8Yhlq0n4SuawATP649lh8byJtFTft' \
  --header 'content-type: application/json' \
  --data '{"user":{"dob":"1921-11-11"}}'

Add a bank account

Next, you will need to add a bank for the new user. If you know the user's routing and account number, you can add their account with Manual Verification. If the user wishes to instantly verify their bank account you can use Instant Account Verification.

👍

Signing the API requests

Either you use Manual or Instant account verification make sure to sign the API requests using the user's API keys that you got when creating the user.