Compense Developers on Compense Docs

Affiliates

Mon, 01 Jan 0001 00:00:00 +0000

The affiliates module is the entry point for any integration: credits, subsidies, monetary allowance and loan portfolio all resolve the affiliate by their document, and the engine rejects the operation if that document isn’t in your entity’s registry. Here you learn how to keep that registry up to date from your system (core, ERP, SOFIA or a spreadsheet) and how to query it.

Affiliates

Mon, 01 Jan 0001 00:00:00 +0000

This page is generated from the contract (data/gateway-v1.json): each operation shows its verb, path, parameters, body, responses, whether it carries an Idempotency-Key, and the equivalent method in all five SDKs. For the end-to-end flow with complete examples, see the implementation guide.

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Every request to the gateway carries one authentication header:

HTTP

X-API-Key: cmp_...

There’s no OAuth, no session tokens and no tenant id in the URL: the key is self-identifying. The gateway looks it up, checks that it’s active and not expired, and derives from it the tenant (your entity), the scopes, the environment (sandbox/prod), the per-minute limit and the monthly quota. The SDKs set the header for you on every call.

Disburse a credit and reconcile

Mon, 01 Jan 0001 00:00:00 +0000

Caja Horizonte originates payroll-deduction loans (libranzas) from its ERP. The analyst approves in the ERP, treasury orders the disbursement, and accounting needs to know, without asking anyone, when the money went out, how much, and against which application. This recipe builds that circuit end to end with the gateway: submit → decide → disburse → receive credits.disbursed → reconcile.

Frequently asked questions

Mon, 01 Jan 0001 00:00:00 +0000

Keys and environments #

Where do I put the id of my family compensation fund (caja de compensación) or my entity? #

Nowhere. The cmp_... key identifies the tenant; the gateway resolves it on its own. Affiliates, patients or account holders are identified by their document.

Get your API key

Mon, 01 Jan 0001 00:00:00 +0000

The entire API Gateway authenticates with an API key that your system sends in the X-API-Key header. The key identifies your entity (the tenant): you never send the id of a family compensation fund (caja de compensación) or of an organization, and a key never sees another tenant’s data.

Python

Mon, 01 Jan 0001 00:00:00 +0000


Package	`compense-sdk-python` (imported as `compense_gateway`)
Version	1.1.0 · API v1
Requirements	Python 3.9+
Dependencies	`httpx` (the `models` and `webhooks` modules only use the standard library)
Repository	Appiasoft/compense-saas-sdk-python · guides in `Docs/features/`

This is the reference SDK: the others compare their requests against what this one sends.

Subscribe an endpoint

Mon, 01 Jan 0001 00:00:00 +0000

An endpoint is a URL you own that receives events. You register it with your API key, choose which events it subscribes to, and Compense returns, only once, the secret it will use to sign every delivery. Everything you do here is tied to the organization that owns the key: an id from another organization responds 404.

Test clocks

Mon, 01 Jan 0001 00:00:00 +0000

Some behaviors only show up as time passes: an installment that goes past due, an obligation that comes due, a subsidy that requires a minimum membership period. Testing them by waiting real days isn’t an option. A test clock is a virtual time source: you freeze it on a date (frozen_time) and move it forward as many times as you like; its current_time is the “now” of your scenario.

Credits

Mon, 01 Jan 0001 00:00:00 +0000

The credits module exposes Compense’s origination engine (rules, scoring and disbursement) to your system: you submit an affiliate’s application, your analyst or the engine decides it, and you disburse it. Every step returns a traceable transaction_id and emits a webhook. What happens after the disbursement (payment schedule, collection, payoff certificate) lives in Loan portfolio.

Credits

Mon, 01 Jan 0001 00:00:00 +0000

Event catalog

Mon, 01 Jan 0001 00:00:00 +0000

Each event has a key (credits.decision, wallets.topup.completed, pqrs.responded…) that you use when subscribing an endpoint and that arrives in the X-Webhook-Event header and in the body’s event field. This page is a snapshot of the catalog as of November 1, 2026 (52 events). The source of truth is the live catalog, GET/v1/gateway/webhooks/event-catalog/ : if a new event shows up, you’ll see it there first, along with its payload_example.

Install the SDK

Mon, 01 Jan 0001 00:00:00 +0000

There’s one official SDK per language. All five cover all 115 operations of the gateway with the same names (adapted to each language’s conventions) and handle what every integration ends up doing by hand: authentication, Idempotency-Key on writes, retries with backoff, typed problem+json errors, pagination, deprecation warnings and webhook verification. They’re all on version 1.1.0 and target API v1 (aligned SemVer: SDK major = API major).

JavaScript / TypeScript

Mon, 01 Jan 0001 00:00:00 +0000


Package	`@compense/sdk` (ESM and CommonJS, with TypeScript declarations)
Version	1.1.0 · API v1
Requirements	Node.js 18+ (uses native `fetch`); also Deno, Bun, Cloudflare Workers and Vercel/Next.js edge
Dependencies	None at runtime
Repository	Appiasoft/compense-saas-sdk-js · guides in `docs/` · examples in `examples/`

Install #

Shell

npm install @compense/sdk

 TypeScript
 
 
import { CompenseClient } from "@compense/sdk"; // ESM / TypeScript
// const { CompenseClient } = require("@compense/sdk"); // CommonJS

Client #

 TypeScript
 
 
const client = new CompenseClient({
 apiKey: process.env.COMPENSE_API_KEY!, // required; sent as X-API-Key
 environment: "sandbox", // "production" (default) | "sandbox" | "dev"
 baseUrl: undefined, // another URL; takes precedence over environment
 timeout: 30_000, // ms per attempt
 retry: { maxAttempts: 3, backoffBaseMs: 500, backoffMaxMs: 30_000, jitter: true, retryWrites: false },
 fetch: undefined, // your own fetch (proxy, instrumentation, tests)
 logger: console, // deprecation warnings
});

There’s a single client and everything returns a Promise. The key is a server secret: even though the client works in browsers, never put a key in frontend code.

Lifecycle simulators

Mon, 01 Jan 0001 00:00:00 +0000

Your integration has to react to every state a money movement goes through: show “in progress”, confirm when it settles, reverse if it fails, reconcile if it’s returned. The simulators let you walk through those states in the sandbox one step at a time and reach every terminal state (failures included) without waiting on any provider.

Monetary allowance for the period

Mon, 01 Jan 0001 00:00:00 +0000

Every month, Caja Horizonte calculates the monetary allowance for its affiliates and pays it out. A mistake here is expensive: paying thousands of affiliates twice, or leaving half of them unpaid because the process crashed halfway through the batch. This recipe closes the October 2026 period in a way that can be interrupted and relaunched at any point without paying twice.

Response envelope

Mon, 01 Jan 0001 00:00:00 +0000

The gateway responds in one of two ways, depending on the type of operation.

Writes: the transaction envelope #

Every operation that changes something (the ones that carry an Idempotency-Key) responds with the same envelope, whatever the module:

Support

Mon, 01 Jan 0001 00:00:00 +0000

Channels #

Channel	What it’s for
developers@compense.co	Integration questions, API or SDK errors, keys and technical onboarding.
Your Compense account executive	Contracts, active modules, production keys and rate limits.
User guides	How to operate the platform from the dashboard and the apps (for advisors and operators).

What to include in your message #

The trace_id of the error (or the response’s X-Request-ID header).
The operation (operationId or method and path) and the approximate time with time zone.
The environment (sandbox, dev or production) and the SDK and version (compense-sdk-python 1.1.0…).
Your Idempotency-Key if it was a write.
The error response body (problem+json) and, if relevant, the request without sensitive data.

Never send

Your first call

Mon, 01 Jan 0001 00:00:00 +0000

You’ll be talking to the sandbox: the gateway responds with the simulated engine, deterministically and with no real money. You need a sandbox key and the SDK installed. Pick your language in any tab: your choice is remembered across the whole site.

Idempotency

Mon, 01 Jan 0001 00:00:00 +0000

On a real network, requests get cut off: a timeout, a load balancer that restarts, your process dying right after sending. At that point you don’t know whether Compense executed the operation. If you retry blindly you might disburse twice; if you don’t retry, you might leave a payment undone. The Idempotency-Key resolves that dilemma: retrying with the same key is always safe.

Loan collections

Mon, 01 Jan 0001 00:00:00 +0000

At the Caja Horizonte branch offices, affiliates pay their loan installments in cash, and every month the payroll deduction file (libranza) arrives as well. All that money comes in outside the platform, so the family compensation fund (caja de compensación) has to report it to Compense to keep the balance, delinquency, the affiliate’s app, and the paid-in-full certificate (paz y salvo) up to date. This recipe connects the teller system and the payroll file process to the Loans module.

PHP

Mon, 01 Jan 0001 00:00:00 +0000


Package	`compense/sdk` (namespace `Compense\Sdk`)
Version	1.1.0 · API v1
Requirements	PHP 8.1+ (`declare(strict_types=1)`, `readonly` DTOs)
HTTP	Any PSR-18 client + PSR-17 factories, discovered with `php-http/discovery` (Guzzle suggested)
Repository	Appiasoft/compense-saas-sdk-php · guides in `docs/` · examples in `examples/` (plain PHP and Laravel)

Install #

 Shell
 
 
composer require compense/sdk guzzlehttp/guzzle
# or with Symfony HttpClient:
composer require compense/sdk symfony/http-client nyholm/psr7

Client #

 PHP
 
 
<?php
declare(strict_types=1);

use Compense\Sdk\CompenseClient;
use Compense\Sdk\RetryConfig;

$client = new CompenseClient(
 apiKey: getenv('COMPENSE_API_KEY'), // cmp_...
 environment: 'sandbox', // 'production' (default) | 'sandbox' | 'dev'; or baseUrl: '...'
 timeout: 30.0, // applies when the SDK builds Guzzle
 retry: new RetryConfig(maxAttempts: 3, retryWrites: false),
 httpClient: null, // any PSR-18 (container, mocks…)
 logger: $psrLogger, // PSR-3: deprecation warnings
);

If you pass your own httpClient, set the timeout on it. The PSR-17 factories (requestFactory:, streamFactory:) are discovered automatically if you don’t provide them.

Subsidies

Mon, 01 Jan 0001 00:00:00 +0000

Subsidies and monetary allowance

Mon, 01 Jan 0001 00:00:00 +0000

This module covers both subsidy fronts of a family compensation fund (caja de compensación):

Application-based subsidies (e.g. the unemployment subsidy): the affiliate requests them, you submit them, and an analyst or the rules engine decides them.
Monetary allowance: the cash subsidy per dependent that is settled every period. There is no application here: you generate the month’s settlement, review it and disburse each allowance.

The affiliate must exist in your entity’s registry (see Affiliates).

The compense CLI

Mon, 01 Jan 0001 00:00:00 +0000

compense is a command-line tool for the tasks you do by hand while you integrate: validating a key, browsing the event catalog, registering an endpoint, triggering a test event, reviewing and retrying deliveries, moving a test clock, advancing a simulator and forwarding webhooks to your machine. Each command is a thin wrapper over the SDK and prints the gateway’s response as JSON, so you can pipe it into jq.

Verify the signature

Mon, 01 Jan 0001 00:00:00 +0000

Your endpoint is a public URL: anyone can POST to it. The signature is what guarantees that the body was sent by Compense and that nobody tampered with it along the way. Never process a delivery without verifying it first. This page includes complete receivers in the five SDK languages, plus manual verification in case you don’t use an SDK.

Subsidies

Mon, 01 Jan 0001 00:00:00 +0000

The Subsidies module lets you manage, end to end, the economic aid your family compensation fund (caja de compensación) provides to its affiliates: from the moment the affiliate submits a request in the app or the portal, through the operator’s review and decision, to the disbursement of the money.

Loans

Mon, 01 Jan 0001 00:00:00 +0000

The Loans module covers the full lifecycle of a loan to an affiliate: application → evaluation → decision → disbursement → repayment. The affiliate simulates and applies from the app or the portal; the platform evaluates the risk automatically; the operator decides the amount and the term; and, once disbursed, the affiliate checks and pays their installments.

Payments and Wallet

Mon, 01 Jan 0001 00:00:00 +0000

When your family compensation fund (caja de compensación) approves a subsidy or disburses a loan, the money reaches the affiliate through their digital wallet. This guide explains, for affiliates and operators, what the wallet is, how payments are disbursed, how to check the balance and transactions, and how to verify the status of a disbursement.

Affiliates

Mon, 01 Jan 0001 00:00:00 +0000

The affiliate registry is the master record of the people affiliated with your family compensation fund (caja de compensación). Everything else depends on its accuracy: who gets paid a subsidy, who can receive a monetary allowance, or who meets the requirements for a loan. This guide explains, for operators, how to look up, register and update affiliates and their family group, and how to keep the database up to date.

PQRS

Mon, 01 Jan 0001 00:00:00 +0000

The PQRS (complaints and requests) module is the formal channel for an affiliate of your family compensation fund (caja de compensación) to file a Petición (petition), Queja (complaint), Reclamo (claim) or Sugerencia (suggestion), and for your operators to handle it within the legal deadlines. Each case gets a filing number, moves through a set of statuses and keeps a complete audit trail (who did what and when).

Notifications

Mon, 01 Jan 0001 00:00:00 +0000

Compense keeps the affiliate informed automatically: every time their request moves forward —it’s submitted, decided, disbursed— or their PQRS gets a response, they receive a notice. Your operators don’t have to send anything manually: notifications fire on their own with each business event.

.NET

Mon, 01 Jan 0001 00:00:00 +0000


NuGet package	`Compense.Sdk`
Version	1.1.0 · API v1
Targets	`net8.0` and `netstandard2.0` (.NET Framework 4.6.2+, .NET 6/7/8+, Mono)
Dependencies	`System.Text.Json`, `Microsoft.Extensions.Http`, `Microsoft.Extensions.Logging.Abstractions`, `Microsoft.Extensions.Options.ConfigurationExtensions`
Repository	Appiasoft/compense-saas-sdk-dotnet · guides in `docs/modulos/` · examples in `examples/` (console and webhook receiver)

Install #

Shell

dotnet add package Compense.Sdk --version 1.1.0

Client #

 C#
 
 
using Compense.Sdk;
using Compense.Sdk.Models;

using var client = new CompenseClient(
 Environment.GetEnvironmentVariable("COMPENSE_API_KEY")!, CompenseEnvironment.Sandbox);

// With every option:
var configured = new CompenseClient(new CompenseClientOptions
{
 ApiKey = "cmp_...",
 Environment = CompenseEnvironment.Sandbox, // Production (default) | Sandbox | Dev
 BaseUrl = null, // another URL; takes precedence over Environment
 Timeout = TimeSpan.FromSeconds(30),
 Retry = new RetryOptions { MaxAttempts = 3, RetryWrites = false },
 UserAgent = "horizonte-erp/2.0",
});

You can also use new CompenseClient(httpClient, options) with your own HttpClient (the SDK doesn’t dispose it and ignores its BaseAddress).

Charge an invoice from the wallet

Mon, 01 Jan 0001 00:00:00 +0000

In this recipe, the Nova app lets its users pay their electricity bill from their wallet. You’ll walk through the full flow on Nova’s backend: choose the biller, look up the bill, confirm with the user, pay without any risk of charging twice even if the network fails, learn the outcome by webhook and hand over a receipt. The details of each operation are in the Wallet guide.

Environments and keys

Mon, 01 Jan 0001 00:00:00 +0000

The gateway has a single contract (the same paths, bodies and errors) across all its deployments. What changes between “testing” and “operating” is the key you call with.

Base URL per environment #

Environment	Base URL	Python / JS / PHP	.NET	Go
Production	`https://api.compense.co`	`"production"` (default)	`CompenseEnvironment.Production`	`compense.Production`
Sandbox	`https://sandbox.dev.compense.co/gw`	`"sandbox"`	`CompenseEnvironment.Sandbox`	`compense.Sandbox`
Dev	`https://gateway.dev.compense.co`	`"dev"`	`CompenseEnvironment.Dev`	`compense.Dev`

Every path starts with /v1/gateway/..., so the base URL never includes /v1. The sandbox URL keeps the /gw prefix of the sandbox console: the full path is https://sandbox.dev.compense.co/gw/v1/gateway/health/.
Production is the URL declared in the contract. There’s no public production deployment yet: the final URL is confirmed during onboarding. If it differs, pass it as a custom base URL (base_url, baseUrl, BaseUrl, WithBaseURL), which always takes precedence over the environment.
Dev is Compense’s development gateway, useful for end-to-end testing with real webhooks (with a production key issued for dev).

The key decides, not the URL #

Every key is issued with an environment:

Monetary allowance

Mon, 01 Jan 0001 00:00:00 +0000

Retries and backoff

Mon, 01 Jan 0001 00:00:00 +0000

All five SDKs ship with the same retry policy, designed so that retrying never duplicates an operation.

The default policy #

Parameter	Default value	What it does
Maximum attempts	3 (the first + 2 retries)	`1` disables retries.
Backoff base	0.5 s	Wait before the first retry, doubling on each one.
Backoff cap	30 s	No wait exceeds this value.
Jitter	full	Each wait is random between 0 and the calculated value, so clients don’t all synchronize.
`Retry-After`	honored	If the gateway sends it, the SDK waits exactly that long.
Statuses that are retried	`429`, `502`, `503`, `504`	Transient failures. Never business `4xx` or `500`.
Methods	`GET` only	Writes are retried only with `retry_writes` enabled.
Network errors with no response	not retried	You resend them with the same `Idempotency-Key`.

flowchart TD
 A[Request] --> B{Response?}
 B -- no: timeout / network --> X[Transport exception<br/>resend it yourself with the same key]
 B -- yes --> C{429/502/503/504?}
 C -- no --> D[Success or typed error]
 C -- yes --> E{GET or retry_writes?}
 E -- no --> D
 E -- yes --> F{Attempts left?}
 F -- no --> D
 F -- yes --> G[Wait Retry-After<br/>or backoff with jitter] --> A

Why aren’t writes retried automatically? #

The gateway does deduplicate: every write with a repeated Idempotency-Key returns the stored response (idempotent_replay: true) instead of executing again, on every route that takes a key. The reason is different: the SDK can’t know which version of the gateway it’s talking to, and retrying a write against an older deployment without that guarantee would execute it twice. That’s why the safe default is to retry only GET.

Rotate the secret

Mon, 01 Jan 0001 00:00:00 +0000

Rotate an endpoint’s secret when it leaked (or you suspect it leaked), when someone with access leaves the team, when you lost it, or periodically according to your security policy. Rotation generates a new secret and shows it only once, just like when you create the endpoint.

Test data

Mon, 01 Jan 0001 00:00:00 +0000

Everything in the sandbox is deterministic: the result is decided by the document you send, a few amounts and the ids the sandbox itself returns to you. This page gathers those values so you can write automated tests that cover the happy path and every documented error. Remember that the sandbox doesn’t store state: state travels in the ids, and a write doesn’t change what later reads return (Sandbox).

Wallet

Mon, 01 Jan 0001 00:00:00 +0000

This guide is for the technical team at a fintech (such as Nova) or a family compensation fund (caja de compensación, such as Caja Horizonte) that operates its affiliates’ wallet through the API, with the same rules as the app: balance and transactions, P2P transfers to another affiliate, Bre-B to other banks, utility bill payments, mobile top-ups, sub-accounts (pockets, savings, goals), cards and currency exchange. Everything lives under the contract’s wallet tag and, in the SDKs, under client.wallet.

Go

Mon, 01 Jan 0001 00:00:00 +0000


Module	`github.com/Appiasoft/compense-saas-sdk-go` (package `compense`, subpackage `webhook`)
Version	1.1.0 (`compense.Version`) · API v1
Requirements	Go 1.21+ (`range-over-func` iterators with Go 1.23+)
Dependencies	Standard library only
Repository	Appiasoft/compense-saas-sdk-go · guides in `docs/` · examples in `examples/`

Install #

 Shell
 
 
go get github.com/Appiasoft/compense-saas-sdk-go@v1.1.0
# Private repository: GOPRIVATE=github.com/Appiasoft/* and git credentials

Client #

 Go
 
 
import compense "github.com/Appiasoft/compense-saas-sdk-go"

client, err := compense.NewClient(os.Getenv("COMPENSE_API_KEY"),
	compense.WithEnvironment(compense.Sandbox), // Production (default) | Sandbox | Dev
	compense.WithBaseURL("https://gw.example.co"), // another URL; takes precedence over the environment
	compense.WithHTTPClient(myHTTPClient), // proxies, mTLS, tracing, tests (not modified)
	compense.WithTimeout(30*time.Second), // per attempt (only for the client the SDK creates)
	compense.WithRetry(compense.RetryConfig{MaxAttempts: 3}),
	compense.WithRetryWrites(false),
	compense.WithUserAgent("horizonte-erp/2.0"),
	compense.WithLogger(slog.Default()), // deprecation warnings
)
if err != nil {
	log.Fatal(err) // *compense.ConfigError
}

The *Client is safe for concurrent use: create one per key and reuse it. Every method takes a context.Context first (deadlines and cancellation, including during the waits between retries).

Loan portfolio

Mon, 01 Jan 0001 00:00:00 +0000

The loans module picks up where Credit leaves off: once disbursed, the loan has an installment schedule, interest, arrears and a balance. From your system you can query all of that (for your online branch, your call center or your ERP) and report the collections your entity receives outside the platform: the cash desk, payroll or libranza (payroll-deduction) deductions, the bank file, an extra payment or a full payoff.

problem+json errors

Mon, 01 Jan 0001 00:00:00 +0000

Every non-2xx response arrives as application/problem+json (RFC 9457), with the same shape across all 13 modules:

 JSON
 
 
{
 "type": "https://errors.compense.co/gateway/validation",
 "title": "Validation error",
 "status": 422,
 "detail": "One or more fields are invalid.",
 "trace_id": "9f1c2e7a4b8d4e6fa1c0d2e3f4a5b6c7",
 "errors": [
 { "field": "term_months", "message": "Input should be greater than or equal to 1" }
 ]
}

Field	What it is
`type`	URI of the error type (or `about:blank`). Use it to tell apart cases that share a code.
`title`	Short summary in English.
`status`	The HTTP code.
`detail`	Explanation. For engine rejections it carries the engine’s message in Spanish (for example «Saldo insuficiente»); when the engine sends no message, the gateway quotes its code (`(code: INSUFFICIENT_FUNDS)`).
`trace_id`	Same as the `X-Request-ID` header. Always give it to support.
`errors`	Only on `422`: a list of `{field, message}`.

The gateway never forwards the engine’s raw body or stack trace: on 502/504 the detail is generic and the real error is logged under the trace_id.

Retries and deliveries

Mon, 01 Jan 0001 00:00:00 +0000

Every time Compense tries to bring an event to one of your endpoints it creates a delivery. If your receiver doesn’t respond 2xx, the delivery is retried automatically; and everything is kept in a history you can query, filter and, for deliveries that failed, retry manually.

Send money: P2P and Bre-B

Mon, 01 Jan 0001 00:00:00 +0000

In this recipe, the Nova app lets users send money to anyone using their mobile number, email, ID number, or alias. If the recipient is also a Nova user, the transfer is an internal, instant P2P transfer; if their key is at another bank, it goes through Bre-B (Colombia’s instant payments). Nova’s backend picks the rail, shows who is going to be paid, sends within the token’s lifetime, and reconciles the final result by webhook. The operations are described in Wallet.

Wallet

Mon, 01 Jan 0001 00:00:00 +0000

Loans

Mon, 01 Jan 0001 00:00:00 +0000

Medical appointment and EPS collection

Mon, 01 Jan 0001 00:00:00 +0000

IPS Horizonte Salud, a healthcare provider (IPS), books appointments from its call center and its portal, and reconciles the transfers it receives from each EPS (health insurer) in its accounts receivable system. In this recipe you connect that journey to Compense: you find a slot, book on the patient’s behalf, send a reminder, handle cancellations and reschedules, record attendance, locate the invoice for the visit and register the EPS payment without duplicating it. The details of each operation are in the Health guide.

Pagination

Mon, 01 Jan 0001 00:00:00 +0000

Gateway lists come in one of two shapes:

Shape	Fields	Parameters	Where
`Page`	`count`, `results`, `next`, `previous`	`page`, `page_size`	Credit and subsidy queues, monetary allowance, PQRS, health (appointments, invoices, billing objections, schedule), administrative, webhook deliveries, loans
`OffsetPage`	`results`, `limit`, `offset`, `has_more`, `next_offset`	`limit`, `offset`	Wallet movements and bill payments

In every SDK a page is iterable over its results and keeps the original body in raw. What differs is how you request the next ones.

PQRS

Mon, 01 Jan 0001 00:00:00 +0000

With this module, your CRM or call center manages your affiliates’ PQRS (complaints and requests: petitions, complaints, claims and suggestions) server-to-server, without logging in to the Compense dashboard: you submit cases on the affiliate’s behalf, list and filter them (including overdue ones), look up the details with their history, respond as the entity and change the status or priority. The rules are exactly the same as in the app and the dashboard: a PQRS-AAAA-NNNNNN filing number (radicado), a statutory deadline, a state machine and a notification to the affiliate when they get a response.

Test your webhooks

Mon, 01 Jan 0001 00:00:00 +0000

Before going to production you want to see your receiver accept a genuinely signed delivery, reject a tampered one and respond in time. This page covers the four tools to get there: the API test event, the compense CLI (trigger and listen), unit tests without a network and the webhooks sandbox.

Amounts as decimal strings

Mon, 01 Jan 0001 00:00:00 +0000

In the contract, every amount is a decimal string: the MoneyCOP schema ("3500000", "467009.88", "53500.00"). Never a floating-point number.

 JSON
 
{ "amount": "467009.88", "currency": "COP" }

The reason is simple: 0.1 + 0.2 isn’t 0.3 in binary. A float can turn 467009.88 into 467009.87999999995 somewhere along the way (your ORM, your JSON serializer, a spreadsheet), and with money a one-cent difference breaks a reconciliation. A string travels exactly from end to end.

From payroll to accounting

Mon, 01 Jan 0001 00:00:00 +0000

Caja Horizonte records its staff’s overtime and surcharges in a shift system and keeps its books in an ERP. In this recipe you connect both to Compense’s Administrative module: you load the month’s payroll adjustments into the payroll period, wait for payroll to approve it in the panel, read the payslips and the electronic payroll status, and record the journal entry as a draft so the accountant can post it.

Health (IPS)

Mon, 01 Jan 0001 00:00:00 +0000

This guide is for the technical team of a healthcare provider (IPS) (or an entity (organization) that has the health module enabled) integrating its system with Compense server-to-server: appointment scheduling, health billing and the vaccination card. It’s the same gateway and the same security model as loans or the wallet. The examples use IPS Horizonte Salud, which books appointments from its call center and reconciles EPS (health insurer) remittances from its accounts receivable system.

PQRS

Mon, 01 Jan 0001 00:00:00 +0000

Administrative (ERP)

Mon, 01 Jan 0001 00:00:00 +0000

This guide is for the technical team at an entity (a family compensation fund (caja de compensación), fintech or healthcare provider (IPS)) that integrates its ERP with Compense’s Administrative Management (Gestión Administrativa) module: HR, payroll, accounting and treasury. Everything is server-to-server with the entity’s key; no end user is involved. The examples use Caja Horizonte’s ERP, which identifies its documents with HORIZONTE-ERP-… references.

Health services

Mon, 01 Jan 0001 00:00:00 +0000

Versioning and deprecations

Mon, 01 Jan 0001 00:00:00 +0000

Versions #

The API is on major version v1, which is part of the path (/v1/gateway/...). Within v1 only backward-compatible changes are made.
The SDKs follow SemVer aligned with the API: the SDK’s major version is the API’s major version (1.x talks to v1). They’re all currently on 1.1.0 (changelog).

Backward-compatible changes (may ship without notice) #

New operations, modules and webhook events.
New fields in responses and in the webhook resource (the event’s version doesn’t change).
New optional parameters.
New values in response enumerations (statuses, categories).

Write your integration to tolerate them: ignore fields you don’t recognize, don’t validate the event catalog against a closed list, and treat unknown statuses as “pending review”.

Administrative

Mon, 01 Jan 0001 00:00:00 +0000

Rate limits and quotas

Mon, 01 Jan 0001 00:00:00 +0000

Every key has two limits, configured when it’s issued:

Limit	Default value	When exceeded
Per minute	120 requests per minute	`429` with `Retry-After` until the window frees up
Monthly quota (optional)	No quota, unless your contract sets one	Warnings when thresholds are crossed and, depending on the contract, `429` until the next period

If your volume needs more, ask for it during onboarding or from support: the limit is adjusted per key.

Transactions and system

Mon, 01 Jan 0001 00:00:00 +0000

Two cross-cutting operations that don’t belong to any business module, but that every integration uses:

Operation	SDK method (Python)	Scope	Used for
GET`/v1/gateway/transactions/{tx_id}/`	`client.transactions.get(tx_id)`	none (any valid key)	State and trace of a write you made through the gateway.
GET`/v1/gateway/health/`	`client.system.health()`	none	Validate the key: tenant and scopes. Health check for your monitoring.

In the other SDKs: client.transactions.get / client.system.health() (TypeScript), $client->transactions->get / $client->system->health() (PHP), client.Transactions.GetAsync / client.System.HealthAsync() (.NET) and client.Transactions.Get / client.System.Health (Go).

Webhooks

Mon, 01 Jan 0001 00:00:00 +0000

Sandbox

Mon, 01 Jan 0001 00:00:00 +0000

Transactions

Mon, 01 Jan 0001 00:00:00 +0000

System

Mon, 01 Jan 0001 00:00:00 +0000

Schemas

Mon, 01 Jan 0001 00:00:00 +0000

The contract’s schemas exactly as the gateway publishes them. Fields marked as required must be sent in the request; additionalProperties means the gateway forwards any additional fields to the engine untouched (which is why the SDKs accept extra / fields).