Initiate Payout

curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-c586066b-2026-10-01-001' \
  -d '{
    "debit_wallet": "USD",
    "payment_method_id": 555,
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed"
  }'

curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-c586066b-2026-10-01-002' \
  -d '{
    "debit_wallet": "USD",
    "payment_method_id": 555,
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "amount": 5000,
    "amount_type": "receive"
  }'

curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-c586066b-2026-10-01-003' \
  -d '{
    "debit_wallet": "USD",
    "payment_method_id": 555,
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "amount": 500
  }'

{
  "status": "success",
  "status_code": 201,
  "message": "Withdrawal request initiated successfully",
  "data": {
    "transaction_id": 4321,
    "payout_id": 4321,
    "status": "pending",
    "amount_type": "receive",
    "send_amount": 275.886423,
    "customer_receive_amount": 5000,
    "debit_amount": 278.386423,
    "currency": "MXN",
    "fees": { "...": "full fee and rate breakdown" },
    "processed_at": "2026-10-01T12:01:30.000000Z"
  }
}

{
  "status": "failed",
  "status_code": 400,
  "message": "Request failed.",
  "data": { "error": "Insufficient wallet balance" }
}

POST

wallet

payout

curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-c586066b-2026-10-01-001' \
  -d '{
    "debit_wallet": "USD",
    "payment_method_id": 555,
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed"
  }'

curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-c586066b-2026-10-01-002' \
  -d '{
    "debit_wallet": "USD",
    "payment_method_id": 555,
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "amount": 5000,
    "amount_type": "receive"
  }'

curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-c586066b-2026-10-01-003' \
  -d '{
    "debit_wallet": "USD",
    "payment_method_id": 555,
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "amount": 500
  }'

{
  "status": "success",
  "status_code": 201,
  "message": "Withdrawal request initiated successfully",
  "data": {
    "transaction_id": 4321,
    "payout_id": 4321,
    "status": "pending",
    "amount_type": "receive",
    "send_amount": 275.886423,
    "customer_receive_amount": 5000,
    "debit_amount": 278.386423,
    "currency": "MXN",
    "fees": { "...": "full fee and rate breakdown" },
    "processed_at": "2026-10-01T12:01:30.000000Z"
  }
}

{
  "status": "failed",
  "status_code": 400,
  "message": "Request failed.",
  "data": { "error": "Insufficient wallet balance" }
}

Send money from one of your wallets to a customer’s saved payout method. Pass a quote_id to lock the rate and fees for 5 minutes, or send amount to pay at the current rate. By default amount is what leaves your wallet. Set amount_type to receive to fix what the customer receives instead. See Pay out by receive amount.

POST /wallet/payout

Requires an Idempotency-Key header. Use a unique key per payout to prevent duplicate transactions.

Request body

Every payout goes through compliance checks before it’s sent. If you include an invoice, it’s reviewed with the payout, so make sure its total and beneficiary match. A payout that needs a closer look stays pending until the review is finished.

curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-c586066b-2026-10-01-001' \
  -d '{
    "debit_wallet": "USD",
    "payment_method_id": 555,
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed"
  }'

curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-c586066b-2026-10-01-002' \
  -d '{
    "debit_wallet": "USD",
    "payment_method_id": 555,
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "amount": 5000,
    "amount_type": "receive"
  }'

curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-c586066b-2026-10-01-003' \
  -d '{
    "debit_wallet": "USD",
    "payment_method_id": 555,
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "amount": 500
  }'

{
  "status": "success",
  "status_code": 201,
  "message": "Withdrawal request initiated successfully",
  "data": {
    "transaction_id": 4321,
    "payout_id": 4321,
    "status": "pending",
    "amount_type": "receive",
    "send_amount": 275.886423,
    "customer_receive_amount": 5000,
    "debit_amount": 278.386423,
    "currency": "MXN",
    "fees": { "...": "full fee and rate breakdown" },
    "processed_at": "2026-10-01T12:01:30.000000Z"
  }
}

{
  "status": "failed",
  "status_code": 400,
  "message": "Request failed.",
  "data": { "error": "Insufficient wallet balance" }
}

Response fields

Field	Description
`transaction_id`	The transaction ID for this payout. Use it with `GET /transaction/tracking/{id}`.
`payout_id`	The payout ID. Use it with `GET /payout/fetch/{payout_id}`.
`status`	Starts as `pending`. Payouts settle asynchronously; use webhooks for the final status.
`amount_type`	`send` or `receive`, as applied to this payout.
`send_amount`	The amount sent, in the debit wallet currency, before fees.
`customer_receive_amount`	The amount the customer receives, in `currency`.
`debit_amount`	The total debited from your wallet, fees included.
`currency`	The payout currency.
`fees`	The full fee and rate breakdown.

Errors

Status	`data.error`
`400`	`Insufficient wallet balance`. Nothing is debited.
`400`	`Quote has expired. Please generate a new quote.`
`400`	`Minimum withdrawal: ...` or `Maximum withdrawal: ...`. Limits are checked against the send amount and shown in your wallet currency, so a receive amount can be rejected for being above or below a limit.
`400`	`Unsupported withdrawal method for quotes`. The quote’s method doesn’t match the payout method.
`422`	`amount_type must be either send or receive`

Authorizations

X-Api-Key

string

header

required

Your API key (yativo_pk_...) from Developers → API Keys. Send together with X-Api-Secret.

X-Api-Secret

string

header

required

Your API secret (yativo_sk_...), shown once when the key is created.

Headers

Idempotency-Key

string

required

A unique string per request to ensure idempotent processing.

Body

application/json

debit_wallet

string

required

The wallet currency to debit (e.g. "USD", "EUR").

Example:

"USD"

payment_method_id

integer

required

The customer's saved payout method ID, from POST /beneficiaries/payment-methods.

Example:

555

customer_id

string

required

The customer the payout method belongs to.

Example:

"da44a3e6-eb5d-429f-8d17-357aa5a6cdf2"

quote_id

string<uuid>

A payout quote from POST /exchange-rate (method_type: "payout"). Recommended. The quote supplies the amount, so amount and amount_type are ignored. The quote's method_id must be the payout method behind payment_method_id.

amount

number

Required if quote_id is not provided. With amount_type: "send" (the default), the amount to send in the debit_wallet currency. With amount_type: "receive", the amount the customer receives in the payout currency.

amount_type

enum<string>

default:send

send or receive. Ignored when quote_id is provided. In both modes fees are added on top and charged to your wallet.

Available options:

send,

receive

reference

string

Payment reference passed to the recipient's bank, up to 250 characters. Depending on the payout rail, it may be shortened or have unsupported characters removed. For example, ACH allows only 10 letters, numbers or spaces.

Maximum string length: 250

invoice

file

Supporting invoice: PDF, PNG or JPEG, up to 15 MB. Send the request as multipart/form-data to attach it.

invoice_url

string<uri>

Public http or https link to the supporting invoice, as an alternative to invoice.

Response

Payout initiated

status

string

status_code

integer

message

string

data

object

Show child attributes

Overview

Customers

KYC / KYB

KYC Lookups

Payments & Transfers

Deposits

Virtual Accounts

Wallets

Beneficiaries

Transactions

Virtual Cards

Payouts

Currency Swap

IP Whitelist & Security

Corporate Cards

Corporate Card Transactions

Corporate Card Links

Webhooks

Developer

Initiate Payout

Request body

Response fields

Errors

Authorizations

Headers

Body

Response

​Request body

​Response fields

​Errors

Authorizations

Headers

Body

Response

Request body

Response fields

Errors