Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.yativo.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through creating a customer, issuing a virtual account, and making your first API call — from zero to live in minutes.

​
Step 1: Create Your Account

Go to app.yativo.com and sign up. Yativo uses passwordless authentication:
  1. Enter your email address
  2. A 5-digit OTP is sent to your inbox
  3. Enter the OTP to log in
You can also sign in with Google.

​
Step 2: Complete Business KYC

Before you can access the API, complete the Business KYC onboarding in the dashboard:
  1. Submit your company details (legal name, registration number, address)
  2. Upload required documents (certificate of incorporation, etc.)
  3. Add and verify your UBOs (Ultimate Beneficial Owners)
Once your business is verified, API access is unlocked.

​
Step 3: Get Your API Credentials

  1. Go to Developer → API Key in your dashboard
  2. Click Generate Secret
  3. Enter your 4-digit transaction PIN when prompted
  4. Copy your App Secret — it is shown only once
  5. Note your Account ID displayed on the same page

​
Step 4: Generate a Bearer Token

Use your Account ID and App Secret to obtain a Bearer token: 
POST /auth/login
cURL
curl -X POST 'https://api.yativo.com/api/v1/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "YOUR_ACCOUNT_ID",
    "app_secret": "YOUR_APP_SECRET"
  }'
Response: 
{
  "status": "success",
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
    "expires_in": 600
  }
}
Tokens expire in 600 seconds (10 minutes). Refresh using GET /auth/refresh-token.

​
Step 5: Create Your First Customer

Create a customer profile for someone you want to serve: 
POST /customer
cURL
curl -X POST 'https://api.yativo.com/api/v1/customer' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-001' \
  -d '{
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "customer_phone": "+5511999999999",
    "customer_country": "BRA",
    "customer_type": "individual"
  }'

{
  "status": "success",
  "data": {
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "customer_phone": "+5511999999999",
    "customer_status": "active",
    "customer_country": "BRA"
  }
}

​
Step 6: Submit KYC for the Customer

Submit identity verification for your customer via the Yativo KYC service: 
POST https://kyc.yativo.com/api/individual-kyc/submit
cURL
curl -X POST 'https://kyc.yativo.com/api/individual-kyc/submit' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-002' \
  -d '{
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "type": "individual",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "11999999999",
    "calling_code": "+55",
    "gender": "female",
    "birth_date": "1990-05-15",
    "nationality": "BR",
    "taxId": "12345678901",
    "selfie_image": "https://example.com/kyc/selfie.jpg",
    "residential_address": {
      "street_line_1": "Av. Paulista, 1000",
      "city": "Sao Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR",
      "proof_of_address_file": "https://example.com/kyc/proof-of-address.pdf"
    },
    "identifying_information": [
      {
        "type": "passport",
        "issuing_country": "BR",
        "number": "AB123456",
        "date_issued": "2020-01-01",
        "expiration_date": "2030-01-01",
        "image_front_file": "https://example.com/kyc/passport-front.jpg"
      }
    ],
    "employment_status": "Employed",
    "most_recent_occupation_code": "132011",
    "expected_monthly_payments_usd": "LessThan5K",
    "source_of_funds": "Salary",
    "account_purpose": "ReceiveSalary",
    "acting_as_intermediary": false,
    "usd_virtual_account": false,
    "eur_virtual_account": false,
    "eurde_virtual_account": false,
    "gbp_virtual_account": false
  }'
See the full field reference at /yativo-fiat/kyc, including optional fields such as account_purpose_other, uploaded_documents, and sumsub_token. In sandbox, KYC approves automatically. In production, allow up to a few minutes for verification.

​
Step 7: Create a Virtual Account

Once the customer’s KYC is approved (is_va_approved: true), issue a virtual account: 
POST /business/virtual-account/create
cURL
curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/create' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-003' \
  -d '{
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "currency": "BRL"
  }'

{
  "status": "success",
  "data": {
    "account_number": "9900123456",
    "account_type": "savings",
    "currency": "BRL",
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2"
  }
}
Your customer can now receive PIX payments at this account number. You’ll receive a virtual_account.deposit webhook when funds arrive.

​
Full Node.js Example

Node.js
const BASE_URL = 'https://api.yativo.com/api/v1';

// Step 1: Get Bearer token
async function getToken() {
  const res = await fetch(`${BASE_URL}/auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      account_id: process.env.YATIVO_ACCOUNT_ID,
      app_secret: process.env.YATIVO_APP_SECRET,
    }),
  });
  const { data } = await res.json();
  return data.access_token;
}

// Step 2: Create a customer
async function createCustomer(token) {
  const res = await fetch(`${BASE_URL}/customer`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID(),
    },
    body: JSON.stringify({
      customer_name: 'Jane Doe',
      customer_email: 'jane@example.com',
      customer_phone: '+5511999999999',
      customer_country: 'BRA',
      customer_type: 'individual',
    }),
  });
  const { data } = await res.json();
  return data.customer_id;
}

// Step 3: Create a virtual account
async function createVirtualAccount(token, customerId) {
  const res = await fetch(`${BASE_URL}/business/virtual-account/create`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID(),
    },
    body: JSON.stringify({
      customer_id: customerId,
      currency: 'BRL',
    }),
  });
  return res.json();
}

// Run the flow
(async () => {
  const token = await getToken();
  const customerId = await createCustomer(token);
  console.log('Customer ID:', customerId);

  // After KYC is approved:
  const account = await createVirtualAccount(token, customerId);
  console.log('Virtual account:', account.data.account_number);
})();

​
Next Steps