API Reference

Build server-to-server payment experiences with identities, accounts, payment attempts, payments, checkout sessions, webhooks, and structured errors.

RESTJSONBearer auth

Base URL https://api.conomyhq.com/sandbox

Auth endpoint POST /auth

Version header conomyhq-api-version: 24-04-2025

Authentication

Authenticate once, then send the same request contract everywhere.

Use POST /auth to obtain an access token from your backend. Protected endpoints expect that token as a bearer credential together with your API key, API version when required by the endpoint, and user agent.

Authorization

Bearer access token returned by the authentication endpoint.

x-api-key

API Gateway key assigned to your Conomy integration.

User-Agent

Application identifier used for observability and support.

conomyhq-api-version

Optional version selector on endpoints that define it in OpenAPI.

Request lifecycle

A payment integration moves through a predictable backend flow.

Model actors

Create identities, assign permissions, and attach accounts.

Discover rails

Inspect origins, destinations, products, and banks before creating a payment.

Prepare transaction

Create an attempt, payment link, or checkout session for the product flow.

Execute and observe

Create the payment, retrieve state, and subscribe to webhook updates.

Handle completion

Branch on success, failure, cancellation, or validation states.

Core resources

Start from the resource area that matches the object you are building with.

Identities

Actors, relationships, and permissions.

Accounts

Financial containers, internal balances, and unassigned funds.

Customers

End-user profiles used by checkout flows.

Payments

Attempts, payments, links, sessions, and refunds.

Webhooks

Signed transaction callbacks for asynchronous state changes.

Errors

Stable response shapes and support diagnostics.

Errors

Failures return structured bodies designed for client logic.

Branch on status, code, and type. Treat detail as diagnostic text and include traceId when contacting support.

400

Malformed request or invalid parameter.

401

Missing or invalid credentials.

422

Valid request, invalid resource state.

500

Unexpected platform error, retry with backoff.