# 

## When to use ACH payouts

* Pay vendors or contractors
* Disburse marketplace seller earnings
* Issue refunds directly to a bank account


## Flow

```mermaid
---
config:
  theme: 'neutral'
---
sequenceDiagram
    participant Merchant
    participant API as Paradise Gateway
    participant Bank as Recipient's Bank
    Merchant->>API: POST /v1/transactions (type: payout)
    API-->>Merchant: approved
    API->>Bank: ACH credit initiated
    Bank-->>API: Settled (2-3 business days)
```

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

If you haven't stored the recipient's bank account yet, create a token first.

```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-VENDOR-001",
    "nickname": "Vendor - ABC Supplies",
    "bank_account": {
      "routing_number": "021000021",
      "account_number": "987654321098",
      "account_type": "checking",
      "name": "ABC Supplies LLC",
      "email": "payments@abcsupplies.example.com"
    }
  }'
```

## Step 2: Send the payout

curl
```shell
curl -X POST \
  https://api.dev.paradisegateway.net/v1/transactions \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{
    "type": "payout",
    "amount": 150000,
    "payment_method": {
      "type": "payment_token",
      "payment_token": "PAYMENT_TOKEN-VENDOR-ABC001"
    },
    "metadata": {
      "payout_reason": "vendor_payment",
      "invoice_ref": "PO-2026-0099"
    }
  }'
```

Python
```python
import os, requests

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

resp = requests.post(
    f"{BASE}/v1/transactions",
    headers={"Content-Type": "application/json", "APIKEY": API_KEY},
    json={
        "type": "payout",
        "amount": 150000,
        "payment_method": {
            "type": "payment_token",
            "payment_token": "PAYMENT_TOKEN-VENDOR-ABC001",
        },
        "metadata": {
            "payout_reason": "vendor_payment",
            "invoice_ref": "PO-2026-0099",
        },
    },
)
payout = resp.json()
print(f"Payout {payout['id']}: {payout['response_status']}")
```

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

const resp = await fetch(`${BASE}/v1/transactions`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "APIKEY": API_KEY },
  body: JSON.stringify({
    type: "payout",
    amount: 150000,
    payment_method: {
      type: "payment_token",
      payment_token: "PAYMENT_TOKEN-VENDOR-ABC001",
    },
    metadata: {
      payout_reason: "vendor_payment",
      invoice_ref: "PO-2026-0099",
    },
  }),
});
const payout = await resp.json();
console.log(`Payout ${payout.id}: ${payout.response_status}`);
```

### Response

```json
{
  "id": "TRANSACTION-03MFHISS2CZTP7XSZ2U4I5DE",
  "type": "payout",
  "amount": 150000,
  "transaction_state": "authorized",
  "response_status": "approved",
  "response_code": "00",
  "correlation_id": "d4e5f6a7-b8c9-0123-def0-1234567890ab"
}
```

## Step 3: Confirm settlement

Monitor the transaction state. Payouts settle in 2–3 business days.

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

## Payments vs. payouts

|  | Payment (debit) | Payout (credit) |
|  --- | --- | --- |
| Direction | Customer → Merchant | Merchant → Recipient |
| Transaction type | `sale` | `payout` |
| Use case | Collect invoice payment | Pay vendor/contractor |
| Returns | Customer may dispute | Recipient bank may reject |


## Cancel a payout

If the payout has not yet settled, you can cancel it.

```shell
curl -X POST \
  https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-03MFHISS2CZTP7XSZ2U4I5DE/cancel \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{ "type": "cancel", "amount": 150000 }'
```

## Best practices

* **Verify the recipient** — confirm the bank account belongs to the intended recipient before sending funds
* **Use metadata** — attach `payout_reason` and `invoice_ref` for audit and reconciliation
* **Monitor for returns** — ACH credits can be returned if the account is closed or invalid. See [ACH returns](/docs/tutorials/payment-cookbook/auth-returns)


## Next steps

* [ACH for invoices](/docs/tutorials/payment-cookbook/ach-for-invoices) — collect payments via ACH debit
* [ACH returns](/docs/tutorials/payment-cookbook/auth-returns) — handle return scenarios
* [Process an ACH payout (how-to)](/docs/how-tos/process-payments/process-ach-payout)