Customers

Understanding Customers

Customers are end users of your platform and can be either individuals or businesses. They represent the entity on whose behalf transactions are executed — the beneficial owner of wallets, balances, and payment activities within the platform.

Before making any transactions, all users must register as customers through UnblockPay's Customers API and undergo a KYC or KYB process to verify their identity. Once approved by UnblockPay, customers can seamlessly transfer stablecoins or fiat currencies between wallets and bank accounts.

Customers API endpoints

Here are the endpoints you'll need to create or manage a customer:

• POST /v1/customers: Create a new customer

• POST /v1/customers/{customerId}/documents: Upload a single verification document

• POST /v1/customers/{customerId}/check: Trigger the verification process

• GET /v1/customers: List all customers

• GET /v1/customers/{id}: Get specific details for one customer

• GET /v1/customers/{customerId}/verification-details: Return the current verification status of the customer

Required information and documents

KYC and KYB verification processes include collecting essential information such as:

How does the KYC/B verification work?

After creating a customer, there are two ways to complete the verification:

Option A – Sumsub link (hosted flow)

The POST /v1/customers response includes a verification.verification_link. You can redirect your user to that URL and let Sumsub handle the document collection UI entirely. No further API calls are needed on your end — the customer completes everything on the hosted page.

1. Create customer POST /v1/customers

2. Redirect user → verification_link (Sumsub hosted flow)

3. Wait for result webhook or GET /v1/customers/{customerId}/verification-details

Option B – Direct API upload

Upload documents yourself via the API, then trigger verification programmatically. This gives you full control over the UI and document collection experience.

1. Create customer POST /v1/customers

2. Upload documents POST /v1/customers/{customerId}/documents (one per call)

3. Trigger verification POST /v1/customers/{customerId}/check

4. Wait for result webhook or GET /v1/customers/{customerId}/verification-details

Status lifecycle

Every customer starts with a pending status upon creation. From there, verification can follow two paths: the customer moves to under_review while documents are being analyzed, and is either approved or moves to partially_rejected if some items need correction — in which case they can resubmit and reach approved or be permanently rejected.

How to create a Customer?

POST /v1/customers

This endpoint lets you create customer profiles that represent your end users. You must create a customer in UnblockPay before processing any pay-ins or payouts.

To create a new Customer, send a POST request to the Customer endpoint with the required fields in the request body, specifying either individual or business as the customer type.

Individual Customer

Here is a request example for creating an individual customer:

curl https://api.unblockpay.com/v1/customers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "type": "individual",
    "first_name": "Satoshi",
    "last_name": "Nakamoto",
    "email": "satoshi@email.com",
    "phone_number": "1234567890",
    "date_of_birth": "1990-01-01",
    "tin": "12345678900",
    "country": "BRA",
    "address": {
      "street_line_1": "123 Main St",
      "street_line_2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "USA"
    }
  }'

Here is a response example when creating an individual customer:

{
  "id": "0196c8cd-839a-7389-b5ce-0a0776023e55",
  "type": "individual",
  "status": "pending",
  "first_name": "Satoshi",
  "last_name": "Nakamoto",
  "email": "satoshi@email.com",
  "phone_number": "1234567890",
  "date_of_birth": "1990-01-01",
  "tin": "12345678900",
  "country": "BRA",
  "address": {
    "street_line_1": "123 Main St",
    "street_line_2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "USA"
  },
  "partner_id": "partner_123",
  "verification": {
    "verification_link": "https://sumsub.com/...",
    "verification_type": "LIGHT"
  },
  "created_at": "2025-05-13T08:40:33.946Z",
  "updated_at": "2025-05-13T08:40:33.946Z"
}

Business Customer

Here is a request example for creating an business customer:

curl https://api.unblockpay.com/customers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "type": "business",
    "business_legal_name": "Satoshi Company LLC",
    "date_of_incorporation": "2020-08-10",
    "email": "satoshi@email.com",
    "phone_number": "1234567890",
    "tax_id": "96585813000160",
    "country": "BRA",
    "address": {
      "street_line_1": "123 Main St",
      "street_line_2": "Apt 4B",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "04514-100",
      "country": "BRA"
    },
    "website": "https://www.techstartup.com",
    "no_ubos": false,
    "beneficiaries": [
      {
        "first_name": "string",
        "last_name": "string",
        "email": "string",
        "phone_number": "string",
        "date_of_birth": "YYYY-MM-DD",
        "tin": "string",
        "country": "string",
        "share_size": "25.5",
        "address": { }
      }
    ]
  }'

Here is a response example when creating a business customer:

{
  "id": "01932e60-1234-7890-bcde-f12345678901",
  "type": "business",
  "status": "pending",
  "business_legal_name": "Satoshi Company LLC",
  "date_of_incorporation": "2020-08-10",
  "email": "satoshi@email.com",
  "phone_number": "1234567890",
  "tax_id": "96585813000160",
  "country": "BRA",
  "website": "https://www.techstartup.com",
  "address": {
    "street_line_1": "123 Main St",
    "street_line_2": "Apt 4B",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "04514-100",
    "country": "BRA"
  },
  "partner_id": "partner_123",
  "verification": {
    "verification_link": "https://sumsub.com/...",
    "verification_type": "LIGHT"
  },
  "beneficiaries": [ ],
  "created_at": "2026-02-18T10:35:00Z",
  "updated_at": "2026-02-18T10:35:00Z"
}

How to upload a document?

POST /v1/customers/{customerId}/documents

Content-Type: multipart/form-data

This endpoint lets you upload a single verification document. Call this endpoint once per file — documents must be uploaded individually.

Request body

Metadata structure

{
  "document_type": "NATIONAL_ID",
  "document_side": "FRONT",
  "country": "BRA",
  "beneficiary_id": "49ea431c-9c71-40a1-8e08-41503ed8eb5b"
}

Field description:

Allowed document_type values:

How to check a KYC/KYB status?

GET /v1/customers/{customerId}/verification-details

This endpoint returns the current verification status of the customer, broken down by individual step or document. Use this endpoint to check what's still pending before uploading, or to understand what was rejected after a partially_rejected status.

Response — 200 OK:

{
  "customer_id": "49ea431c-9c71-40a1-8e08-41503ed8eb5b",
  "customer_status": "pending",
  "verification_steps": {
    "pending": [
      "SHAREHOLDER_REGISTRY"
    ],
    "under_review": [
      "CUSTOMER_BENEFICIARIES"
    ],
    "partially_rejected": [
      {
        "name": "CUSTOMER_DATA",
        "rejection_code": ["WRONG_ADDRESS"],
        "rejection_description": "Invalid customer data, please update customer info."
      }
    ],
    "approved": [
      "INCORPORATION_CERT"
    ],
    "rejected": [
      {
        "name": "INCORPORATION_ARTICLES",
        "rejection_code": ["EXPIRED", "FRAUDULENT"],
        "rejection_description": "Document has expired and appears to be fraudulent."
      }
    ]
  }
}

How to run a KYC/KYB verification?

POST /v1/customers/{customerId}/check

Triggers the verification process. Must be called after the customer is created and all required documents have been uploaded.

The verification runs asynchronously. You'll receive the result via webhook, or you can poll GET /v1/customers/{customerId}/verification-details.

No response body. A 200 confirms the verification was successfully triggered.