Payment gateway integration
topropay's integration is one API in front of every connected acquirer, PSP and method. Pick the surface — hosted, embedded or low-level SDK — drop it into the merchant's web or mobile checkout, and the routing engine handles the multi-gateway traffic split behind it.
$
npm install @topropay/sdk await
topropay.payments.create({ amount: 18900 })
200
authorised · acquirer · 184ms
Key benefits
Four outcomes that show up consistently once one integration sits in front of the multi-gateway portfolio rather than per-provider plumbing.
Drop-in hosted checkout for the fastest start, embedded hosted fields for inline UI, low-level SDK for full control. All three back onto the same authorisation engine — pick the simplest shape that fits and upgrade later without re-integrating.
The merchant writes one integration; the routing engine fans authorisations out across the connected acquirer panel. Multiple-payment-gateway behaviour without per-gateway plumbing — the merchant doesn't maintain a separate webhook handler per provider.
Native iOS and Android SDKs share the same authorisation engine, vault and webhook model as the web checkout. A mobile payment gateway integration is the same back-end as the desktop one — different surface, identical contract.
No platform retainer, no monthly minimum, no per-environment fee. Pricing is per-authorisation on top of underlying provider economics; the sandbox is free. Payment gateway integration charges are predictable line-items on the invoice, not bundled into a long-form quote.
Integration shapes
Three valid integration shapes back onto the same orchestration. The difference is PCI scope and UI control; pick the shape that fits the team, not the platform.
The buyer leaves the merchant's site for the platform-hosted checkout (or sees an iframe). PCI scope sits with topropay; the merchant integration is a signed session token plus one webhook handler.
Card-number, expiry and CVV render as hosted iframes inside the merchant's own checkout. The rest of the page is fully under merchant control; sensitive fields still capture into the vault.
Server SDKs (Node, Python, PHP, Ruby, Java, Go) wrap the REST API with idiomatic helpers; native iOS and Android SDKs cover mobile surfaces with the same primitives.
How it works
Six concrete stages between the first scope call and live traffic. Hosted-path merchants reach the live stage in days; embedded and SDK builds take weeks.
30-minute integration review covers method mix, geography, traffic shape and the integration shape that fits the team — hosted, embedded or SDK.
Sandbox tenant and signed API keys issued. Engineering starts building against the sandbox; no live volume needed during integration.
Pick the integration shape and drop it into the checkout. Hosted-page: a redirect / iframe and a webhook handler. Embedded: hosted fields. SDK: the merchant's own surface against the primitives.
Method availability per market and routing policy (approval-, cost- or composite-weighted) are dashboard configuration. Engineering integrates once; ops tunes afterwards.
Deterministic helpers in the sandbox trigger specific outcomes — soft / hard declines, 3DS challenges, iDEAL bank-confirmation, ACH R-code rejections, webhook replays. Build confidence before live traffic.
Onboarding / KYB completes in parallel; live API keys are issued and the merchant flips traffic over. Most merchants reach live in days on the hosted path, weeks on embedded or SDK builds.
Main use cases
Six merchant shapes that share the same integration but stress it differently — website, mobile, multi-gateway, marketplace, PSP and recurring.
Most common shape: drop the hosted checkout into the merchant's existing website via a redirect or iframe. Methods per market and routing policies are dashboard-configurable; the merchant doesn't ship a release every time the method mix changes.
Native iOS and Android SDKs surface Apple Pay, Google Pay, regional wallets and cards inside the same authorisation engine the web checkout uses. A mobile-application payment-gateway integration ships alongside the web one, not as a separate build.
Where merchants ran several gateways separately, topropay collapses the lot behind one API. Multiple-payment-gateway integration becomes one integration job, plus dashboard configuration to switch on each connected provider per market.
Split payments, per-seller payouts and per-tenant reporting on one orchestration layer. The platform handles facilitation; the marketplace handles its sellers.
Resellers ride the connected portfolio downstream. The integration is one-off for the PSP; their merchants inherit the routing, method coverage and reconciliation.
Vault-token-driven recurring on cards, plus ACH and SEPA Direct Debit, share the same scheduling engine. Renewals run server-to-server; cancel surfaces are dashboard-configurable.
Cost structure
Six lines that explain how the cost stacks. No bundled "effective rate" — every component is named and reconcilable against the daily export.
There's no fixed monthly fee for accessing the integration — pricing is per-authorisation on top of underlying acquirer / rail economics.
Card authorisations carry interchange and scheme fees as pass-through where the underlying acquirer supports it; the platform fee is a separate line.
The sandbox environment is unmetered — payment gateway integration testing doesn't add to the invoice.
Per-authorisation fees compress at higher monthly authorisation counts, agreed up-front and surfaced in the dashboard.
Production and sandbox keys, multi-tenant API keys, scoped sub-merchant keys — all included.
Most merchants self-serve the integration via docs, SDKs and sandbox. Where high-complexity migrations or marketplace facilitation flows need help, a paid integration-services engagement is available.
Platform features
What the platform actually ships — the API contract, the SDK family, the routing engine and the operator surface.
JSON-over-HTTPS REST surface with idempotency, signed webhooks and OpenAPI specs.
Node, Python, PHP, Ruby, Java, Go and .NET — idiomatic helpers with webhook-signature verification built in.
Native iOS and Android SDKs share the same authorisation engine as web.
Drop-in checkout via redirect or iframe; signed session tokens; brandable surface; localised method ordering per market.
Inline iframes for PAN / expiry / CVV that keep PCI scope on the platform side.
Per-transaction scoring across the connected acquirer panel — chosen route varies per BIN, scheme, currency and country pair.
Soft declines fail over to the next ranked acquirer inside the same authorisation; nothing leaks back to the buyer.
Card data captures into the vault before it touches the merchant's origin; refunds, retries and recurring run on vault tokens.
Network-token-by-default plus scheme account updaters keep saved cards alive across re-issuance.
Selective challenges per transaction — PSD2-compliant in Europe without breaking conversion elsewhere.
One dashboard for authorisations, refunds, disputes and chargebacks across every connected gateway.
Per-environment sandbox that mirrors production with deterministic decline / 3DS / cascade scenarios.
Trust & compliance
Every authorisation runs through a single audited environment regardless of integration shape. Merchants inherit posture rather than carrying separate certifications per provider or per surface.
Ready to integrate
A 30-minute integration review covers the shape that fits your team — hosted, embedded or SDK — the SDK family for your stack, the routing policy that fits, and a sandbox to test against before any commercial commitment.
Frequently asked
Questions buyers ask before committing — integration shape, mobile, multi-gateway, cost / charges, sandbox parity and the licensed-verticals-only boundary.
Payment gateway integration on topropay means wiring the merchant's checkout (web, mobile or both) against the platform's unified payments API. The merchant picks an integration shape — hosted page, embedded hosted fields or low-level SDK — and the platform handles the routing across multiple connected acquirers behind it.
Online payment gateway integration on the hosted-page path takes days for most merchants — a redirect / iframe, a signed session token, one webhook handler. Embedded hosted-fields builds take a few weeks; full custom SDK builds take longer depending on the complexity of the merchant's surface.
Payment gateway integration in website flows: the website calls topropay to create a payment session, redirects (or embeds) the hosted checkout, the buyer completes the payment, the platform fires a signed webhook back to the merchant's URL with the authorisation result, and the merchant ships the order. The same shape powers refunds and disputes through different endpoints.
Payment gateway integration with website on an existing stack is usually a one-week sprint for a senior engineer on the hosted-page path: install the SDK, render the hosted checkout from the cart page, wire one webhook handler, swap sandbox keys for live keys. Common ecommerce platforms (Shopify-like, WooCommerce-like, custom) can wire it in hours rather than days.
Most merchants self-serve the integration via docs, SDKs and the sandbox — payment gateway integration services on the platform side aren't required. For high-complexity migrations (legacy gateway swap, marketplace facilitation flows, custom routing requirements), a paid integration-services engagement is available.
Gambling payment gateway integration services are available only for licensed operators in permitted jurisdictions. The operator must hold a current operating licence and run full KYC, AML and responsible-gaming controls; the platform's underlying acquirers must underwrite the vertical for the operator's market. Unlicensed gambling and grey-market betting are out of scope regardless of integration shape.
The simple payment gateway integration shape is the hosted page on a redirect — minimal merchant-side code, minimal PCI scope, one webhook handler. Most low-volume merchants and ecommerce-platform-based stores pick this path. Upgrading to embedded or SDK later doesn't require re-integrating; the back-end stays the same.
Multiple payment gateway integration on topropay isn't multiple integrations — it's one integration against the platform API, plus dashboard configuration to switch on each connected provider per market. The merchant doesn't pick a different SDK per gateway; the routing engine handles the cross-gateway traffic split.
Payment gateway integration process on topropay: scope review (30 minutes) → sandbox keys → drop in the surface → configure methods and routing → test against the sandbox → switch keys to live. Hosted-path merchants reach live in days; embedded and SDK paths take weeks. KYB / underwriting runs in parallel.
Mobile payment gateway integration differs only at the surface level — native iOS and Android SDKs render the pay-sheet and handle wallet handoff (Apple Pay, Google Pay). Behind the surface, the same authorisation engine, vault and webhook model power both. A web-then-mobile rollout is a second SDK install, not a second integration project.
Payment gateway integration in mobile application uses the native SDK (iOS / Android) — install via Cocoapods / SPM or Gradle, instantiate the client with a publishable key, present the platform-rendered pay-sheet, handle the resulting authorisation in the app's back-end via the same /v1/payments endpoint as web. PCI scope stays on the platform; PAN never lands in the app process.
Payment gateway integration cost is per-authorisation on top of underlying acquirer / rail economics — no platform retainer, no monthly minimum, no per-environment fee. Interchange and scheme fees pass through where the underlying provider supports it; the platform fee is a separate line. Sandbox is free.
Payment gateway integration charges are split into explicit invoice lines: interchange (pass-through where supported), scheme fees (pass-through where supported), acquirer markup, platform fee per authorisation. No bundled 'effective rate' — every component is named and reconcilable against the daily export.
Topropay sits one level above traditional payment-gateway-integration companies — instead of selling one gateway integration, the platform integrates with multiple gateways and exposes them through one unified API. The merchant gets the result of a multi-gateway integration without doing the integration work per gateway.
The sandbox during integration mirrors production endpoints exactly — same REST shape, same error model, same signed webhooks (with rotating test secrets). Deterministic helpers trigger specific outcomes (soft/hard decline, 3DS challenge / frictionless, iDEAL bank-confirmation, PIX timing, ACH R-codes, refund and chargeback simulations) so the merchant builds the full integration against the sandbox before any live traffic.
Related