A live transaction can fail because a BIN is unmapped, a webhook is delayed, or settlement does not reconcile. The commercial decision to connect to card acceptance infrastructure is only the starting point. This guide explains the engineering steps, likely delays, decisions required before work begins, and the failures commonly found in sandbox testing and production review.
The process is not scheme-agnostic. Connecting to Visa, Mastercard, Verve, or local African schemes has different details. Still, the architecture and step order are similar enough to make a general walkthrough useful before consulting scheme-specific documentation.
Before Requesting API Credentials
Before engineering reviews any API documentation, answer two questions.
First, which card schemes will you accept? That choice determines BIN setup, scheme membership obligations, and production clearing routes. A Nigerian bank accepting Verve cards needs Interswitch connectivity. Accepting Mastercard requires direct Mastercard membership or sub-membership through a principal member. Engineering cannot settle these questions alone. They require business and compliance approval, and starting before resolution creates rework.
Second, which currency will settle the transactions? For a domestic Nigerian bank accepting only NGN transactions, the answer is clear. A bank taking foreign cards or processing cross-border payments must define multi-currency settlement before integration. The enza API supports multi-currency settlement, with onboarding configuration determining reconciliation report output.
API Credentials and Sandbox Setup
After dashboard access is granted, you receive a sandbox API key linked to your account. The sandbox uses scheme simulators rather than live scheme connections, allowing full lifecycle testing, including declines, reversals, and dispute events, without touching live accounts.
The sandbox key is restricted to your account. After production review, the production key uses the same format and API surface. The API contract has no breaking difference between environments. Only the base URL and underlying scheme connectivity change.
Authentication uses bearer tokens. Send the API key in the Authorization header with every request. The core transaction API has no OAuth flow or session-token handling. Keys are long-lived, so keep them in secrets management, never application code or source control.
Core API Endpoints
enza's card acceptance API has four main endpoint groups:
Authorization: Use POST /v1/authorizations to submit card data, including PAN, expiry, CVV or token, amount, currency, merchant category code, and terminal ID. It returns the authorization result, with an approval code, decline reason code, and transaction ID for later operations.
Capture: The POST /v1/authorizations/{id}/capture endpoint settles an approved authorization. Most African point-of-sale transactions authorize and capture in one message. Pre-authorizations, such as hotel holds and fuel station pre-auths, authorize first, then capture the actual amount.
Reversal: Call POST /v1/authorizations/{id}/reversal to void an authorization before capture. This applies when cancelling before the cardholder leaves, or releasing a pre-authorization.
Transaction status: Call GET /v1/transactions/{id} for the current state of a transaction. Core banking systems use it after a missed webhook, and teams can use it for manual reconciliation searches.
The design stays minimal. These credentials expose no session management, dashboard-proxy, or reporting API. Reporting data is provided through dashboard reconciliation exports, not the transaction API.
Webhook Configuration
Webhooks let enza send transaction lifecycle events to your core banking system. Set the endpoint URL in the dashboard. enza sends a signed POST for each event: authorization created, captured, reversed, settled, or disputed.
Each payload carries the event type, transaction ID, current state, and applicable financial amounts. Every request has an HMAC-SHA256 signature header based on a signing key generated in the dashboard. Verify it before handling the event. An unverified endpoint can allow fraudulent transaction state changes.
Delivery is at-least-once, rather than exactly-once. The handler must be idempotent: a retry after a non-200 response must not create a second ledger transaction record. A standard pattern checks whether that transaction ID and event type were already processed before changing the ledger.
Webhook endpoints must return 200 within 10 seconds. Longer processing causes enza's delivery system to time out and retry. If synchronous database writes or downstream calls slow the endpoint, place processing on an async queue and return 200 immediately. The queue handles the event while the handler acknowledges receipt.
BIN Configuration and Scheme Routing
BIN configuration tells enza's routing engine which cards you may accept and which scheme connection serves each BIN range. It is set during onboarding and changed through a change request.
For domestic Nigerian Verve cards accepted through Interswitch, map Verve BIN ranges to the Interswitch clearing connection. For Visa, map Visa BINs to the Visa clearing connection. If both are accepted, both configurations must be active before go-live.
Integration tests often use a card from an unconfigured BIN range. Its authorization fails with an error code for an unconfigured BIN, not a scheme decline. When sandbox authorizations fail unexpectedly, inspect BIN configuration before treating the issue as code.
Testing in Sandbox
Sandbox scheme simulators return defined outcomes for defined test card numbers. enza documentation provides a test card matrix covering approvals, hard declines such as stolen card and do not honor, soft declines such as insufficient funds and try again, reversals, and disputes.
Validate these test scenarios before requesting production review:
- Successful authorization and capture for each currency you intend to accept
- Hard decline handling: your system correctly records the decline without creating a debit in the cardholder's account
- Soft decline handling: your system presents a retry option where appropriate
- Reversal: authorization created then reversed before capture, confirmed the original authorization does not appear in settlement
- Webhook handling: your endpoint processes all event types correctly, including duplicate delivery
- Timeout handling: your client handles authorization endpoint timeouts with idempotent retry
- Reconciliation: your core banking system's end-of-day balances match the enza sandbox settlement report for the test transactions you ran
Reconciliation is the test teams skip most often and the source most often linked to first-week production problems. Run it in sandbox before production review, never after.
Production Review and Go-Live
Production review examines the integration for technical and compliance readiness. Submit through the dashboard. Reviewers verify webhook signature validation, check BIN configuration completeness, and confirm that required sandbox scenarios were tested.
For banks with existing scheme memberships, review confirms that enza's scheme connectivity matches the scheme agreements. Banks using enza's principal membership arrangements for particular schemes also need scheme onboarding. It usually runs alongside technical integration, not at the end.
Once production review approves the integration, the account moves to production and a production API key is issued. Monitor the first live transactions in the dashboard. On go-live day, keep the core banking reconciliation team ready to confirm settlement reports match the ledger before end-of-day.
Ongoing Operations
Card acceptance infrastructure requires continuing integration work. Scheme rule changes can alter BIN configuration and transaction data requirements. Regulatory reporting changes, while fraud thresholds need tuning as transaction patterns develop.
A non-responsive webhook endpoint builds a delivery queue backlog. When a new card product adds a BIN range, add it to acceptance configuration before issuing cards. Test any core banking change that affects webhook idempotency before deployment.
Treating card acceptance integration as an ongoing operational duty, rather than a finished project, separates banks with stable processing from those facing recurring transaction integrity problems. The technical integration is the base, not the endpoint.