# Bank rail credits

Source: https://docs.settlemint.com/docs/api-reference/guides/bank-rail-credits
List and read the credits a bank reports, approve a credit before it mints, screen credits, and recall a credit through the API.

These routes follow credits the bank reports to the reserve account: list and read them, resolve parked credits, approve credits before minting, configure screening, and process recalls. All relative paths sit under `/api/v2/bank-rail`. See [Bank rail API](https://docs.settlemint.com/docs/api-reference/guides/bank-rail) for connections, token links, and clients.

## Follow and resolve credits [#follow-and-resolve-credits]

`GET /connections/{connectionId}/credits` lists reported credits newest first, and `GET /connections/{connectionId}/credits/{creditId}` reads one. A matched credit mints once to the client. Unmatched credits or credits blocked by token compliance mint to the rail wallet as suspense. Credits that cannot complete are parked with an operations case.

Send resolution actions to `POST /connections/{connectionId}/credits/{creditId}/transitions`:

| Body | Effect |
| --- | --- |
| `{"action": "retry"}` | Retries minting an unminted parked credit, or resends a failed custody gateway delivery. |
| `{"action": "allocate", "clientLinkId": "..."}` | Moves suspense tokens to a client. `clientLinkId` is required if unmatched or if the original link was removed (must belong to the same client, or returns `client-mismatch`). |
| `{"action": "return-to-payer", "refundReference": "..."}` | Burns suspense tokens under the bank's refund reference. |

When the `bank-rail` approval family is on, `allocate` and `return-to-payer` move the credit to `awaiting-checker`. Another manager decides via `POST /connections/{connectionId}/credits/{creditId}/decisions` with `{"action": "approve", "approvalId": "..."}` or `"reject"`. Refusals return `409 bankRail.credit.RESOLUTION_REFUSED` with `data.reason` (such as `proposer-cannot-approve` or `approver-role-not-permitted`).

When the approval family is off, resolution starts immediately. Approving transfers or burns tokens once (plain transfer and supply-delegate burn in `delegate` mode), while rejecting leaves the credit parked.

### Switch a client to gateway delivery [#switch-a-client-to-gateway-delivery]

Client links deliver to the client's wallet until two bank rail managers switch them. The link's `delivery` object holds `target` (`wallet` or `gateway`), any open `request`, `lastCheck`, and `rowVersion`.

- `POST /connections/{connectionId}/client-links/{clientLinkId}/delivery-checks` checks gateway readiness without saving anything, returning `ready`, `gateway`, `receiptToken`, per-check `passed`/`detail`/`fix`, and `depositFee` (or retryable `503` if unreadable).
- `POST /connections/{connectionId}/client-links/{clientLinkId}/transitions` with `{"transition": "enable-gateway-delivery", "rowVersion": 3}` validates the gateway and opens a maker-checker request (`preconditions-failed`, `booked-mode`, `delivery-request-open`, or `row-version` on refusal).
- `POST /connections/{connectionId}/client-links/{clientLinkId}/decisions` with `{"decision": "approve", "approvalId": "..."}` or `"reject"` decides the request (`same-actor` if proposer decides). Approval rechecks the gateway: failing rechecks withdraw the request with `delivery-stale` and a warning case. Undecided requests expire after seven days.
- `{"transition": "disable-gateway-delivery", "rowVersion": 4}` immediately reverts future credits to wallet delivery and withdraws any open request.

### Credits for a custody gateway client [#credits-for-a-custody-gateway-client]

A gateway-targeted credit mints to the rail wallet after prechecking the gateway, returning `minted` with a `delivery` object. Failing checks park the credit as `delivery-blocked` before minting (unreadable gateways keep the credit `admitted` for the next pass):

- `fee-account-unset`: a coin with a deposit fee lacks a non-gateway fee account. Set one as custody gateway admin.
- `fee-account-blocked`: the fee account fails the coin's compliance rules. Clear it as compliance officer.

Fix the gateway or switch back to wallet delivery, then send `{"action": "retry"}`. Each credit keeps the target chosen when its mint was prepared, so switching back to wallet delivery affects only unminted credits.

For wallet-delivered credits, `delivery` is `null`. For gateway credits, `delivery` carries `gateway`, `receiptToken`, `lastCheck`, and `state`: `null` while submitting the mint, then `minted-undelivered` with `amount` in base units. Undelivered coins count as `inTransit` (not suspense) and cannot be allocated, returned to payer, or recalled mid-send.

After rechecking the gateway, the rail transfers coins to it: `state` moves through `sending` to `sent-unreported` (carrying `transactionHash` and `logIndex`). Unreadable or paused gateways defer the send under a `screening-outage` case without spending an attempt. Other failures set `state` to `send-failed` with a critical case.

Send `{"action": "retry"}` on a `send-failed` credit to try again. The rail checks whether the previous transfer landed first so nothing sends twice. Refused retries return `409 RETRY_REFUSED` with `data.reason`:

- `delivery-in-flight`: the previous transfer may still land.
- `recall-open`: a bank recall is open on the credit.
- `returned-elsewhere`: the gateway returned coins to a wallet other than the current rail wallet.
- `delivery-not-retryable`: the current delivery state cannot be retried.

### A client suspended in the organisation [#a-client-suspended-in-the-organisation]

The rail sends nothing to a client whose participant account is `suspended`, `closed` or `terminated` in the credit's organisation. The same account in another organisation does not hold the credit.

- Before the mint, the credit parks as `client-suspended` with nothing minted, and a warning case names the wallet and its status. This covers wallet and gateway delivery alike, and a client whose wallet the token also blocks. A credit that matched no client still mints to the rail wallet as suspense.
- A gateway credit that minted before the suspension is not sent. Its `delivery.state` reads `send-failed`, and the case names the status.
- `{ "action": "retry" }` runs the credit again once the account is active again, and parks it again while it is not. `{ "action": "return-to-payer" }` closes the unminted credit under the bank's refund reference.
- An `allocate` to such a client is refused with `403` `RECIPIENT_SUSPENDED` (`DALP-190196`), both when it is requested and when it is approved. An allocation approved before the suspension does not start: the credit parks again under a new case. The suspense stays in the rail wallet.

### Where the coins are [#where-the-coins-are]

The rail tracks sent credits against gateway deposits by `(transactionHash, logIndex)` and `depositId`, populating `gatewayStage`, `gatewayStages`, and on settlement `receiptsMinted`, `fee`, and `receiptRecipient` (matching `custody.gateway-deposit.settled`):

| `delivery.state` | Meaning and next action |
| --- | --- |
| `sent-unreported` | Keeper has not reported the deposit yet. After 60 minutes it becomes `unattributed` with a warning case listing common causes. |
| `quarantined` | Held by the gateway for screening. Raises a `screening-freeze` warning case after 24 hours. |
| `refused` | Gateway refused the mint and holds coins in escrow. Raises a critical case (plus an overdue case after the settlement window). Recover to the rail wallet as gateway manager. |
| `settled` | Gateway accepted the credit and resolved all open credit cases. |
| `returned` | Gateway returned coins to `returnedTo`. If that is the rail wallet, `retry` resends `amount`. Otherwise a critical case opens and `retry` returns `returned-elsewhere`. |

Failed gateway reads leave state unchanged and open no case.

### Approve a credit before it mints [#approve-a-credit-before-it-mints]

When `creditCheckerThreshold` is set on the token link, the rail sums the client's credits over the past 24 hours before minting (unmatched credits are evaluated alone). While the `bank-rail` approval family is on, credits exceeding the threshold wait in `awaiting-mint-approval` with `mintApproval` (`approvalId` and 7-day expiry).

- **Approve:** Send `{"action": "approve", "approvalId": "..."}` to the credit's decisions route (any bank rail manager can decide since the bank opened it). Completed wallet rotations invalidate unminted approvals so they re-evaluate. Credits under recall cannot be approved.
- **Reject:** Moves the credit (or expired approval) to `mint-unapproved` with a critical case. `retry` re-requests approval with you as maker, or `return-to-payer` closes it without a transaction.
- **Reconciliation:** Credits awaiting mint approval appear in `pendingIn` as `awaitingApproval` and are never overdue.

Update the threshold via `POST /connections/{connectionId}/token-links/{tokenLinkId}/transitions` with `{"transition": "update-credit-threshold", "creditCheckerThreshold": "..."}`. Setting or lowering applies immediately. Raising or removing (`null`) opens `mintLimitRequest` for another manager to decide via `POST /connections/{connectionId}/token-links/{tokenLinkId}/decisions` (`approve` or `reject`, 7-day expiry). With the `bank-rail` family off, raises still need wallet verification on session calls and store a waived record. Concurrent changes return `mint-limit-pending`.

#### Delegate mint caps [#delegate-mint-caps]

A `delegate` link can pass `expectedMintCap` (token base units) at creation to cap rail wallet minting (`booked` links refuse it with `mint-cap-booked`). Update the cap later with `{"transition": "update-mint-cap", "expectedMintCap": "..."}` from a token governor wallet (with wallet verification on session calls).

Re-delegation is an async transaction honouring `Prefer: wait`: returns `200` if settled, or `202` with `mintCapReplacement` (`transactionId`, `previousMintCap`) and `Location` pointing to `GET /connections/{connectionId}/token-links`. Reading the list (or running credits, reconciliation, or rotation readiness) settles `mintCapReplacement`, restoring `previousMintCap` on failure. Concurrent changes return `state`.

First, lower, or unchanged caps apply immediately (parking credits as `supply-authority` until indexed). Raises or removals (`null`) open `mintLimitRequest`, and the approving manager's wallet submits the re-delegation. Changes during wallet rotation return `rail-wallet-contained`. Links report `outstandingMint` beside `expectedMintCap`. Credits hitting the cap park as `mint-cap` until you raise the cap or tokens burn.

### A mint the token refuses [#a-mint-the-token-refuses]

Before submitting a mint, the rail checks token acceptance. Refusals keep the credit in `minting` for five minutes (allowing recent role or unpause updates to index), then park it with `parkReason: "mint-refused"`, a critical case, and `mintRefusal`:

| `mintRefusal` | Cause | Fix |
| --- | --- | --- |
| `token-paused` | Token operations are paused. | Resume with the Emergency role, then `retry`. |
| `token-matured` | Token has matured and cannot mint. | Refund via bank, then `return-to-payer`. |
| `not-custodian-token` | Not a DALP custodian token. | Refund via bank, then `return-to-payer`. |
| `sender-lacks-supply-role` | Rail wallet lacks Supply management role (`booked` mode). | Grant role as token governor, then `retry`. |
| `sender-not-supply-delegate` | Rail wallet is not an active supply delegate (`delegate` mode). | Add as mint/burn supply delegate as token governor, then `retry`. |

Once resolved, send `{"action": "retry"}` to re-run from admission.

### Screen credits and cash-outs [#screen-credits-and-cash-outs]

Every confirmed deposit (including unmatched ones) and every cash-out prior to bank instruction is screened by the connection's AML provider. Results are stored on the credit (`screening`), on screening rows, and on an investor-linked case. Credit payer details from FIX tags 5001, 5002, and 5003 appear on `payer`.

Configure screening with `GET` and `PUT /connections/{connectionId}/screening-settings`:

| Field | Meaning |
| --- | --- |
| `providerId` | Linked compliance provider id, or `null` to disable provider screening. |
| `levelName` | Provider fiat screening level, or `null` for provider default. |
| `payerAccountCheck` | `true` (default) parks credits whose payer account is not an active client bank account. |
| `expectedRowVersion` | Last read `rowVersion` (`0` before first save). Mismatches return `409 bankRail.connection.STALE`. |

List available providers via `GET /connections/{connectionId}/screening-providers` (bank rail manager or auditor, returning `403 bankRail.access.MANAGER_REQUIRED` to others). Only `active` providers screen.

Failed checks park credits without minting:

- `payer-account-not-verified`: add and approve the payer account under maker-checker, then `retry`. Mint approval cannot bypass this check.
- `aml-held` / `aml-rejected`: `retry` opens a non-waivable maker-checker approval decided via `POST /connections/{connectionId}/credits/{creditId}/decisions`. Held or rejected cash-outs move to `awaiting-checker` for another manager to decide via `POST /connections/{connectionId}/cash-outs/{cashOutId}/decisions`.

List screening records via `GET /connections/{connectionId}/fiat-screenings` with optional ISO date-time `filter[from]` and `filter[to]` (invalid bounds return `400 wire.http.COLLECTION_FILTER_VALUE_INVALID`).

### Recalls [#recalls]

When a bank sends a FIX credit reversal (requires `credit-reversal` in `allowedMessages.inbound` via `PATCH /connections/{connectionId}`), the rail creates a `received` recall, blocks further minting or retries on that credit, and opens a critical case.

List and read recalls with `GET /connections/{connectionId}/recalls` (`filter[state]`) and `GET /connections/{connectionId}/recalls/{recallId}`. Duplicate open recalls or over-reversals are refused with a critical case. Reversals arriving before their credit receive no reply so the bank resends once the credit lands.

### Execute or abandon a recall [#execute-or-abandon-a-recall]

Recalls always require maker-checker via `POST /connections/{connectionId}/recalls/{recallId}/transitions`:

- `{"transition": "request-execution"}` requests recovery matching the credit's state: cancel unminted credits, burn or book suspense, claw from a delegate client, book a correction on a booked client, or wait for a custody gateway return. Refused while minting, `delivery-in-flight`, park resolution, live cash-out, or wallet containment blocks it. Open recalls also refuse new cash-outs (`recall-open`).
- `{"transition": "abandon", "reason": "..."}` closes the recall without token recovery (leaving a reserve gap until adjusted).

A different manager decides via `POST /connections/{connectionId}/recalls/{recallId}/decisions` (`approve` or `reject` with `approvalId`). If the credit moved before approval, `approve` returns `recall-stale` and resets to `received` with a case. Rejections and expiries also reset to `received`.

#### Clawing and burning a delegate or gateway recall [#clawing-and-burning-a-delegate-or-gateway-recall]

An approved delegate recall enters `clawing`. A token custodian force-transfers tokens from the client (or a gateway manager returns/recovers a gateway deposit) into the rail wallet, and a manager records each finalised transfer via `POST /connections/{connectionId}/recalls/{recallId}/transitions`:

```json
{
  "transition": "record-claw",
  "transactionHash": "0x3f9c2a7e5b1d84c06e2a9f4b7d3c1e8a5f6b2d9c0e7a4f1b3c5d8e2a6f9b0c4d",
  "logIndex": 0
}
```

- Mismatched transfers (wrong timing, token, sender, or destination) return `claw-mismatch`. Duplicates across recalls return `claw-duplicate`, and unfinalised blocks return `claw-unfinalized`.
- Once recorded claws reach the recall amount, or when you send `{"transition": "close-claw"}`, the recall moves to `burning`.
- The rail burns recovered units once, writes down any shortfall, completes the recall, and returns any excess to the client (retrying every five minutes under a warning case if blocked).
- A `booked` recall books one correction from the client against the minting line directly.

### Recall a delivered credit [#recall-a-delivered-credit]

A credit with `delivery.state: "settled"` minted receipts at the client's custody gateway. Because the rail cannot burn receipts directly, it claws receipts back into the rail wallet, redeems them through the rail wallet's own custody gateway, and burns the resulting coins (writing down gateway fees and any unrecovered balance).

Ensure the rail wallet has a registered identity, its own custody gateway, client link, and active approved payout address before requesting execution. Otherwise `request-execution` returns `409 DALP-14137` (`recall-gateway-missing`). If `receiptRecipient` is not indexed yet, it returns `delivery-in-flight`.

Once approved (`clawing`), a receipt-token custodian force-transfers receipts from `delivery.receiptRecipient` into the rail wallet and records each transfer with `record-claw` (or sends `close-claw` if receipts moved away).

In `burning`, the rail approves the gateway escrow, opens a redemption to the rail wallet, and tracks `redemption` (`gateway`, `wallet`, `stage`, `requestId`, `receiptUnits`, `paidUnits`). It claims automatically if auto-claim is off, burns the paid coins up to recorded receipts, and completes the recall.

If the gateway freezes, holds, rejects, or misdirects the redemption, `redemption.stage` reads `failed` with a critical case while staying `burning`. Once fixed on the gateway (or once rejected receipts return to the rail wallet, triggering a retry after five minutes), the recall resumes automatically.

A completed recall reads `recalled` with `recoveredUnits`, `writtenDownUnits`, and `txHash`, automatically creating a `credit-recall` reserve adjustment for any write-down. The credit reads `recalled` once cumulative recalls equal its full amount (`recalledAmount` otherwise).