Create ACH 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\":\"[email protected]\",\"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 -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

{
  "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 RequestSolution: 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 RequestSolution: Ensure accountType is either “checking” or “savings” (lowercase).

Missing required fields

Error: 400 Bad RequestSolution: Verify all required fields are present: paymentType, merchantId, StandardEntryClassCode, bank object, and transaction object.

Payment processing failed

Error: 422 Unprocessable EntitySolution: 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

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

Overview

Authorization

Payments

Merchants

Endpoint

Overview

Authentication

Request Body

Example Request

Response

Success Response (201 Created)

Example Response

Code Examples

Error Responses

Common Error Scenarios

Important Notes

Best Practices

Next Steps

Get Payment Status

Refund Payment

Overview

Authorization

Payments

Merchants

​Endpoint

​Overview

​Authentication

​Request Body

​Example Request

​Response

​Success Response (201 Created)

​Example Response

​Code Examples

​Error Responses

​Common Error Scenarios

​Important Notes

​Best Practices

​Next Steps

Get Payment Status

Refund Payment

Endpoint

Overview

Authentication

Request Body

Example Request

Response

Success Response (201 Created)

Example Response

Code Examples

Error Responses

Common Error Scenarios

Important Notes

Best Practices

Next Steps