Checkmarble Integration Flow

How the Banks API talks to Checkmarble (Marble) today, and where it does not send Marble the full picture.

Reviewed: D:\Workspace\API\Banks, branch feature/marble-2026-09-18 (commit 010c0b49), with the ArthaMarble 0.1.1 NuGet package (AmlCompliance.Marble.dll) decompiled to confirm exactly what goes over the wire. File and line references below are to that commit.

At a glance

1. The moving parts

flowchart LR
  subgraph API["Banks API"]
    QT["Quick Transfer<br/>withdrawal"]
    ND["Noah fiat deposit<br/>webhook"]
    NS["Noah settlement<br/>webhook"]
    ED["External deposit<br/>approval"]
    AD["Admin test endpoint<br/>POST api/marble/decide-all"]
    SVC["MarbleComplianceService<br/>tenant switch · worst outcome · fail-safe"]
  end
  PKG["ArthaMarble 0.1.1<br/>MarbleAmlProvider"]
  M[("Checkmarble<br/>Marble")]
  QT -->|decide + ingest| SVC
  ND -->|decide + ingest| SVC
  NS -->|decide + ingest| SVC
  ED -->|ingest only| SVC
  AD -->|decide| SVC
  SVC --> PKG
  PKG -->|"POST /v1/decisions/all"| M
  PKG -->|"POST /v1/ingest/transactions"| M
  subgraph NC["Never reach Marble"]
    X1["TazaPay · Openpayd · Mesta<br/>FiatRepublic · Artha deposits"]
    X2["FiatRepublic withdrawal<br/>crypto withdrawal · refunds"]
    X3["Customers · wallets<br/>admin approve / reject"]
  end

2. How a decision becomes an action

EvaluateAsync sends the transaction to every Marble scenario for transactions, then takes the worst outcome. The score kept is the highest single-scenario score.

The outcome and score are written to the transaction row as ComplianceStatus and ComplianceScore.

3. The four flows that touch Marble

3.1 Quick Transfer withdrawal

ApplicationService/WithdrawApplicationService.QuickTransfer.cs — decision at lines 226–236, ingest at 256–260.

sequenceDiagram
  participant C as Customer
  participant API as Banks API
  participant FX as Rate feed
  participant M as Marble
  participant DB as Database
  participant P as Payout provider
  C->>API: Quick Transfer request
  API->>API: Validate, build withdrawal
  API->>FX: Convert amount to CAD
  API->>M: Decide (all "transactions" scenarios)
  M-->>API: Worst outcome + score
  alt Approve
    API->>DB: Save withdrawal
    API->>P: Dispatch payout (unless admin approval or Travel Rule applies)
  else Review, Block or Marble error
    API->>DB: Save as Submitted, AML status Pending — held
  end
  API->>M: Ingest the withdrawal (best effort)

3.2 Noah fiat deposit

ApplicationService/WebhookApplicationService.NoahCallbacks.cs — decision at lines 196–201, ingest at 233–234.

sequenceDiagram
  participant N as Noah
  participant API as Banks API
  participant M as Marble
  participant DB as Database
  N->>API: FiatDeposit webhook (Pending or Settled)
  API->>API: Build deposit row, convert amount to CAD
  API->>M: Decide (all "transactions" scenarios)
  M-->>API: Worst outcome + score
  alt Approve, no admin approval needed
    API->>DB: Approved — wallet credited (fiat)
  else Review or Marble error
    API->>DB: Submitted for admin approval — not credited
  else Decline or Block and Review
    API->>DB: Pending — not credited
  end
  API->>M: Ingest the deposit (best effort)

3.3 Noah settlement — the decision is taken, then ignored

Same file — decision at lines 633–637, promotion at 688–784, ingest at 641–644.

sequenceDiagram
  participant N as Noah
  participant API as Banks API
  participant M as Marble
  participant DB as Database
  N->>API: Transaction event (In, Settled)
  API->>DB: Store the locked FX rate
  API->>API: Stop if the crypto leg is already AML-pending
  API->>M: Decide again (second decision for the same deposit)
  M-->>API: Outcome — could be Decline
  rect rgb(253, 226, 225)
  Note over API,DB: Outcome is only recorded on the row — never checked
  API->>DB: Promote to Approved and credit the crypto wallet — always
  end
  API->>M: Ingest the fiat leg only (best effort)

3.4 External deposit approval

Same file, ProcessExternalDepositAsync (line 977). A pending deposit is matched to Noah by transaction hash, promoted to Approved and credited without any Marble decision, and only then ingested (lines 1062–1066). The crypto leg that is actually credited (referenceTx) is never sent.

4. What Marble actually receives

The two builders — BuildMarbleWithdrawTransaction (QuickTransfer.cs 1217–1238) and BuildMarbleTransaction (NoahCallbacks.cs 293–321) — are near copies and fill the same 16 fields.

Sent today

Supported by Marble, not sent — but the data exists in the Banks API

Supported by Marble, not available yet

5. Gaps

Ordered by severity. Each links to the requirement it breaks in the Requirements tab.

Critical

High

Medium

What is already done well

• Fail-safe on outage. A Marble error or timeout holds the money for approval instead of letting it through (FR-513, in part).
• One door to Marble. Every call goes through MarbleComplianceService, with a per-tenant switch that fails closed.
• Verdict on the row. ComplianceStatus and ComplianceScore give admins the Marble result on each transaction.
• Secrets are kept out of the code. API keys come from CoreConfig, and the test endpoint is admin-only.

6. Target: one shared mapper

MG-03, MG-05, MG-07, MG-08 and MG-09 can all be fixed in one place: a single mapper used by every flow, replacing the two duplicated builders. A sketch using only fields that exist today on TransactionEntity, CustomerEntity and PayeeAccountEntity:

public static MarbleTransaction ToMarble(
    TransactionEntity txn, CustomerEntity? customer, PayeeAccountEntity? payee,
    CadValue cad, string direction, string? ipAddress)
{
    bool outbound = direction == BanksConstants.DirectionOut;
    return new MarbleTransaction
    {
        ObjectId           = txn.Id.ToString(),
        CreatedAt          = ToUtc(txn.CreatedDate),
        UpdatedAt          = ToUtc(txn.ModifiedDate ?? txn.CreatedDate),
        CustId             = txn.CustomerId?.ToString(),
        WalletId           = txn.CustomerWalletId?.ToString(),

        Amount             = cad.Amount,                    // scenarios stay in CAD
        FiatValue          = cad.Amount,
        Fee                = txn.TotalComission ?? txn.Fee,
        NetAmount          = cad.Amount - cad.ToCad(txn.TotalComission ?? txn.Fee ?? 0m),
        Asset              = "CAD",
        TransactionAmount  = $"{txn.Amount} {txn.TxWallet}", // original amount + currency
        CryptoValue        = txn.Volume,

        Direction          = direction,
        Status             = txn.State,                     // real state, not "Completed"
        TransactionType    = txn.TxType,
        TransactionSubtype = txn.TxSubType,
        PaymentMethod      = txn.PaymentType ?? payee?.PaymentType,
        ProviderReference  = txn.TransactionReferenceId ?? txn.TxRef,

        PayeeName          = payee?.BeneficiaryName ?? payee?.HolderName ?? txn.SenderName,
        PayeeBankCountry   = payee?.BankCountry,
        PayeeAmlStatus     = payee?.Status,
        Source             = outbound ? null : txn.SenderAccountNumber,
        Destination        = outbound ? payee?.IBAN ?? txn.SenderAccountNumber : null,
        WalletAddress      = txn.AccNoOrCryptoAddress,
        Country            = customer?.Country,
        IpAddress          = ipAddress,
    };
}

CadValue carries the converted amount together with the rate, its source and its timestamp. When no rate is available it fails the evaluation (hold for approval) rather than passing the original amount through. The rate, source and timestamp — and any other attribute Marble has no field for, such as purpose — need new fields in Marble's data model and in the ArthaMarble package (a 0.1.2 release), because MarbleTransaction is sealed.

7. Suggested order of work