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.
Virtual account eligibility
Virtual accounts require additional approval from BVNK's compliance team. To qualify, your business must:
- Be a fully licensed financial services provider (for example, UK FCA license, Canadian MSB).
- Demonstrate a robust financial crime control framework including AML policies, risk management, and transaction monitoring.
- Complete compliance checks with documentation review and interviews.
Contact your Account Manager to initiate the virtual account approval process. After approval, BVNK's commercial team configures your VA product and maps your parameters to the appropriate banking partner.
Fiat wallet setup
Virtual accounts connect to fiat wallets, which store your funds. Request wallet activation from your Account Manager—fiat wallets require verification before use.
Specify the currency (EUR, USD, GBP) and payment method based on your use case:
- EUR: SEPA payments for EEA transactions
- USD: ACH, FedWire, or SWIFT for US and international payments
- GBP: Faster Payments for UK domestic transactions
Each wallet receives a virtual account with a unique vIBAN. Named accounts are issued in your business name or your customers' names for personalized payment routing.
After you have created the wallet, find its ID in the Wallet section on the Portal. You will later need it for creating payments.
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 initiating fiat payouts.