Credits · Compense Docs

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.

Operations in tag `credits` #

Contract description: Credit application intake, decisioning and disbursement (→ BRE pipeline).

Method	Path	Operation	Scope	Idem.
POST	`/v1/gateway/credits/application/`	Submit a credit (→ BRE pipeline)	`credits:submit`	recommended
GET	`/v1/gateway/credits/applications/`	Credit application inbox	`credits:read`	—
GET	`/v1/gateway/credits/applications/{app_id}/`	Credit application detail	`credits:read`	—
POST	`/v1/gateway/credits/applications/{app_id}/decision/`	Approve / reject a credit	`credits:decide`	recommended
POST	`/v1/gateway/credits/applications/{app_id}/disburse/`	Disburse a credit	`credits:disburse`	recommended

Submit a credit (→ BRE pipeline) #

POST/v1/gateway/credits/application/

operationId submitCreditApplication
Authentication X-API-Key · scope credits:submit
Idempotency-Key recommended (the SDK generates it)

Parameters

Name	In	Type	Description
`Idempotency-Key`	header	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. E.g.: `horizonte-2026-06-26-credit-000123`

Request body

Content type: application/json · required

Schema CreditApplicationIn — Credit application submitted into the BRE pipeline. Proxied to the engine as-is.

Field	Type	Description
`afiliado` required	`AffiliateRef`
`amount` required	`MoneyCOP`
`external_reference` required	string	Caja-side application id; echoed back and used for idempotency correlation. E.g.: `"HORIZONTE-CRED-2026-000123"`
`product_code` required	string	E.g.: `"LIBRANZA_12M"`
`purpose`	string (nullable)	E.g.: `"Compra de cartera"`
`term_months` required	integer	E.g.: `12` Range 1–120.

Accepts additional fields (additionalProperties): they're forwarded to the engine unchanged.

Responses

Code	Description	Body
200	Accepted; transaction enqueued / processed.	`TransactionEnvelope` application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.credits.submit_application()

client.credits.submitApplication()

$client->credits->submitApplication()

await client.Credits.SubmitApplicationAsync()

client.Credits.SubmitApplication(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/credits/application/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "afiliado": {
      "document_type": "CC",
      "document_number": "1032456789"
    },
    "product_code": "LIBRANZA_12M",
    "amount": "3500000",
    "term_months": 12,
    "purpose": "Compra de cartera",
    "external_reference": "HORIZONTE-CRED-2026-000123"
  }'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Credit application inbox #

GET/v1/gateway/credits/applications/

operationId listCreditApplications
Authentication X-API-Key · scope credits:read
Idempotency-Key not applicable

Parameters

Name	In	Type
`page`	query	integer
`page_size`	query	integer
`search`	query	string
`status`	query	string

Responses

Code	Description	Body
200	Paginated credit applications.	`Page` application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.credits.list_applications()

client.credits.listApplications()

$client->credits->listApplications()

await client.Credits.ListApplicationsAsync()

client.Credits.ListApplications(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/credits/applications/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Credit application detail #

GET/v1/gateway/credits/applications/{app_id}/

operationId getCreditApplication
Authentication X-API-Key · scope credits:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`app_id` required	path	string	Credit application id. E.g.: `CRED-2026-000123`

Responses

Code	Description	Body
200	Credit application detail.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.credits.get_application()

client.credits.getApplication()

$client->credits->getApplication()

await client.Credits.GetApplicationAsync()

client.Credits.GetApplication(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/credits/applications/CRED-2026-000123/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Approve / reject a credit #

POST/v1/gateway/credits/applications/{app_id}/decision/

operationId decideCreditApplication
Authentication X-API-Key · scope credits:decide
Idempotency-Key recommended (the SDK generates it)

Parameters

Name	In	Type	Description
`app_id` required	path	string	Credit application id. E.g.: `CRED-2026-000123`
`Idempotency-Key`	header	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. E.g.: `horizonte-2026-06-26-credit-000123`

Request body

Content type: application/json · required

Schema CreditDecisionIn

Field	Type	Description
`approved_amount`	`MoneyCOP`	Required when decision is APPROVE.
`decision` required	string	Values: `APPROVE`, `REJECT`. E.g.: `"APPROVE"`
`reason`	string (nullable)	E.g.: `"Cumple capacidad de pago."`

Accepts additional fields (additionalProperties): they're forwarded to the engine unchanged.

Responses

Code	Description	Body
200	Accepted; transaction enqueued / processed.	`TransactionEnvelope` application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.credits.decide_application()

client.credits.decideApplication()

$client->credits->decideApplication()

await client.Credits.DecideApplicationAsync()

client.Credits.DecideApplication(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/credits/applications/CRED-2026-000123/decision/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "APPROVE",
    "approved_amount": "3500000",
    "reason": "Cumple capacidad de pago."
  }'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Disburse a credit #

POST/v1/gateway/credits/applications/{app_id}/disburse/

operationId disburseCreditApplication
Authentication X-API-Key · scope credits:disburse
Idempotency-Key recommended (the SDK generates it)

Parameters

Name	In	Type	Description
`app_id` required	path	string	Credit application id. E.g.: `CRED-2026-000123`
`Idempotency-Key`	header	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. E.g.: `horizonte-2026-06-26-credit-000123`

Responses

Code	Description	Body
200	Accepted; transaction enqueued / processed.	`TransactionEnvelope` application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.credits.disburse_application()

client.credits.disburseApplication()

$client->credits->disburseApplication()

await client.Credits.DisburseApplicationAsync()

client.Credits.DisburseApplication(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/credits/applications/CRED-2026-000123/disburse/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Operations in tag credits #

Submit a credit (→ BRE pipeline) #

Parameters

Request body

Responses

Example

Credit application inbox #

Parameters

Responses

Example

Credit application detail #

Parameters

Responses

Example

Approve / reject a credit #

Parameters

Request body

Responses

Example

Disburse a credit #

Parameters

Responses

Example

Operations in tag `credits` #