Reference

API reference

The 115 operations of API Gateway v1, generated from the OpenAPI contract pinned by the SDKs: verb, path, parameters, body, responses, idempotency and the equivalent method in Python, JavaScript/TypeScript, PHP, .NET and Go.

The reference is generated on every build from data/gateway-v1.json, a copy of the OpenAPI 3.1 contract that the gateway publishes at /v1/openapi.json and that all five SDKs pin in their parity tests (gateway develop 9cf78da, 2026-10-27). It isn’t edited by hand: it’s regenerated with scripts/sync_contract.py (see the repository README).

The published contract has 102 paths and 115 operations (45 writes with an Idempotency-Key) across 13 tags, and 80 reusable schemas.

TagPageOperationsWhat it covers
affiliatesAffiliates3Matching and ingestion of the entity’s affiliate base: by JSON batch, by file, and lookup by document.
creditsCredits5Credit origination: submit applications to the decision engine (BRE), look them up, decide on them and disburse them.
subsidiesSubsidies4Submitting and deciding statutory subsidies (unemployment, housing…) and custom ones.
monetary-allowanceMonetary allowance3Generating the monetary allowance period, looking it up and disbursing it.
walletWallet24Wallet: balance, movements, P2P, Bre-B, bills, top-ups, accounts and pockets, cards and FX. The account holder is identified by document.
loansLoans12The life of a disbursed credit: payment plan, installments, collections, extraordinary partial payments, payoff and certificates.
pqrsPQRS6Petitions, complaints, claims and suggestions from the entity’s CRM or call center.
healthHealth services15For healthcare providers (IPS): catalog and schedule, appointments on the patient’s behalf, healthcare billing (DIAN, RIPS, billing objections, collection) and vaccination card.
adminAdministrative25ERP module: human resources, payroll, accounting and treasury. Documents come in as drafts (DRAFT); approvals still happen in the dashboard.
webhooksWebhooks11Webhook self-service via the API: event catalog, endpoints, secret rotation, test events, deliveries and redeliveries.
sandboxSandbox5Deterministic simulation for sandbox keys: test clocks and lifecycle advancement. Production keys get a 403.
transactionsTransactions1Status of an asynchronous gateway transaction by its transaction_id.
systemSystem1Gateway health and key introspection: tenant and scopes.

How to read each operation #

  • Verb and path. Every path lives under /v1/gateway/. The base URL depends on the environment (see Environments and keys); the path always includes /v1.
  • Authentication. Every operation requires the X-API-Key header with a cmp_... key. The key identifies the tenant: you don’t send any entity id. Details in Authentication.
  • Idempotency-Key. Required on writes that move money (P2P, Bre-B, bills, top-ups): without it the gateway responds 400. Recommended on all other writes: the SDKs generate it for you. Reads and POSTs that only query (resolve, quote, look up a bill, calculate taxes, simulators) don’t carry it. See Idempotency.
  • Responses. Reads return the engine’s body; writes return the transaction envelope {status, transaction_id, module, data}. Errors follow RFC 9457 (application/problem+json): see Errors.
  • Example. Tabs with each SDK’s method (derived from its parity suite) and a curl ready for the sandbox.

Schemas #

The 80 reusable schemas (components.schemas) are in Schemas. Amounts use MoneyCOP: decimal string.