# Banxa Native API

Official Banxa Enterprise API Specs

Version: 0 BETA
License: MIT

## Servers

Production environment server
```
https://api.banxa.com
```

Sandbox environment server
```
https://api.banxa-sandbox.com
```

## Security

### HMACAuth

HMAC authentication using SHA256.
The URI must be used to generate the hmac signature e.g. `/eapi/v0/ramps` example:    
"POST    
/eapi/v0/ramps   
1741220905019999   
{\"subPartnerId\":null,\"identityReference\":\"926553-1732538-7235638-6352926\",\"source\":{\"crypto\":{\"id\":\"USDT\",\"blockchain\":\"ETH\",\"walletAddress\":\"0xc292474673cf1a96a96e8c56ec4f45ecf2e0b448\",\"walletAddressMemo\":null},\"amount\":\"100\"},\"target\":{\"fiat\":{\"id\":\"AUD\",\"method\":\"payid-bank-transfer\",\"instructions\":{\"accountName\":\"Foo Bar\",\"accountNumber\":\"12345678\",\"bsb\":\"063123\"}}}}"


Type: apiKey
In: header
Name: Authorization

## Download OpenAPI description

[Banxa Native API](https://docs.banxa.com/_bundle/products/native-api/@v0-beta/openapi.yaml)

## Ramps (Transactions)

**Ramp Transactions** - Create and manage cryptocurrency on-ramp (fiat → crypto) and off-ramp (crypto → fiat) transactions.

**Key Operations**:
- Create on-ramp transactions (buy cryptocurrency)
- Create off-ramp transactions (sell cryptocurrency)
- Retrieve transaction status and details
- Monitor transaction lifecycle via webhooks

**Transaction Flow**:
1. Check eligibility and limits
2. Get price quote
3. Create ramp transaction
4. Customer completes payment/deposit
5. Receive status updates via webhooks
6. Transaction completes

**Supported Payment Methods**: PayID (AU), SEPA (EU), ACH (US), Interac (CA)

**Supported Blockchains**: Bitcoin, Ethereum, TRON, Polygon, BSC

### Ramps List

 - [GET /eapi/v0/ramps](https://docs.banxa.com/products/native-api/openapi/ramps/listramps.md): Retrieve a paginated list of transfer orders (ramps).

Pagination Modes:
- Cursor Pagination: Use startAfter, endBefore, or cursor parameters. Dates are optional.
- Offset Pagination: Use page parameter. Dates (dateFrom and dateTo) are required.

Important: Cannot mix pagination types. Choose either cursor-based or offset-based pagination.

Use Cases:
- Retrieve transaction history for reporting
- Sync transactions to your system
- Display transaction list to customers
- Export transaction data

### Ramps enable Fiat to Crypto and Crypto to fiat on and off ramp.

 - [POST /eapi/v0/ramps](https://docs.banxa.com/products/native-api/openapi/ramps/createramp.md): Enables conversion between fiat and cryptocurrency in both directions.

### Ramp retrieval

 - [GET /eapi/v0/ramps/{ramp_id}](https://docs.banxa.com/products/native-api/openapi/ramps/getramp.md): Enables retrieval of detailed information about a specific order using its unique identifier.

### Inbound message regarding the ramp status

 - [POST rampMessage](https://docs.banxa.com/products/native-api/openapi/ramps/rampmessage.md): When a ramp transitions into a new status, the status update will be sent to the provided callback endpoint to your server.

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

### Identity token sharing (sumsub)

 - [POST /eapi/v0/identities/share/token](https://docs.banxa.com/products/native-api/openapi/identities/shareidentity.md): Share customer identity

### Identity Reliance

 - [POST /eapi/v0/identities/reliance](https://docs.banxa.com/products/native-api/openapi/identities/identityreliance.md): Share customer identity

### Identity Retrieval

 - [GET /eapi/v0/identities/{identity_reference}](https://docs.banxa.com/products/native-api/openapi/identities/getidentity.md): Enables retrieval of detailed information about a specific identity using the unique identityReference.

### Identity create

 - [POST /eapi/v0/identities/basic](https://docs.banxa.com/products/native-api/openapi/identities/createidentity.md): Low level identity onboarding

### Identity Document sharing

 - [POST /eapi/v0/identities/share/documents](https://docs.banxa.com/products/native-api/openapi/identities/shareidentitydocuments.md): Share identity documents for KYC verification.

Use Case: Submit customer identity documents directly to Banxa for verification.

Process:
1. Collect customer information and documents
2. Submit via this endpoint
3. Receive 202 Accepted response
4. Wait for webhook notification with verification result

Required Documents:
- At least one government-issued photo ID
- Proof of address (if required)
- Selfie for liveness verification

Document Quality:
- Clear, high-resolution images
- All text readable
- No glare or shadows
- Maximum 10MB per image

### Identity update

 - [PATCH /eapi/v0/identities](https://docs.banxa.com/products/native-api/openapi/identities/patchidentity.md): 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

### Inbound message regarding customer Identity related messages

 - [POST identityMessage](https://docs.banxa.com/products/native-api/openapi/identities/identitymessage.md): When a customer failed to create an order for a specific reason, the status update will be sent to the provided callback endpoint to your server.

## Quote

**Quotes** - Get a locked price quote with a unique `quoteId` and a 3-minute TTL.

**Key Features**:
- Returns a `quoteId` that can be used to create a ramp transaction
- Quote is valid for 3 minutes (`expiresAt`)
- Includes all fees (processing + network)
- Lock fiat OR crypto amount

**Flow**:
1. Request a quote via `GET /eapi/v0/quote`
2. Display the quote to the customer
3. Use the `quoteId` in the ramp creation payload before it expires

**Important Notes**:
- Prices are subject to market volatility and network congestion
- Once expired, a new quote must be requested
- The `quoteId` can only be used once

### Quote request

 - [GET /eapi/v0/quote](https://docs.banxa.com/products/native-api/openapi/quote/getquote.md): Request a quote with a locked price and a unique quoteId. The quote is valid for 3 minutes (expiresAt). Unique identifier for this quote. Use this when creating a ramp transaction via the Ramps Request payload to lock the quote in.

Prices are subject to change based on market volatility and network congestion. Once expired, a new quote must be requested.

## Price (Indicative)

**Indicative Pricing** - Get real-time, non-persisted price estimates for cryptocurrency transactions.

The price endpoint returns an **indicative** price that is not stored or locked. It carries no `quoteId` and cannot be referenced when creating a ramp transaction. For a locked quote that can be used to create a ramp, use the `GET /eapi/v0/quote` endpoint.

**Key Features**:
- Real-time market rates
- Includes all fees (processing + network)
- Lock fiat OR crypto amount

**Important Notes**:
- Prices are indicative and not persisted
- Prices fluctuate with market conditions
- Don't cache prices for more than 1 minute
- Use the Quote endpoint to obtain a locked, referenceable quote

**Use Cases**:
- Display indicative price to customer
- Transaction previews and fee breakdowns
- UI price tickers and estimates

### Indicative price request

 - [GET /eapi/v0/price](https://docs.banxa.com/products/native-api/openapi/price/getprice.md): Request an indicative, non-persisted price. The returned price is a point-in-time estimate and is not stored or locked — it carries no quoteId and cannot be referenced later.

Use this endpoint for display purposes, transaction previews, or fee breakdowns. For a locked price that can be used to create a ramp transaction, use the GET /eapi/v0/quote endpoint instead.

Prices are subject to change based on market volatility and network congestion.

## Eligibility (Pre-checks)

**Transaction Eligibility** - Pre-check if a customer can perform a transaction.

**Purpose**: Determine if customer meets requirements before attempting transaction.

**Returns**:
- `paymentReady`: Boolean indicating if customer can transact immediately
- `requirements`: Array of outstanding KYC/compliance requirements

**Possible Requirements**:
- `US_TAX_ID`: US tax identification needed
- `PERSONAL_DETAILS`: Name, DOB, address required
- `DOCUMENT`: Government ID needed
- `SELFIE`: Liveness check required
- `SOURCE_FUNDS`: Source of funds declaration needed
- `OCCUPATION`: Occupation information required
- `PURPOSE_OF_TX`: Transaction purpose needed

**Best Practice**: Check eligibility before showing price quotes to avoid failed transactions.

### Identity transaction eligibility

 - [POST /eapi/v0/identities/transactions/eligibility](https://docs.banxa.com/products/native-api/openapi/eligibility/identities/transactions.md): Request transaction eligibility for a specific identity

## Limits (Transaction Limits)

**Transaction Limits** - Check applicable transaction limits for customers.

**Limit Types**:
- **Transaction Limits**: Minimum and maximum per transaction
- **Daily Limits**: 24-hour rolling window
- **Weekly Limits**: 7-day rolling window
- **Monthly Limits**: 30-day rolling window
- **Annual Limits**: 365-day rolling window

**Limit Sources**:
- **Provider Limits**: Payment method/route specific limits
- **Customer Limits**: User tier-based limits and overrides

**Effective Limit**: The most restrictive limit applies (minimum of provider and customer limits).

**Use Cases**:
- Display available transaction amounts to customer
- Validate transaction amount before submission
- Show customer their current tier limits
- Explain why a transaction amount is not allowed

### Transaction Limits

 - [POST /eapi/v0/identities/transactions/limits](https://docs.banxa.com/products/native-api/openapi/limits/postidentitytransactionlimits.md): Returns applicable transaction limits for a given identity and transaction context.

Limits are derived from:
- payment-provider limits (route/method specific), and
- customer-specific limits (tier-based and/or overrides)

The response returns:
- limits for DAILY/WEEKLY/MONTHLY/ANNUAL windows,
  including provider vs customer sources

## Verifications (OTP)

**OTP Verification** - Email verification using one-time password (OTP) codes.

**Key Operations**:
- Request OTP code to be sent to customer's email
- Verify OTP code to confirm email ownership

**Flow**:
1. Request OTP via `POST /eapi/v0/verifications/otp`
2. Customer receives OTP code via email
3. Verify OTP via `POST /eapi/v0/verifications/otp/verify`

**Rate Limits**:
- OTP requests: 3 per minute per customer
- OTP verification attempts: 4 per minute per customer

**Important Notes**:
- OTP codes are single-use and expire after a set time
- Email must be verified for certain compliance requirements
- Feature must be enabled for your merchant account

### Request OTP Code

 - [POST /eapi/v0/verifications/otp](https://docs.banxa.com/products/native-api/openapi/verifications/requestotp.md): Sends a one-time password (OTP) code to the customer's email address for verification. The OTP code is valid for a limited time and can only be used once. Rate limited to 3 requests per minute per customer.

### Verify OTP Code

 - [POST /eapi/v0/verifications/otp/verify](https://docs.banxa.com/products/native-api/openapi/verifications/verifyotp.md): Verifies the OTP code sent to the customer's email address. Upon successful verification, the customer's email is marked as verified. OTP codes are single-use and expire after a set time period. Rate limited to 4 verification attempts per minute per customer.

## Configuration

**Configuration Endpoints** - Retrieve supported payment methods, fiat currencies, countries, crypto currencies, and other configuration data required to build onboarding and transaction flows.

**Key Operations**:
- List supported fiat currencies for on-ramp and off-ramp transactions
- Retrieve available payment methods for a given transaction direction
- Get supported countries and any required states or provinces
- List supported crypto currencies for transaction setup
- Use configuration data to pre-fill forms before pricing or ramp creation

**Use Cases**:
- Populate dropdowns and selectors in your UI
- Filter valid options based on customer choices
- Validate transaction parameters before submission
- Display supported onboarding and payout options

### Payment Methods

 - [GET /eapi/v0/payment-methods/{transactionType}](https://docs.banxa.com/products/native-api/openapi/configuration/listpaymentmethods.md): Retrieve supported payment methods for the specified transaction type as part of the configuration data required to build onboarding and transaction flows.

Use Cases:
- Populate payment method selectors for on-ramp and off-ramp journeys
- Determine which fiat currencies are available for each payment method
- Pre-configure transaction forms before requesting quotes or creating ramps
- Show only valid payment options for the customer's selected transaction direction

Transaction Types:
- onramp - Payment methods available for buying cryptocurrency with fiat
- offramp - Payment methods available for selling cryptocurrency to fiat

Response Structure:
Each payment method includes:
- method: Unique code used in API requests
- name: Human-readable payment method name
- supportedFiats: Fiat currencies supported by that payment method

### Cryptocurrencies

 - [GET /eapi/v0/cryptocurrencies/{transactionType}](https://docs.banxa.com/products/native-api/openapi/configuration/listcryptocurrencies.md): Retrieve supported cryptocurrencies for the specified transaction type as part of the configuration data required to build onboarding and transaction flows.

Use Cases:
- Display available cryptocurrency options to customers
- Show supported blockchains for each cryptocurrency
- Pre-configure asset and network selectors before pricing or ramp creation
- Filter cryptocurrencies by transaction direction

Transaction Types:
- onramp - Cryptocurrencies available for buying (fiat → crypto)
- offramp - Cryptocurrencies available for selling (crypto → fiat)

Response Structure: Each cryptocurrency includes:
- crypto: Unique coin code (e.g., BTC, ETH, USDT)
- name: Human-readable display name
- blockchains: Array of supported blockchain networks, each with contract address, minimum amount, default flag, and restricted countries

### Supported Fiats

 - [GET /eapi/v0/fiats/{transactionType}](https://docs.banxa.com/products/native-api/openapi/configuration/listfiats.md): Retrieve a list of supported fiat currencies for the specified transaction type (onramp or offramp).

Use Cases:
- Display available fiat currencies to customers during onboarding
- Filter payment methods by fiat currency
- Show fiat options in transaction creation UI
- Validate customer-selected fiat before transaction

Transaction Types:
- onramp - Returns fiat currencies supported for buying cryptocurrency
- offramp - Returns fiat currencies supported for selling cryptocurrency

Response Structure: Each fiat currency includes:
- fiat - Three-letter ISO 4217 currency code (e.g., "AUD", "USD")
- name - Human-readable currency name (e.g., "Australian Dollar")
- symbol - Currency symbol (e.g., "$", "€")
- supportedPaymentMethods - Array of payment methods available for this fiat

### Supported Countries

 - [GET /eapi/v0/countries](https://docs.banxa.com/products/native-api/openapi/configuration/listcountries.md): Retrieve supported countries for KYC and transaction flows as part of the configuration data required to build onboarding and transaction flows.

Use Cases:
- Populate country dropdowns during customer onboarding
- Determine which countries are enabled for your merchant configuration
- Retrieve state or province options for countries that require region selection
- Filter valid options based on customer location

Response Structure: Each country includes:
- id: Two-letter ISO country code
- description: Human-readable country name
- states: List of supported states or provinces for that country, if applicable