Onboard a Person

What is a Person?

A Person in the Quickvee Pay Payments API represents an individual who can send or receive ACH transfers. Each person is uniquely identified by a ksuid, which is returned upon successful onboarding and is required for future operations such as linking bank accounts and initiating transfers.

The first step in integrating with the Quickvee Pay Payments API is to onboard a person and this guide outlines the onboarding workflow and provides context for common use cases.

We do have an alternative onboarding method outside of our API that allows you to create a person using our BankLink SDK product. This method allows you to embed our bank link SDK directly into your application and users can connect their bank account using open banking.

Testing

When testing in Quickvee Pay’s sandbox environment, you can create a person as usual. To include a bank account, simply use any random 12-digit account number along with one of our supported test routing numbers.

Step 1: Collect Person Information

To create a person, you can provide any combination of the following fields:

• First name
• Last name
• Email
• Phone
• Address

While only a bank account is required to create a person, we strongly recommend supplying full information to ensure a smooth onboarding experience and help meet regulatory and compliance standards.

Step 2: Provide a Bank Account

You can onboard a person with or without a connected bank account. If you choose to provide one, we support two methods:

Option A: Manual Entry

You can onboard a person using manually provided account details:

• account_number
• routing_number
• account_name
• account_type (checking or savings)

Example

curl --location '{base}/api/v1/m/persons' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: {sha256(API_KEY)}' \
--header 'X-Timestamp: {current_unix_timestamp}' \
--header 'X-Nonce: {unique_random_string}' \
--header 'X-Signature: {hex_encoded_signature}' \
--data '{
  "person": {
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "address": {
      "line_1": "string",
      "line_2": "string",
      "city": "string",
      "state": "string",
      "zip": "string"
    }
  },
  "bank_account": {
    "account_number": "9876543211",
    "routing_number": "021000021",
    "account_name": "string",
    "account_type": "checking|savings"
  }
}'

Option B: Link a Plaid Account (WIP)

If you're using Plaid for bank account linking, include the following fields:

• bank_account.plaid.access_token
• bank_account.plaid.account_id

Real-Time Validation (Recommended)

To reduce fraud risk and ensure funds can be successfully routed, we recommend enabling real-time bank account validation during onboarding. This feature is powered by our Account Intelligence product, which provides intelligent validation of routing and account numbers at the time of submission.

This validation step confirms that the provided routing and account numbers are both valid and correctly formatted. If name_match is enabled, it also checks that the account holder’s name aligns with the expected identity. In addition to these checks, the response includes a Risk Score and a set of decisioning insights that explain how the account was evaluated.

Although optional, enabling this validation is strongly recommended for all production integrations to reduce failure rates and improve payout reliability.

Error Handling

The onboarding endpoint may return the following common HTTP status codes:

• 400 — Bad Request: Missing headers, malformed body, or other request issues.
• 401 — Unauthorized: Invalid or malformed access token.
• 403 — Forbidden: Blocked IP address or restricted access.
• 406 — Not Acceptable: Failed account validation or invalid billing merchant UUID.
• 422 — Unprocessable Entity: Field-level validation errors.

Next Up

Read Manage Users

Questions?

If you're encountering any issues, please reach out to support@quickveepay.com.