Menu
Talk with sales

Integration questions? [email protected]

The BazPay payment API, field by field.

One REST payment API covers cards, alternative methods, open banking, payouts and subscriptions for merchants in the EU, UK, Australia, Canada and New Zealand. Objects share a shape. Errors share a code list. Webhooks are signed. This page is the contract you build against, and every claim below is checkable against the tables that follow.

Talk with sales Read the guides
  • 6Core endpoints listed below
  • 25 / 100Default and max page size
  • 24hIdempotency key lifetime
  • 30dWebhook replay window
request headers · response envelope 
POST https://api.bazpay.com/v1/paymentsAuthorization: Bearer sk_live_9f2c…BazPay-Version: 2026-04-01Idempotency-Key: ord_10482Content-Type: application/json​{ "id": "pay_3fJ2Qk", "object": "payment", "amount": 4200, "currency": "EUR", "status": "succeeded", "method": "card", "sca": "frictionless", "created": "2026-04-12T09:31:07Z" }

Sandbox example. Amounts are minor units; 4200 is 42.00 EUR.

Auth, versions and formats.

Four settings decide whether your first request works. Read them once. They hold for every endpoint on this page, and the rules behind them — scopes, version pinning, idempotent retries — are set out in the authentication guide.

  • Base URL

    api.bazpay.com/v1

    One host serves every product in the payment API. TLS 1.2 or higher is required. Plain HTTP requests are refused, never redirected.

  • Keys

    sk_test_ · sk_live_

    The prefix tells you the mode. Test keys touch no real money. Secret keys stay server side, always, and rotate from the dashboard.

  • Versioning

    BazPay-Version

    Versions are dated, like 2026-04-01. Your account pins one. Send the header to test a newer contract on a single request first.

  • Format

    JSON in · JSON out

    Bodies are JSON or form-encoded. Amounts are minor units, so 4200 means 42.00 EUR. Timestamps are UTC in ISO 8601.

What the payment API actually covers.

One credential set, one object shape and one webhook contract span every rail below. That is what makes an API payment gateway comfortable to live with as product scope grows — the second endpoint you integrate feels like the first.

  • Card acceptance

    Charge Visa, Mastercard, Cartes Bancaires, eftpos and major co-badged schemes across the region. 3-D Secure 2.2 runs behind the payment API call, including the frictionless path and issuer step-up when the risk score demands it.

  • Alternative methods

    SEPA Instant, BLIK, BACS Direct Debit, Przelewy24 and other local APMs share the /v1/payments object. The method parameter selects the rail; the rest of the request stays identical, which keeps online payment API integration boring.

  • Open banking

    PSD2 account-to-account debits run through /v1/bank_payments. The payer approves the transfer in their bank app, funds land in your acquiring account, and the payment API returns a signed webhook when settled.

  • Payouts

    Send SEPA Instant to any reachable settlement account in seconds; classic SCT is the fallback for banks off the Instant scheme. SWIFT and push-to-card corridors are available on approved corridors after underwriting review.

  • Recurring billing

    Model plans, trials and proration on /v1/subscriptions. Off-session charges use stored network tokens where the scheme supports them, and dunning schedules retry declines on realistic issuer windows.

  • Vaulting and tokens

    Card details enter the browser through hosted fields and never touch your server. The payment API returns a gateway-side token you can charge later, so credit card payment API flows stay inside merchant SAQ A scope.

Six routes, the whole platform.

Learn one object and you have learned the platform. Each route below returns the same envelope and the same event names. Worked examples for each one live in the payments guide.

Browse the product pillars
Core resources and what each one does
Route What it does Product
POST /v1/payments Create a card or APM charge, with 3-D Secure 2 applied for you Cards and APMs
POST /v1/bank_payments Start an PSD2 account-to-account debit the payer approves in-app Open banking
POST /v1/payouts Send funds to a bank account over SEPA Instant, with SCT as fallback Payouts
POST /v1/subscriptions Open a plan with trial, proration and dunning handled our side Recurring billing
POST /v1/refunds Refund part or all of a captured payment on the original rail Checkout products
GET /v1/reports Pull settlement, decline and interchange++ data as JSON or CSV Real-time analytics

Five steps from account to first live charge.

A working payment API integration follows the same path whether you are a checkout team, a subscription team or a treasury team. The order below reflects the shortest safe route we see in production.

  1. Provision keys

    Create a workspace, verify the merchant record, and pull sk_test_ and sk_live_ from the dashboard. Restricted keys let you scope a webhook worker to /v1/reports only, so a leaked reporter cannot move money.

  2. Wire up hosted fields

    Drop the BazPay.js loader on the checkout template. The payment API for website flows keeps PAN, CVV and expiry inside our iframe, so your DOM never sees card data and your PCI audit stays at SAQ A.

  3. Confirm on the server

    The browser returns a payment_method token. Your server posts /v1/payments with the amount, currency, customer id and an Idempotency-Key. 3-D Secure 2 is applied automatically when the transaction needs 3-D Secure.

  4. Listen for the outcome

    Register an endpoint for payment.succeeded, payment.failed and refund.updated events. Verify the HMAC signature, mark the order, and reply 2xx within 20 seconds so we do not retry a message you already handled.

  5. Reconcile in reports

    Query /v1/reports for daily settlement, interchange++ splits and decline reasons. Feed the CSV into your finance stack, or stream the JSON into a warehouse for BI. The API payment integration ends where accounting begins.

Error codes and the right response
Status Code Meaning Do this
400 parameter_invalid A field is missing or malformed Fix the body and resend
401 key_invalid The secret key is wrong or revoked Rotate the key in the dashboard
402 card_declined The issuer refused the charge Show the reason, offer another method
409 idempotency_conflict A key was reused with a new body Use a fresh key per request
429 rate_limited Too many calls in the window Back off, then retry with the same key
5xx gateway_error Our side failed to complete Retry safely; writes are idempotent

Errors you can act on.

Every error returns a stable machine code beside the HTTP status. The message is for your logs. The code is for your logic. Decline reasons pass through from the issuer, so support can answer the buyer.

How fraud rules affect declines

Four habits that keep ledgers clean.

These four rules cover most support tickets we see. Apply them and integration stays boring.

  1. Retry with a key

    Every write accepts an Idempotency-Key header. Repeat the key and you get the first result back. Keys live 24 hours.

  2. Page with cursors

    List calls return a cursor, not an offset. Pass it as starting_after. The default page size is 25 and the cap is 100.

  3. Verify every webhook

    Each event body carries an HMAC signature and a timestamp. Check both, then act. Delivery is at-least-once.

  4. Expand, do not poll

    Use the expand parameter to inline related objects. One call replaces three. Polling a payment status is never needed.

Who runs on this API.

BazPay is scoped for merchants in the EU, UK, Australia, Canada and New Zealand. The API surface below reflects that scope: we do not onboard adult, gambling, forex, crypto-exchange, nutraceutical or debt-collection businesses, and the payment API contract is not designed for them.

  • E-commerce carts

    Physical-goods stores on WooCommerce, Magento 2, PrestaShop or Shopware plug in through official modules and get the same payment API endpoints under the hood. Cards, SEPA Instant, BLIK and BACS Direct Debit ship in the same checkout.

  • SaaS subscriptions

    Subscription software firms use /v1/subscriptions for trials, seat upgrades and proration. Failed renewals enter dunning, network tokens shrink involuntary churn, and event webhooks feed the CRM without a polling loop.

  • Professional services

    Consultancies, agencies and licensed practices invoice in EUR, EUR and other supported currencies. Hosted payment links carry the same payment API object shape, so a manual invoice and a self-serve checkout reconcile the same way.

  • Marketplaces of your own

    Split a captured payment across your own connected merchants by chaining /v1/payouts after settlement. This is a first-party split for your own entities — BazPay is not a marketplace of third-party PSPs and does not onboard sub-merchants on your behalf.

Security and compliance the API guarantees.

Every certification below applies at the endpoint boundary, not to a marketing page. If you cannot see the guarantee in a request header, a response field or a webhook signature, it is not part of the contract.

  • PCI DSS Level 1

    BazPay is assessed annually at PCI DSS Level 1, the top service-provider tier. The certification covers the payment API perimeter, the vault and every internal service that touches cardholder data.

  • Merchant SAQ A scope

    Hosted fields and the redirect variant keep PAN, CVV and expiry inside our origin. Merchants who use them qualify for SAQ A, the shortest self-assessment questionnaire the PCI Council publishes.

  • 3-D Secure 2.2

    The payment API runs 3-D Secure 2.2 for card charges, including device-binding, delegated authentication where the issuer supports it and out-of-band challenges on mobile devices.

  • Authentication and exemptions

    Low-value, trusted-beneficiary and transaction-risk analysis exemptions are requested on your behalf when the transaction qualifies. Every request stays audit-traceable in the exemption field on the payment object.

  • Signed webhooks

    Every event carries an HMAC-SHA256 signature and a timestamp header. Rotating the signing secret in the dashboard is a single click and takes effect on the next event.

  • Idempotent writes

    Every POST accepts an Idempotency-Key header valid for 24 hours. A retried payment does not create a duplicate charge, which is what makes safe mobile payment API flows possible on flaky networks.

Integrate on the stack you already run.

The REST payment API is the ground truth, but most teams reach it through a plugin or SDK. Every wrapper below emits the same objects, so a support ticket from a WooCommerce store and a support ticket from a custom Node service open the same payment record.

Full integration catalogue

  • E-commerce platforms

    Official modules for WooCommerce, Magento 2, PrestaShop and Shopware install the hosted-field checkout and wire /v1/payments and /v1/refunds under the cart's own admin. No card data enters the platform database.

  • Server SDKs and CLI

    First-party libraries for Node.js, PHP, Python, .NET and Java speak the same dated version header as the raw payment API. The command-line client scaffolds webhook receivers and tails events during local development.

  • Mobile SDKs

    iOS and Android SDKs handle Apple Pay, Google Pay and hosted card entry, then hand a payment_method token to your server. The mobile payment API request that follows is identical to a web one.

  • Data and finance

    Signed webhook streams push events to your warehouse; /v1/reports returns settlement, refund and interchange++ splits as JSON or CSV. Reconciliation runs against the same object ids your checkout wrote.

Payment API questions, answered plainly.

The answers below are the same ones our sales engineers give on discovery calls. If a question you have is not here, the general FAQ and the resources library go deeper.

  • What does a REST payment API for developers give me that a hosted checkout does not?

    Full control over the object graph. You store the customer id, choose when to authorise versus capture, expand related resources in a single request, and drive refunds, subscriptions and payouts from the same key set. Hosted checkout is a UI on top of the same payment API for developers — you can adopt one, both, or move between them without migrating data.

  • Do you support ACH-style bank debits for US buyers?

    BazPay operates as a regional acquirer. Our account-to-account rail is PSD2 open banking through /v1/bank_payments, and our recurring bank rail is BACS Direct Debit — the regional equivalent of an ACH payment API. Direct US ACH is not part of the current product surface.

  • Is there a crypto payment API on BazPay?

    No. BazPay processes fiat card, APM, open banking and SEPA Instant transactions for merchants across the EU, UK, Australia, Canada and New Zealand. We are not a crypto payment API, a wallet or an exchange provider, and we do not settle in cryptocurrency.

  • Where is the payment API documentation?

    The reference on this page names every core endpoint. Worked request/response pairs, error tables and event payloads live in the payment API documentation at /docs/payments/. Authentication, key scopes and versioning live at /docs/authentication/. Anything not in those guides is not part of the supported contract.

  • Can I use the payment API for website checkout and mobile apps at the same time?

    Yes. The REST contract is identical for both. Native iOS and Android apps call the same endpoints through the same secret key; the mobile payment API path differs only in how you collect card data — Apple Pay and Google Pay tokens post to /v1/payments the same way a hosted-field token does.

  • How is credit card payment API pricing structured?

    Card processing is quoted on interchange++, so scheme fees and interchange pass through at cost and BazPay's margin is a separate line. Full breakdowns and non-card method rates live on the /pricing/ page. Interchange++ appears in /v1/reports responses so finance can reconcile without a spreadsheet.

  • Does BazPay support bill payment API use cases?

    For business-to-business invoice collection — recurring bank debits, one-off invoice links, instant payouts to suppliers — yes. Consumer utility bill aggregation (rent, telecoms, energy across third-party billers) is outside the current product; the platform is built for merchants collecting revenue, not for consumers paying household bills.

  • How long does an api payment integration take end to end?

    Test-key to first live charge is a week for a typical single-currency card+SEPA Instant checkout, plus underwriting time. Adding open banking, subscriptions and payouts extends the scope but reuses the same authentication, error shape and webhook signature, so the marginal work drops after the first endpoint is live.

Test keys, then live traffic.

The sandbox mirrors this reference exactly. Card data stays inside our hosted fields, so you remain at PCI DSS SAQ A. Bring a question and a specialist will answer it in plain language.

Talk with sales

Prefer email? Write to [email protected].