Payouts

Payouts let you send money from your PerfectPay account to external recipients -- sellers, gig workers, vendors, or any third party. PerfectPay supports multiple payout rails and selects the best one based on speed, cost, and recipient bank capabilities.

Supported Payout Rails

Rail	Speed	Best for
ACH	1-3 business days	Standard vendor and seller payouts
Same Day ACH	Same business day	Time-sensitive payouts within banking hours
Push-to-Card (Visa Direct / Mastercard Send)	Minutes	Gig worker payouts, instant tips
RTP	Seconds	Real-time account-to-account transfers
FedNow	Seconds	Real-time bank transfers, 24/7 availability

For instant payout options, see the Instant Settlement guide.

Payout Lifecycle

Code

create --> confirm --> pending --> success
                  |           |
                  |           +--> failed
                  |
                  +--> cancel

Create a Payout

POST /payouts/create

GET //sandbox.perfectpay.ai/payouts/create

curl https://sandbox.perfectpay.ai/payouts/create \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "currency": "USD",
    "payout_type": "bank",
    "customer_id": "cus_seller_abc",
    "description": "Weekly seller payout",
    "return_url": "https://example.com/payouts/status"
  }'

Response excerpt:

JSON

{
  "payout_id": "po_abc123",
  "amount": 25000,
  "currency": "USD",
  "status": "requires_confirmation"
}

Confirm a Payout

POST /payouts/{payout_id}/confirm

GET //sandbox.perfectpay.ai/payouts/po_abc123/confirm

curl https://sandbox.perfectpay.ai/payouts/po_abc123/confirm \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payout_method_data": {
      "bank": {
        "routing_number": "110000000",
        "account_number": "000123456789",
        "account_holder_name": "Jane Seller"
      }
    }
  }'

Retrieve a Payout

GET /payouts/{payout_id}

GET //sandbox.perfectpay.ai/payouts/po_abc123

curl https://sandbox.perfectpay.ai/payouts/po_abc123 \
  -H "api-key: YOUR_SECRET_API_KEY"

Cancel a Payout

POST /payouts/{payout_id}/cancel

Cancel a payout before it has been fulfilled.

GET //sandbox.perfectpay.ai/payouts/po_abc123/cancel

curl https://sandbox.perfectpay.ai/payouts/po_abc123/cancel \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Fulfill a Payout

POST /payouts/{payout_id}/fulfill

Mark a payout as fulfilled after the funds have been sent.

GET //sandbox.perfectpay.ai/payouts/po_abc123/fulfill

curl https://sandbox.perfectpay.ai/payouts/po_abc123/fulfill \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

List Payouts

POST /payouts/list

GET //sandbox.perfectpay.ai/payouts/list

curl https://sandbox.perfectpay.ai/payouts/list \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Filter by status, date range, or customer ID for reconciliation and reporting.

Payout Status Values

Status	Meaning
`requires_creation`	Payout record exists but has not been fully created
`requires_confirmation`	Payout is created and waiting for confirmation
`requires_payout_method_data`	Payout needs recipient bank or card details before it can proceed
`requires_fulfillment`	Payout is confirmed and waiting to be fulfilled
`pending`	Payout has been submitted to the rail and is in transit
`success`	Funds have been delivered to the recipient
`failed`	Payout could not be completed
`cancelled`	Payout was cancelled before fulfillment
`expired`	Payout timed out before completion
`reversed`	Payout was returned after delivery (e.g., invalid account)

Smart Rail Selection

When multiple payout rails are available, PerfectPay can automatically select the best rail for each payout based on:

Speed requirements -- if the payout is marked as instant, prefer RTP, FedNow, or Push-to-Card
Cost optimization -- ACH is typically cheapest for non-urgent payouts
Recipient bank capabilities -- not all banks support RTP or FedNow; PerfectPay falls back to the next best rail
Availability -- FedNow operates 24/7; Same Day ACH has cutoff windows

Configure smart rail selection in your routing settings or specify a preferred rail explicitly in the payout request.

Operational Notes

Use Webhooks to receive notifications on payout status changes
Monitor payout performance and failure rates in the dashboard
For marketplace flows, combine payouts with Split Payments to automate seller disbursements