# 

## When to use ACH for invoices

* B2B payments where customers pay by bank transfer
* Recurring invoices (rent, subscriptions, memberships)
* High-value transactions where card fees would be significant


## Flow

```mermaid
---
config:
  theme: 'neutral'
---
sequenceDiagram
    participant Merchant
    participant API as Paradise Gateway
    participant Bank as Customer's Bank
    Merchant->>API: POST /v1/payment_tokens (tokenize bank account)
    API-->>Merchant: payment_token
    Note over Merchant: Invoice generated
    Merchant->>API: POST /v1/transactions (bank_account_payment)
    API-->>Merchant: approved (pending settlement)
    API->>Bank: ACH debit initiated
    Bank-->>API: Settled (2-3 business days)
```

## Step 1: Tokenize the customer's bank account

Store the customer's bank account once. Use the token for all future invoice payments.

curl
```shell
curl -X POST \
  https://api.dev.paradisegateway.net/v1/payment_tokens \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{
    "customer_id": "CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB",
    "nickname": "Acme Corp Checking",
    "bank_account": {
      "routing_number": "021000021",
      "account_number": "123456789012",
      "account_type": "checking",
      "name": "Acme Corporation",
      "email": "ap@acmecorp.example.com"
    }
  }'
```

Python
```python
import os, requests

API_KEY = os.environ["PARADISE_API_KEY"]
BASE = "https://api.dev.paradisegateway.net"

token_resp = requests.post(
    f"{BASE}/v1/payment_tokens",
    headers={"Content-Type": "application/json", "APIKEY": API_KEY},
    json={
        "customer_id": "CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB",
        "nickname": "Acme Corp Checking",
        "bank_account": {
            "routing_number": "021000021",
            "account_number": "123456789012",
            "account_type": "checking",
            "name": "Acme Corporation",
            "email": "ap@acmecorp.example.com",
        },
    },
)
payment_token = token_resp.json()["payment_token"]
print(f"Token: {payment_token}")
```

JavaScript
```javascript
const API_KEY = process.env.PARADISE_API_KEY;
const BASE = "https://api.dev.paradisegateway.net";

const tokenResp = await fetch(`${BASE}/v1/payment_tokens`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "APIKEY": API_KEY },
  body: JSON.stringify({
    customer_id: "CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB",
    nickname: "Acme Corp Checking",
    bank_account: {
      routing_number: "021000021",
      account_number: "123456789012",
      account_type: "checking",
      name: "Acme Corporation",
      email: "ap@acmecorp.example.com",
    },
  }),
});
const { payment_token } = await tokenResp.json();
console.log(`Token: ${payment_token}`);
```

## Step 2: Process the invoice payment

When the invoice is due, debit the customer's bank account using the stored token.

curl
```shell
curl -X POST \
  https://api.dev.paradisegateway.net/v1/transactions \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{
    "type": "sale",
    "amount": 250000,
    "payment_method": {
      "type": "payment_token",
      "payment_token": "PAYMENT_TOKEN-02LGEHBA0BZSPA6WRY1T3H4CD"
    },
    "metadata": {
      "invoice_id": "INV-2026-0042"
    }
  }'
```

Python
```python
txn_resp = requests.post(
    f"{BASE}/v1/transactions",
    headers={"Content-Type": "application/json", "APIKEY": API_KEY},
    json={
        "type": "sale",
        "amount": 250000,
        "payment_method": {
            "type": "payment_token",
            "payment_token": payment_token,
        },
        "metadata": {"invoice_id": "INV-2026-0042"},
    },
)
txn = txn_resp.json()
print(f"Status: {txn['response_status']}, ID: {txn['id']}")
```

JavaScript
```javascript
const txnResp = await fetch(`${BASE}/v1/transactions`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "APIKEY": API_KEY },
  body: JSON.stringify({
    type: "sale",
    amount: 250000,
    payment_method: { type: "payment_token", payment_token },
    metadata: { invoice_id: "INV-2026-0042" },
  }),
});
const txn = await txnResp.json();
console.log(`Status: ${txn.response_status}, ID: ${txn.id}`);
```

## Step 3: Track settlement

ACH transactions settle in 2–3 business days. Poll the transaction or check batch status to confirm.

```shell
curl https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC \
  -H "APIKEY: YOUR-API-KEY"
```

| State | Meaning |
|  --- | --- |
| `authorized` | ACH debit submitted to the network |
| `completed` | Funds transfer completed |
| `settled` | Funds deposited to your account |
| `failed` | ACH return received (see [ACH returns](/docs/tutorials/payment-cookbook/auth-returns)) |


## ACH vs. card payments for invoices

| Factor | ACH | Card |
|  --- | --- | --- |
| Processing fee | Flat fee (lower) | Percentage + flat fee (higher) |
| Settlement time | 2–3 business days | Next business day |
| Chargebacks | ACH returns (limited window) | Card disputes (longer window) |
| Best for | High-value, recurring B2B | Consumer, low-value |


## Best practices

* **Store the token once** — reuse for every invoice to avoid re-collecting bank details
* **Use metadata** — attach `invoice_id` for reconciliation
* **Handle returns** — ACH debits can be returned for up to 60 days. See [ACH returns](/docs/tutorials/payment-cookbook/auth-returns)
* **Notify the customer** — send an email when the debit is initiated and another when it settles


## Next steps

* [ACH payouts](/docs/tutorials/payment-cookbook/ach-payouts) — send funds to vendors
* [ACH returns](/docs/tutorials/payment-cookbook/auth-returns) — handle returned debits
* [About ACH payments](/docs/concepts/transactions/ach-accounts)