Create a Transaction

What is a Transaction?

A Transaction in the Quickvee Pay Payments API initiates the movement of funds between two users — typically a payer (sender) and a payee (recipient) — via the ACH network. It represents the debit leg of the transfer, capturing the withdrawal of funds from the payer’s bank account. Once processed, the transaction will result in a corresponding Payout, which reflects the credit leg — the delivery of funds to the payee. Each transaction is uniquely identified by a ksuid and includes metadata such as the amount, participants, and processing status.

Transactions can represent:

Business to Business payments
Business to Person disbursements
Person to Business collections

Once created, the transaction enters a processing pipeline that will debit the payer's bank account and credit the payee's bank account, subject to ACH network rules and timing.

Overview

Creating a transaction involves initiating a fund transfer between two parties — a payer (sender) and a payee (recipient). Both parties must be onboarded and must have valid, connected bank accounts within the Quickvee Pay system.

When a transaction is successfully created, the API returns a unique ksuid that can be used to track its status or retrieve its details later.

This guide outlines the required fields, entity prerequisites, and common validation scenarios encountered when initiating a transaction.

Failure Simulation

Quickvee Pay provides support for simulating transaction failures in the sandbox environment, allowing you to test how your integration responds to various ACH return scenarios.

To simulate a failure, include the failure_simulation parameter in the request payload when creating a transaction. This parameter accepts one of the following values:

beforePayout – Simulates an ACH failure before the credit (payout) is sent to the destination bank.
afterPayout – Simulates an ACH failure after the payout has been sent.

Both scenarios will result in a transaction failure with an ACH return code of R01 (Insufficient Funds), allowing you to test failure-handling logic at different points in the transaction lifecycle.

Testing

To test transactions in Quickvee Pay’s sandbox environment, you’ll need two entities:

One with a connected bank account to act as the payer
One with a connected bank account to act as the payee

You can provide these details when creating test users via the following endpoints:

This setup allows you to perform end-to-end transaction testing — including creation, settlement, and simulated failure — without using real financial data.

Every transaction created within the Quickvee Pay system requires that at least one party (either the payer or payee) has successfully completed KYB verification. This means one side of the transaction must be a registered Merchant.

Step 1: Confirm Participants Are Onboarded

Before creating a transaction, both the payer and payee must exist in the system as valid users (i.e. persons or businesses).

Each must meet the following criteria:

Successfully onboarded using the appropriate flow
Possess a valid ksuid
Have an active, connected bank account (manual or Plaid-linked)

You will reference these participants using:

payer_id — the sender of funds
payee_id — the recipient of funds

If either party is missing or has an invalid account, the transaction will be rejected.

Step 2: Determine Transaction Type and Amount

Each transaction must include:

amount — The dollar value to be transferred
speed — Indicates processing tier (e.g., standard or sameday, if available in your integration)

Optional fields include:

description — Optional metadata for reporting

All amounts must be denominated in USD and specified in cents (e.g., $10.00 = 1000).

Step 3: Submit the Transaction

To initiate the transaction, send a POST request to the following endpoint: /api/v1/m/payments with the required fields. Upon success, the API will return a ksuid representing the newly created payment. This can be used to fetch status updates or cancellation requests.

Character Limits

When creating a transaction, some fields have strict maximum lengths. These limits come from ACH and banking-partner rules so entries stay compatible with downstream processing:

company_name — 16 characters maximum.
description — 10 characters maximum.
addenda — 80 characters maximum.

Values longer than these limits can cause the request or downstream ACH processing to fail—truncate or validate in your app before calling the API.

Step 4: Monitor the Transaction Status

Once submitted, a transaction may move through multiple states depending on processing speed, ACH timing, and risk evaluation.

Possible states include:

RECEIVED
PENDING
PROCESSING
SETTLED
RETURNED
FAILED
PAUSED
CANCELLED

To monitor the state of a transaction, you can use one of the following methods:

API Polling: Use the GET /api/v1/m/payments/{payment_id} endpoint to fetch the current status of a specific transaction.

To fully monitor the lifecycle of a funds transfer, it’s important to understand that a Transaction only represents the debit leg of the movement. The Payout, which delivers funds to the payee, follows its own processing lifecycle and status updates.

We strongly recommend polling the Transaction to accurately track the complete flow of funds — from initiation to settlement.

Example

Create a Payment

curl --location '{base}/api/v1/m/payments' \
--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}' \
--header 'Idempotency-Key: {unique_random_string}' \
--data '{
    "payee_id": "{ksuid_of_payee}",
    "payer_id": "{ksuid_of_payer}",
    "amount": 100000,
    "speed": "standard",
    "memo": "optional"
}'

Next Up

Read Manage Transactions

Questions?

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

Resources

Below you will find some helpful resources to assist with understanding how transactions work in Quickvee Pay.

ACH Return Codes