Prepare for integration
This guide outlines the prerequisites for integrating BVNK's Cards capabilities into your platform. Cards use the Embedded Custom delivery model — your platform owns the full customer-facing experience while BVNK handles card issuance, transaction authorisation, and PCI-scoped operations.
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.
Steps to complete this phase:
Customer onboarding
Cards require the Embedded Custom delivery model. Before your customers can be issued a card, 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.
Steps to complete this phase:
USDC wallet setup
Each card is linked to a customer's USDC wallet. Before issuing a card, ensure the customer has a USDC wallet created.
The wallet serves as the funding source for all card transactions — BVNK debits the wallet balance when authorising card spend and credits it for refunds or chargebacks.
After you have created the wallet, find its ID in the Wallet section on the Portal. You will need the wallet ID when issuing a card.
See Create a wallet for setup instructions.
Customer data requirements
Cards require the following customer data to be on file before a card can be issued:
| Requirement | Notes |
|---|---|
| Phone number | Must be verified by your platform |
| Email address | Must be verified by your platform |
| KYC approved | Customer must be fully onboarded and verified by BVNK |
| Supported jurisdiction | Customer must be in a jurisdiction that supports cards |
| BVNK entity | Customer must be signed to a BVNK entity that can issue cards |
BVNK does not independently validate the customer's contact information — your platform is trusted to have verified phone number and email.
PCI compliance
As a partner integrating Cards, you are required to be PCI-compliant but do not need PCI certification.
Sensitive card data (PAN, CVV, expiry) is displayed via the BVNK front-end SDK inside a PCI-scoped iFrame. Your application never receives or stores cardholder data. You must confirm that you operate in a PCI-compliant manner.
Webhook integration
Webhooks provide real-time notifications when card and transaction states change, eliminating the need for continuous polling.
Your webhook endpoint receives HTTP POST requests from BVNK whenever relevant events occur — card status changes, transaction authorisations, settlements, declines, 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.
Steps to complete this phase:
- Configure webhooks for endpoint setup and signature verification examples.
Integration testing
Use the sandbox environment to validate your Cards implementation before going live. Test the full lifecycle:
- Customer onboarding and eligibility checks
- Card issuance and activation
- Viewing card details via the SDK
- Transaction authorisation, settlement, and decline scenarios
- Card controls (freeze, unfreeze, cancel)
- Webhook delivery for all card and transaction events
Cards-specific testing flows and simulators are coming soon — contact your account manager for early access.
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 customer onboarding is complete and confirm all webhook subscriptions are active.
What's next?
Once you have completed all prerequisites above, you can proceed with implementing Cards.