> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cr3dentials.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Lending API overview

> Offer loans to your customers: send applications with their data, perform the money steps we return, and report repayments.

The Lending API lets a financial platform offer Cr3dentials-underwritten loans to its customers. Every call goes from your platform to Cr3dentials: you send applications, acceptances and events, and we answer with decisions, loan views and the money steps your platform performs. Cr3dentials never calls your core systems and never moves money in your accounts.

## How it works

```mermaid actions={false} theme={null}
sequenceDiagram
    autonumber
    participant P as Your platform
    participant C as Cr3dentials
    P->>C: POST /v1/applications (customer data + consent)
    C-->>P: Offer or decline
    P->>C: POST /v1/applications/{id}/acceptance (fresh data)
    C-->>P: Application view, funding started
    loop Every 30 s while the loan is pending_disbursement
        P->>C: GET /v1/loans/{loan_id}
        C-->>P: Loan view with pending instructions
    end
    P->>C: POST /v1/events (hold.placed, then payout.confirmed)
    C-->>P: 202 with the loan view
    P->>C: GET /v1/loans/{loan_id}
    C-->>P: Loan current, deduction instruction
    P->>C: POST /v1/events (deposit.settled)
    C-->>P: Loan view, next deduction version
```

| Stage | What happens | Guide |
| - | - | - |
| Apply | You send the application with the customer's account data inline. We answer with an offer or a decline. | [Applications](https://docs.cr3dentials.xyz/lending/applications.md) |
| Platform income (optional) | The customer verifies work-platform income with the Cr3dentials SDK, and the offer is recalculated. | [Applications](https://docs.cr3dentials.xyz/lending/applications.md#optional-platform-income) |
| Accept | You send the acceptance with a fresh copy of the data. Final checks run on it, and funding starts. | [Applications](https://docs.cr3dentials.xyz/lending/applications.md#accept) |
| Money steps | Each hold, payout, release and refund is an instruction in our answers. You perform it and confirm it as an event. | [Money steps](https://docs.cr3dentials.xyz/lending/money-steps.md) |
| Repayments | You deduct repayments from income deposits as the deduction instruction says, and report each one. | [Repayments](https://docs.cr3dentials.xyz/lending/repayments.md) |
| Credit profile | You read the borrower's repayment history and show it in your app. | [Credit profile](https://docs.cr3dentials.xyz/lending/credit-profile.md) |

## Basics

| Topic | Rule |
| - | - |
| Base URL | Sandbox and production base URLs are sent with your credentials. |
| Credentials | One client id and secret per environment, shared once over a secure channel. |
| Money | Integer cents of USD: `10500` is US\$105.00. |
| Times and dates | Times are RFC 3339 in UTC. Dates are `YYYY-MM-DD` in the program's local time (Colombia time for Colombian programs). |
| Bodies | JSON, at most 1 MiB. Unknown fields are rejected with 400. A body that doesn't parse answers 400 with a fixed message, so no submitted value is echoed back. |
| Envelope | None: the body is the resource itself, unlike the verification Partner API. |
| Personal data | Encrypted at rest. Names, ids, phones and emails never appear in our logs or in any answer. |

## Authentication

The Lending API uses OAuth 2.0 client credentials. Tokens last 900 seconds; request a new one on a 401.

```bash Request theme={null}
curl -X POST "$BASE_URL/v1/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials
```

```json Response theme={null}
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 900
}
```

Send the token on every call:

```text theme={null}
Authorization: Bearer ACCESS_TOKEN
```

## Idempotency

Every `POST` needs an `Idempotency-Key` header of 1 to 255 visible ASCII characters.

| You send | We answer |
| - | - |
| The same key with the same body | The first answer again |
| The same key with a different body | 409 `IDEMPOTENCY_KEY_REUSED` |
| The same key while the first request is still running | 409 `REQUEST_IN_PROGRESS` |

For events, use the `event_id` as the key.

## Errors and retries

```json theme={null}
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "invalid event",
    "details": [
      { "field": "data.deducted_cents" }
    ]
  },
  "request_id": "b7d1c0de-0000-4000-8000-000000000000"
}
```

A 400 lists each bad field in `details`, by name only, never its value.

| Answer | What to do |
| - | - |
| 5xx, 409 `REQUEST_IN_PROGRESS`, 429 | Retry with the same `Idempotency-Key` and body, with backoff |
| 401 | Get a new token, then retry |
| 400, 404, 409 `INVALID_STATE`, 409 `IDEMPOTENCY_KEY_REUSED`, 413, 422 | Final for that request: send a corrected request under a new key |

## Webhooks

Webhooks are optional. If your platform can receive HTTPS POSTs, register a webhook URL with us and we send these as they happen:

| Event | When |
| - | - |
| `offer.updated` | A finished income verification raised the offer |
| `application.declined` | The bureau check declined an accepted application |
| `application.funding_failed` | Funding failed after acceptance |
| `loan.status_changed` | A loan changed status, such as `pending_disbursement` to `current` |
| `loan.deduction_instruction.updated` | What to deduct from the borrower's deposits changed |

Each is signed with HMAC-SHA256: verify `X-Signature` against `X-Timestamp` and the raw body, as the [API Reference](https://docs.cr3dentials.xyz/api-reference/introduction.md) describes. Delivery is at least once, so deduplicate by `event_id`. Everything a webhook carries is also in the loan and application views, so a platform that can't receive webhooks reads those instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.