Payouts

Send money to bank accounts, wallets, or cards with Yuno’s Payouts API for disbursements and settlements.

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

1. Create a recipient with their banking or wallet details.
2. Initiate a payout specifying the amount, currency, and recipient.
3. Yuno routes the payout through the appropriate provider for the destination.
4. Track the status via webhooks or the Payouts API.

Creating a Recipient

Before sending a payout, register the recipient’s financial details.

cURL

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": "[e-mail]",
    "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.