# Integration Overview

Banxa Native is an API- and SDK-driven integration model for partners building deeply integrated fiat ↔ crypto experiences inside their own mobile app. The partner orchestrates identity, eligibility, and transactions via the Native API, and uses the Banxa SDK for card, Apple Pay, and Google Pay payment execution.

## Who it's for

Banxa Native is best suited to mobile apps with user accounts and engineering capability — exchanges, custodial wallets, fintech apps, and any partner that wants full control over the user journey at the point of transaction.

### Prerequisites

- **You verify user identity (KYC)** — directly, or through a provider like Sumsub. The Native API is designed around partners who manage their own user verification.
- **You have a backend** — required for HMAC server-to-server authentication.
- **You have a persistent, unique identifier for each user** — the `identityReference`, stable across transactions.
- **A mobile app, for now** — the native payment experience for cards, Apple Pay, and Google Pay currently depends on the Banxa React Native SDK. Bank transfers work on web today via the Native API, and a JS SDK bringing card and wallet support to web is in active development. If you're a web-first partner, reach out to your Banxa contact to discuss timing.


### If you're not a fit

If you don't do KYC, don't have a backend, or are building a web-only experience, Banxa Native may not be the right product for you today. Reach out to your Banxa contact to discuss alternative integration models — there are separate offerings designed for partners without compliance infrastructure or without a persistent user account model.

## How it works

Banxa Native separates transaction orchestration from payment execution.

**Transaction orchestration** — pricing, identity, eligibility, and ramp creation — is handled through the Native API. Your backend makes authenticated server-to-server calls.

**Payment execution** depends on the selected payment method:

- **Bank transfers** are completed through the Native API. Banxa returns funding instructions for you to display to the user.
- **Cards, Apple Pay, and Google Pay** are handled by the Banxa React Native SDK, which presents a native payment sheet inside your app.
- **Some alternative payment methods** (iDEAL, Klarna, PayPal) cannot be completed in a webview and require redirecting the user outside the app. There is no automatic return.


Card payments, Apple Pay, and Google Pay are handled through the SDK rather than the API directly because processing card data via the API would require PCI compliance — a significant certification burden. The SDK integrates with Primer to handle card data in a PCI-certified environment, so partners do not need to achieve PCI compliance themselves.

## Integration stages

A typical Banxa Native integration moves through five stages. The [Integration Guide](/products/native-api/docs/integration-guide) walks through each stage with concrete API calls and SDK examples.

### 1. Pricing

Retrieve a real-time quote before initiating a transaction. Quotes are indicative and should be refreshed before the user commits.

### 2. Identity

Every transaction is tied to a persistent `identityReference`. Establish the identity record with Banxa via basic identity creation, token sharing, reliance, or document submission — depending on how you verify users.

### 3. Eligibility

Eligibility evaluates whether a specific transaction can proceed. It considers the identity state, the payment method, the transaction parameters, and regulatory context, and returns either `paymentReady: true` or a list of outstanding requirements. Act on the response before creating a ramp.

### 4. Ramp creation and payment execution

Once the transaction is cleared, the ramp is created:

- **Bank transfers:** Created through the Native API. Banxa returns funding instructions for you to display to the user.
- **Cards, Apple Pay, Google Pay:** The Banxa SDK creates the order and presents the native payment sheet.


### 5. Status updates

Transactions are asynchronous. You can track state through:

- **Webhooks** — server-to-server notifications as the order progresses through its lifecycle. Primary mechanism for reconciliation.
- **SDK callbacks** — `onCheckoutComplete` and similar, firing when the user completes or abandons the native payment flow.
- **Polling** — `GET /ramps/{id}` for direct state checks.


## Next steps

- [Integration Guide](/products/native-api/docs/integration-guide) — full walkthrough with API calls and SDK examples.
- [Supported Payment Methods](/products/native-api/docs/how-it-works/supported-psp) — payment methods available in Banxa Native.
- [React Native SDK Reference](/products/native-api/docs/sdk/sdk-reference) — SDK configuration and methods.