Acquirer connectors, carrying card authorisation, capture, refund and settlement reporting.
Payment Connector: Link Providers to One Platform
One integration. Every provider behind it.
A payment connector is the adapter that translates your platform's single payment API into whatever dialect an acquirer, PSP or local method actually speaks. Written once, maintained forever, and the reason adding the next provider is configuration rather than a project.
What Is a Payment Connector?
It sits between a unified payment layer and one external provider, and it owns every difference between them. Four responsibilities, and a connector that skips any of them leaks that provider's quirks into your product code.
Responsibility
Request mapping
Response mapping
Capability declaration
Credential handling
What the connector does
Turns one normalised payment request into the provider's format.
Maps statuses and reason codes back into your single taxonomy.
Declares what this provider supports, and what it does not.
Holds keys and signing rules per merchant and per environment.
What breaks without it
Provider-specific fields spread through your own codebase.
Routing rules need a translation table per partner.
Traffic is sent to a route that cannot fulfil it.
Secrets end up in application config nobody rotates.
Request mapping
Connector does
Turns one normalised payment request into the provider's format.
Without it
Provider-specific fields spread through your own codebase.
Response mapping
Connector does
Maps statuses and reason codes back into your single taxonomy.
Without it
Routing rules need a translation table per partner.
Capability declaration
Connector does
Declares what this provider supports, and what it does not.
Without it
Traffic is sent to a route that cannot fulfil it.
Credential handling
Connector does
Holds keys and signing rules per merchant and per environment.
Without it
Secrets end up in application config nobody rotates.
Where the connector sits in a full stack is described on payment gateway infrastructure.
Why Payment Teams Use Connectors
The alternative is a direct integration per provider, which is five builds and five maintenance commitments. Connectors collapse that into one interface plus a list. Five reasons teams make the switch, usually at the third provider.
- One integration for your platform, regardless of how many providers sit behind it.
- One data model, so risk rules and reporting do not need a dialect per partner.
- Provider switching becomes a configuration change rather than a release.
- Maintenance is centralised, so an API version bump is one change, not five.
- New markets arrive as a connector plus settings instead of a quarter of work.
The economics are simple: the first integration costs the same either way, and every one after that is where a connector layer pays for itself.
Types of Payment Connectors
Six families, and they behave differently enough that a platform should not pretend they are one thing.
PSP connectors, which resell acquiring and often add their own risk layer on top.
Alternative method connectors for wallets, instant bank rails, vouchers and open banking.
Payout connectors, which have their own limits, cut-offs and approval lifecycle.
Value-added connectors for fraud scoring, KYC and KYB checks called mid-flow.
Data connectors that pull settlement and dispute files for automated reconciliation.
An operator-facing view of the same layer sits on igaming payments platform.
Normalized Payment API and Data Mapping
Normalisation is the whole value of a connector layer. Three mappings decide whether it holds.
One shape for amount, currency, instrument, customer reference and metadata, with provider-specific extras carried in a namespaced block rather than promoted into the core object. Once a field leaks into the shared model to satisfy one partner, every other connector has to answer for it.
A finite set of states with defined transitions, plus a decline taxonomy that every provider code maps into. This is what lets a routing rule read soft decline once instead of learning forty vendor codes, and it is the piece most homegrown integrations skip until it hurts.
A machine-readable declaration of what each connector supports: partial capture, refund windows, tokenisation, external authentication, payouts. Routing consults it before it selects, so no payment is ever sent to a provider that structurally cannot complete it.
Credentials, Authentication and Configuration
Every connector needs credentials, and every provider issues them differently: API keys, signed requests, mutual TLS, rotating tokens. A connector layer holds all of it per merchant and per environment, so a sandbox key can never reach production traffic.
Configuration sits alongside the credentials: which merchant accounts this connector may use, which currencies it is enabled for, which limits apply. All of it belongs in the platform rather than in a deployment file.
The conclusion worth acting on
Credentials are per merchant, not per platform. A connector layer that holds one set of keys for everyone cannot support a portfolio, cannot rotate a single merchant's secret after an incident, and cannot let a merchant bring its own acquirer relationship. Get this wrong and the whole layer has to be rebuilt at the first PSP client.
Transaction Operations and Capability Mapping
1
Authorize
The connector maps the request, signs it, sends it and returns a normalised result with the raw provider payload attached for support.
2
Capture
Some providers capture automatically, some support partial capture and some do neither. The capability map says which, before routing chooses.
3
Refund and void
Refund windows, partial support and the difference between a void and a refund vary widely, and the connector normalises the semantics rather than the wording.
4
Tokenize
Where the provider supports external tokens, the connector passes them through; where it does not, it declares that so routing never sends a token-only payment there.
Error Handling, Retries and Provider Responses
A connector has to distinguish three things a provider blurs together: the payment was refused, the request was malformed, and the provider did not answer. Only the first is a decline, only the second is your bug, and only the third is safely retryable.
Timeouts are the difficult case. Silence means unknown, not failed, so the connector queries the transaction status before anything upstream is allowed to act on it. That single discipline prevents most duplicate charges.
Idempotency key: a value your platform generates once per payment intent and reuses on every retry of the same request. If a response is lost in transit and the request arrives twice, the provider returns the original result instead of creating a second payment. Retry mechanics built on top of this are covered on cascading payments.
Counting how many provider integrations you maintain?
Using Connectors in Routing and Cascading
Routing is only possible because connectors make providers comparable. The engine reads the capability map to see which routes are eligible, then ranks them on live approval, cost and health, all of which arrive through the connectors in one shape.
Cascading depends on the same normalisation. A retry can only be judged eligible if the first decline was mapped into a taxonomy the engine understands, and the second connector has to accept the token and authentication state the first one produced. The decision model that consumes all of this is on intelligent payment routing.
Security and PCI Considerations
A connector should never be the place card numbers live. Tokenise at the platform edge, hand the connector a reference, and your PCI scope stays where it belongs instead of expanding by one boundary every time you add a provider. Credentials belong in a managed store with per-merchant rotation, and every connector call should be logged with its request, response and timing minus the sensitive fields.
Connector Maintenance and API Version Changes
The cost of a connector is not writing it. It is the four things that happen afterwards, on somebody else's schedule.
Providers deprecate endpoints on their timeline, not yours. A connector layer absorbs that once rather than in every integration you own.
An unmapped code silently becomes an unknown decline, which quietly disables the cascade for that case until somebody notices.
A changed column in a reconciliation file breaks matching without breaking payments, so it is found by finance rather than by monitoring.
Card schemes mandate periodic recertification, and each connected acquirer carries its own cycle and its own test pack.
Developer Workflow for Adding a New Provider
Six steps from signed contract to live traffic, and what each one actually produces.
Step
Read the spec
Declare capabilities
Map requests
Map responses
Certify
Weight in
What it produces
A gap list: what this provider cannot do at all.
A capability record routing can read before it selects.
Authorize, capture, refund and payout in the provider's format.
Every status and reason code mapped into your taxonomy.
A passed test pack, including declines and timeouts.
Five percent of live traffic, then more as data justifies it.
Read the spec
Produces
A gap list: what this provider cannot do at all.
Declare capabilities
Produces
A capability record routing can read before it selects.
Map requests
Produces
Authorize, capture, refund and payout in the provider's format.
Map responses
Produces
Every status and reason code mapped into your taxonomy.
Certify
Produces
A passed test pack, including declines and timeouts.
Weight in
Produces
Five percent of live traffic, then more as data justifies it.
For a PSP onboarding sub-merchants onto these connectors, the surrounding model is on white label payment facilitator.
Frequently Asked Questions
How long does a new payment connector take to build?
The mapping work is usually days rather than weeks. Certification and the provider's own test schedule set the real timeline, which is why the commercial agreement is almost always the longer half.
Can we write our own connectors on the platform?
Existing acquirers and PSPs an operator already holds are connected as part of deployment, and new ones are added by the platform team against the same interface. The contract stays yours in every case.
What happens when a provider changes its API?
The change is absorbed inside that one connector. Your platform keeps calling the same normalised API, which is the entire reason for putting an adapter there rather than integrating directly.
Do connectors add latency?
A few milliseconds for mapping, which is invisible next to the authorisation round trip. Anything measurable is the provider's own response time rather than the translation layer, and the routing decision on top of it is described on smart payment routing.
Does a connector hold card data?
No. Card data is tokenised at the platform edge inside a PCI DSS Level 1 ready environment, and the connector works with a reference. That is what keeps PCI scope from growing with every provider you add.
Can we test a connector before sending real traffic?
Yes, in a sandbox that reproduces declines, timeouts and duplicate notifications rather than only the happy path. After that a new connector takes a small weighted share of live traffic before it takes anything meaningful.