curl -X POST 'https://api.yativo.com/api/v1/wallet/deposits/new' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: deposit-001' \
-d '{
"gateway": 20,
"quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
"currency": "USD",
"redirect_url": "https://your-app.com/deposit/complete"
}'
curl -X POST 'https://api.yativo.com/api/v1/wallet/deposits/new' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: deposit-002' \
-d '{
"gateway": 15,
"amount": 1000,
"currency": "BRL",
"redirect_url": "https://your-app.com/deposit/complete"
}'
// Step 1: Create a payin quote
const quoteRes = await fetch('https://api.yativo.com/api/v1/exchange-rate', {
method: 'POST',
headers: { 'X-Api-Key': process.env.YATIVO_API_KEY, 'X-Api-Secret': process.env.YATIVO_API_SECRET, 'Content-Type': 'application/json' },
body: JSON.stringify({
from_currency: 'BRL',
to_currency: 'USD',
method_id: 15,
method_type: 'payin',
amount: 1000,
}),
});
const { data: quote } = await quoteRes.json();
// Step 2: Initiate the deposit
const depositRes = await fetch('https://api.yativo.com/api/v1/wallet/deposits/new', {
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': `deposit-${Date.now()}`,
},
body: JSON.stringify({
gateway: 15,
quote_id: quote.quote_id,
currency: 'USD',
redirect_url: 'https://your-app.com/deposit/complete',
}),
});
const deposit = await depositRes.json();
// Redirect customer to deposit.data.deposit_url
{
"status": "success",
"status_code": 200,
"message": "Request successful",
"data": {
"id": "dep-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"gateway": 15,
"deposit_currency": "BRL",
"amount": 1000.00,
"receive_amount": 9.36,
"currency_to": "USD",
"status": "pending",
"deposit_url": "https://checkout.yativo.com/pay/dep-a1b2c3d4",
"transaction_id": "txn-2026060101",
"created_at": "2026-06-01T10:00:00.000000Z"
}
}
{
"status": "failed",
"status_code": 400,
"message": "Quote has expired. Please generate a new quote.",
"data": {
"error": "Quote has expired. Please generate a new quote."
}
}
{
"status": "failed",
"status_code": 404,
"message": "Payment gateway not found",
"data": {
"error": "Payment gateway not found"
}
}
{
"status": "failed",
"status_code": 400,
"message": "Minimum deposit amount is 5 BRL",
"data": {
"error": "Minimum deposit amount is 5 BRL"
}
}
{
"status": "failed",
"status_code": 422,
"message": "Request failed.",
"data": {
"gateway": ["The gateway field is required."],
"currency": ["The currency field is required."]
}
}
Create Deposit (Payin)
Initiate an incoming payment using a payin gateway
curl -X POST 'https://api.yativo.com/api/v1/wallet/deposits/new' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: deposit-001' \
-d '{
"gateway": 20,
"quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
"currency": "USD",
"redirect_url": "https://your-app.com/deposit/complete"
}'
curl -X POST 'https://api.yativo.com/api/v1/wallet/deposits/new' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: deposit-002' \
-d '{
"gateway": 15,
"amount": 1000,
"currency": "BRL",
"redirect_url": "https://your-app.com/deposit/complete"
}'
// Step 1: Create a payin quote
const quoteRes = await fetch('https://api.yativo.com/api/v1/exchange-rate', {
method: 'POST',
headers: { 'X-Api-Key': process.env.YATIVO_API_KEY, 'X-Api-Secret': process.env.YATIVO_API_SECRET, 'Content-Type': 'application/json' },
body: JSON.stringify({
from_currency: 'BRL',
to_currency: 'USD',
method_id: 15,
method_type: 'payin',
amount: 1000,
}),
});
const { data: quote } = await quoteRes.json();
// Step 2: Initiate the deposit
const depositRes = await fetch('https://api.yativo.com/api/v1/wallet/deposits/new', {
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': `deposit-${Date.now()}`,
},
body: JSON.stringify({
gateway: 15,
quote_id: quote.quote_id,
currency: 'USD',
redirect_url: 'https://your-app.com/deposit/complete',
}),
});
const deposit = await depositRes.json();
// Redirect customer to deposit.data.deposit_url
{
"status": "success",
"status_code": 200,
"message": "Request successful",
"data": {
"id": "dep-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"gateway": 15,
"deposit_currency": "BRL",
"amount": 1000.00,
"receive_amount": 9.36,
"currency_to": "USD",
"status": "pending",
"deposit_url": "https://checkout.yativo.com/pay/dep-a1b2c3d4",
"transaction_id": "txn-2026060101",
"created_at": "2026-06-01T10:00:00.000000Z"
}
}
{
"status": "failed",
"status_code": 400,
"message": "Quote has expired. Please generate a new quote.",
"data": {
"error": "Quote has expired. Please generate a new quote."
}
}
{
"status": "failed",
"status_code": 404,
"message": "Payment gateway not found",
"data": {
"error": "Payment gateway not found"
}
}
{
"status": "failed",
"status_code": 400,
"message": "Minimum deposit amount is 5 BRL",
"data": {
"error": "Minimum deposit amount is 5 BRL"
}
}
{
"status": "failed",
"status_code": 422,
"message": "Request failed.",
"data": {
"gateway": ["The gateway field is required."],
"currency": ["The currency field is required."]
}
}
quote_id from POST /exchange-rate to lock the rate and amount before redirecting the customer.
POST https://api.yativo.com/api/v1/wallet/deposits/new
Idempotency-Key header. Retrieve available gateways and their IDs with GET /payment-methods/payin?country={iso2}.curl -X POST 'https://api.yativo.com/api/v1/wallet/deposits/new' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: deposit-001' \
-d '{
"gateway": 20,
"quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
"currency": "USD",
"redirect_url": "https://your-app.com/deposit/complete"
}'
curl -X POST 'https://api.yativo.com/api/v1/wallet/deposits/new' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: deposit-002' \
-d '{
"gateway": 15,
"amount": 1000,
"currency": "BRL",
"redirect_url": "https://your-app.com/deposit/complete"
}'
// Step 1: Create a payin quote
const quoteRes = await fetch('https://api.yativo.com/api/v1/exchange-rate', {
method: 'POST',
headers: { 'X-Api-Key': process.env.YATIVO_API_KEY, 'X-Api-Secret': process.env.YATIVO_API_SECRET, 'Content-Type': 'application/json' },
body: JSON.stringify({
from_currency: 'BRL',
to_currency: 'USD',
method_id: 15,
method_type: 'payin',
amount: 1000,
}),
});
const { data: quote } = await quoteRes.json();
// Step 2: Initiate the deposit
const depositRes = await fetch('https://api.yativo.com/api/v1/wallet/deposits/new', {
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': `deposit-${Date.now()}`,
},
body: JSON.stringify({
gateway: 15,
quote_id: quote.quote_id,
currency: 'USD',
redirect_url: 'https://your-app.com/deposit/complete',
}),
});
const deposit = await depositRes.json();
// Redirect customer to deposit.data.deposit_url
{
"status": "success",
"status_code": 200,
"message": "Request successful",
"data": {
"id": "dep-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"gateway": 15,
"deposit_currency": "BRL",
"amount": 1000.00,
"receive_amount": 9.36,
"currency_to": "USD",
"status": "pending",
"deposit_url": "https://checkout.yativo.com/pay/dep-a1b2c3d4",
"transaction_id": "txn-2026060101",
"created_at": "2026-06-01T10:00:00.000000Z"
}
}
{
"status": "failed",
"status_code": 400,
"message": "Quote has expired. Please generate a new quote.",
"data": {
"error": "Quote has expired. Please generate a new quote."
}
}
{
"status": "failed",
"status_code": 404,
"message": "Payment gateway not found",
"data": {
"error": "Payment gateway not found"
}
}
{
"status": "failed",
"status_code": 400,
"message": "Minimum deposit amount is 5 BRL",
"data": {
"error": "Minimum deposit amount is 5 BRL"
}
}
{
"status": "failed",
"status_code": 422,
"message": "Request failed.",
"data": {
"gateway": ["The gateway field is required."],
"currency": ["The currency field is required."]
}
}
deposit_url to complete payment on the gateway’s hosted page. Once completed, the customer is returned to your redirect_url and a deposit.completed webhook fires.Authorizations
Your API key (yativo_pk_...) from Developers → API Keys. Send together with X-Api-Secret.
Your API secret (yativo_sk_...), shown once when the key is created.
Headers
A unique string per request to ensure idempotent processing.
Body
The payin gateway ID. Get valid IDs from GET /payment-methods/payin?country={iso2}.
The wallet currency to credit (e.g. "USD", "BRL"). Must match one of the gateway's supported base currencies.
"USD"
Amount to deposit in the local (payin) currency. Required if quote_id is not provided. If quote_id is present, the amount is taken from the quote.
A quote ID from POST /exchange-rate (created with method_type: "payin"). When supplied, the locked amount and rate from the quote are used — amount is ignored.
URL to redirect the customer to after completing the payment on the gateway's hosted page.

