> ## 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.

# Money steps

> Read each loan's instructions, perform them on your platform, and confirm them as events.

Cr3dentials never moves money on your platform. Each money step is an **instruction** in our answers; your platform performs it and confirms it with an event on `POST /v1/events`.

## Funding a loan

```mermaid actions={false} theme={null}
sequenceDiagram
    autonumber
    participant P as Your platform
    participant C as Cr3dentials
    P->>C: POST /v1/applications/{id}/acceptance
    C-->>P: step funding, loan pending_disbursement
    loop Every 30 s until place_hold is listed
        P->>C: GET /v1/loans/{loan_id}
        C-->>P: instructions [place_hold]
    end
    P->>P: Place the hold
    P->>C: POST /v1/events hold.placed
    C-->>P: 202, loan view
    loop Every 30 s until pay_out is listed
        P->>C: GET /v1/loans/{loan_id}
        C-->>P: instructions [pay_out]
    end
    P->>P: Pay the customer
    P->>C: POST /v1/events payout.confirmed
    C-->>P: 202, loan view
    P->>C: GET /v1/loans/{loan_id}
    C-->>P: loan current, deduction v1
```

`place_hold` is listed once the bureau check passes, and `pay_out` once the hold is placed and the draw on the credit line is approved. Neither is in the answer that triggers it, which is why you read the loan until it appears.

## Loan status

```mermaid actions={false} theme={null}
flowchart TD
    A[acceptance] --> PD[pending_disbursement]
    PD -->|payout.confirmed| C[current]
    PD -->|hold fails, bureau declines, or third pay_out fails| X([cancelled])
    C -->|fully repaid| R([repaid])
```

`overdue`, `delinquent`, `default` and `charged_off` come with late-payment handling.

## The loan view

Every answer that carries a loan view lists that loan's pending instructions:

* the `loan` field of the application view, from the acceptance and from `GET /v1/applications/{id}`
* the answer to every `POST /v1/events` about the loan
* `GET /v1/loans/{loan_id}`

```json theme={null}
{
  "loan_id": "c4d5e6f7-0a1b-4c2d-8e3f-a4b5c6d7e8f9",
  "status": "pending_disbursement",
  "currency": "USD",
  "principal_cents": 10000,
  "interest_cents": 500,
  "hold_cents": 12500,
  "outstanding_cents": 0,
  "installments": [
    {
      "seq": 1,
      "amount_due_cents": 10500,
      "principal_due_cents": 10000,
      "interest_due_cents": 500,
      "due_date": null,
      "provisional_due_date": null,
      "status": "scheduled",
      "amount_paid_cents": 0,
      "paid_at": null
    }
  ],
  "instructions": [
    {
      "instruction_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
      "kind": "place_hold",
      "amount_cents": 12500,
      "currency": "USD",
      "issued_at": "2026-11-18T15:20:01Z"
    }
  ],
  "deduction": null
}
```

**outstanding\_cents** `integer`

0 until the payout is confirmed: nothing is owed yet.

**installments** `array`

The schedule. `due_date` stays null until the payout is confirmed.

**instructions** `array`

Steps you have not yet confirmed or reported as failed. Perform each `instruction_id` once. If you see the same id again, your confirmation hasn't reached us: send it again instead of repeating the step.

**deduction** `object | null`

The current deduction instruction, from `payout.confirmed` on. See [Deductions](#deductions).

## The steps

| `kind` | Appears | Your platform does | Confirm with |
| - | - | - | - |
| `place_hold` | Once the bureau check passes | Hold `amount_cents` (125% of the loan) on the customer's balance | `hold.placed` |
| `pay_out` | Once the hold is placed and the draw on the credit line is approved | Pay `amount_cents` out to the customer | `payout.confirmed` |
| `release_hold` | Seconds after the `deposit.settled` that repays the loan, or after funding stops once the hold is placed | Release the hold | `hold.released` |
| `refund` | Seconds after a `deposit.settled` that deducted more than the loan owed | Pay `amount_cents` back to the customer | `refund.paid` |
| `debit_balance` | Coming with late-payment handling: on a due date, if that installment is unpaid | Debit up to `amount_cents` from the available balance | `balance.debited` |
| `apply_hold` | Coming with late-payment handling: when the loan is 30 days late | Take up to `amount_cents` from the hold | `hold.applied` |

## Confirming a step

```mermaid actions={false} theme={null}
stateDiagram-v2
    [*] --> pending: issued
    pending --> done: confirmation, 202
    pending --> failed: instruction.failed, 202
```

Sending the same confirmation or failure again answers 202 and changes nothing. Any other event on a step that is already `done` or `failed` answers 409 `INVALID_STATE`, such as a confirmation after a failure. Use the `event_id` as the `Idempotency-Key`.

```json Confirmation theme={null}
{
  "event_id": "evt_9",
  "type": "hold.placed",
  "created_at": "2026-11-18T15:20:41Z",
  "data": {
    "loan_id": "c4d5e6f7-0a1b-4c2d-8e3f-a4b5c6d7e8f9",
    "partner_account_id": "acc_83920",
    "instruction_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
    "amount_cents": 12500,
    "reference": "HOLD-551",
    "done_at": "2026-11-18T15:20:40Z"
  }
}
```

```json Failure theme={null}
{
  "event_id": "evt_10",
  "type": "instruction.failed",
  "created_at": "2026-11-18T15:21:02Z",
  "data": {
    "loan_id": "c4d5e6f7-0a1b-4c2d-8e3f-a4b5c6d7e8f9",
    "partner_account_id": "acc_83920",
    "instruction_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
    "reason": "insufficient_balance",
    "failed_at": "2026-11-18T15:21:00Z"
  }
}
```

**data.instruction\_id** `string` *required*

The step you performed. It must belong to `data.loan_id` and match the event type: `hold.placed` for `place_hold`, `payout.confirmed` for `pay_out`, `hold.released` for `release_hold`, `refund.paid` for `refund`.

**data.amount\_cents** `integer` *required*

What you moved. It must equal the instruction's amount for `place_hold`, `pay_out`, `release_hold` and `refund`. Not sent on a failure.

**data.reference** `string` *required*

Your own id for the movement, for reconciliation: 1 to 128 characters. Not sent on a failure.

**data.done\_at** `string` *required*

When you performed the step: at most 5 minutes ahead of our clock. A failure sends `failed_at` instead.

**data.reason** `string`

Failures only: `insufficient_balance`, `account_blocked` or `other`.

There is no deadline: a confirmation or failure sent hours later still moves the loan.

| Answer | When |
| - | - |
| 202 | Recorded, or the same confirmation (same `reference` and `amount_cents`) or the same failure (same `reason`) sent again under any `event_id`. Resending is always safe. |
| 400 | A field is wrong. Fields are checked first, so the step stays as it was. |
| 404 | Unknown loan, unknown `instruction_id`, or another partner's instruction |
| 409 `INVALID_STATE` | Any other event on a step already confirmed or failed |

## When a step fails

| Step | What happens |
| - | - |
| `place_hold` | The application ends as `funding_failed`. The customer can apply again. |
| `pay_out` | A new `pay_out` instruction is issued with a new `instruction_id`, up to 3 in all, and the loan stays `pending_disbursement`. After the third failure the loan is cancelled, a `release_hold` is issued, and Cr3dentials contacts you to unwind the draw. |
| `release_hold`, `refund` | Not issued again. If you can't do one right now, leave it pending and confirm it once done: it stays in `instructions` until then. Send `instruction.failed` only if it can never be done, and tell us so we can settle it with you directly. |

## Deductions

From `payout.confirmed` on, the loan view carries a `deduction` object, and every later answer carries the current one:

```json theme={null}
{
  "instruction_version": 1,
  "status": "active",
  "installment_seq": 1,
  "amount_cents": 10500,
  "currency": "USD",
  "deposit_filter": "inbound_bank_transfer_from_outside",
  "max_deposit_pct": 100
}
```

* Deduct from each income deposit that matches `deposit_filter`: an inbound bank transfer from another institution into the customer's own account.
* Deduct up to `amount_cents`, and at most `max_deposit_pct` of the deposit.
* Report each deduction as `deposit.settled` with the `instruction_version` you applied. See [Repayments](https://docs.cr3dentials.xyz/lending/repayments.md).
* The answer to that event carries the next version. Always apply the highest version you have seen.
* `status: cancelled` means stop deducting.

## When to read the loan

Some steps are issued after the call that causes them has been answered: `place_hold` after the bureau check, `pay_out` after the draw, and `release_hold` and `refund` seconds after the `deposit.settled` that causes them. Read `GET /v1/loans/{loan_id}` on this schedule:

| When | How often |
| - | - |
| The loan's `status` is `pending_disbursement`, or its `instructions` list isn't empty | Every 30 seconds |
| 1 minute after the loan leaves `pending_disbursement`, and 1 minute after every `deposit.settled` you send | Once |
| Any other open loan | Once a day, after 06:00 program local time, for the dated steps that are coming |

If your platform takes [webhooks](https://docs.cr3dentials.xyz/lending/overview.md#webhooks), the dated steps can be pushed the moment they are due instead of read daily.


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