Manage Users

Overview

In the Quickvee Pay Payments API, a user can take the form of a Person or a Business. These entities work together to represent the full lifecycle of participants in your ACH flow — from individuals initiating transactions, to businesses receiving funds, to merchants operating within a platform.

This guide provides a centralized reference for managing users across all three entity types. It includes endpoints for:

• Updating, listing, and retrieving people
• Updating, listing, and retrieving businesses
• Deleting a person
• Deleting a business

Each user record is uniquely identified by a ksuid, and many of these endpoints return rich data models, including associated relationships such as bank accounts, linked entities, and KYB status (where applicable). When deleting a user (such as a person), the record is logically deleted — meaning it is hidden from the API but retained in the system for compliance and auditing purposes.

Use this guide to query and manage the users in your platform efficiently.

People

In the Quickvee Pay Payments API, a Person represents an individual user within your platform. A person may be directly involved in sending or receiving funds, or they may be linked to a Business or Merchant entity as part of an onboarding or transaction workflow.

This flexible structure allows you to model a wide range of real-world scenarios—from independent users to employees or representatives acting on behalf of a larger organization. Person records support essential attributes such as name, contact information, and optional associations to other entities, enabling rich identity and relationship management across your integration.

A Person can be associated with a Business or Merchant. When retrieving a single Person or listing all People, there is a relations object in the response that will contain the UUID of the Business or Merchant associated with that Person.

List People

To retrieve a list of people, you can use the endpoint that returns all people associated with your vendor. This endpoint allows you to fetch a paginated list of people, including their UUIDs, names, and email addresses.

Example

curl --location '{base}/api/v1/m/customers?limit=10&offset=0&customer_type=person' \
--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}'

Fetch a Person

To retrieve a specific person, you will need the UUID of the person you want to retrieve. This endpoint allows you to fetch detailed information about a person, including their name, email, phone number, and the vendor they are associated with.

curl --location '{base}/api/v1/m/persons/{ksuid}' \
--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}'

Update a Person

To update a person, you must supply the UUID of the person record you wish to modify along with the fields you intend to change. This endpoint allows you to update basic identifying information such as name, email, or phone number.

Only fields explicitly passed in the request will be updated — all other fields will remain unchanged. This ensures you can make partial updates without affecting the full record.

Delete a Person

To delete a specific person, you will need the UUID of the person you want to delete. This endpoint allows you to remove a person from the system, which will also make any associated information such as bank accounts, transfers, and related businesses or merchants inaccessible.

Person Statuses

Each person record within the Quickvee Pay Payments API includes a status field that reflects their current standing within the system. This status determines whether they are permitted to participate in transactions and helps guide workflows related to compliance, fraud mitigation, and lifecycle management.

APPROVED

The person is fully verified and approved to send or receive funds.

REJECTED

The person has been rejected and cannot participate in any transactions. This is a status we add manually and signifies a user that cannot be reinstated.

ON_HOLD_FRAUD_PAYER

A fraud-related return has been reported by the payer. The person is on hold and cannot transact. You must reach out to customer support to initiate an internal review to reinstate the user.

ON_HOLD_FRAUD_PAYEE

A fraud-related return has been reported by the payee. The person is on hold and cannot transact. You must reach out to customer support to initiate an internal review to reinstate the user.

ON_HOLD_SANCTIONS

The person has been flagged for potential sanctions risk. They are on hold and cannot transact. You must reach out to customer support to initiate an internal review to reinstate the user.

SCHEDULED_FOR_DELETE

A deletion request has been received. The person is scheduled for deletion and cannot transact.

If a person enters a restricted status such as ON_HOLD_FRAUD_PAYER, ON_HOLD_SANCTIONS, or ON_HOLD_FRAUD_PAYEE, your system will receive a PersonStatusChanged event with details about the change, including reason and suggested next steps. In most cases, you will need to contact our support team, at support@quickveepay.com, to resolve the issue and restore the person's ability to transact.

Businesses

In the Quickvee Pay Payments API, a Business is a simple entity type that represents an organization capable of sending or receiving funds. Unlike Merchants, Businesses do not undergo KYB (Know Your Business) verification. However, they are modeled separately from People to ensure proper ACH classification and compliance with NACHA regulations.

A Business is automatically associated with a Person when it is onboarded. When retrieving a single Business or listing all Businesses, there is a relations object in the response that will contain the UUID of the Person associated with that Business.

List Businesses

To retrieve a list of all businesses associated with your API token, use the list endpoint. This will return a paginated array of business records including attributes such as UUID, legal name, and timestamps.

curl --location '{base}/api/v1/m/customers?limit=10&offset=0&customer_type=business' \
--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}'

Fetch a Business

To fetch details for a specific business, provide the business UUID. The response will include core attributes and metadata related to the business entity.

curl --location '{base}/api/v1/m/businesses/{ksuid}' \
--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}'

Update a Business

To update an existing business, send a PATCH request with the updated fields—such as name, address, or contact information. This helps maintain accurate records for downstream ACH processing and reporting.

While transactions are typically created using the UUID of the Person associated with a Business, this endpoint specifically requires the UUID of the Business entity itself.

List Customers (Person and Business)

To retrieve a list of all customers (person and business) associated with your merchant, use the list endpoint. This will return a paginated array of customer records including attributes such as KSUID, name, email addresses, etc.

curl --location '{base}/api/v1/m/customers?limit=10&offset=0' \
--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}'

Merchants

In the Quickvee Pay Payments API, a Merchant is a specialized type of Business that has completed KYB (Know Your Business) verification. KYB is a regulatory requirement that ensures the identity and legitimacy of a business entity before it can participate in financial transactions. At least one party in every transaction must be KYB-verified, which is why Merchants play a critical role in Quickvee Pay's compliance and payment workflows.

Although Merchants are technically a kind of Business, they require additional data during onboarding and are subject to stricter validation rules. This distinction allows Quickvee Pay to maintain compliance while enabling robust and flexible transaction models.

A Person is automatically associated with a Merchant when it is onboarded. When retrieving a single Merchant or listing all Merchants, there is a relations object in the response that will contain the UUID of the Person associated with that Merchant.

Compliance Status

Each Merchant record includes a compliance_status object that provides a complete view of the Merchant's eligibility to transact. This object contains the computed Compliance Status along with the underlying verification results that determine it. The kyb field reflects the status of the Merchant's business verification, while the kyc array contains the verification status for each Beneficial Owner associated with the Merchant. The top-level status field represents the overall computed Compliance Status, which must be approved for the Merchant to be eligible to transact.

Fields

Top Level

KYB Object

KYC Array Items

Each object in the kyc array represents a Beneficial Owner and their KYC verification result.

• ksuid (string) — Unique identifier of the Beneficial Owner.
• first_name (string) — First name of the Beneficial Owner.
• last_name (string) — Last name of the Beneficial Owner.
• status (string) — KYC verification status: approved or rejected.
• message (string or null) — When verification fails, the reason; otherwise null.
• updated_at (string) — Timestamp of the most recent status update.

In the example above, the computed status is rejected even though the KYB status is approved. This is because one of the Beneficial Owners (Jane Doe) has a KYC status of rejected. A Merchant is rejected if either KYB fails or any Beneficial Owner fails KYC.

When testing in the Sandbox environment, Social Security Numbers (SSNs) must follow specific formatting rules to be considered valid. The SSN:

• Cannot begin with "000" or any value in the range "900–999"
• Cannot have "00" as the middle two digits
• Cannot end in "0000"

Any other valid 9-digit SSN format outside of these constraints is acceptable for testing purposes.

Next Up

Read Create a Transaction

Questions?

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