Payment API

Payment API: one REST contract in front of every provider you'll ever need.

topropay's unified payment API is the integration point for every connected acquirer, PSP and method — card, wallet, bank rail, ACH, bill payment, mass payout and crypto via partner gateways. Same endpoints across every rail; smart routing on every authorisation; one signed webhook stream; one ledger.

Open the API docs Book a technical review
request.http 
POST /v1/authorizations HTTP/1.1
Host: api.topropay.com
Authorization: Bearer sk_live_***
Idempotency-Key: 1f3a7b09-7d12-4a02-9c5e
Content-Type: application/json

{
  "amount": { "value": 18900, "currency": "EUR" },
  "customer": { "token": "cus_2nQ8R7zXyJ" },
  "payment_method": { "type": "card", "vault_token": "tok_VWxAa3" },
  "routing_policy": "approval_weighted",
  "metadata": { "order_id": "ORD-71204" }
}
response.json 
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "auth_8KpQ2vRm",
  "status": "authorized",
  "amount": { "value": 18900, "currency": "EUR" },
  "acquirer": { "id": "acq_eu_visa_03", "bin": "411111" },
  "scheme_response": "00",
  "route_decision_ms": 134,
  "cascade_attempts": 0,
  "vault_token": "tok_VWxAa3"
}
1
//REST contract
300+
//methods reachable
<200ms
//routing decision
L1
//PCI DSS posture

Endpoint set

The api for payment gateway operations, all behind one contract

Six endpoint groups cover the vast majority of merchant flows. The same shape applies whether you're authorising a card, sending a payout or refunding a crypto receipt.

  • POST /v1/authorizations

    Authorise a transaction

    The single entry point for card, wallet, bank-rail, bill-payment and crypto-gateway authorisations. Same request body shape across methods; the routing engine picks the best provider per call.

  • POST /v1/captures

    Capture an authorisation

    Full or partial capture against a held authorisation. Vault tokens replace card data, so this call carries no PAN. Webhooks fire on every state change.

  • POST /v1/refunds

    Refund a captured payment

    Full or partial refunds; metadata follows the customer record so the refund pairs with the original ledger row in the reconciliation export.

  • POST /v1/payouts

    Send a payout

    Cards, bank rails, ACH, SEPA and crypto destinations through one endpoint — useful for marketplace seller payouts, mass-payment solution flows and refunds-as-payouts.

  • GET /v1/transactions/:id

    Read a transaction

    Full transaction record — authorisation, captures, refunds, disputes, chargebacks, settlement — keyed off the vault token, not a PAN.

  • POST /v1/customers

    Create or update a customer

    Vault-token-backed customer record that survives across rails, regions and methods; renewals, retries and account-updater events all reference it.

How it works

From a signed POST to a normalised ledger row

Five lanes between your signed REST call and a normalised ledger row in tomorrow's finance export — with everything from routing to webhooks happening inside the same request lifecycle.

  1. Request

    Signed REST call from your back-end

    POST the authorisation body with an idempotency key; the SDK signs the request with your API key. The same call shape works for cards, wallets, bank rails, bill payment and crypto gateway routes.

  2. Route

    Per-transaction scoring across the connected portfolio

    The routing engine scores connected acquirers and partner gateways on approval likelihood, cost, country pair and risk signals — picks one in under 200ms. Soft declines cascade to the next inside the same request.

  3. Vault

    PCI DSS Level 1 vault tokenisation

    Card data captures into the vault; subsequent refunds, retries, recurring and chargebacks all run on tokens. Your origin servers never see a PAN.

  4. Event

    Signed webhook + event-stream emission

    Authorisation, capture, refund, dispute and settlement events fire as signed webhooks and on the event stream — one shape across every method and rail.

  5. Reconcile

    Normalised ledger across acquirers and gateways

    Settlement, fees, refunds and chargebacks across every connected provider normalise into one ledger keyed off vault tokens. CSV / Parquet exports drop daily.

Main use cases

From credit card payment API to mass payment solution — same contract

Six concrete shapes of api payment integration that share the same request/response model. The rail differs; the operational shape doesn't.

  • Card checkout

    Credit card payment API for online retail

    A credit card payment API call from a hosted checkout authorises against the routed acquirer, captures on order confirmation, and refunds via the same endpoint set. SDKs cover web, mobile and server.

  • Mobile

    Mobile payment API for native apps

    A mobile payment API surface for iOS and Android exposes the same authorise/capture/refund endpoints used on web, plus helpers for Apple Pay, Google Pay and wallet deeplinks. One API, two surfaces.

  • ACH

    ACH payment API for US bank-rail flows

    An ACH payment API surface routes debits and credits through connected ACH providers — same request shape as cards, just a different method field. Settlement reports normalise into the unified ledger.

  • Bill

    Bill payment API for utilities and recurring invoices

    A bill payment API endpoint takes the bill metadata (account number, payee code, due date) and routes through the right connected bill-pay gateway for the merchant's region.

  • Payouts

    Mass payment solution for marketplaces and platforms

    A mass payment solution call accepts a batch of destinations — bank account, card, wallet or crypto address — and dispatches each through the appropriate connected rail; one webhook per disbursement, one settlement row per batch.

  • Crypto

    Crypto payment API alongside fiat

    A crypto payment API call surfaces stablecoins, majors and L2 routes via partner crypto gateways. Conversion-on-receipt is a per-asset policy; the response shape matches a card authorisation.

Model comparison

Per-provider API stack vs unified payment API integration

What changes when N per-provider integrations collapse into one unified contract — the difference shows up most in long-term maintenance, not day-one engineering.

Dimension Per-provider stack topropay unified payment API
Integration count One per provider — N integrations to maintain One unified REST contract regardless of how many providers sit behind it
Method coverage Per-provider — card here, ACH there, crypto somewhere else Card, wallet, bank-rail, bill-pay, mass-payout and crypto behind the same endpoints
Routing Static — your code chooses the provider Dynamic — the platform picks the best route per authorisation with cascade on soft decline
Webhooks N event schemas, N signing schemes One signed webhook contract, one event model, one secret to rotate
Vault Per-provider; PAN may touch your servers Single PCI DSS L1 vault; PAN never touches your origin
Reconciliation N settlement files to merge One normalised ledger export across every connected provider

Platform features

Capabilities behind the payment api documentation

What the platform actually ships at the API layer — versioning posture, signing, sandbox parity and the integration ergonomics that make a payment API survive into production at scale.

  • Unified REST contract

    One endpoint set across every method and rail; SDKs for web, iOS, Android, server-side languages.

  • Signed webhooks

    Replay-safe signed events for every transaction state change, with subscription per event type.

  • Idempotency by default

    Idempotency-Key header on every mutating call; safe to retry on network failure without double-charging.

  • Vault tokenisation

    PCI DSS Level 1 vault returns tokens scoped to your merchant; refunds, retries and recurring all run on tokens.

  • Per-environment sandbox

    Sandbox mirrors production behaviour including routing decisions, cascade scenarios and settlement timing.

  • Bring-your-own fraud engine

    Adapter contract lets you plug a fraud provider in front of the routing decision; otherwise use the platform's default.

  • Versioned endpoints

    Major-version pinning with a 12-month deprecation window; breaking changes never land mid-version.

  • OpenAPI + Postman

    OpenAPI 3.1 spec plus a maintained Postman collection that mirrors every endpoint and example response.

  • Comprehensive payment api documentation

    Hosted payment api documentation with searchable endpoints, runnable examples and per-method recipes for cards, ACH, bill-pay, mass-payouts and crypto.

Trust & compliance

Compliance posture inherited at the API layer

Every call runs through the platform's audited environment. Sub-merchants inherit the posture without per-provider re-certification, and the developer surface preserves it (signed everything, scoped keys, versioning discipline).

PCI DSS Level 1
Service-provider posture validated annually on-site; quarterly ASV scans run on the platform cycle and inherited by sub-merchants.
Signed everything
Webhooks, events and SDK requests are signed; replay protection and idempotency built in by default.
Scoped API keys
Multiple key scopes (read-only, write, payouts) with rotation, IP allow-lists and per-key audit logs.
SCA & 3DS2
Selective authentication wired into the authorisation path — PSD2-compliant in Europe without breaking conversion.
Versioning discipline
Major-version pinning, 12-month deprecation windows, advance breaking-change notice — predictable for production teams.
Sandbox parity
Production-equivalent sandbox per environment, including routing, cascade and dispute scenarios.

Ready to integrate

One REST contract. Every provider. Production-ready.

Open the docs, spin up a sandbox key in a minute, and POST your first authorisation before the end of the working day. Or book a 30-minute technical review and we'll walk through the integration shape that fits your stack.

Open the API docs Book a technical review

Frequently asked

Buyer and developer questions about the payment API

The questions integration engineers and buyers ask before committing — covering the contract, sandbox parity, versioning, vault, sandbox, mobile, ACH, mass-payment and crypto surfaces.

  • What does topropay's payment api actually do?

    The payment api is one REST contract in front of every connected acquirer, PSP and method on the platform. Your back-end calls authorise / capture / refund / payout against a single endpoint set; the platform routes the call to the best connected provider, returns a normalised response, and emits signed webhooks for every state change. The same API covers card, wallet, bank-rail, ACH, bill-pay, mass-payouts and crypto via partner gateways.

  • How is an api for payments different from an api for payment gateway?

    An api for payments is the wider category — anything that initiates or reports on a payment. An api for payment gateway specifically refers to the surface a gateway exposes for authorisation, capture and refund. topropay's payment api covers both: gateway-style endpoints plus payout, mass-payment, dispute and reconciliation endpoints in one contract.

  • Is topropay itself an api payment gateway?

    topropay exposes an api payment gateway surface and orchestrates traffic across many connected gateways underneath. From your code's perspective it behaves like one gateway; from the routing engine's perspective each connected gateway is a lane that the engine scores per transaction.

  • What does an online payment api integration look like in practice?

    An online payment api integration starts with a single authorisation call from your storefront or back-end, a webhook handler to receive state-change events, and (optionally) a hosted checkout iframe if you don't want to build the surface yourself. SDKs cover JavaScript, Python, Go, PHP, Java, Ruby, Swift and Kotlin. Most teams reach a live integration in days.

  • How does the mobile payment api differ from the web one?

    Same endpoints, plus native SDKs for iOS and Android that wrap the wallet pay-sheet, biometric authorisation and Apple Pay / Google Pay flows. The mobile payment api also exposes deeplink helpers for crypto wallet flows. Mobile authorisations roll up into the same ledger as web authorisations.

  • Is there a dedicated crypto payment api or is crypto a method on the main API?

    Crypto is a method on the main API. The crypto payment api shape is identical to a card authorisation — you set payment_method.type to the relevant crypto rail (USDC on Base, USDT on Tron, BTC on Lightning) and the connected partner gateway handles the chain side. The response shape, vault-token model and reconciliation are the same as for cards.

  • How quickly can a team complete a payment api integration?

    A payment api integration with the hosted checkout ships in hours; a fully embedded build is typically a sprint or two. The slowest step is usually onboarding (KYC, underwriting), not engineering — the API surface is small enough that a single back-end engineer can take it end-to-end.

  • Do you offer an ach payment api for US bank flows?

    Yes — an ach payment api surface for ACH debits and credits is part of the same unified API. Settlement timing follows ACH norms (T+1 / T+2); the endpoints, webhook events and reconciliation feed match the card flow. Returns and chargebacks are handled in the same dispute queue.

  • How does the mass payment solution endpoint work for marketplaces and platforms?

    The mass payment solution endpoint accepts a batch of disbursements — each one a destination (bank account, card, wallet, crypto address), an amount and a metadata blob. The platform fans them out across the appropriate connected rails, emits one webhook per disbursement, and groups the batch into a single settlement row in reconciliation.

  • Is there a bill payment api for utilities and recurring invoices?

    Yes. The bill payment api endpoint takes the payee code, account number, due date and amount, and routes the authorisation through the connected bill-pay gateway relevant for the merchant's region. Responses surface confirmation numbers and the underlying provider's reference for downstream reconciliation.

  • Is there a payment api for website checkouts without writing a full integration?

    A payment api for website checkouts is available as a drop-in hosted checkout: a single script tag or iframe ships the full checkout UI. Behind the scenes the same payment api is called; for teams that want full control of the UI the SDK / hosted-fields path exposes the same primitives.

  • Where is the payment api documentation?

    Hosted payment api documentation lives at the platform's docs site, mirrored as an OpenAPI 3.1 specification and a maintained Postman collection. Every endpoint carries runnable examples, request/response payloads, error codes and a 'recipe' page per method (cards, ACH, crypto, mass-payout, bill-pay).

  • Can the credit card payment api handle 3DS2 and SCA out of the box?

    Yes. The credit card payment api exposes selective 3DS2 / SCA on the authorisation path; the platform decides per transaction whether to step up based on the relevant regional rules and the merchant's risk policy. Step-up responses are returned in the same authorisation flow without a second integration.

  • Are the endpoints versioned, and how do breaking changes land?

    Endpoints are pinned to a major version (v1, v2 …); breaking changes only happen at major-version increments with a 12-month deprecation window and advance written notice. Non-breaking additions (new fields, new methods, new event types) ship continuously and never break existing clients.

  • Is there a sandbox that behaves like production?

    Yes — every environment has a sandbox that mirrors production behaviour, including routing decisions, cascade scenarios, settlement timing, dispute injection and webhook delivery. Most production bugs we see are caught in sandbox; the parity is deliberate.

Related

Related on the topropay platform