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.

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.sandbox.unblockpay.com/v1/customers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "type": "individual",
    "first_name": "João",
    "last_name": "Silva",
    "email": "joao.silva@example.com",
    "phone_number": "+5511987654321",
    "date_of_birth": "1990-05-15",
    "tin": "123.456.789-00",
    "country": "BRA",
    "address": {
      "street_line_1": "Rua das Flores, 123",
      "street_line_2": "Apt 45",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BRA"
    }
  }'

Here is a response example when creating an individual customer:

{
  "id": "019d7904-ec72-7754-b5f5-443defb20da0",
  "type": "individual",
  "status": "pending",
  "first_name": "João",
  "last_name": "Silva",
  "email": "joao.silva@example.com",
  "phone_number": "+5511987654321",
  "date_of_birth": "1990-05-15",
  "tin": "123.456.789-00",
  "country": "BRA",
  "address": {
    "street_line_1": "Rua das Flores, 123",
    "street_line_2": "Apt 45",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310-100",
    "country": "BRA"
  },
  "partner_id": "partner_123",
  "verification": {
    "verification_link": "https://cockpit.sumsub.com/idensic/l/#/uni_ABC1...",
    "verification_type": "LIGHT"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Business Customer

Here is a request example for creating a business customer:

curl https://api.sandbox.unblockpay.com/v1/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": "+5511987654321",
    "tax_id": "96585813000160",
    "country": "BRA",
    "address": {
      "street_line_1": "Rua das Flores, 123",
      "street_line_2": "Apt 45",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-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": "+5511987654321",
  "tax_id": "96585813000160",
  "country": "BRA",
  "website": "https://www.techstartup.com",
  "address": {
    "street_line_1": "Rua das Flores, 123",
    "street_line_2": "Apt 45",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310-100",
    "country": "BRA"
  },
  "partner_id": "partner_123",
  "verification": {
    "verification_link": "https://cockpit.sumsub.com/idensic/l/#/uni_ABC1...",
    "verification_type": "LIGHT"
  },
  "beneficiaries": [],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

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.

Create customer POST /v1/customers
Redirect user → verification_link (Sumsub hosted flow)
Wait for result webhook or GET /v1/customers/{customerId}/verification-details

Option B – Direct API upload

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

Create customer POST /v1/customers
Upload documents POST /v1/customers/{customerId}/documents (one document per call)
Trigger verification POST /v1/customers/{customerId}/check
Wait for result via webhook or GET /v1/customers/{customerId}/verification-details

The required documents are fixed and listed below, so you can start uploading immediately. If you want to confirm exactly what's still pending — especially after a partially_rejected status — call GET /v1/customers/{customerId}/verification-details first.

Required information and documents

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

Individual Customer	Business Customer
Full name	Legal name
Date of birth	Date of incorporation
Email	Email
Phone	Phone
TIN (Taxpayer Identification Number)	Tax ID
Country	Country
Address	Address
Identity document	Company formation documents + shareholder structure
Proof of address	Information and documents from Representative + UBOs + shareholders with more than 25%

KYC and KYB may not be available for Customers in specific jurisdictions, and some fiat ramps – such as USD and EUR – may require enhanced KYC and KYB documentation.

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

Field	Type	Required	Description
`file`	file	Yes	Document file — PDF, JPG, PNG, etc.
`metadata`	JSON string	Yes	Document metadata (see structure below)

curl https://api.sandbox.unblockpay.com/v1/customers/123e4567-e89b-12d3-a456-426614174000/documents \
  --request POST \
  --header 'Content-Type: multipart/form-data' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --form 'file=@/path/to/document.pdf' \
  --form 'metadata={"document_type":"NATIONAL_ID","document_side":"FRONT","country":"BRA"}'

Response — **204 No Body**. A 204 confirms the document was uploaded successfully.

Metadata structure

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

Metadata description

Field	Type	Required	Description
`document_type`	string	Yes	Type of document being uploaded. See allowed values below.
`document_side`	string	Conditional	Side of the document.Allowed values: `FRONT` or `BACK`.Required for `NATIONAL_ID`, `PASSPORT`, `DRIVER_LICENSE`.
`country`	string	No	3-letter ISO country code.Example: `BRA`, `USA`, `MEX`.
`beneficiary_id`	string	No	UBO identifier — KYB only. Associates the document with a specific beneficial owner.

Allowed `document_type` values:

Value	Description	Applies to
`PASSPORT`	Valid passport — must be within expiry date and show personal details page	Individuals
`NATIONAL_ID`	Government-issued national identity card — front and back required	Individuals
`DRIVER_LICENSE`	Valid driver's license — front and back required	Individuals
`PROOF_OF_ADDRESS`	Recent utility bill, bank statement, or official letter — must be no older than 3 months and show full name and address	Individuals
`SELFIE`	A clear photo of the customer holding their identity document	Individuals
`INCORPORATION_ARTICLES`	Articles of incorporation or equivalent founding document	Businesses
`INCORPORATION_CERTIFICATE`	Official certificate of incorporation issued by the relevant government authority	Businesses
`INCUMBENCY_CERTIFICATE`	Certificate confirming current company officers and directors	Businesses
`SHAREHOLDER_REGISTRY`	Official document listing all shareholders and their ownership stakes	Businesses
`STATE_COMPANY_REGISTRY`	Company registration extract from the state or local business registry	Businesses

For NATIONAL_ID, PASSPORT, and DRIVER_LICENSE, both FRONT and BACK sides must be uploaded in separate calls.

For business customers with UBOs or beneficiaries, documents can be associated with a specific person using the beneficiary_id field.

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.

Response — **204 No Body**. A 204 confirms the verification was successfully triggered.

Status lifecycle

Every customer starts with a pending status upon creation. From there, verification follows this path:

Status	Description
`pending`	Customer created. Awaiting document upload or verification trigger.
`under_review`	Documents submitted and currently being analyzed.
`approved`	Verification passed — customer can transact.
`partially_rejected`	One or more items were rejected. Check verification details and resubmit.
`rejected`	Customer permanently blocked — no further submissions accepted.

Successful verification flow:

pending → under_review → approved

When submitted information is invalid, the customer can resubmit corrected documents:

pending → under_review → partially_rejected → approved

When a customer is permanently rejected:

pending → under_review → partially_rejected → rejected
pending → under_review → rejected

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."
      }
    ]
  }
}

Field	Description
`customer_status`	Overall verification status: `pending`, `under_review`, `approved`, `partially_rejected`, or `rejected`
`verification_steps.pending`	Items awaiting upload
`verification_steps.under_review`	Items currently being analyzed
`verification_steps.partially_rejected`	Items rejected that can be resubmitted — includes `rejection_code` and `rejection_description`
`verification_steps.approved`	Items that passed
`verification_steps.rejected`	Items permanently rejected — includes `rejection_code` and `rejection_description`

How to list Customers

GET /v1/customers

Returns a paginated list of all customers associated with the authenticated partner. Use limit, after, and before to paginate through results. Use start_date and end_date to filter by creation date.

Note: The verification_link field is only present for customers with status of pending or partially_rejected.

curl 'https://api.sandbox.unblockpay.com/v1/customers?limit=20&amp;after=eyJw...' \
  --header 'Authorization: YOUR_SECRET_TOKEN'

Response — 200 OK:

{
  "items": [
    {
      "id": "019d7904-ec72-7754-b5f5-443defb20da0",
      "type": "individual",
      "status": "approved",
      "first_name": "João",
      "last_name": "Silva",
      "email": "joao.silva@example.com",
      "phone_number": "+5511987654321",
      "date_of_birth": "1990-05-15",
      "tin": "123.456.789-00",
      "country": "BRA",
      "address": {
        "street_line_1": "Rua das Flores, 123",
        "city": "São Paulo",
        "state": "SP",
        "postal_code": "01310-100",
        "country": "BRA"
      },
      "created_at": "2024-03-01T09:00:00Z",
      "updated_at": "2024-03-01T09:00:00Z"
    }
  ],
  "cursor": {
    "after": "eyJwYXJhbXMiOiJ7ImxpbWl0IjoyMH19...",
    "before": null,
    "limit": 20,
    "page_count": 2
  }
}

Customers API endpoints

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

Method	Endpoint	Description
`POST`	`/v1/customers`	Create a new customer
`POST`	`/v1/customers/{customer_id}/documents`	Upload a single verification document
`POST`	`/v1/customers/{customer_id}/check`	Trigger the verification process
`GET`	`/v1/customers`	List all customers
`GET`	`/v1/customers/{customer_id}`	Get details for a specific customer

For the full schema and request/response details, see the API Reference .

Dashboard

Wallets

Customers

Understanding Customers

How to create a Customer

Individual Customer

Business Customer

How does the KYC/B verification work

Option A – Sumsub link (hosted flow)

Option B – Direct API upload

Required information and documents

How to upload a document

Request body

Metadata structure

Metadata description

Allowed document_type values:

How to run a KYC/KYB verification

Status lifecycle

How to check a KYC/KYB status

How to list Customers

Customers API endpoints

Allowed `document_type` values: