Quickstart

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:

Enter your email address
A 5-digit OTP is sent to your inbox
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:

Submit your company details (legal name, registration number, address)
Upload required documents (certificate of incorporation, etc.)
Add and verify your UBOs (Ultimate Beneficial Owners)

Once your business is verified, API access is unlocked.

Step 3: Get Your API Credentials

Go to Developer → API Key in your dashboard
Click Generate Secret
Enter your 4-digit transaction PIN when prompted
Copy your App Secret — it is shown only once
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": "0_4999",
    "source_of_funds": "salary",
    "account_purpose": "receive_salary",
    "acting_as_intermediary": false,
    "uploaded_documents": [
      { "type": "bank_statement", "file": "https://example.com/kyc/bank-statement.pdf" }
    ]
  }'

See the full field reference at KYC & KYB, including all enum values, Nigeria-specific fields, and document upload guidance. 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

Accept Payments — receive deposits via virtual accounts
Send Money — send cross-border payments
Sandbox — test your integration safely
Webhooks — receive real-time payment notifications

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

Regional Guides

Step 1: Create Your Account

Step 2: Complete Business KYC

Step 3: Get Your API Credentials

Step 4: Generate a Bearer Token

Step 5: Create Your First Customer

Step 6: Submit KYC for the Customer

Step 7: Create a Virtual Account

Full Node.js Example

Next Steps

​Step 1: Create Your Account

​Step 2: Complete Business KYC

​Step 3: Get Your API Credentials

​Step 4: Generate a Bearer Token

​Step 5: Create Your First Customer

​Step 6: Submit KYC for the Customer

​Step 7: Create a Virtual Account

​Full Node.js Example

​Next Steps

Step 1: Create Your Account

Step 2: Complete Business KYC

Step 3: Get Your API Credentials

Step 4: Generate a Bearer Token

Step 5: Create Your First Customer

Step 6: Submit KYC for the Customer

Step 7: Create a Virtual Account

Full Node.js Example

Next Steps