Skip to content
Last updated

Recipe: ACH payouts

When to use ACH payouts

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

Flow

Recipient's BankParadise GatewayMerchantRecipient's BankParadise GatewayMerchantPOST /v1/transactions (type: payout)approvedACH credit initiatedSettled (2-3 business days)
Recipient's BankParadise GatewayMerchantRecipient's BankParadise GatewayMerchantPOST /v1/transactions (type: payout)approvedACH credit initiatedSettled (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.

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 -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"
    }
  }'

Response

{
  "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.

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

Payments vs. payouts

Payment (debit)Payout (credit)
DirectionCustomer → MerchantMerchant → Recipient
Transaction typesalepayout
Use caseCollect invoice paymentPay vendor/contractor
ReturnsCustomer may disputeRecipient bank may reject

Cancel a payout

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

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

Next steps