Skip to main content
Initiate a customer deposit via a supported payin gateway. Optionally pass a 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
Requires Idempotency-Key header. Retrieve available gateways and their IDs with GET /payment-methods/payin?country={iso2}.

​
Request body

​
gateway
integer
required
The payin gateway ID. Get valid IDs from GET /payment-methods/payin?country={iso2}.
​
currency
string
required
The wallet currency to credit (e.g. "USD", "BRL"). Must match one of the gateway’s supported base currencies.
​
amount
number
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.
​
quote_id
string
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.
​
redirect_url
string
URL to redirect the customer to after completing the payment on the gateway’s hosted page.
curl -X POST 'https://api.yativo.com/api/v1/wallet/deposits/new' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -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: { 'Authorization': `Bearer ${token}`, '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: {
    'Authorization': `Bearer ${token}`,
    '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": "error",
  "status_code": 400,
  "message": "Quote has expired. Please generate a new quote."
}

{
  "status": "error",
  "status_code": 404,
  "message": "Payment gateway not found"
}

{
  "status": "error",
  "status_code": 400,
  "message": "Minimum deposit amount is 5 BRL"
}

{
  "status": "error",
  "status_code": 422,
  "message": "Request failed",
  "data": {
    "gateway": ["The gateway field is required."],
    "currency": ["The currency field is required."]
  }
}
After a successful response, redirect the customer to 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.