AQ Pay

API reference

The AQ Pay API is REST over HTTPS with JSON bodies. Resources are consistent across every connected provider; provider-specific details appear in a route object rather than in the shape of the resource. This reference describes the v1 contract; a machine-readable OpenAPI document will be published alongside the sandbox.

Authentication

Server calls use a secret key in the Authorization: Bearer header. Browser-side tokenization uses a publishable key that can only create tokens. Keys are scoped to one environment and one tenant.

sk_live_… / sk_sandbox_…
Secret key
Server-side. Full access within the tenant and environment.
pk_live_… / pk_sandbox_…
Publishable key
Browser-side. Can only create tokens.
whsec_…
Webhook secret
Per endpoint. Used to verify event signatures.

Conventions

Idempotency-KeyRequired on POST. Same key within 24h returns the original response.
AmountsIntegers in minor units. Currencies without minor units use the whole number.
PaginationCursor-based: limit (max 100) and starting_after. Responses include has_more.
VersioningPath version (/v1). Additive changes are not versioned; breaking changes get a new path.
Rate limitsPer key. 429 responses include Retry-After.
TimestampsISO 8601 UTC everywhere.

Error model

Errors return a stable type and code. Provider decline codes are normalised into a shared taxonomy and the raw provider code is preserved for support.

{ "error": {
    "type": "card_declined",
    "code": "insufficient_funds",
    "retryable": false,
    "provider": { "id": "acquirer_a", "raw_code": "51" },
    "request_id": "req_…" } }

Payments

A payment is one customer intent to pay. It may contain several provider attempts (cascades); the resource exposes the final state and the route that produced it.

POST/paymentsCreate and authorize (or authorize + capture) a payment.
GET/payments/{id}Retrieve a payment with attempts, route and 3DS result.
POST/payments/{id}/captureCapture an authorized amount, fully or partially.
POST/payments/{id}/voidRelease an uncaptured authorization.
POST/payments/{id}/refundsRefund a captured payment, fully or partially.
GET/paymentsList with filters: status, merchant, created range, method.
Key fields
amountintegerMinor units (cents). 12800 = €128.00.
currencyISO 4217Presentment currency. Settlement currency depends on the route.
payment_methodobjectA token, a stored method id, or a redirect method type.
routing.profilestringRouting profile to evaluate. Defaults to the merchant’s assigned profile.
statusenumrequires_action · authorized · captured · voided · refunded · failed
routeobjectprovider, attempt number, cascade reason, 3DS outcome.

Tokens & customers

Tokens replace card data. Create them from hosted fields with a publishable key; attach them to a customer to reuse for recurring or one-click payments.

POST/tokensCreate a single-use token (publishable key, browser).
POST/customersCreate a customer record.
POST/customers/{id}/payment-methodsStore a token as a reusable payment method.
DELETE/customers/{id}/payment-methods/{pm}Remove a stored method.
Key fields
tokenstringtok_… — single use, expires after 15 minutes.
network_tokenbooleanWhether a scheme network token was provisioned for the stored method.

Merchants

For tenants and platforms. Create merchants, assign provider accounts and routing profiles, and read per-merchant configuration. Requires a tenant-scoped key.

POST/merchantsCreate a merchant under your tenant.
GET/merchants/{id}Retrieve configuration and status.
PATCH/merchants/{id}Update routing profile, risk profile, fee schedule or status.
GET/merchants/{id}/balancesSettled and pending balances per provider.

Routing profiles

Ordered rule sets evaluated per payment. Read access is available to all keys; write access requires the routing permission on a tenant key.

GET/routing-profilesList profiles visible to the key.
GET/routing-profiles/{id}Retrieve rules, cascade settings and health policy.
POST/routing-profilesCreate a profile (tenant keys).
POST/routing-profiles/{id}/simulateEvaluate a hypothetical payment and return the chosen route.

Disputes

Chargebacks and retrieval requests from any connected provider, normalised into one lifecycle with deadlines.

GET/disputesList disputes with status and due dates.
GET/disputes/{id}Retrieve a dispute with the originating payment.
POST/disputes/{id}/evidenceUpload evidence files and structured fields.
POST/disputes/{id}/acceptAccept liability without representment.

Webhooks

Events are signed with an HMAC-SHA256 over timestamp.body using your endpoint secret, delivered at least once, and retried with exponential backoff for 24 hours until your endpoint returns 2xx. Reject signatures older than five minutes to prevent replay.

payment.authorized
Authorization succeeded on a route.
payment.requires_action
3DS or redirect needed; action URL in data.
payment.captured
Funds captured.
payment.failed
Final failure after any cascades.
payment.refunded
Refund completed by the provider.
payment.cascaded
A cascade attempt started; includes reason.
dispute.created
Chargeback or retrieval received.
dispute.updated
Status or deadline changed.
payout.settled
Provider payout reconciled.
provider.health_changed
Connector demoted or recovered.
Need sandbox access?
Sandbox tenants are issued after a short call so we can configure simulated providers for your use case.
Request sandbox access

API reference

The AQ Pay API is REST over HTTPS with JSON bodies. Resources are consistent across every connected provider; provider-specific details appear in a route object rather than in the shape of the resource. This reference describes the v1 contract; a machine-readable OpenAPI document will be published alongside the sandbox.

Authentication

Server calls use a secret key in the Authorization: Bearer header. Browser-side tokenization uses a publishable key that can only create tokens. Keys are scoped to one environment and one tenant.

{{ k.p }}
{{ k.t }}
{{ k.d }}

Conventions

{{ c.k }}{{ c.v }}

Error model

Errors return a stable type and code. Provider decline codes are normalised into a shared taxonomy and the raw provider code is preserved for support.

{ "error": {
    "type": "card_declined",
    "code": "insufficient_funds",
    "retryable": false,
    "provider": { "id": "acquirer_a", "raw_code": "51" },
    "request_id": "req_…" } }

{{ r.t }}

{{ r.d }}

{{ e.m }}{{ e.p }}{{ e.d }}
Key fields
{{ f.n }}{{ f.ty }}{{ f.d }}

Webhooks

Events are signed with an HMAC-SHA256 over timestamp.body using your endpoint secret, delivered at least once, and retried with exponential backoff for 24 hours until your endpoint returns 2xx. Reject signatures older than five minutes to prevent replay.

{{ ev.t }}
{{ ev.d }}
Need sandbox access?
Sandbox tenants are issued after a short call so we can configure simulated providers for your use case.
Request sandbox access