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)
  • Selfie for liveness verification

Verification Tiers:

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

Identity token sharing (sumsub)

Request

Share customer identity

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
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