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: Create an API Key

Go to Developers → API Keys in your dashboard
Click Generate key
Enter a Label and the public IPs of the servers that will call Yativo (run curl https://checkip.amazonaws.com on each server to find it)
Copy the API secret — it is shown only once

See API Keys and IP whitelisting for details.

Step 4: Authenticate Your Requests

Send your key and secret as headers on every request. There’s no login call or token to refresh:

cURL

curl 'https://api.yativo.com/api/v1/ip-whitelist/check' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

This checks your key and confirms your server’s IP is allowed. Look for "allowed_server": true in the response.

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 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -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 '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. Sandbox uses the same customer KYC submission as production. Creating a customer does not approve them. Your own sandbox account also has to be approved before most API calls succeed. See Sandbox KYC.

Step 7: Create a Virtual Account

Once the customer’s endorsement for the currency is approved (watch the endorsement.updated webhook), issue a virtual account. See Track verification with endorsements.

POST /business/virtual-account/create

cURL

curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/create' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -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';

// Your API key and secret are read from the environment on each request.

// Step 1: Create a customer
async function createCustomer() {
  const res = await fetch(`${BASE_URL}/customer`, {
    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': 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 2: Create a virtual account
async function createVirtualAccount(customerId) {
  const res = await fetch(`${BASE_URL}/business/virtual-account/create`, {
    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': crypto.randomUUID(),
    },
    body: JSON.stringify({
      customer_id: customerId,
      currency: 'BRL',
    }),
  });
  return res.json();
}

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

  // After KYC is approved:
  const account = await createVirtualAccount(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: Create an API Key

Step 4: Authenticate Your Requests

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: Create an API Key

​Step 4: Authenticate Your Requests

​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: Create an API Key

Step 4: Authenticate Your Requests

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