partners

Integration requirements for partner banks

The technical contract between apay and a partner bank or processor, so integration scoping can start from a fixed list.

Architecture

merchant app ──► apay API / checkout SDK ──► apay switch ──► bank connector ──► partner bank API
                                                     ▲                                          │
                                                     └────────── webhooks / notifications ◄─────┘

apay implements a connector for each partner: an adapter that maps the apay payment lifecycle to the bank’s API. Everything a bank exposes through a documented HTTPS API with JSON or XML can be connected. Banks that already have an acquiring API used by PSPs need no changes; the list below states what apay looks for.

A. Acquiring connector

Capability	Required	Notes
Authorise (card, with and without 3DS)	Yes	Card data or network token; amount, currency, order reference, billing address
Capture (full and partial)	Yes	Or auto-capture flag on authorise
Void / cancel	Yes	Before capture
Refund (full and partial)	Yes	Asynchronous refunds supported via webhooks
Payment status query	Yes	By bank reference and by apay reference
3-D Secure 2	Yes	Either bank-hosted challenge (redirect) or external 3DS server integration
Apple Pay, Google Pay	Strongly preferred	Bank decrypts wallet token, or accepts network token plus cryptogram from apay’s decryption
Local wallets and RTP schemes	Per market	Redirect or QR flows with status webhooks
Tokenisation / card-on-file	Preferred	Bank token or network token; otherwise apay vault is used
Webhooks for status changes	Yes	Signed (HMAC or mTLS), with retries; payload includes bank reference and final status
Disputes and chargebacks	Yes	Webhook or report file with case id, reason, deadline, evidence upload API preferred
Settlement reports	Yes	Daily file (CSV/XML/SFTP or API) with per-transaction fees and net amounts
Idempotency	Yes	Idempotency key on authorise, capture and refund
Sandbox	Yes	Test credentials, test cards for approve/decline/3DS, simulated webhooks

B. Virtual accounts and payouts (optional)

Capability	Notes
Create virtual account under master account	Return account number, bank code, holder name; optional expiry for single-use accounts
Credit notification	Real-time webhook with reference, amount, currency, sender details; signed
Payout / disbursement	Domestic transfers (RTP and batch), status webhook, failure codes
Balance and statement	Master account balance, daily statement file for reconciliation
Beneficiary validation	Name check where the scheme supports it

C. Security and operations

TLS 1.2+; authentication by API key, OAuth2 client credentials or mTLS; IP allow-listing supported (apay egress IP is static).
Webhook signing: HMAC-SHA256 or better with timestamp, or mTLS. apay verifies before processing.
PCI DSS: card data flows between the apay vault and the bank; apay supplies its PCI attestation of compliance; merchants stay in SAQ A.
Data residency: apay can deploy a switch instance in the bank’s region if required.
Environments: sandbox, optional UAT with real-money limits, production.
Monitoring: apay provides success-rate and latency dashboards per connector; the bank provides a status page or incident channel.

D. Certification checklist

apay runs this suite against the bank sandbox before pilot and records the evidence:

Authorise + auto capture, approve
Authorise, decline (insufficient funds, do-not-honour, stolen)
Authorise with 3DS challenge, approve
Authorise then partial capture, then void of remainder
Full refund, partial refund, refund of a refund (rejected)
Apple Pay and Google Pay authorise
Webhook delivery for each state change, with signature verification and replay
Idempotent retry of authorise and refund
Timeout and status recovery through the status query
Settlement file parsing and reconciliation to the cent for a test day
Dispute notification and evidence submission

E. What apay needs from the bank to start

API documentation and sandbox credentials
Named technical contact and a shared channel
Merchant onboarding form and prohibited MCC list
Fee schedule and settlement terms for the pilot
Webhook signing method and test tooling

F. What the bank receives from apay

Connector specification mapped to the bank’s endpoints
Certification evidence pack
Reconciliation report format and sample files
Security and PCI documentation, data-flow diagram, subprocessor list
Access to the apay dashboard for the partner’s operations team

Questions: dev@apay.to · Back to docs