USA Payouts API

This method allows you to create a new digital payment to a beneficiary bank account in the United States.

Endpoint

POST /us/payout/create

Parameter	Type	Required	Description
`amount`	decimal	Yes	The transfer amount in USD. Must be greater than 0. Up to two decimal places allowed.
`account`	string	Yes	The beneficiary's bank account number.
`name`	string	Yes	The name of the account holder.
`routing`	string	Yes	The 9-digit bank routing number (ABA routing number).
`sandbox`	integer	Optional	Set to `1` for sandbox mode, `0` or omit for production. Default: `0`

Request Example

{
    "amount": 150.00,
    "account": "428100000",
    "name": "Checking account", 
    "routing": "021000021",
    "sandbox": 0
}

Response 200 (Success)

ACH Payment Example

{
    "code": 200,
    "msg": "OK",
    "caseid": "b8ca3dca-1692-4a5b-8277-0684c0fb8c4f",
    "date": "2025-08-20 16:51:21",
    "status": "SUCCESS",
    "message": "Digital payment processed successfully",
    "data": {
        "transaction_id": "5da23fab51ac47adabb41ca2f07d9f76",
        "amount": 150.00,
        "recipient_account": "428100000",
        "recipient_name": "Checking account",
        "recipient_routing": "021000021",
        "payment_status": "IN_PROCESS",
        "payment_method": "ACH",
        "payment_method_description": "Automated Clearing House - Payment processing (status: IN_PROCESS)",
        "transaction_number": 5001,
        "created_at": "2025-08-20 20:50:00"
    }
}

RTP Payment Example

{
    "code": 200,
    "msg": "OK",
    "caseid": "b8ca3dca-1692-4a5b-8277-0684c0fb8c4f",
    "date": "2025-08-20 16:51:21",
    "status": "SUCCESS",
    "message": "Digital payment processed successfully",
    "data": {
        "transaction_id": "5da23fab51ac47adabb41ca2f07d9f76",
        "amount": 150.00,
        "recipient_account": "428100000",
        "recipient_name": "Checking account",
        "recipient_routing": "021000021",
        "payment_status": "PAID",
        "payment_method": "RTP",
        "payment_method_description": "Real-Time Payments - Payment completed immediately (status: PAID)",
        "transaction_number": 5002,
        "created_at": "2025-08-20 20:50:00"
    }
}

Response 400 (Error)

{
    "code": 400,
    "msg": "ERROR",
    "caseid": "b8ca3dca-1692-4a5b-8277-0684c0fb8c4f",
    "date": "2025-08-20 16:51:21",
    "status": "ERROR",
    "error_message": "Payment failed or not processed",
    "display_message": "Error in payment processing: Payment failed or not processed"
}

Response Fields

Field	Type	Description
`code`	integer	HTTP response code (200 for success, 400+ for errors)
`msg`	string	Response status ("OK" or "ERROR")
`caseid`	string	The case ID from the request
`date`	string	Response timestamp in YYYY-MM-DD HH:MM:SS format
`status`	string	Transaction status ("SUCCESS", "ERROR")
`message`	string	Human-readable status message
`data.transaction_id`	string	Unique transaction identifier
`data.amount`	decimal	Transaction amount
`data.recipient_account`	string	Beneficiary account number
`data.recipient_name`	string	Beneficiary account name
`data.recipient_routing`	string	Bank routing number
`data.payment_status`	string	Payment status ("PAID", "IN_PROCESS", "UNPAID")
`data.payment_method`	string	Payment method used ("RTP", "ACH", "ERROR")
`data.payment_method_description`	string	Detailed payment method description
`data.transaction_number`	integer	Sequential transaction number
`data.created_at`	string	Transaction creation timestamp

Payment Methods

RTP (Real-Time Payments)

Status: PAID
Description: Payment is processed and completed immediately
Typical processing: Instant (within seconds)

ACH (Automated Clearing House)

Status: IN_PROCESS
Description: Payment is being processed through the ACH network
Typical processing: 1-3 business days

Sandbox Testing

For sandbox testing, use "sandbox": 1 in your request.

Sandbox Test Amounts

Amount	Expected Result	Payment Method
`150.00`	Success - ACH	ACH (IN_PROCESS)
`250.00`	Success - RTP	RTP (PAID)
`0` or negative	Validation Error	N/A
Other amounts	Payment Error	ERROR

Sandbox Test Accounts

Use these test account details for sandbox:

{
    "account": "428100000",
    "name": "Test Account",
    "routing": "021000021"
}

Error Codes

Code	Description
`200`	Success - Payment processed
`400`	Bad Request - Invalid parameters or payment failed
`403`	Forbidden - IP not whitelisted
`500`	Internal Server Error - System error

Common Error Scenarios

Invalid Token: Check that id_token corresponds to an active account
IP Restriction: Ensure client_ip is whitelisted for the client
Invalid Amount: Amount must be greater than 0 with max 2 decimals
Invalid Routing: Routing number must be exactly 9 digits
Account Mismatch: Sandbox flag must match the account configuration

Flow Overview

Account Validation: System validates the client token and selects appropriate credentials (sandbox vs production)
Bank Account Setup: System checks for existing bank account or creates a new one
Digital Payment: Creates and sends the digital payment using client's credentials
Payment Deposit: Processes the payment deposit using system credentials
Status Check: Waits 10 seconds then polls for payment status to determine ACH vs RTP
Response: Returns final payment status and method

Security

All requests must include a valid client_ip that is whitelisted for the client account
Client credentials are stored securely and used only for the digital payment creation
System credentials handle account management and payment processing
All API communications use HTTPS encryption

Support

For API support, integration questions, or to request IP whitelisting, contact our technical support team.