🏦 Direct Debits

Initiate automated bank debits to collect premiums directly from an insured's bank account. Supports individual debits and batch collections across multiple policies.

Initiate a Direct Debit

POST /api/v1/ach/debits

Field	Type	Required	Description
`employer_id`	string	Yes	Employer ObjectId
`carrier_id`	string	Yes	Carrier ObjectId
`policy_id`	string	Yes	Policy ObjectId
`bank_account_id`	string	Yes	Bank account ID to debit from
`amount_cents`	integer	Yes	Amount in cents
`payment_purpose`	string	Yes	See payment purposes below
`description`	string	No	Human-readable description
`idempotency_key`	string	No	Unique key to prevent duplicate charges
`effective_date`	string	No	Desired effective date (ISO 8601)
`metadata`	object	No	Custom key-value pairs

Payment Purposes

Purpose	Description
`paygo`	Pay-as-you-go premium collection
`down_payment`	Initial policy down payment
`installment`	Scheduled installment payment
`late_payment`	Late payment collection
`extra_payment`	Extra/overpayment
`overdue_payment`	Overdue amount

curl -X POST /api/v1/ach/debits \
  -H "X-Client-ID: $CLIENT_ID" \
  -H "X-Client-Secret: $CLIENT_SECRET" \
  -d '{
    "employer_id": "681xyz789abc123456789012",
    "carrier_id": "680abc456def789012345678",
    "policy_id": "682def789ghi012345678901",
    "bank_account_id": "684abc123def456789012345",
    "amount_cents": 85000,
    "payment_purpose": "paygo",
    "description": "PayGo premium - March 2026",
    "idempotency_key": "paygo_march_2026_acme"
  }'

✅
Response (201 Created)

{
  "ok": true,
  "data": {
    "success": true,
    "transaction_id": "685def456ghi789012345678",
    "status": "PENDING",
    "amount": 85000
  }
}

⚠️
Idempotency: Always provide an idempotency_key to prevent duplicate charges. If you retry a request with the same key, the original transaction is returned instead of creating a new one.

Check Debit Status

GET /api/v1/ach/debits/{transaction_id}/status

Transaction Statuses

PENDING → UPLOADED → PROCESSING → COMPLETED
                                  ↘ RETURNED → RESOLVED
                                  ↘ FAILED   → RESOLVED

Status	Description
`PENDING`	Created, awaiting batch processing
`UPLOADED`	Submitted to the banking network
`PROCESSING`	Being processed by the banking network
`COMPLETED`	Funds received
`RETURNED`	Bank rejected the debit (insufficient funds, closed account, etc.)
`FAILED`	Processing error
`RESOLVED`	Return or failure has been handled

Batch Collection

Collect from a single employer across multiple policies in one batch.

POST /api/v1/ach/collections

Field	Type	Required	Description
`employerId`	string	Yes	Employer to debit
`bankAccountId`	string	Yes	Bank account ID
`policyCollections`	array	Yes	One entry per policy
`policyCollections[].policyId`	string	Yes	Policy ObjectId
`policyCollections[].totalInDollars`	number	Yes	Amount in dollars
`policyCollections[].description`	string	Yes	Line-item description
`policyCollections[].idempotencyKey`	string	Yes	Unique per collection

curl -X POST /api/v1/ach/collections \
  -H "X-Client-ID: $CLIENT_ID" \
  -H "X-Client-Secret: $CLIENT_SECRET" \
  -d '{
    "employerId": "681xyz789abc123456789012",
    "bankAccountId": "684abc123def456789012345",
    "policyCollections": [
      {
        "policyId": "682def789ghi012345678901",
        "totalInDollars": 1500.00,
        "description": "WC Premium - Q1 2026",
        "idempotencyKey": "wc_q1_2026_acme"
      },
      {
        "policyId": "682ghi012jkl345678901234",
        "totalInDollars": 850.00,
        "description": "GL Premium - Q1 2026",
        "idempotencyKey": "gl_q1_2026_acme"
      }
    ]
  }'

✅
Response (202 Accepted) — batch processing is asynchronous.

List Transactions

GET /api/v1/ach/transactions?employer_id=...&status=COMPLETED&from_date=2026-01-01&page=1&limit=50

Parameter	Type	Description
`carrier_id`	string	Filter by carrier
`employer_id`	string	Filter by employer
`policy_id`	string	Filter by policy
`status`	string	`PENDING`, `COMPLETED`, `RETURNED`, etc.
`from_date`	string	Start date (ISO 8601)
`to_date`	string	End date
`sort_by`	string	Field to sort by
`sort_order`	string	`asc` or `desc`

Transaction History

GET /api/v1/ach/transactions/{id}/history

Returns the audit trail for a specific transaction.

Transaction Fees

GET /api/v1/ach/transactions/{id}/fees

Returns fee breakdown for a transaction.

💡
Bank debit settlement typically takes 2-5 business days. The COMPLETED status means funds have been received. Use webhooks to get notified in real time.

Direct Debits

🏦 Direct Debits

Initiate a Direct Debit

Payment Purposes

Response (201 Created)

Idempotency: Always provide an `idempotency_key` to prevent duplicate charges. If you retry a request with the same key, the original transaction is returned instead of creating a new one.

Check Debit Status

Transaction Statuses

Batch Collection

Response (202 Accepted) — batch processing is asynchronous.

List Transactions

Transaction History

Transaction Fees

Bank debit settlement typically takes 2-5 business days. The `COMPLETED` status means funds have been received. Use webhooks to get notified in real time.

🏦 Direct Debits

Initiate a Direct Debit

Payment Purposes

Response (201 Created)

Idempotency: Always provide an idempotency_key to prevent duplicate charges. If you retry a request with the same key, the original transaction is returned instead of creating a new one.

Check Debit Status

Transaction Statuses

Batch Collection

Response (202 Accepted) — batch processing is asynchronous.

List Transactions

Transaction History

Transaction Fees

Bank debit settlement typically takes 2-5 business days. The COMPLETED status means funds have been received. Use webhooks to get notified in real time.

Idempotency: Always provide an `idempotency_key` to prevent duplicate charges. If you retry a request with the same key, the original transaction is returned instead of creating a new one.

Bank debit settlement typically takes 2-5 business days. The `COMPLETED` status means funds have been received. Use webhooks to get notified in real time.