# 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 Native integration requires your platform to explicitly orchestrate five stages:

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


## 1. Identity

Each user must be associated with a persistent `identityReference`. Identity must be reused across transactions. Multiple identities per user can lead to:

- duplicated KYC
- inconsistent limits
- degraded conversion


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. Status Updates

Ramps are asynchronous.

Native integrations must consume webhooks to remain in sync with transaction and compliance state. Polling is provided as a fallback and for reconciliation only.

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


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