Payouts

curl -X POST 'https://api.yativo.com/api/v1/payout/simple' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-simple-001' \
  -d '{
    "debit_wallet": "USD",
    "amount": 250,
    "beneficiary_details_id": 42,
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "reference": "INV-2026-0042"
  }'

const response = await fetch('https://api.yativo.com/api/v1/payout/simple', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.YATIVO_API_KEY,
    'X-Api-Secret': process.env.YATIVO_API_SECRET,
    'Content-Type': 'application/json',
    'Idempotency-Key': `payout-simple-${Date.now()}`,
  },
  body: JSON.stringify({
    debit_wallet: 'USD',
    amount: 250,
    beneficiary_details_id: 42,
    customer_id: 'da44a3e6-eb5d-429f-8d17-357aa5a6cdf2',
  }),
});
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": "failed",
  "status_code": 400,
  "message": "Request failed.",
  "data": {
    "error": "Insufficient wallet balance"
  }
}

curl -X POST 'https://api.yativo.com/api/v1/payout/simple' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-simple-001' \
  -d '{
    "debit_wallet": "USD",
    "amount": 250,
    "beneficiary_details_id": 42,
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "reference": "INV-2026-0042"
  }'

const response = await fetch('https://api.yativo.com/api/v1/payout/simple', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.YATIVO_API_KEY,
    'X-Api-Secret': process.env.YATIVO_API_SECRET,
    'Content-Type': 'application/json',
    'Idempotency-Key': `payout-simple-${Date.now()}`,
  },
  body: JSON.stringify({
    debit_wallet: 'USD',
    amount: 250,
    beneficiary_details_id: 42,
    customer_id: 'da44a3e6-eb5d-429f-8d17-357aa5a6cdf2',
  }),
});
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": "failed",
  "status_code": 400,
  "message": "Request failed.",
  "data": {
    "error": "Insufficient wallet balance"
  }
}

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. Your wallet balance is charged when the payout is submitted.

Single Payout

Send one payment to a saved beneficiary payment method.

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

string

required

The wallet currency to debit, for example "USD".

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

required

The customer the payout is for. If the beneficiary belongs to a customer, it must be that customer.

string

Optional. The beneficiary that owns the payment method.

string

Payment reference shown to the recipient’s bank, up to 250 characters. Some payout rails shorten it or remove unsupported characters.

/payout/simple also accepts quote_id, invoice and invoice_url, like POST /wallet/payout.

curl -X POST 'https://api.yativo.com/api/v1/payout/simple' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-simple-001' \
  -d '{
    "debit_wallet": "USD",
    "amount": 250,
    "beneficiary_details_id": 42,
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "reference": "INV-2026-0042"
  }'

const response = await fetch('https://api.yativo.com/api/v1/payout/simple', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.YATIVO_API_KEY,
    'X-Api-Secret': process.env.YATIVO_API_SECRET,
    'Content-Type': 'application/json',
    'Idempotency-Key': `payout-simple-${Date.now()}`,
  },
  body: JSON.stringify({
    debit_wallet: 'USD',
    amount: 250,
    beneficiary_details_id: 42,
    customer_id: 'da44a3e6-eb5d-429f-8d17-357aa5a6cdf2',
  }),
});
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": "failed",
  "status_code": 400,
  "message": "Request failed.",
  "data": {
    "error": "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 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -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: {
    'X-Api-Key': process.env.YATIVO_API_KEY,
    'X-Api-Secret': process.env.YATIVO_API_SECRET,
    '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={
        'X-Api-Key': os.environ['YATIVO_API_KEY'],
        'X-Api-Secret': os.environ['YATIVO_API_SECRET'],
        '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": "failed",
  "status_code": 400,
  "message": "Request failed.",
  "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 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

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 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

Payout vs. Wallet Payout

	`POST /payout/simple` or `/batch`	`POST /wallet/payout`
Beneficiary required	Yes — `beneficiary_details_id`	Yes — `payment_method_id` + `customer_id`
Quote support	No	Yes — pass `quote_id` for locked rate
Fix the receive amount	No	Yes — `amount_type: "receive"`
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 /exchange-rate (with method_type: "payout") → POST /wallet/payout. To fix what the customer receives rather than what you send, see Pay out by receive amount. 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