Overview
Yuno Payouts enable you to send money from your merchant account to recipients’ bank accounts, digital wallets, or cards. This is essential for marketplaces paying sellers, platforms disbursing earnings, insurance companies processing claims, or any business that needs to move funds outward.
Payout Flow
- Create a recipient with their banking or wallet details.
- Initiate a payout specifying the amount, currency, and recipient.
- Yuno routes the payout through the appropriate provider for the destination.
- Track the status via webhooks or the Payouts API.
Creating a Recipient
Before sending a payout, register the recipient’s financial details.
curl --request POST \
--url https://api.y.uno/v1/payout-recipients \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: YOUR_API_KEY' \
--data '{
"name": "Carlos Oliveira",
"email": "carlos@example.com",
"document": {
"document_type": "CPF",
"document_number": "12345678901"
},
"bank_account": {
"bank_code": "001",
"branch": "1234",
"account_number": "567890-1",
"account_type": "CHECKING"
},
"country": "BR"
}'
Initiating a Payout
POST /v1/payouts
{
"recipient_id": "rec_carlos_001",
"amount": {
"value": 1500.00,
"currency": "BRL"
},
"country": "BR",
"description": "Seller earnings - February 2026",
"metadata": {
"seller_id": "seller_456",
"period": "2026-02"
}
}
Payout Status Lifecycle
| Status | Description |
|---|
CREATED | Payout request received |
PROCESSING | Payout is being processed by the provider |
COMPLETED | Funds delivered to recipient |
FAILED | Payout could not be completed |
CANCELLED | Payout was cancelled before processing |
Payout processing times vary by destination. Bank transfers in Brazil (via PIX) can be instant, while traditional wire transfers may take 1-3 business days.
Supported Payout Destinations
| Destination | Countries | Speed |
|---|
| Bank account (PIX) | BR | Instant |
| Bank account (wire) | BR, MX, CO, CL, AR | 1-3 business days |
| Digital wallet | BR, MX | Near-instant |
| Card (Visa Direct) | Select markets | Near-instant |
Webhook Events
| Event | Trigger |
|---|
payout.created | Payout request submitted |
payout.processing | Payout sent to provider |
payout.completed | Funds delivered successfully |
payout.failed | Payout could not be completed |
Always validate recipient bank details before initiating payouts. Invalid account information results in failed payouts and potential delays in re-processing.
Error Handling
| Error Code | Cause | Resolution |
|---|
INVALID_RECIPIENT | Recipient details are incorrect | Verify bank account number and branch |
INSUFFICIENT_BALANCE | Merchant account balance too low | Fund your account or reduce payout amount |
PROVIDER_ERROR | Downstream provider issue | Retry after checking provider status |
UNSUPPORTED_COUNTRY | Country not enabled for payouts | Contact Yuno support for enablement |
Payout availability and supported destinations depend on your merchant configuration and enabled providers. Check your Yuno Dashboard under Settings > Payouts for your current setup.
