Postback system

🇨🇴 Leer en español →

Overview #

When a consumer applies for one of your products through Prosperas,
you process that application on your side (approve it, disburse it,
reject it). A postback is how you tell Prosperas what
happened, in near real time, so we can update the lead status, reconcile
revenue, and keep the consumer experience in sync.

The integration is deliberately small: one endpoint, one
credential, one payload shape.

{BASE_URL} is the Prosperas base URL for your market
(Colombia / Mexico). Prosperas will give you the exact staging and
production URLs during onboarding.

Authentication #

Every postback must authenticate. Prosperas checks the API
key first, then the source IP. If neither
matches a registered credential, the request is rejected with
403.

API key (recommended) #

Send your key in the HTTP header:

X-API-KEY: <your-key>

• The header name is case-insensitive
  (X-API-KEY, x-api-key, X-Api-Key
  all work).
• The key is matched by exact string. No prefix, no
  Bearer, no encoding.

IP allowlist (alternative) #

If you were provisioned by IP, no header is required — we read your
source IP from X-Forwarded-For, then
X-Real-IP, then the socket peer.

• The match is exact string against the IP we
  registered.
• No CIDR / subnet ranges are supported. Every
  individual egress IP you use must be registered. If your infrastructure
  rotates IPs, use the API key method instead.

The “a lead must exist” rule #

Authentication is not only about the credential — it is bound to a
real lead. A request succeeds only when all of the
following hold:

1. Your credential (key or IP) matches a registered lender origin,
   and
2. the click_id in the request resolves to a lead,
   and
3. that lead belongs to a product owned by your lender
   account.

If your credential is valid but the click_id does not
resolve to one of your leads, you still get
403 (not 404). In practice
this means: a wrong, unknown, or foreign click_id
returns 403.

Security note: There is no HMAC / request-signing on
this endpoint. Protect your API key like any other secret: store it in a
secrets manager, never commit it, never send it in plaintext, and ask
Prosperas to rotate it if it is ever exposed.

The tracking id
(click_id) #

click_id is the single identifier that ties a consumer’s
journey together across Prosperas and your systems.

• Prosperas generates it and hands it to you at the moment the
  consumer is redirected to you (as the tracking / click identifier in the
  hand-off URL).
• You must store it and echo it back — exactly — in every
  postback for that application.
• It carries no personal data; it is an opaque
  reference.

Accepted formats:

More than one underscore, or an unparseable UUID, returns
400.

Request contract #

Method: POST (recommended). A
GET variant exists with the same fields as query
parameters, but POST with a JSON body is the supported server-to-server
method.

Headers:

Content-Type: application/json
X-API-KEY: <your-key>

Body (JSON, snake_case):

{
  "click_id": "claro_7e1c2f1f-9b4d-4c1d-9f6c-2f3c1a2b4d5e",
  "event": "approval",
  "occurred_at": "2026-07-01T12:34:56Z",
  "data": {
    "provider": "your-brand",
    "client": {
      "email": "consumer@example.com",
      "fullName": "Ana Gomez",
      "firstName": "Ana",
      "lastName": "Gomez",
      "idNumber": "1234567890",
      "phoneNumber": "3001234567",
      "returningCustomer": false
    }
  }
}

Field reference #

The data.client
object (optional) #

data.client lets you enrich the consumer record.
All fields are optional.

Important — we never overwrite consumer-entered
data. data.client only fills fields that are
currently empty on the consumer’s record. Anything the
consumer already provided in the Prosperas flow wins. This protects data
the consumer explicitly entered.

Caution — returningCustomer is not
sticky. If you omit returningCustomer on a
postback, it is treated as false. If you rely on this flag,
send it explicitly on every postback where it should be
true.

Events & lifecycle #

Send one postback per status transition, using the event that matches
what happened:

application is accepted but optional — send it if you
have a meaningful “application received” milestone; otherwise the three
terminal outcomes (approval, disbursement,
rejected) are what matter most.

Send events in the order they occur. Prosperas
tolerates events arriving out of order, but in-order delivery keeps the
lead history clean.

Responses & status codes #

Success body (200 OK):

{
  "ok": true,
  "lead_id": 12345,
  "status": "APPROVAL",
  "user_id": 6789
}

• ok — always true on success.
• lead_id — the Prosperas lead the event was recorded
  against.
• status — the internal status your event mapped to
  (APPLICATION / APPROVAL /
  DISBURSEMENT / REJECTED).
• user_id — the consumer record id, when available.

Status codes:

Common mistakes
(read this before you build) #

These four mistakes account for almost every failed first
integration. Avoid them:

Retries & delivery
guarantees #

• You own retries. Prosperas does
  not retry you. On a 5xx or a network
  failure, retry the postback with exponential backoff
  (e.g. 1s, 2s, 4s, 8s…), up to a sensible ceiling.
• Do not retry on 4xx. A
  400, 403, or 422 means the
  request is wrong — fix it and send a corrected request instead of
  hammering the same payload.
• The endpoint is not idempotent. Each accepted
  postback records a new event. If you retry after a request that actually
  succeeded (but whose response you missed), you may create a duplicate
  event. Keep retries bounded and prefer retrying only on confirmed
  failures.
• Every request is logged on our side (with your API
  key masked) for support and reconciliation.

Worked examples #

Happy path — approval (POST) #

curl -X POST "{BASE_URL}/client_app/webhook/lender/loan-status" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <your-key>" \
  -d '{
    "click_id": "claro_7e1c2f1f-9b4d-4c1d-9f6c-2f3c1a2b4d5e",
    "event": "approval",
    "occurred_at": "2026-07-01T12:34:56Z",
    "data": { "provider": "your-brand" }
  }'

Response — 200 OK:

{ "ok": true, "lead_id": 12345, "status": "APPROVAL", "user_id": 6789 }

Disbursement with
consumer enrichment (POST) #

curl -X POST "{BASE_URL}/client_app/webhook/lender/loan-status" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <your-key>" \
  -d '{
    "click_id": "7e1c2f1f-9b4d-4c1d-9f6c-2f3c1a2b4d5e",
    "event": "disbursement",
    "occurred_at": "2026-07-01T15:00:00Z",
    "data": {
      "provider": "your-brand",
      "client": { "fullName": "Ana Gomez", "idNumber": "1234567890" }
    }
  }'

Error — camelCase field
(422) #

# WRONG: "clickId" (camelCase) instead of "click_id"
curl -X POST "{BASE_URL}/client_app/webhook/lender/loan-status" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <your-key>" \
  -d '{ "clickId": "7e1c2f1f-...", "event": "approval" }'
# → 422 Unprocessable Entity (field "click_id" is required)

Error — missing / wrong
credential (403) #

# No X-API-KEY header and IP not allowlisted → 403
curl -X POST "{BASE_URL}/client_app/webhook/lender/loan-status" \
  -H "Content-Type: application/json" \
  -d '{ "click_id": "7e1c2f1f-...", "event": "approval" }'
# → 403 Forbidden

Quick reference #

Important notes #

Casing: top-level fields are snake_case (click_id, occurred_at). The nested data.client object uses camelCase (fullName, idNumber, returningCustomer) — this is intentional, not a bug.

Response: you send event lowercase (approval); the response returns status in UPPERCASE (APPROVAL). This is expected.

Idempotency & retries: the endpoint is not idempotent and Prosperas does not retry you. If a timeout leaves you without a response after we recorded the event, a retry creates a duplicate event. Recommendation: retry only on 5xx or network errors, with exponential backoff (1s, 2s, 4s…, max 3 attempts), and dedupe on your side by click_id + event + occurred_at. (Note: your decision/submission API in the Embedded Flow MUST be idempotent by tracking ID — that direction we do retry.)

Last verified: 2026-07-01 · v1.1 · matches
Lender-Postback-Integration-Guide.md