API overview

Centrobill provides a REST API for accepting payments, managing consumers, and handling payment lifecycle events. Use the API to integrate secure payment flows.

All API access occurs over HTTPS. Two environments are available: Staging for development and testing, and a Production environment for production traffic. Make sure you send requests to the correct environment. Requests sent to the wrong environment are rejected.

The API is organized into functional groups: payment initiation, subscription management, merchant object configuration (Sites and SKUs), consumer management, payouts, and reporting. Each group is documented in its own section of this reference.

Environments

Centrobill provides two base URLs. Use the Staging environment for all development and QA work. The Staging environment accepts real API requests but does not process actual financial transactions.

To verify that the Staging environment will accept requests from your server, you can retrieve the current list of Centrobill IP addresses via GET /ips and add your server's IP address if needed.

The Staging environment includes a dedicated Test Data API that allows you to create synthetic payment credentials, simulate 3DS authentication flows, emulate approvals and declines, and adjust balances for testing purposes without issuing real charges.

Authentication

All requests to protected endpoints must include an API key in the Authorization HTTP header. Keys are issued per merchant account and should be treated as secrets — do not include them in client-side code or commit them to version control.

curl -X POST https://api.centrobill.com/payment \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Requests that omit the Authorization header, or that supply an invalid key, receive a 401 Unauthorized response. Requests that supply a valid key but lack the required permissions receive a 403 Forbidden response.

The tokenization endpoint (POST /tokenize) does not require an API key in the header, as it is designed to be called from a PCI-compliant client context where raw card data is exchanged for a short-lived token before any server-side processing occurs.

Requests & responses

The API accepts application/json request bodies and returns application/json responses. Set the Content-Type: application/json header on all POST and PUT requests.

Successful creation operations return HTTP 201 Created. Successful retrieval and update operations return HTTP 200 OK. The response body is always a JSON object.

HTTP status codes

X-Request-ID header

All endpoints accept an X-Request-ID header containing a unique string you supply. Including it on all POST requests is strongly recommended: the value is recorded in server logs, making it easier to correlate requests with Centrobill support queries, and it is the basis for idempotency.

Metadata

Payment and payout requests accept an optional metadata object. Use this field to attach arbitrary key-value pairs to a transaction. For example, to reference an internal order ID or a user identifier from your system. Centrobill returns metadata in IPN callbacks and the Feed API but doesn't process it.

{
  "metadata": {
    "orderId": "ord_9182",
    "userId":  "usr_4242"
  }
}

Error handling

When a request can't be processed, the API returns an HTTP status code and a JSON error object describing the reason.

Payment outcomes are reported separately from transport-level errors. A payment request that reaches the gateway but is declined by the issuer returns 201 Created at the HTTP level. The decline is indicated by payment.status and payment.code in the response body. A payment.code of "0" with payment.status of "success" indicates approval.

IPN (Instant payment notification)

Centrobill uses IPNs to notify your server of asynchronous payment events. When a transaction event occurs — such as a payment, subscription renewal, or chargeback — Centrobill sends an HTTP POST to the ipnUrl you specify per request. Your endpoint must respond with 200, 201, or 202. If none of these codes is received, Centrobill retries the notification according to a documented retry schedule. More on IPNs:

Idempotency

To safely retry a failed request without risking a duplicate charge, include a unique string in the X-Request-ID header. If Centrobill receives a second request with the same X-Request-ID within the deduplication window, it returns the result of the original request instead of processing a new transaction.

Generate a new X-Request-ID for each distinct payment attempt. Reuse the same value only when retrying the same operation after a network failure or timeout.

Payment API (receive payments)

The Payment API covers four payment initiation flows: tokenization, tokenization using a payment account and consumer ID, server-to-server charges, and the Hosted Payment Page.

Payout API (return payments)

The Payout API transfers funds from your merchant balance to a consumer's payment account or external destination. Supported payout methods include Card, PayId, Crypto, ACH, SEPA, Pix, Netbanking, Token of tokenized card data for payouts, Chile_transfers, and SPEI.

Site API

A site represents a merchant website. Each site has a unique ID and stores default configuration values, including the IPN URL and redirect URL. Payment requests reference a site via siteId.

Product (SKU) API

A SKU defines a billing product: its title, associated site, and price schedule.

Subscription API

The Subscription API lets you retrieve subscription state and manage the subscription lifecycle after initial creation.

Consumer API

A consumer object represents an end user in the Centrobill system. Once created, a consumer accumulates payment accounts (stored representations of their payment methods) that you can use to initiate subsequent charges without re-entering card details.

Service API

The Service API provides operational utilities for IP allowlisting, chargeback management, and Apple Pay session initialization.

Feed API

The Feed API provides paginated access to your full transaction history. Use it for reconciliation, reporting, and auditing. You can filter transactions by date range, status, mode, payment type, PSP name, card BIN, consumer email, site, and many other fields.

Test data API

The Test Data API is available in the Staging environment only. It lets you create and manage synthetic payment credentials for testing payment flows without issuing real charges.

Verification API

The Verification API supports consumer identity verification. It sends a one-time code via an available channel — such as SMS or email — and validates the code that the consumer submits.

Currency exchange API

The Currency Exchange API returns the exchange rates that Centrobill uses for currency conversion. You can retrieve all rates or query a specific rate by ISO 3-letter currency code.