Payouts

Yativo provides two payout paths depending on your use case:

Path	Best for
`POST /payout/simple`	A single payment to one beneficiary
`POST /payout/batch`	Multiple payments to different beneficiaries in one request

Both require a saved beneficiary with an attached payment method. See Send Money for setting up beneficiaries.

All payout requests require an Idempotency-Key header and the chargeWallet middleware — meaning your wallet balance is charged at submission time.

Single Payout

Send one payment to a saved beneficiary payment method.

POST https://api.yativo.com/api/v1/payout/simple

number

required

Amount to send in the debit wallet currency.

number

required

The ID of the saved beneficiary payment method (from POST /beneficiaries/payment-methods).

string

Optional beneficiary UUID. Useful for tracking but not required if beneficiary_details_id is provided.

curl -X POST 'https://api.yativo.com/api/v1/payout/simple' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-simple-001' \
  -d '{
    "amount": 250,
    "beneficiary_details_id": 42
  }'

const response = await fetch('https://api.yativo.com/api/v1/payout/simple', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `payout-simple-${Date.now()}`,
  },
  body: JSON.stringify({
    amount: 250,
    beneficiary_details_id: 42,
  }),
});
const data = await response.json();

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "transaction_id": "txn-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "processing",
    "amount": "250.00",
    "currency": "CLP",
    "beneficiary_id": 42,
    "created_at": "2026-06-01T10:00:00.000000Z"
  }
}

{
  "status": "error",
  "status_code": 402,
  "message": "Insufficient wallet balance"
}

Batch Payout

Send multiple payments in a single request. Each item in the payouts array is processed independently — partial failures are returned in an errors array rather than rolling back the entire batch.

POST https://api.yativo.com/api/v1/payout/batch

array

required

Array of payout objects to process.

Show payouts item fields

number

required

Amount to send for this payout.

number

required

The saved beneficiary payment method ID.

number

Optional beneficiary UUID for tracking.

Batch payouts are processed within a database transaction — if your wallet has insufficient balance for the total amount, the entire batch is rejected before processing begins. Individual line-item errors (e.g. invalid beneficiary) are returned in the errors object and do not affect other items.

curl -X POST 'https://api.yativo.com/api/v1/payout/batch' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: batch-payout-june-payroll-001' \
  -d '{
    "payouts": [
      { "amount": 500, "beneficiary_details_id": 41 },
      { "amount": 750, "beneficiary_details_id": 42 },
      { "amount": 300, "beneficiary_details_id": 43 }
    ]
  }'

const response = await fetch('https://api.yativo.com/api/v1/payout/batch', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `batch-${Date.now()}`,
  },
  body: JSON.stringify({
    payouts: [
      { amount: 500, beneficiary_details_id: 41 },
      { amount: 750, beneficiary_details_id: 42 },
      { amount: 300, beneficiary_details_id: 43 },
    ],
  }),
});
const data = await response.json();

import requests, time

response = requests.post(
    'https://api.yativo.com/api/v1/payout/batch',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json',
        'Idempotency-Key': f'batch-{int(time.time())}',
    },
    json={
        'payouts': [
            {'amount': 500, 'beneficiary_details_id': 41},
            {'amount': 750, 'beneficiary_details_id': 42},
            {'amount': 300, 'beneficiary_details_id': 43},
        ]
    }
)

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "0": { "transaction_id": "txn-aaa", "status": "processing", "amount": "500.00" },
    "1": { "transaction_id": "txn-bbb", "status": "processing", "amount": "750.00" },
    "2": { "transaction_id": "txn-ccc", "status": "processing", "amount": "300.00" }
  }
}

{
  "status": "error",
  "status_code": 400,
  "data": {
    "errors": {
      "1": { "error": "Beneficiary not found" }
    }
  }
}

List Payouts

Retrieve a paginated list of all your payouts.

GET https://api.yativo.com/api/v1/payout/get

curl -X GET 'https://api.yativo.com/api/v1/payout/get' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Get Single Payout

GET https://api.yativo.com/api/v1/payout/fetch/{payout_id}

string

required

The UUID of the payout to retrieve.

curl -X GET 'https://api.yativo.com/api/v1/payout/fetch/txn-a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Payout vs. Wallet Payout

	`POST /payout/simple` or `/batch`	`POST /wallet/payout`
Beneficiary required	Yes — `beneficiary_details_id`	Yes — `beneficiary_id`
Quote support	No	Yes — pass `quote_id` for locked rate
Bulk support	Yes (`/batch`)	No
Use case	Disbursements, payroll	Single cross-currency payments with rate lock

For a single payment where you want to lock a rate first, use POST /sendmoney/quote → POST /wallet/payout. For payroll-style bulk disbursements without rate locking, use POST /payout/batch.

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

Regional Guides

Single Payout

Batch Payout

List Payouts

Get Single Payout

Payout vs. Wallet Payout

​Single Payout

​Batch Payout

​List Payouts

​Get Single Payout

​Payout vs. Wallet Payout

Single Payout

Batch Payout

List Payouts

Get Single Payout

Payout vs. Wallet Payout