Deposits (Payins)

curl -X GET 'https://api.yativo.com/api/v1/payment-methods/payin/countries' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": [
    { "country": "BRA", "name": "Brazil", "flag": "https://cdn.jsdelivr.net/gh/hampusborgos/country-flags@main/svg/BR.svg", "currencies": [] },
    { "country": "MEX", "name": "Mexico", "flag": "https://cdn.jsdelivr.net/gh/hampusborgos/country-flags@main/svg/MX.svg", "currencies": [] }
  ]
}

curl -X GET 'https://api.yativo.com/api/v1/payment-methods/payin/countries' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": [
    { "country": "BRA", "name": "Brazil", "flag": "https://cdn.jsdelivr.net/gh/hampusborgos/country-flags@main/svg/BR.svg", "currencies": [] },
    { "country": "MEX", "name": "Mexico", "flag": "https://cdn.jsdelivr.net/gh/hampusborgos/country-flags@main/svg/MX.svg", "currencies": [] }
  ]
}

A payin creates a payment link your customer uses to send funds. First discover the right payment gateway for the destination currency, then create the payin — optionally locking an exchange rate with a quote first.

Type Definitions

interface PayinGateway {
  id: number;
  method_name: string;
  country: string;    // ISO 3166-1 alpha-3
  currency: string;
  base_currency: string;
}

interface CreatePayinRequest {
  gateway: number;        // ID from /payment-methods/payin
  currency: string;       // currency of the deposit
  amount?: number;        // required if no quote_id
  quote_id?: string;      // from /exchange-rate (locks rate for 5 mins)
  customer_id?: string;   // attach to a specific customer
  redirect_url?: string;  // redirect after payment
}

interface PayinResponse {
  id: string;
  deposit_url: string;    // send this to your customer
  amount: number;
  currency: string;
  gateway: string;
  status: "pending" | "success" | "failed";
  receive_amount: string;
  customer_id?: string;
  created_at: string;
}

Step 1 — Find your gateway ID

Supported payin countries

Returns countries available for receiving payments (ISO 3166-1 alpha-3 codes).

GET /payment-methods/payin/countries

curl -X GET 'https://api.yativo.com/api/v1/payment-methods/payin/countries' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": [
    { "country": "BRA", "name": "Brazil", "flag": "https://cdn.jsdelivr.net/gh/hampusborgos/country-flags@main/svg/BR.svg", "currencies": [] },
    { "country": "MEX", "name": "Mexico", "flag": "https://cdn.jsdelivr.net/gh/hampusborgos/country-flags@main/svg/MX.svg", "currencies": [] }
  ]
}

Gateway ID by country and currency

GET /payment-methods/payin?country={iso3}&currency={code}

string

required

Country ISO 3166-1 alpha-3 code (e.g. CHL, BRA, MEX).

string

required

Currency code (e.g. CLP, BRL, MXN).

curl -X GET 'https://api.yativo.com/api/v1/payment-methods/payin?country=CHL&currency=CLP' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": [
    {
      "id": 22,
      "method_name": "Bank Transfer",
      "country": "CHL",
      "currency": "CLP",
      "base_currency": "CLP"
    },
    {
      "id": 23,
      "method_name": "Bank Transfer",
      "country": "CHL",
      "currency": "CLP",
      "base_currency": "USD"
    }
  ]
}

Note the id — this is your gateway value in the payin request.

Step 2 — Create a payin

POST /wallet/deposits/new

number

required

Gateway ID from Step 1.

string

required

Currency of the deposit (e.g. "CLP", "BRL", "MXN").

string

Quote ID from /exchange-rate. Locks the rate for 5 minutes. Recommended — amount is taken from the quote.

number

Amount to collect. Required if quote_id is not provided. Uses current market rate.

string

Attach this deposit to a specific customer wallet.

string

URL to redirect the customer after payment is completed.

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: unique-key-here' \
  -d '{
    "gateway": 22,
    "currency": "CLP",
    "quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
    "customer_id": "xxxxxx-xxxx-xxxx-xxxxxx",
    "redirect_url": "https://yourapp.com/payment/success"
  }'

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: unique-key-here' \
  -d '{
    "gateway": 22,
    "amount": 10000,
    "currency": "CLP"
  }'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "deposit_url": "https://checkout.yativo.com/process-payin/b3150e03-xxxx-4de3-a0ff-xxxxxxxxxx/paynow",
    "deposit_data": {
      "currency": "CLP",
      "deposit_currency": "USD",
      "amount": 10000,
      "gateway": 22,
      "receive_amount": 9,
      "customer_id": "948a039f-9883-xxxx-88a6-xxxxxxxxx",
      "id": "b3150e03-d27e-4de3-a0ff-16ebeb55683c",
      "created_at": "2026-03-18T15:52:43.000000Z"
    },
    "payment_info": {
      "send_amount": "10000 CLP",
      "receive_amount": "9 USD",
      "exchange_rate": "1 USD = 936.0336 CLP",
      "transaction_fee": "1236.03 CLP",
      "payment_method": "Bank Transfer",
      "estimate_delivery_time": "6 Minute(s)",
      "total_amount_due": "10000 CLP"
    }
  }
}

Send deposit_url to your customer — they complete payment through Yativo’s hosted checkout.

EUR bank transfer (SEPA)

Customers can fund a deposit in EUR with a SEPA transfer to a Yativo IBAN.

Find the gateway with GET /payment-methods/payin?country=MLT&currency=EUR. The method is named EUR Bank Transfer (SEPA).
Create the payin with that gateway, currency: "EUR", an amount and a customer_id. customer_id is required for this method.
Optionally send sender_account_number with the IBAN your customer will pay from. It helps match the transfer.

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: unique-key-here' \
  -d '{
    "gateway": GATEWAY_ID,
    "currency": "EUR",
    "amount": 250,
    "customer_id": "xxxxxx-xxxx-xxxx-xxxxxx",
    "sender_account_number": "DE89370400440532013000"
  }'

The deposit_url page shows the IBAN, BIC (SWIFT code), account name, amount and a unique payment reference.

Your customer must put the payment reference in the transfer’s reference field, and send it from a bank account in their own name (the name on their KYC). Transfers without the reference, or from third parties, can’t be matched to the deposit.

Card payments

Customers can pay a deposit by card on a secure card page. Card details are entered on that page, never in your app.

Find the gateway with GET /payment-methods/payin?country=BOL&currency=BOB, country=BOL&currency=USD or country=USA&currency=USD. The methods are named Card.
Create the payin with that gateway, currency: "USD" and an amount. Amounts can include cents. Send a return_url to bring the payer back to your app.
Redirect the payer to the returned link. The card page stays open for 60 minutes, and the payer can retry with another card during that time.

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: unique-key-here' \
  -d '{
    "gateway": GATEWAY_ID,
    "currency": "USD",
    "amount": 700.50,
    "customer_id": "xxxxxx-xxxx-xxxx-xxxxxx",
    "return_url": "https://your-app.com/payments/return"
  }'

When the payer finishes, they’re sent to your return_url with deposit_id and status in the query string. Use the deposit.updated webhook as the final result, and confirm it with Get a deposit before you fulfil the order.

Card payments are credited in USD only. A request for any other currency returns an error.

When card funds are available

Card payments aren’t available to spend straight away. They’re held for 3 US business days, not counting weekends and US federal holidays. If your account has a reserve, that part is held for your reserve period after that. The funds then move to your card balance. Refunds and chargebacks are taken from that balance.

List deposits

GET /wallet/deposits/

Filter by gateway, currency, start_date, or end_date as query parameters.

curl -X GET 'https://api.yativo.com/api/v1/wallet/deposits/?currency=CLP&start_date=2026-03-01&end_date=2026-03-31' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "status_code": 200,
  "message": "Records retrieved successfully",
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
      "amount": 10000,
      "gateway": "22",
      "currency": "CLP",
      "status": "success",
      "deposit_currency": "USD",
      "receive_amount": "9.36",
      "customer_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
      "created_at": "2026-03-15T10:00:00.000000Z"
    }
  ],
  "pagination": {
    "total": 7,
    "per_page": 10,
    "current_page": 1,
    "last_page": 1
  }
}

Get a deposit

GET /wallet/deposits/{depositId}

Returns one deposit, by its id or its deposit_id reference. The object is the same as an item from the list above. Check its status before you fulfil an order. A redirect to your return_url or redirect_url isn’t proof of payment.

curl -X GET 'https://api.yativo.com/api/v1/wallet/deposits/b3150e03-d27e-4de3-a0ff-16ebeb55683c' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

404 Deposit not found means the ID isn’t one of your deposits. See Get Deposit.

Stablecoin funding

Fund your Yativo balance with stablecoins, to use for payouts or fee payments.

Generate a deposit wallet address

POST /crypto/create-wallet

string

required

The coin and network, as {COIN}_{NETWORK}:

Network	Values
Solana	`USDC_SOL`, `EURC_SOL`, `USDT_SOL`, `USDG_SOL`, `PYUSD_SOL`
Polygon	`USDC_POL`, `USDT_POL`

string

Pass a customer ID to generate a deposit address for a specific customer’s account.

curl -X POST 'https://api.yativo.com/api/v1/crypto/create-wallet' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{ "currency": "USDC_SOL" }'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "customer_id": null,
    "wallet_address": "7TzXXXXXXXXXXXXX",
    "wallet_currency": "USDC_SOL",
    "wallet_network": "SOL",
    "coin_name": "USDC"
  }
}

Each address belongs to one currency, and to one customer when you pass customer_id. Asking again for the same currency and customer returns the existing address with the message Wallet already exists.

Wallet address limits

You can request at most 3 wallet addresses a minute for each customer_id, or 3 a minute for your own account when you don’t pass one. This applies to POST /crypto/create-wallet and to the corporate card funding addresses created by GET /corporate-card/wallet. The request that goes over the limit returns 403. Both endpoints then stay blocked for that customer for 24 hours:

{
  "status": "failed",
  "status_code": 403,
  "message": "Request failed.",
  "data": {
    "error": "Too many wallet address generation requests. Access to this endpoint has been blocked."
  }
}

Later requests during the block return 403 with You have been blocked from generating wallet addresses due to excessive requests. Contact Yativo support to lift it early. To avoid the limit, store each address and look it up with GET /crypto/get-wallets instead of requesting a new one.

Retrieve your deposit wallet addresses

GET /crypto/get-wallets

Deposit history

GET /crypto/deposit-histories

For a specific wallet address:

GET /crypto/wallet/deposit/histories/{wallet_address}

Recommended workflow

# Option A: With locked rate (recommended)
1. POST /exchange-rate           → get quote_id (rate locked 5 minutes)
2. POST /wallet/deposits/new     → create payin using quote_id

# Option B: Market rate
1. POST /wallet/deposits/new     → create payin with amount directly

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

SDKs

Regional Guides

Deposits (Payins)

Step 1 — Find your gateway ID

Supported payin countries

Gateway ID by country and currency

Step 2 — Create a payin

EUR bank transfer (SEPA)

Card payments

When card funds are available

List deposits

Get a deposit

Stablecoin funding

Generate a deposit wallet address

Wallet address limits

Retrieve your deposit wallet addresses

Deposit history

Recommended workflow

​Step 1 — Find your gateway ID

​Supported payin countries

​Gateway ID by country and currency

​Step 2 — Create a payin

​EUR bank transfer (SEPA)

​Card payments

​When card funds are available

​List deposits

​Get a deposit

​Stablecoin funding

​Generate a deposit wallet address

​Wallet address limits

​Retrieve your deposit wallet addresses

​Deposit history

​Recommended workflow

Step 1 — Find your gateway ID

Supported payin countries

Gateway ID by country and currency

Step 2 — Create a payin

EUR bank transfer (SEPA)

Card payments

When card funds are available

List deposits

Get a deposit

Stablecoin funding

Generate a deposit wallet address

Wallet address limits

Retrieve your deposit wallet addresses

Deposit history

Recommended workflow