Which API key do I use for which Banxa endpoint?

Banxa has two credential types, and using the wrong one is the most common cause of 401 Unauthorized errors. The v2 API key, sent in the x-api-key header, is for all /v2 endpoints: quotes, orders, payment methods, fiats, crypto and countries. The HMAC key pair, an API key plus secret, is for POST /v2/identities/token/share (KYC sharing) and for verifying incoming webhook signatures. Both credential sets are visible in the merchant dashboard, per environment.

Is a Banxa quote a guaranteed price?

No. Quotes are indicative and carry no quote ID, so there is nothing to pass into order creation. The final price is confirmed at checkout. Re-quote whenever the customer changes amount, currency, or payment method.

How long is a Banxa checkout URL valid?

The checkoutUrl returned by POST /v2/buy is valid for 1 minute, starting from Banxa's response to the order creation request. Once the URL has been loaded there is no further expiry. Create the order at the moment the customer confirms, then open the URL immediately. Do not create orders in advance.

When is a Banxa order final?

Only the terminal statuses are final: complete, cancelled, declined and refunded. In particular paymentReceived is not final, because an order can still be cancelled after payment if it is held for risk or compliance review. Do not credit your customer or trigger downstream fulfilment until you receive complete.

Which Banxa product should I integrate?

The choice is decided by who runs KYC. Use the Banxa Native API when your platform already runs its own KYC and wants no Banxa screens at all: it is headless, HMAC-signed server-to-server, and requires a backend. Use Banxa Hosted Checkout when you do not want to run KYC: Banxa handles identity, payment and delivery in its own flow, by redirect, embedded iFrame, or React Native SDK, with no backend required for the referral path. The Legacy API is maintained for existing integrations only.

Does Banxa support OAuth for API authentication?

No. Banxa runs no OAuth authorization server and publishes no OpenID Connect discovery document. The Native API authenticates with HMAC-SHA256 signatures and Hosted Checkout with an x-api-key header. Credentials are issued to onboarded partners through the Partner Dashboard and cannot be provisioned programmatically.

Identity update

Request

Update specific fields of an existing customer identity.

Use Case: Update customer information without resubmitting all documents.

Partial Updates: Only include fields you want to update. Omitted fields remain unchanged.

Important Notes:

Some changes may trigger re-verification
Email and identityReference are required to identify the customer
Changes to critical fields (name, DOB) may require document re-submission

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"

mobileNumberstring, [ 8 .. 20 ] characters(Mobile Number)^\+[1-9]\d{1,14}$

Updated mobile phone number in international format (E.164).

Example:"+61431000001"

emailstring, (email), <= 254 characters(Email Address)required

Updated email address.

Example:"[email protected]"

customerIdentityobject(Customer Identity Updates)

Partial customer identity updates. Only include fields to update.

occupationIndustrystring(Occupation Industry)

The industry sector of the customer's occupation.

Important: The selected industry determines which specific occupations are valid. See the Occupation schema for the mapping table.

Compliance Requirement: Required for AML/KYC compliance to assess customer risk profile.

Enum:"Consulting, IT, or business services""Design, marketing or communication""Travel, accommodation, or transport""Entertainment, arts or photography""Health, sports or personal care""Food, beverages, or tobacco""Retail, eCommerce, wholesale or manufacturing""Dealers & Resellers""Financial services, products, or holding companies""Real estate or construction"

Example:"Consulting, IT, or business services"

occupationstring(Occupation)

Customer's occupation. Must be a valid occupation for the selected 'occupationIndustry'. When the selected combination is invalid a validation error will be thrown. Refer to the Occupation-Industry mapping table:

occupationIndustry	occupation
Consulting, IT, or business services	Architect
Consulting, IT, or business services	IT developer
Consulting, IT, or business services	IT hosting services
Consulting, IT, or business services	IT consulting/services - other
Consulting, IT, or business services	Scientific or technical consulting
Consulting, IT, or business services	Management consulting and coaching
Consulting, IT, or business services	Employment placement and recruitment services
Consulting, IT, or business services	Cleaning, repair and maintenance services
Consulting, IT, or business services	Financial (inc. tax, accounting, audit)
Consulting, IT, or business services	Lawyer / Legal services
Consulting, IT, or business services	Translation or language services
Consulting, IT, or business services	Company establishment/formation services
Consulting, IT, or business services	Freelance platform
Consulting, IT, or business services	Other consulting
Design, marketing or communication	Advertising and marketing
Design, marketing or communication	Designer
Design, marketing or communication	Interior design
Design, marketing or communication	Audio and video
Design, marketing or communication	Photography
Design, marketing or communication	Print and online media
Design, marketing or communication	Translation or language services
Design, marketing or communication	Telecommunications services
Travel, accommodation, or transport	Travel agent
Travel, accommodation, or transport	Tour operator
Travel, accommodation, or transport	Accommodation or hotelier
Travel, accommodation, or transport	Other travel or tour activities
Travel, accommodation, or transport	Passenger transport or rentals
Travel, accommodation, or transport	Freight transport
Travel, accommodation, or transport	Rideshare and transport share services
Travel, accommodation, or transport	Transport - other
Entertainment, arts or photography	Audio and video engineer
Entertainment, arts or photography	Events and entertainment organiser
Entertainment, arts or photography	Photographer
Entertainment, arts or photography	Books, magazines, blogs, news
Entertainment, arts or photography	Video gaming
Entertainment, arts or photography	Performing arts
Entertainment, arts or photography	Gambling, betting, and lotteries
Entertainment, arts or photography	Telecommunications services
Entertainment, arts or photography	Adult Entertainment
Health, sports or personal care	Beautician
Health, sports or personal care	Vitamins and dietary supplements
Health, sports or personal care	Fitness or sports services
Health, sports or personal care	Medical or veterinary services
Health, sports or personal care	Dental services
Health, sports or personal care	Medical equipment
Health, sports or personal care	Elderly or other care home
Health, sports or personal care	Nursing or other care services
Health, sports or personal care	Pharmaceuticals
Health, sports or personal care	Pharmacy
Food, beverages, or tobacco	Food manufacturing and retail
Food, beverages, or tobacco	Restaurants and catering
Food, beverages, or tobacco	Vitamins and dietary supplements
Food, beverages, or tobacco	Alcohol
Food, beverages, or tobacco	Soft drinks
Food, beverages, or tobacco	Tobacco
Retail, eCommerce, wholesale or manufacturing	Clothing and accessories
Retail, eCommerce, wholesale or manufacturing	Beauty products and services
Retail, eCommerce, wholesale or manufacturing	Home and garden
Retail, eCommerce, wholesale or manufacturing	Toys, games and musical instruments
Retail, eCommerce, wholesale or manufacturing	Electronics and electrical products
Retail, eCommerce, wholesale or manufacturing	Sports equipment (excl. weapons)
Retail, eCommerce, wholesale or manufacturing	Manufacturing
Retail, eCommerce, wholesale or manufacturing	Farming, seeds, plants
Retail, eCommerce, wholesale or manufacturing	Pets or pet supplies
Dealers & Resellers	Vehicle sales
Dealers & Resellers	Vehicle accessories, spare parts, manufacturing
Dealers & Resellers	Machinery and equipment
Dealers & Resellers	Firearms, weapons, and military goods/services
Dealers & Resellers	Arts - fine art sales, auctions or procurement
Dealers & Resellers	Arts - other arts and crafts products or services
Dealers & Resellers	Jewellery - fine jewellery, watches
Dealers & Resellers	Jewellery - fashion jewellery
Dealers & Resellers	Precious stones, diamonds, or metals
Dealers & Resellers	Chemicals
Dealers & Resellers	Legal highs and related accessories
Dealers & Resellers	Selling products on behalf of others (incl. auction, online marketplace)
Dealers & Resellers	Other retail or wholesale (not listed above)
Financial services, products, or holding companies	Financial Adviser (inc. tax, accounting, audit)
Financial services, products, or holding companies	Investment Manager
Financial services, products, or holding companies	Money service business operator
Financial services, products, or holding companies	Professional Trader
Financial services, products, or holding companies	Insurance Manager
Financial services, products, or holding companies	Crowdfunding and peer lending
Financial services, products, or holding companies	Other financial services
Real estate or construction	Real estate sale, purchase, and management
Real estate or construction	Construction
Real estate or construction	Real estate development
Education or learning	Online learning
Education or learning	Teaching and tutoring
Education or learning	Schools and universities
Charity or not-for-profit	Any charity related activity
Public or government services	Government Official
Public or government services	Politician
Public or government services	Other, not listed above
Utility services	Utility services and providers
Utility services	Cleaning, repair and maintenance services
Utility services	Telecommunications services
Utility services	Other, not listed above
Unemployed/Retired	Unemployed/Retired
In between jobs/looking for work	In between jobs/looking for work
Fulltime student	Fulltime student

Enum:"Architect""IT developer""IT hosting services""IT consulting/services - other""Scientific or technical consulting""Management consulting and coaching""Employment placement and recruitment services""Cleaning, repair and maintenance services""Financial (inc. tax, accounting, audit)""Lawyer / Legal services"

Example:"IT developer"

sourceOfFundsstring(Source of Funds)

The source from which the customer's funds are obtained.

Compliance Requirement: Required for AML compliance to verify the origin of funds.

Common Sources:

Employment income (Salary)
Business revenue (Business Income/Profits)
Investment returns
Savings and inheritance

Enum:"Personal Savings""Salary""Business Income/Profits""Pension""Government Benefits""Income from Cryptocurrency Trading""Income from Investments (e.g. shares, bonds, investment funds)""Income from sale of real estate or other property""Income from renting/leasing""Private loan from family members/ friends/others"

Example:"Salary"

purposeOfTransactionstring(Purpose of Transaction)

The intended purpose for the cryptocurrency transaction.

Compliance Requirement: Required for AML compliance to understand transaction intent.

Note: Currently only 'investment' is supported.

Enum:"Investment""Trading""Payment for Online Purchase""Payment for Services""Gaming""Charity""Ransomware/Virus/Cyber Extortion Demands""Other"

Example:"Investment"

identityDocumentsArray of objects, [ 1 .. 10 ] items(Updated Identity Documents)

New or updated identity documents.

curl -i -X PATCH \
  https://docs.banxa.com/_mock/products/native-api/openapi/eapi/v0/identities \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "identityReference": "customer-12345",
    "email": "[email protected]",
    "mobileNumber": "+61431000002"
  }'

Responses

No content, success. The identity has been updated successfully.

Response

No content

Identity update

Request

Responses

Was this helpful?