Prepare for integration
This guide outlines the phases required to integrate BVNK's stablecoin payment capabilities into your platform. The scope of each phase depends on your delivery model—Direct integrations require fewer steps, while Embedded integrations include additional customer onboarding and compliance workflows.
Sandbox account and API credentials
The sandbox environment mirrors production but operates with test data, allowing you to build and validate your integration without financial risk.
Your sandbox account provides access to the BVNK Portal where you manage wallets, configure integrations, and monitor transactions. API credentials use Hawk authentication, a cryptographic scheme that signs each request without exposing your secret key.
When configuring API keys, consider which operations your integration requires. Payouts and withdrawals require IP address whitelisting for security. Read-only operations like fetching transaction data have fewer restrictions.
See Create a sandbox account and Create API keys for setup instructions.
Customer onboarding (Embedded model)
This phase applies only to the Embedded model. Skip to Wallet setup if you are using the Direct model.
The Embedded model allows your platform to offer stablecoin payment capabilities to your customers. Before your customers can transact, they must complete BVNK's compliance onboarding process.
As a partner, you act as the integration layer between your customers and BVNK. You collect customer information through your own onboarding flows, submit it to BVNK via API, and track onboarding status through webhooks or polling. BVNK handles compliance reviews and activates customer accounts once approved.
See Create an embedded customer and Onboard customers for implementation details.
Fiat wallet setup
On-ramp conversions require a fiat wallet to receive incoming payments before converting to stablecoins. Request fiat wallet activation from your Account Manager—fiat wallets require verification before use.
Specify the currency (EUR, USD, GBP) and payment method (SEPA, SWIFT, ACH, Faster Payments) based on your customers' geography and preferences. Each wallet receives a virtual account with banking details your customers use for deposits.
After you have created the wallet, find its ID in the Wallet section on the Portal. You will later need it for creating payments.
Customer fee wallet (optional)
If you plan to charge markup fees on your customers' transactions, designate a wallet to receive these fees. Customer fees are optional charges separate from transaction amounts and BVNK fees—they let you collect additional revenue from your customers. The fee wallet currency must match the currency of the fees you charge.
See Charge customer fees for implementation details.
Webhook integration
Webhooks provide real-time notifications when transaction states change, eliminating the need for continuous polling.
Your webhook endpoint receives HTTP POST requests from BVNK whenever relevant events occur—payment confirmations, status changes, customer onboarding updates, and more. Design your endpoint to acknowledge receipt immediately (return HTTP 200) and process the event asynchronously to avoid timeouts.
Webhook payloads include cryptographic signatures for authenticity verification. Implement signature validation to ensure requests originate from BVNK and haven't been tampered with.
See Configure webhooks for endpoint setup and signature verification examples.
Integration testing
Use the sandbox environment to validate your implementation before going live. Test both success paths and error scenarios to ensure your system handles edge cases gracefully.
For pay-ins, create payment channels and simulate incoming transactions to verify your webhook handling and balance updates. For payouts, send test transactions to destination wallets and confirm delivery. If using the Embedded model, test the full customer onboarding lifecycle.
Optional external wallets like MetaMask (Ethereum) or TronLink (Tron) can simulate end-user interactions during testing.
Go live
Production activation requires coordination with your Account Manager. Sandbox configuration does not transfer automatically—you must replicate settings in your live account.
Update your codebase to use production credentials and endpoints. The base URL changes from https://api.sandbox.bvnk.com/ to https://api.bvnk.com/. Generate new API keys in your live Portal account and configure webhooks with production endpoint URLs.
Before processing real transactions, verify your live wallets have sufficient balance for payouts and confirm all webhook subscriptions are active.
What's next?
Once you have completed all prerequisites above, you can proceed with automating on-ramp payments.