Skip to content

Identities (KYC)

Identity & KYC Management - Manage customer identity verification and Know Your Customer (KYC) compliance.

Key Operations:

  • Create basic customer identities
  • Share KYC verification via third-party providers (Sumsub)
  • Upload identity documents directly
  • Update customer information
  • Retrieve identity verification status

Verification Methods:

  1. Token Sharing: Use existing KYC from Sumsub
  2. Identity Reliance: Share verified identity data
  3. Document Upload: Submit documents directly to Banxa

Required Documents:

  • Government-issued photo ID (passport, driver's license, national ID)
  • Proof of address (utility bill, bank statement)
  • Liveness check, completed through Sumsub token sharing or a Banxa-hosted flow

Verification Tiers:

  • Tier 0: Basic info (low limits)
  • Tier 1: Email + phone verified (medium limits)
  • Tier 2: Full KYC verified (high limits)
Operations
Webhooks

Share a Sumsub KYC token

Request

Share customer identity

Requires KYC sharing: KYC sharing must be enabled for your account. If it isn't, this endpoint returns 400 with code 4005 and the message "KYC sharing not enabled". Contact your Banxa integration manager to enable it.

Security
HMACAuth
Bodyapplication/jsonrequired
identityReferencestring, [ 1 .. 255 ] characters(Identity Reference)^[A-Za-z0-9-]+$required

A unique customer identifier provided by the partner. This field is required and must be unique for each customer.

Important: You must consistently reuse the same identityReference for repeat interactions with the same customer, allowing Banxa to reliably recognize and associate their identity across multiple transactions.

Format Requirements:

  • Only ASCII letters (a-z, A-Z), digits (0-9), and hyphens (-) are allowed
  • Must be between 1 and 255 characters
  • Case-sensitive

Best Practices:

  • Use a consistent format across your system
  • Consider using a prefix to identify your organization (e.g., 'partner-customer-123')
  • Do not include personally identifiable information (PII) in the reference
  • Store the mapping between your internal customer ID and this reference securely
Example:"c-13344"
emailstring, (email), <= 200 charactersrequired

The customer email

Example:"[email protected]"
mobileNumberstring

Mobile phone number in international format (E.164).

Format: Include country code with + prefix

Examples:

  • "+61431000001" (Australia)
  • "+14155552671" (USA)
  • "+442071234567" (UK)

Requirements:

  • Must be a valid, active mobile number
  • Used for SMS verification if needed
  • Maximum 20 characters
Example:"61410001000"
taxIdTypestring(TaxIdType)

The category of tax or government identifier supplied in taxId. The correct value depends on the customer's country and the identifier type accepted for that country.

ValueDescription
identity_cardA government-issued identity card number used for identity or tax reporting in the customer's country.
tax_idA tax identification number issued by a tax authority, such as a TFN, TIN, ITIN, or equivalent.
national_numberA national, citizen, resident, or social insurance number used to identify an individual in their country.
ssnA Social Security Number, generally used for US individuals.
Enum:"identity_card""tax_id""national_number""ssn"
Example:"tax_id"
taxIdstring(TaxId)

Tax identification number.

See TIN validation.

Example:"123-11-123"
taxStatestring

Tax state or region if applicable.(associated with the taxId) Required format as two characters. Note; We do not accept any states where Banxa is not licensed.

Example:"IL"
providerobjectrequired

Share existing KYC verification from Sumsub

curl -i -X POST \
  https://docs.banxa.com/_mock/products/native-api/openapi/eapi/v0/identities/share/token \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "identityReference": "customer-12345",
    "email": "[email protected]",
    "mobileNumber": "+61431000001",
    "provider": {
      "vendor": "sumsub",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
    }
  }'

Responses

The identity sharing request has been accepted for processing, but the processing has not been finished yet.

Bodyapplication/json
identityReferencestring, [ 1 .. 255 ] characters(Identity Reference)^[A-Za-z0-9-]+$required

A unique customer identifier provided by the partner. This field is required and must be unique for each customer.

Important: You must consistently reuse the same identityReference for repeat interactions with the same customer, allowing Banxa to reliably recognize and associate their identity across multiple transactions.

Format Requirements:

  • Only ASCII letters (a-z, A-Z), digits (0-9), and hyphens (-) are allowed
  • Must be between 1 and 255 characters
  • Case-sensitive

Best Practices:

  • Use a consistent format across your system
  • Consider using a prefix to identify your organization (e.g., 'partner-customer-123')
  • Do not include personally identifiable information (PII) in the reference
  • Store the mapping between your internal customer ID and this reference securely
Example:"c-13344"
Response
{
  "identityReference": "customer-12345"
}
© Banxa 2026