Skip to content

KYC Sessions (Standalone KYC)

Standalone KYC - Have Banxa verify a customer in Banxa-hosted identity screens before any order, then take payment with Banxa Native.

Authentication: this endpoint uses your Hosted Checkout API key (x-api-key), not HMAC, and is served under /{partnerRef}/v2/. You need both your Native API HMAC credentials and a Hosted Checkout API key.

Flow:

  1. Create a session from your backend
  2. Show redirectUrl to the customer in an iframe or webview, or redirect them
  3. Receive the KYC webhook
  4. Check eligibility before creating a ramp

See Standalone KYC.

Operations

Create a Standalone KYC session

Request

Start a Standalone KYC session: Banxa verifies the customer in Banxa-hosted identity screens before any order.

Uses your Hosted Checkout API key, not HMAC. This endpoint is served under /{partnerRef}/v2/, not /eapi/v0/. Send your Hosted Checkout API key in the x-api-key header. You need both sets of credentials: HMAC for the Native API, and the Hosted Checkout API key for this endpoint.

Requires Standalone KYC: until it's enabled for your account, this endpoint returns 403. Contact your Banxa integration manager to enable it.

Idempotent per customer: calling again for the same externalCustomerId while the link is valid returns the same redirectUrl and expiresAt. A changed tier or country still applies the next time the customer loads a screen.

The response doesn't include the verification result. Use the KYC webhook and eligibility.

Security
ApiKeyAuth
Path
partnerRefstringrequired

Your partner reference (merchant code). It must match the account your Hosted Checkout API key belongs to.

Example:yourpartner
Bodyapplication/jsonrequired
externalCustomerIdstring, <= 255 charactersrequired

Your identityReference for the customer. Use the same value you use in Native API calls. Longer values are rejected, not truncated.

Example:"partner-abc123"
countrystring or null, = 2 characters

The customer's country of residence, as a 2-letter ISO 3166-1 code. If omitted, the customer is asked for it.

Example:"AU"
tierstring

The verification level to request. Banxa combines it with the customer's country to decide what to collect. express must be enabled for your account and country; otherwise the customer gets standard. See Standalone KYC.

Default:"standard"
Enum:"standard""enhanced""express"
returnUrlstring or null

An https URL or an app deep link, for example myapp://kyc-done. If auto-redirect is enabled for your account, the customer is sent here when they finish.

Example:"https://yourapp.com/kyc/done"
curl -i -X POST \
  https://docs.banxa.com/_mock/products/native-api/openapi/yourpartner/v2/kyc/sessions \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "externalCustomerId": "partner-abc123",
    "country": "AU",
    "tier": "standard",
    "returnUrl": "https://yourapp.com/kyc/done"
  }'

Responses

Session created, or the existing valid session returned.

Bodyapplication/json
redirectUrlstring, (uri)required

The link to show the customer in an iframe or webview, or to redirect them to.

Example:"https://checkout.banxa.com/..."
expiresAtstring, (date-time)required

When the link expires, 1 hour after it was first created.

Example:"2026-08-21T08:10:00+00:00"
Response
{
  "redirectUrl": "https://checkout.banxa.com/...",
  "expiresAt": "2026-08-21T08:10:00+00:00"
}
© Banxa 2026