Create ACH Payment

Process an ACH (Automated Clearing House) bank transfer payment

Endpoint

POST https://api.digitzs.com/payments

Overview

Use this endpoint to process ACH payments directly from a customer’s bank account. This method does not require creating a customer account or storing payment method tokens.

ACH payments typically take 3-5 business days to settle. Funds are not immediately available.

Authentication

Header	Value	Required
x-api-key	Your API key from onboarding	Yes
Authorization	Bearer {appToken}	Yes
appId	Your application ID	Yes
Content-Type	application/json	Yes

Request Body

data · object · required

Container for API data

data.requestId · string

UUID for idempotency. If provided, must be in valid UUID format. Optional but recommended for preventing duplicate transactions.

data.type · string · required

Must be "payments"

data.attributes · object · required

Container for payment attributes

data.attributes.paymentType · string · required

Must be "ACH" for ACH payments

data.attributes.merchantId · string · required

The merchant account identifier

data.attributes.miscData · string

Optional JSON string containing additional metadata like email, IP addresses, or custom data

data.attributes.StandardEntryClassCode · string · required

Must be "WEB" for internet-initiated ACH transactions

data.attributes.bank · object · required

Bank account information

Show Bank object properties

data.attributes.bank.bankName · string · required

Name of the financial institution

data.attributes.bank.accountType · string · required

Type of account - must be "checking" or "savings"

data.attributes.bank.accountName · string · required

Full name of the account holder

data.attributes.bank.accountNumber · string · required

Bank account number

data.attributes.bank.routingNumber · string · required

9-digit bank routing number. Must be a valid routing number even in test environment.

data.attributes.transaction · object · required

Transaction details

Show Transaction object properties

data.attributes.transaction.amount · string · required

Payment amount in cents (e.g., “3635” for $36.35)

data.attributes.transaction.currency · string · required

Three-letter currency code (ISO 4217). Currently only "USD" is supported.

data.attributes.transaction.invoice · string · required

Invoice or reference number for the transaction

Example Request

{
  "data": {
    "requestId": "f8d0fedd-fad0-4c53-bb8d-44a4cd28573b",
    "type": "payments",
    "attributes": {
      "paymentType": "ACH",
      "merchantId": "merchant_123456",
      "miscData": "{\"email\":\"[e-mail]\",\"originIp\":\"192.168.1.1\",\"customerIp\":\"203.0.113.0\"}",
      "StandardEntryClassCode": "WEB",
      "bank": {
        "bankName": "Wells Fargo",
        "accountType": "checking",
        "accountName": "John Doe",
        "accountNumber": "1234567890",
        "routingNumber": "026009593"
      },
      "transaction": {
        "amount": "3635",
        "currency": "USD",
        "invoice": "INV-2024-001"
      }
    }
  }
}

Response

Success Response (201 Created)

links · object

Contains URLs related to the resource

Show properties

links.self · string

URL of the current endpoint

data · object

Container for response data

Show properties

data.type · string

Resource type - will be "payments"

data.id · string

Unique payment transaction identifier

data.attributes · object

Show properties

data.attributes.paymentType · string

Payment type - "ACH"

data.attributes.transaction · object

Show Transaction details

data.attributes.transaction.code · string

Response code - "0" indicates success

data.attributes.transaction.message · string

Human-readable response message

data.attributes.transaction.amount · string

Transaction amount in cents

data.attributes.transaction.currency · string

Currency code

data.attributes.transaction.invoice · string

Invoice reference number

Example Response

{
  "links": {
    "self": "https://api.digitzs.com/payments"
  },
  "data": {
    "type": "payments",
    "id": "pay_ach_abc123xyz",
    "attributes": {
      "paymentType": "ACH",
      "transaction": {
        "code": "0",
        "message": "Success",
        "amount": "3635",
        "currency": "USD",
        "invoice": "INV-2024-001"
      }
    }
  }
}

Code Examples

cURL

curl -X POST https://api.digitzs.com/payments \
  -H "x-api-key: your-api-key" \
  -H "Authorization: Bearer your-app-token" \
  -H "appId: your-app-id" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "payments",
      "attributes": {
        "paymentType": "ACH",
        "merchantId": "merchant_123456",
        "StandardEntryClassCode": "WEB",
        "bank": {
          "bankName": "Wells Fargo",
          "accountType": "checking",
          "accountName": "John Doe",
          "accountNumber": "1234567890",
          "routingNumber": "026009593"
        },
        "transaction": {
          "amount": "3635",
          "currency": "USD",
          "invoice": "INV-2024-001"
        }
      }
    }
  }'

Error Responses

400 Bad Request

{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "Invalid routing number",
      "source": {
        "pointer": "/data/attributes/bank/routingNumber"
      }
    }
  ]
}

Common Error Scenarios

Invalid routing number

Error: 400 Bad Request

Solution: Verify the routing number is a valid 9-digit ABA routing number. The test environment requires real routing numbers.

Invalid account type

Error: 400 Bad Request

Solution: Ensure accountType is either “checking” or “savings” (lowercase).

Missing required fields

Error: 400 Bad Request

Solution: Verify all required fields are present: paymentType, merchantId, StandardEntryClassCode, bank object, and transaction object.

Payment processing failed

Error: 422 Unprocessable Entity

Solution: The payment was rejected by the bank. Common reasons include insufficient funds, closed account, or invalid account information.

Important Notes

Real Routing Numbers Required: Even in the test environment, you must use valid bank routing numbers. Invalid routing numbers will be rejected.

Settlement Time: ACH payments take 3-5 business days to settle. The payment will appear as “pending” during this time.

Idempotency: Use the optional requestId field with a UUID to prevent duplicate payments if your request is accidentally submitted multiple times.

Best Practices

1. Validate Bank Information: Verify routing and account numbers before submitting to reduce failed payments
2. Store Payment IDs: Save the returned payment ID for status checking and reconciliation
3. Handle Async Nature: ACH is asynchronous - implement webhooks or polling to track payment status
4. Collect Customer Consent: Ensure you have proper authorization to debit the customer’s account
5. Use miscData Field: Store additional context like customer email, IP addresses for fraud prevention and customer support

Next Steps

Get Payment Status

Check the status of your ACH payment

Refund Payment

Learn how to refund an ACH payment