Skip to main content

Follow and resolve 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 for connections, token links, and clients.

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

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

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

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

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

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

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

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

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

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

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

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:

{
  "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

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

Was this page helpful?