Customer Verification

Create Customer

The POST {{baseUrl}}/customer endpoint is designed to facilitate the creation and storage of new customer records within the system.

• HTTP Method: POST

• Endpoint URL: {{baseUrl}}/customer

• Authentication: Requires Bearer token.

• Request Payload: Accepts a JSON object with customer details (name, email, phone, address, identification, etc.)

Parameter	Description
customer_name	required, customer’s full name
customer_email	required, customer’s email
customer_phone	required, customer’s phone number
customer_type	Not required, Accepts individual or business, if not passed it defaults to individual

Create customer (example)

const url = '{{baseUrl}}/customer';

const payload = JSON.stringify({
    "customer_name": "Customer Name",
    "customer_email": "[email protected]",
    "customer_phone": "+xx xxxx xxxxx",
    "customer_country": "USA",
    "customer_type": "individual", // or business, defaults to individual when not passed
});

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer eyJ0xxxxxxxxxxx'
  },
  body: payload
};

fetch(url, options)
  .then(response => {
    if (!response.ok) {
      throw new Error('Network response was not ok ' + response.statusText);
    }
    return response.json();
  })
  .then(data => console.log('Customer created:', data))
  .catch(error => console.error('Error:', error));

Response example:

{
    "status": "success",
    "status_code": 200,
    "message": "Request successful",
    "data": {
        "customer_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
        "customer_name": "Some Body",
        "customer_email": "[email protected]",
        "customer_phone": "[phone]",
        "customer_status": "active",
        "customer_country": "USA",
        "created_at": "2025-04-14T08:45:31.000000Z"
    }
}

---

KYC

The Yativo Business API verifies end-users/customers for KYC compliance. For business customers refer to KYB.

The KYC can be completed via API. Request parameters:

Parameter	Type	Required	Description
first_name	string	Yes	The customer's first name.
last_name	string	Yes	The customer's last name.
middle_name	string	No	The customer's middle name.
email	string	No	The customer's email address.
phone	string	No	The customer's phone number.
date_of_birth / birth_date	string	Yes	Date of birth (YYYY-MM-DD).
ip_address	string	No	The customer's IP address.
type	string	Yes	The type of customer (e.g., "individual").
address.street_line_1	string	Yes	First line of address.
address.city	string	Yes	City.
address.state	string	No*	State/province (ISO 3166-2). Required if the country has subdivisions.
address.postal_code	string	Yes	Postal/ZIP code.
address.country	string (ISO 3166-1)	Yes	Country code (e.g., "USA", "NGA").
nationality	string (ISO 3166-1)	Yes	Nationality (e.g., "USA", "NGA").
employment_status	string	Yes	Employment status (e.g., "employed").
expected_monthly_payments	string (range)	Yes	Expected monthly payments (e.g., "5000_9999").
acting_as_intermediary	string ("yes" / "no")	Yes	Whether acting as an intermediary.
most_recent_occupation	string (code)	Yes	Occupation code (use occupation-codes endpoint).
account_purpose	string	Yes	Purpose of account (e.g., "purchase_goods_and_services").
account_purpose_other	string / null	No	Required if account_purpose includes "other".
source_of_funds	string	Yes	Source of funds (e.g., "salary").
identifying_information	array of objects	Yes*	Required if customer is from the USA.
identifying_information[].type	string	Yes	ID type (e.g., "ssn", "drivers_license").
identifying_information[].issuing_country	string (ISO 3166-1)	Yes	Issuing country for the ID.
identifying_information[].number	string	Yes	Identification number.
identifying_information[].image_front	string (Base64)	No	Base64 image of front (if applicable).
identifying_information[].image_back	string (Base64)	No	Base64 image of back (if applicable).
documents	array of objects	No	Additional documents.
documents[].purposes	array of strings	Yes	Purpose of the document (e.g., "proof_of_address").
documents[].file	string (Base64)	Yes	Base64-encoded document file.

1

Step 1 — Submit KYC via API

POST to: https://smtp.yativo.com/api/v1/verification/verify-customer

KYC submission (example)

const response = await fetch('https://smtp.yativo.com/api/v1/verification/verify-customer', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer YOUR_SECRET_TOKEN",
      "Idempotency-Key": "sfasfasfsadfasfsaf",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "customer_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
      "type": "individual",
      "first_name": "Lionel",
      "last_name": "Mandela",
      "email": "[email protected]",
      "address": {
        "street_line_1": "30 STREET",
        "city": "Lima",
        "state": "FC",
        "postal_code": "900901",
        "country": "PER"
      },
      "nationality": "PER",
      "birth_date": "xxxx-01-09",
      "employment_status": "employed",
      "expected_monthly_payments": "0_4999",
      "acting_as_intermediary": false,
      "most_recent_occupation": "291291",
      "account_purpose": "purchase_goods_and_services",
      "account_purpose_other": null,
      "source_of_funds": "salary",
      "documents": [],
      "identifying_information": [
        {
          "type": "passport",
          "issuing_country": "PER",
          "number": "xxxxxxxxx",
          "image_front": "data:image/jpeg;base64,kaD5HIroRqOFrHSAFtw",
          "image_back": "data:image/jpeg;base64,/9j/4AAQSkZJRg"
        }
      ]
    })
});

const data = await response.json();

Response (normal success):

{
    "status": "success",
    "status_code": 200,
    "message": "Request successful",
    "data": {
        "first_name": "FirstName",
        "last_name": "LastName",
        "status": "not_started",
        "rejection_reasons": [],
        "requirements_due": [],
        "future_requirements_due": []
    }
}

2

Step 2 — Check KYC status

GET: {{host}}/customer/kyc/{{customer_id}}

Example response:

{
    "status": "success",
    "status_code": 200,
    "message": "Request successful",
    "data": {
        "first_name": "FirstName",
        "last_name": "LastName",
        "status": "manual_review",
        "kyc_rejection_reasons": [],
        "kyc_requirements_due": [],
        "kyc_future_requirements_due": [],
        "bio_data": {
            "customer_id": "xxxxxx-xxxx-xxxx-xxxxx-xxxxxx",
            "customer_name": "Customer Name",
            "customer_email": "[email protected]",
            "customer_phone": "+xxxxxxx",
            "customer_country": "USA",
            "customer_address": null,
            "customer_status": "active",
            "customer_kyc_status": "approved",
            "customer_kyc_reject_reason": null,
            "created_at": "2025-04-14T08:45:31.000000Z",
            "kyc_verified_date": "2025-04-14T15:00:26.423619Z"
        },
        "kyc_link": "https://checkout.yativo.com/kyc/update-biodata/xxxxx-xxxxx-xxx-xxxx-xxxx",
        "is_va_approved": false
    }
}

3

Step 3 — KYC link (use only if approval delays > 24 hours)

If the response includes kyc_link, follow that link to complete verification manually:

"kyc_link": "https://checkout.yativo.com/kyc/update-biodata/xxxxx-xxxxx-xxx-xxxx-xxxx"

---

Get occupation codes

GET {{base_url}}/occupation-codes

Response (truncated):

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": [
    {
      "display_name": "Accountant and auditor",
      "code": "132011"
    },
    {
      "display_name": "Actor",
      "code": "272011"
    },
    {
      "display_name": "Actuary",
      "code": "152011"
    },
    {
      "display_name": "Acupuncturist",
      "code": "291291"
    }
    // clipped for brevity, make the request to get full list.
  ]
}

---

KYB

Know Your Business (KYB) verification validates company details. For individual customers see KYC.

Endpoint: /api/v1/verification/verify-customer

Parameter	Type	Required	Description
customer_id	string (UUID)	Yes	Unique identifier for the customer.
type	string	Yes	Type of customer entity (e.g., "business").
primary_website	string (URL)	Yes*	Business website URL. Required if nature_of_business not provided.
nature_of_business	string (Base64)	Yes*	Document explaining business nature. Required if primary_website not provided.
address.street_line_1	string	Yes	Business address first line.
address.city	string	Yes	City.
address.state	string	No*	State/province (ISO 3166-2). Required if country has subdivisions.
address.postal_code	string	Yes	Postal/ZIP code.
address.country	string (ISO 3166-1)	Yes	Country code (e.g., "USA", "NGA").
business_type	string	Yes	Type of business entity (e.g., "corporation").
business_industry	string (code)	Yes	Industry code.
compliance_screening_explanation	string	Yes	Explanation for compliance screening.
description	string	Yes	Business description.
email	string (email)	Yes	Business contact email.
formation_document	string (Base64)	Yes	Formation document (Base64).
is_dao	boolean	Yes	Whether it's a DAO.
is_high_risk	boolean	Yes	High-risk status.
name	string	Yes	Business name.
business_name	string	Yes	Formal registered business name.
registration_number	string	Yes	Registration number.
contact_person	string	Yes	Primary contact person.
business_address	string	Yes	Formatted business address.
source_of_funds_description	string	Yes	Source of funds description.
ownership_document	string (Base64)	Yes	Ownership docs (Base64).
service_usage_description	string	Yes	How services will be used.
documents	array of objects	Yes	Additional docs.
documents[].type	string	Yes	Type (e.g., "business_license").
documents[].file	string (Base64)	Yes	File (Base64).
sof_eu_questionnaire	object	Yes	Source of funds questionnaire (see fields below).
statement_of_funds	string (Base64)	Yes	Statement of funds (Base64).
tax_identification_number	string	Yes	Tax ID.
ultimate_beneficial_owners	array of objects	Yes	Beneficial owners info (see fields below).

Fields in sof_eu_questionnaire and ultimate_beneficial_owners are described in the original spec (estimated_annual_revenue_usd, expected_monthly_payments_usd, operates_in_prohibited_countries, primary_purpose, high_risk_activities, source_of_funds, and detailed owner fields including gov_id images and proof_of_address documents).

Example request (truncated):

KYB submission (example)

{
  "customer_id": "022611d5-d874-4351-b902-ffea270112a7",
  "type": "business",
  "primary_website": "https://www.example.com",
  "nature_of_business": "data:image/jpeg;base64,DUMMY_BASE64_STRING",
  "address": {
    "street_line_1": "123 Business St",
    "city": "Sample City",
    "state": "FC",
    "postal_code": "900901",
    "country": "CHL"
  },
  "business_type": "corporation",
  "business_industry": "1153",
  "compliance_screening_explanation": "Sample business description",
  "description": "Sample business",
  "email": "[email protected]",
  "formation_document": "data:image/jpeg;base64,DUMMY_BASE64_STRING",
  "is_dao": false,
  "is_high_risk": false,
  "name": "Sample Business",
  ...
  "ultimate_beneficial_owners": [
    {
      "first_name": "First",
      "middle_name": "Middle",
      "last_name": "Last",
      "birth_date": "1990-01-01",
      "email": "[email protected]",
      ...
      "gov_id_image_front": "data:image/jpeg;base64,DUMMY_BASE64_STRING",
      "gov_id_image_back": "data:image/jpeg;base64,DUMMY_BASE64_STRING",
      "proof_of_address_document": "data:image/jpeg;base64,DUMMY_BASE64_STRING"
    }
  ]
}

---

KYC/KYB Update

To update a KYC or KYB submission send a PUT to:

PUT api/v1/customer/kyc/update

Example payload (truncated):

Update KYC/KYB (example)

{
    "customer_id": "4026f9ef-567f-4e91-97eb-9d5e4246d922",
    "type": "business",
    "primary_website": "https://google.com",
    "address": {
        "street_line_1": "123 Main St",
        "city": "New York City",
        "state": "FC",
        "postal_code": "900901",
        "country": "NGA"
    },
    "business_type": "corporation",
    "business_industry": "1153",
    "compliance_screening_explanation": "A business",
    "description": "A business",
    "email": "[email protected]",
    "formation_document": "data:image/jpeg;base64,",
    ...
    "ultimate_beneficial_owners": [
        {
            "first_name": "John",
            "middle_name": "Smith",
            "last_name": "Doe",
            "birth_date": "1990-01-01",
            "email": "[email protected]",
            ...
            "proof_of_address_document": "data:image/jpeg;base64,"
        }
    ]
}

---

KYC Status

To check KYC/KYB status make a GET request with the customer’s id:

GET /api/v1/customer/kyc/{{customer_id}}

Example response:

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "first_name": "John",
    "last_name": "Doe",
    "status": "active",
    "kyc_rejection_reasons": [],
    "kyc_requirements_due": [],
    "kyc_future_requirements_due": [],
    "bio_data": {
      "customer_id": "00000000-0000-0000-0000-000000000000",
      "customer_name": "John Doe",
      "customer_email": "[email protected]",
      "customer_phone": "[phone]",
      "customer_country": "USA",
      "customer_address": null,
      "customer_status": "active",
      "customer_kyc_status": "approved",
      "customer_kyc_reject_reason": null,
      "created_at": "2025-02-13T14:59:54.000000Z",
      "kyc_verified_date": "2025-03-29 22:14:53"
    },
    "is_va_approved": true
  }
}

---

Fetch Customer

GET a single customer by ID:

GET /api/v1/customer/customer/{{customer_id}}

Example response (truncated):

{
  "status": "success",
  "status_code": 200,
  "message": "Customer retrieved successfully",
  "data": {
    "customer_id": "00000000-0000-0000-0000-000000000000",
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "customer_phone": "[phone]",
    "customer_country": "USA",
    "customer_address": null,
    "customer_status": "active",
    "customer_kyc_status": null,
    "customer_kyc_reject_reason": null,
    "created_at": "2025-02-13T14:59:54.000000Z",
    "kyc_verified_date": "2025-03-29 22:14:53",
    "customer_virtualaccounts": [
      {
        "account_id": "11111111-1111-1111-1111-111111111111",
        "currency": "USD",
        "account_info": {
          "bank_name": "Sample Bank",
          "account_name": "John Doe",
          "account_type": "Checking",
          "account_number": "000000000000",
          "routing_number": "000000000"
        },
        "created_at": "2025-02-14T13:10:08.000000Z"
      }
    ]
  }
}

---

Fetch all Customers

GET /api/v1/customer/customer

Example response (truncated):

{
  "status": "success",
  "status_code": 200,
  "message": "Records retrieved successfully",
  "data": [
    {
      "customer_id": "11111111-1111-1111-1111-111111111111",
      "customer_name": "John Doe",
      "customer_email": "[email protected]",
      "customer_phone": "[phone]",
      "customer_country": "USA",
      "customer_status": "active",
      "created_at": "2025-02-13T14:59:54.000000Z",
      "kyc_verified_date": "2025-03-29 22:14:53"
    },
    {
      "customer_id": "22222222-2222-2222-2222-222222222222",
      "customer_name": "Jane Smith",
      "customer_email": "[email protected]",
      "customer_phone": "[phone]",
      "customer_country": "CAN",
      "customer_status": "active",
      "created_at": "2025-02-06T18:39:02.000000Z",
      "kyc_verified_date": "2025-03-29 22:15:02"
    }
  ],
  "pagination": {
    "total": 4,
    "per_page": 20,
    "current_page": 1,
    "last_page": 1,
    "next_page_url": null,
    "prev_page_url": null
  }
}

---

Enroll Customer for Omnibus

Use this endpoint to enroll your customer for Omnibus payments (enables omnibus deposits and withdrawals).

1

Step 1 — Enroll customer

POST {{base_url}}/api/v1/epay/enroll-customer

Parameter	Required	Description
customer_id	Yes	The customer’s yativo ID
legalId	Yes	The ID number on the customer’s legal ID document
country	Yes	The customer’s country
state	Yes	The customer’s state

Example:

Enroll customer (example)

{
    "customer_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx",
    "legalId": "20xxxxxxx",
    "country": "Argentina",
    "state": "SOLTERO"
}

2

Step 2 — Verify Customer ID for Omnibus Deposit

After step 1, verify the customer ID. For two-sided IDs send two form-data requests (front and back).

POST {{base_url}}/api/v1/epay/compliance

Parameter	Required	Description
document	Yes	The identification document (file)
customer_id	Yes	Their customer id
docType	Yes	Document type (e.g., DNI_FRONT, DNI_BACK, FUNDS, etc.)
fileName	Yes	Name of the uploaded file

Example (browser JavaScript using FormData):

Omnibus compliance (example)

var formdata = new FormData();
formdata.append("document", fileInput.files[0], "1eeb926f-5d72-4ec0-8c2d-3b9816134de9");
formdata.append("customer_id", "c586066b-0f29-468f-b775-15483871a202");
formdata.append("docType", "DNI_BACK");
formdata.append("fileName", "dni_back.jpg");

var requestOptions = {
  method: 'POST',
  body: formdata,
  redirect: 'follow'
};

fetch(`{{base_url}}/api/v1/epay/compliance`, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));