Event Catalog

banca.me emits three webhook events. This page documents every field each one carries.

Event	Belongs to	Fires when	Registered through
`loan_approved`	BNPL partners	A BNPL loan is approved	`POST /partner/webhook`
`new_lead`	Real-estate partners	A lead is created, before any evaluation	`POST /partner/webhook/subscription`
`pre_approve`	Real-estate partners	That lead's evaluation completes	`POST /partner/webhook/subscription`

If you are not sure which side you are on, start at Which Webhook Integration Is Yours. For the envelope all three travel in, see Webhook Event Format. Verification differs by integration: HMAC for BNPL, token for real estate.

Choosing events, filtering and scoping is a real-estate feature. On the subscription route you pick which events a destination receives, filter pre_approve by outcome — for example to receive only aprobado — and narrow a destination to a single project. The BNPL route has no equivalent; it always registers a plain loan_approved destination.

A result filter only narrows events that have a result

new_lead fires before any evaluation, so it has no outcome to filter on. A destination subscribed to both events with filters.results set receives every new_lead regardless — the filter applies to pre_approve alone.

This surprises people: narrowing to aprobado does not reduce new_lead traffic at all. If you want a low-volume feed, subscribe a destination to pre_approve only.

Delivery guarantees are not the same for every event

new_lead runs on a tighter budget than the other two — 3-second timeout and no retry, because it fires inside a form submission. See Best Practices.

Telling the events apart

The envelope does not carry an event type. The body is { eventId, data } and nothing in it names the event:

{
  "eventId": "9f2a1c4e-3b8d-4f71-a205-6c9e8d0b1a37",
  "data": { }
}

This only matters if one endpoint is subscribed to more than one event — which, since the two real-estate events go to the same route, is a realistic setup. Discriminating on the payload:

Event	Tell
`loan_approved`	`data.externalTrxId` present
`new_lead`	`data.idBancame` present, `data.estado` absent
`pre_approve`	`data.idBancame` and `data.estado` present

new_lead and pre_approve share eleven identity fields, so idBancame alone does not separate them — you need a field that only the evaluation carries, such as estado or riesgo.

The simpler approach, and the one we recommend, is to register one destination per event type. Each destination has its own URL, so the URL tells you which event arrived and no sniffing is needed.

`loan_approved` — BNPL

The BNPL event. Fires when a BNPL loan is approved; receiving it is itself the confirmation that the loan was approved — there is no status to check to find that out.

Destinations for this event are registered through POST /partner/webhook and verify by HMAC signature.

Fields

Field	Type	Description
`externalTrxId`	string	External transaction identifier — your own reference for the purchase
`loanAmount`	number	Total amount of the loan
`interestRate`	number	Interest rate, as a decimal
`periods`	number	Number of instalments
`installmentAmount`	number	Amount of each instalment
`lastInstallmentAmount`	number	Amount of the final instalment, which may differ from the rest
`state`	string	Current state of the loan — see below
`transferDate`	string	ISO 8601 date the loan was funded
`installments`	array	The payment schedule

Each entry of installments carries:

Field	Type	Description
`state`	string	State of that instalment
`period`	number	Instalment number, starting at 1
`expirationDate`	string	ISO 8601 date the payment is due

Loan states

state reports the loan's situation at the moment of delivery:

ACTIVE — active loan
PARTIAL_PREPAID — partially prepaid
PREPAID — fully prepaid
PAID — fully paid
REFINANCED — refinanced
SOFT_DEBT — overdue, 1 to 30 days
INTERMEDIATE_DEBT — overdue, 31 to 89 days
HARD_DEBT — overdue, 90+ days
RECOVERED — recovered
PUNISHED — written off
OUTSOURCED — outsourced
CANCELED — canceled

Receiving the webhook already tells you the loan was approved, so there is no need to inspect state to confirm that. It is there to tell you what has happened to the loan since.

Example

{
  "eventId": "evt_123456789abcdefghijk",
  "data": {
    "externalTrxId": "txr_abc123def456",
    "loanAmount": 500000,
    "interestRate": 0.015,
    "periods": 3,
    "installmentAmount": 170000,
    "lastInstallmentAmount": 170000,
    "state": "ACTIVE",
    "transferDate": "2023-09-15T15:10:33Z",
    "installments": [
      { "state": "PAID", "period": 1, "expirationDate": "2023-10-15T00:00:00Z" },
      { "state": "ACTIVE", "period": 2, "expirationDate": "2023-11-15T00:00:00Z" },
      { "state": "ACTIVE", "period": 3, "expirationDate": "2023-12-15T00:00:00Z" }
    ]
  }
}

Handling it

function processLoanEvent(event) {
  const { eventId, data } = event;

  updateLoanStatus(data.externalTrxId, data.state);

  const schedule = data.installments.map((inst) => ({
    number: inst.period,
    amount:
      inst.period === data.periods
        ? data.lastInstallmentAmount
        : data.installmentAmount,
    dueDate: new Date(inst.expirationDate),
    status: inst.state,
  }));

  savePaymentSchedule(data.externalTrxId, schedule);
}

`new_lead` — Real estate

Fires the moment a lead is created, before any evaluation has run. It is the first thing you hear about a person.

Registered through POST /partner/webhook/subscription, verifies by token, and requires the evaluation module.

Order matters when you read this against the funnel

new_lead arrives before pre_approve, not after. A lead that abandons the flow before finishing still generated its new_lead — so this event counts arrivals, not qualified leads, and the two will not reconcile. Expect new_lead volume to exceed pre_approve volume.

Fields

Twelve fields, all identity and contact. Eleven of them are byte-for-byte the same as the identity block of pre_approve and come from the same code, so you can map both events with one function. The only difference is fechaCreacion here versus fechaEvaluacion there.

Field	Type	Description
`idBancame`	string	The lead's identifier in banca.me. The `preLoanRequestId` the read endpoints take
`nombre`	string	Given name
`apellidoPaterno`	string	First surname
`apellidoMaterno`	string	Second surname
`rut`	string	National identifier
`telefono`	string \| null	Phone number
`email`	string \| null	Email address
`origen`	string	Where the lead came from (QR, web, bot, ...)
`proyecto`	string \| null	Name of the PartnerEntity the lead belongs to — the readable one
`proyectoIdExterno`	string \| null	The external id you assigned to that PartnerEntity. This is the homologation key
`fechaCreacion`	string	When the lead was created, ISO 8601
`linkBancame`	string	The lead's page in the banca.me portal

No financial data, by design

new_lead carries no risk parameters and no outcome fields — not because they were left out, but because nothing has been evaluated yet when it fires. There is nothing to send. Those fields arrive later, in pre_approve, for the same lead.

Example

{
  "eventId": "4c7e2a91-6d35-4b80-9f12-3a8c5e7d0b24",
  "data": {
    "idBancame": "3f1a9c2e-8b47-4d51-9e6a-2c7d0b5f8a13",
    "nombre": "María",
    "apellidoPaterno": "González",
    "apellidoMaterno": "Pérez",
    "rut": "12345678-9",
    "telefono": "+56912345678",
    "email": "maria.gonzalez@example.com",
    "origen": "inmobiliaria-qr",
    "proyecto": "Condominio Los Robles",
    "proyectoIdExterno": "ex-test-123",
    "fechaCreacion": "2026-09-01T14:05:11.000Z",
    "linkBancame": "https://partners.banca.me/leads/id/3f1a9c2e-8b47-4d51-9e6a-2c7d0b5f8a13"
  }
}

Correlate it with the pre_approve that follows using idBancame: both events carry the same value for the same lead.

`pre_approve` — Real estate

Fires when a lead's risk evaluation completes and produces an outcome — after the new_lead for that same person.

Destinations for this event are registered through POST /partner/webhook/subscription, verify by token, and require the evaluation module. BNPL partners cannot subscribe to it.

The outcome fields are binary — complementable is not one of their values

estado, resultadoHipotecario and resultadoPie are derived from whether the pre-approval was accepted, so each is either aprobado or rechazado and nothing else.

A lead that does not qualify alone but would with an income co-applicant reads estado: "rechazado" together with complementable: true. Read the boolean — branching on estado === "complementable" will never match.

The three-value set aprobado | complementable | rechazado is real, but it belongs to the delivery filters you set when registering a destination, which is a different dimension from the payload fields.

note

There is no "evaluation started" event. The webhook fires when the evaluation finishes; while one is in progress there is nothing to send.

data is a flat object in camelCase — no nesting. The groups below are documentation only; they are not levels in the JSON.

The read API returns the same data in a different shape

The evaluation read endpoints return this same evaluation nested, with hipotecario and pie as sibling blocks, because their consumer is a UI rather than a CRM field mapping. If you consume both the event and the API, expect two shapes of the same data. The correspondence is noted per field below.

Identification and contact

Field	Type	Description
`idBancame`	string	The lead's identifier in banca.me. This is the `preLoanRequestId` the read endpoints take.
`nombre`	string	Given name
`apellidoPaterno`	string	First surname
`apellidoMaterno`	string	Second surname
`rut`	string	National identifier
`telefono`	string \| null	Phone number
`email`	string \| null	Email address

Origin and context

Field	Type	Description
`origen`	string	Where the lead came from (QR, web, bot, ...)
`proyecto`	string \| null	Name of the PartnerEntity the lead belongs to — the readable one
`proyectoIdExterno`	string \| null	The external id you assigned to that PartnerEntity. This is the homologation key
`fechaEvaluacion`	string	When the evaluation ran, ISO 8601
`vigenteHasta`	string \| null	When the evaluation expires, ISO 8601. Mortgage and down-payment pre-approvals last 28 days; other products 14

Outcome

Field	Type	Description
`estado`	string \| null	Overall outcome. Binary: `aprobado` or `rechazado` only
`complementable`	boolean \| null	Whether the lead qualifies with an income co-applicant. This is where "complementable" lives — not in `estado`
`idComplementario`	string \| null	The co-applicant's lead id, when there is one
`grupoSocioeconomico`	string \| null	Net-income bracket, as a display label derived from `sueldoLiquido` — for example `"Desde de $1.500.000 hasta $2.500.000"` or `"Más de $5.500.000"`. Not a letter code

Credit terms

These describe the mortgage product. resultadoPie is the only down-payment field in the event; the read API returns the down payment as a full sibling block.

Field	Type	Description
`resultadoHipotecario`	string \| null	Mortgage outcome. Binary (`aprobado` / `rechazado`). Equivalent to `hipotecario.resultado` in the read API
`resultadoPie`	string \| null	Down-payment outcome. Binary. Equivalent to `pie.resultado`
`subproducto`	string \| null	Sub-product evaluated. Equivalent to `hipotecario.subproducto`
`montoAprobado`	string \| null	Approved amount in UF, pre-formatted for display — e.g. `"262.00 UF"`. It is a string and it is not pesos; the same figure as a number is `montoAprobadoUf`
`montoAprobadoUf`	number \| null	Approved amount in UF. Equivalent to `hipotecario.montoMaximoUf`
`plazoHipotecario`	number \| null	Maximum term, in months. Equivalent to `hipotecario.plazoMaximo`
`tasa`	number \| null	Interest rate, as a decimal. Equivalent to `hipotecario.interes`
`dividendoMaximo`	number \| null	Maximum monthly instalment, in the product's own currency. The read API's `hipotecario.dividendoMaximoUf` is the same figure converted to UF — the two are not interchangeable
`causaRechazo`	string[]	Rejection reasons. Empty array when the lead was not rejected

Report and links

Field	Type	Description
`idPreAprobacion`	string \| null	The pre-approval id, and the stable half of this pair. Pass it to Get the evaluation report
`urlInforme`	string \| null	Link that opens the PDF report. Takes no API token — see Open the evaluation report from its link
`linkBancame`	string	The lead's page in the banca.me portal

urlInforme and linkBancame are not interchangeable

urlInforme opens the report, and it takes no token: a plain GET with no headers answers a redirect to the PDF. That is why it works pasted into a browser, stored in a CRM field, or put behind a "view report" button in your own platform.

linkBancame opens the lead's page in our portal, and it prompts for a banca.me login.

Do not send your Authorization header to urlInforme. If you would rather stay server to server, Get the evaluation report takes your token and idPreAprobacion and returns the download link as JSON.

urlInforme is a credential, and it does not expire

The report carries the lead's personal data, so anyone holding the link can read it. It cannot be revoked once shared — keep it inside systems you control, and think twice before putting it in a forwardable email.

It is also new on every read: each read mints a fresh signature, so two consecutive calls for the same lead give different urlInforme values that open the same report, and older links keep working. If you diff payloads to detect changes, or cache by URL, key on idPreAprobacion instead — that one is stable.

And it can arrive null while idPreAprobacion is not. Minting the signature is a call to our key service; if that call fails we still deliver the event, with this field null, rather than dropping it over one link. Read null here as "no link this time", not as "no report" — Get the evaluation report still reaches the document with idPreAprobacion.

Financial profile

The evaluation's underlying risk parameters. Every field in this group is optional: a parameter that was not computed for a given lead is omitted from the object rather than sent as null.

Sensitive personal data

This group is sensitive financial data about an individual, and every destination subscribed to pre_approve receives it. The payload is built once per event and delivered as-is to each destination — there is no per-destination setting that omits these fields.

Plan for that when choosing where pre_approve is delivered: if a destination only needs to create an opportunity in a CRM and alert an executive, it will still receive the full financial profile. Treat every pre_approve endpoint as handling sensitive personal data.

Field	Type	Description
`edad`	number	Age, in years
`sexo`	string	Sex, as declared
`sueldoBruto`	number	Gross monthly salary
`sueldoLiquido`	number	Net monthly salary
`tipoTrabajador`	string	Worker type
`tipoContrato`	string	Contract type
`antiguedadLaboral`	number	Job tenure, in months
`lagunasPrevisionales`	number	Gaps in pension contributions
`esDuenoEmpresa`	boolean	Whether the lead owns a company
`protestos1Ano`	number	Protests and delinquencies over the last year
`protestos5Anos`	number	Protests and delinquencies over the last five years
`deudaCastigada`	number	Written-off debt
`deudaConsumo`	number	Consumer debt
`deudaComercial`	number	Commercial debt
`deudaHipotecaria`	number	Mortgage debt
`deudaMensual`	number	Total monthly debt service
`apalancamientoConsumo`	number	Consumer-debt leverage
`apalancamientoTotal`	number	Total leverage
`cargaFinancieraTotal`	number	Total financial burden, over net salary
`cargaFinancieraConsumo`	number	Consumer financial burden, over net salary
`cargaFinancieraHipotecario`	number	Mortgage financial burden, over net salary
`cargaFinancieraSobreSueldoBruto`	number	Financial burden over gross salary
`deudorPensionAlimenticia`	boolean	Whether the lead is an alimony debtor
`fechaNacimiento`	string	Date of birth

banca.me never sends policy thresholds — the cut-off values a lead was measured against — and never sends its internal scoring. The read API additionally returns three policy results as booleans, in a resultadosPolitica block; those do not travel in the event.

Example

{
  "eventId": "9f2a1c4e-3b8d-4f71-a205-6c9e8d0b1a37",
  "data": {
    "idBancame": "3f1a9c2e-8b47-4d51-9e6a-2c7d0b5f8a13",
    "nombre": "María",
    "apellidoPaterno": "González",
    "apellidoMaterno": "Pérez",
    "rut": "12345678-9",
    "telefono": "+56912345678",
    "email": "maria.gonzalez@example.com",
    "origen": "inmobiliaria-qr",
    "proyecto": "Condominio Los Robles",
    "proyectoIdExterno": "ex-test-123",
    "fechaEvaluacion": "2026-09-01T14:22:07.000Z",
    "vigenteHasta": "2026-09-29T14:22:07.000Z",
    "estado": "aprobado",
    "complementable": false,
    "idComplementario": null,
    "grupoSocioeconomico": "Desde de $1.500.000 hasta $2.500.000",
    "resultadoHipotecario": "aprobado",
    "resultadoPie": null,
    "subproducto": "main",
    "montoAprobado": "262.00 UF",
    "montoAprobadoUf": 262,
    "plazoHipotecario": 60,
    "tasa": 0.0,
    "dividendoMaximo": 585000,
    "causaRechazo": [],
    "idPreAprobacion": "a91f3d70-5c28-4e19-b6f2-84d7e0c1a5b9",
    "urlInforme": "https://api.banca.me/partner/pre-approve/AQICAHhQb1nQ2vJ0kK9rT7xYf3mN8pR4sL6wD1cE5aZ0uB2gXQFhVn7yKtM3pS9dG4jW6cR1/pdf",
    "linkBancame": "https://partners.banca.me/leads/id/3f1a9c2e-8b47-4d51-9e6a-2c7d0b5f8a13",
    "edad": 47,
    "sueldoLiquido": 1700000,
    "cargaFinancieraTotal": 0.105,
    "deudorPensionAlimenticia": false
  }
}

The data object above is truncated in the financial profile group for readability — a live payload carries every parameter that was computed for the lead.

Telling the events apart​

loan_approved — BNPL​

Fields​

Loan states​

Example​

Handling it​

new_lead — Real estate​

Fields​

Example​

pre_approve — Real estate​

Identification and contact​

Origin and context​

Outcome​

Credit terms​

Report and links​

Financial profile​

Example​

Telling the events apart

`loan_approved` — BNPL

Fields

Loan states

Example

Handling it

`new_lead` — Real estate

Fields

Example

`pre_approve` — Real estate

Identification and contact

Origin and context

Outcome

Credit terms

Report and links

Financial profile

Example