# Integration Overview

## Banxa Native API (API-driven)

The Banxa Native API is designed for platforms requiring full control of onboarding, authentication, and user experience.

Banxa operates as the regulated payments, compliance, and settlement layer behind the scenes, while your platform manages user-facing flows and session control.

> **Note:** Banxa also offers a hosted Widget integration for platforms preferring a managed front-end experience.


## Native API Integration Flow

A typical integration follows five stages:

1. Identity
2. Eligibility & Limits
3. Pricing
4. Ramp Creation
5. Settlement & Status Updates


## 1. Identity

Each user must be associated with a persistent `identityReference`.

Depending on your integration model, identity requirements can be satisfied using:

- Basic identity creation (low-tier use cases)
- Identity reliance (partner-managed KYC)
- KYC provider token sharing (e.g. Sumsub)
- Document submission (Banxa-managed verification)


Identity records persist and may be updated as transaction requirements evolve.

## 2. Eligibility & Limits

Before creating a transaction, your platform should:

- Check transaction eligibility
- Retrieve applicable transaction limits


Eligibility evaluates whether the user is permitted to transact based on identity state, payment method, jurisdiction, and transaction parameters.

Limits reflect provider constraints and customer-tier thresholds across daily, weekly, monthly, and annual windows.

This step reduces failed transactions caused by compliance or limit restrictions.

## 3. Pricing

Retrieve real-time pricing prior to transaction creation:

- Call `GET /price`
- Display source amount, target amount, and fee breakdown to the user


Prices are not binding and may change due to market conditions. Quotes should not be cached beyond short durations.

## 4. Ramp Creation

Once confirmed:

- Call `POST /ramps`
- Provide identity reference and transaction details
- Receive `ramp_id`, initial status, and funding instructions (if applicable)


Payment execution model depends on the selected method:

- Bank transfers: fully API-driven
- Cards / Apple Pay / Google Pay: SDK-based payment execution
- Selected alternative payment methods: controlled webview or redirect fallback


## 5. Settlement & Status Updates

Ramps are asynchronous.

Banxa communicates transaction progress via:

- Webhooks (`rampMessage`)
- Optional polling (`GET /ramps/{id}`)


Status updates reflect payment processing, verification requirements, asset transfer, and final outcome.