ACH Sale Transactions

An ACH Sale transaction debits funds from a customer's bank account. This is the primary method for accepting ACH payments.

Endpoint

POST /v1/transactions

Request Format

Using a Token (Recommended)

If you have an existing ACH token, use it directly:

{
  "type": "sale",
  "merchantId": "mid_abc123",
  "amount": 5000,
  "currency": "USD",
  "payment": {
    "token": "tkn_xyz789"
  }
}

Token Field Inheritance: If the token was created with firstName, lastName, accountBusinessName, or achMandate, those values are automatically used for the transaction. You don't need to include them in the request.

Overriding Token Fields: If you include firstName, lastName, accountBusinessName, or achMandate in the request, those values will be used for the transaction and the token will be updated with the new values.

Using Raw Bank Account Details

Alternatively, you can pass bank account details directly:

{
  "type": "sale",
  "merchantId": "mid_abc123",
  "amount": 5000,
  "currency": "USD",
  "payment": {
    "bankAccount": {
      "type": "personalChecking",
      "account": "123456789",
      "routing": "987654321",
      "bankCountry": "USA"
    }
  },
  "firstName": "John",
  "lastName": "Doe",
  "billingAddress": {
    "address": "123 Main St",
    "city": "New York",
    "region": "NY",
    "postal": "10001",
    "country": "USA"
  }
}

Request Fields

Required Fields

Bank Account Fields (when not using token)

Account Types

Customer Information (Required for Personal Accounts)

For personal account types (personalChecking, personalSavings):

Business Name (Required for Corporate Accounts)

For corporate account types (corporateChecking, corporateSavings):

Note: When using a token, firstName, lastName, and accountBusinessName are only required if they weren't provided when the token was created. If included in the request, they will override the token's stored values.

Optional Fields

Response Format

Pending Response (Typical for ACH)

{
  "id": "txn_01abc123def456",
  "type": "sale",
  "amount": 5000,
  "fee": 0,
  "currency": "USD",
  "merchantId": "mid_abc123",
  "authorization": {
    "status": "P",
    "processorCode": "00",
    "processorMessage": "ACH transaction submitted",
    "approvedAmount": 0
  },
  "payment": {
    "type": "personalChecking",
    "last4": "6789",
    "bin": "987654321"
  },
  "processor": {
    "id": "pfmCon_xyz789",
    "name": "Payrix",
    "routingSource": "plan"
  },
  "firstName": "John",
  "lastName": "Doe",
  "createdOn": "2024-01-15T10:30:00Z"
}

Response Fields

Transaction Statuses

Example: Personal Account Sale

{
  "type": "sale",
  "merchantId": "mid_abc123",
  "amount": 7500,
  "currency": "USD",
  "payment": {
    "bankAccount": {
      "type": "personalChecking",
      "account": "123456789",
      "routing": "987654321",
      "bankCountry": "USA"
    }
  },
  "firstName": "Jane",
  "lastName": "Smith",
  "description": "Monthly subscription",
  "reference": "INV-2024-001"
}

Example: Corporate Account Sale

{
  "type": "sale",
  "merchantId": "mid_abc123",
  "amount": 150000,
  "currency": "USD",
  "payment": {
    "bankAccount": {
      "type": "corporateChecking",
      "account": "987654321",
      "routing": "123456789",
      "bankCountry": "USA"
    }
  },
  "accountBusinessName": "Acme Corporation",
  "description": "Q1 Invoice Payment",
  "reference": "PO-2024-100"
}

Example: Sale with Tokenization

Create a multi-use token for future recurring payments by adding ?tokenize=true to the endpoint:

POST /v1/transactions?tokenize=true

{
  "type": "sale",
  "merchantId": "mid_abc123",
  "amount": 5000,
  "currency": "USD",
  "payment": {
    "bankAccount": {
      "type": "personalChecking",
      "account": "123456789",
      "routing": "987654321",
      "bankCountry": "USA"
    }
  },
  "firstName": "John",
  "lastName": "Doe"
}

The response will include a payment.token field that can be used for future transactions.

Webhooks

ACH transactions go through the ACH network and may take 1-3 business days to settle. Use webhooks to track status changes:

Important: Always rely on webhooks for final transaction status. Do not assume a pending ACH transaction will be approved.

Error Messages

These are Preczn API errors returned when a request fails validation or processing. The error and message fields correspond to the API response format documented in the ACH Error Reference.

Bank Account Validation Errors

Customer Information Errors

Token Errors

Transaction Errors

Configuration Errors

For a complete list of errors, see the ACH Error Reference.