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.
A Native integration requires your platform to explicitly orchestrate five stages:
- Identity
- Eligibility & Limits
- Pricing
- Ramp Creation
- Status Updates
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.
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.
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.
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
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.