Fund Flow

All EUR payout funding flows follow a two-leg pattern: a 1P FX leg (OpenFX controls) and a 3P payout leg (Schuman controls). The two patterns are just-in-time FX-funded and collection-funded.

Universal Flow (FX-Funded)#

All three funding currencies (USDC, GBP, USD) follow this sequence. The only variable is what the client sends to OpenFX's trade engine in step 4.

Just-in-Time Funding Design Principle#

For FX-funded payouts, the trade is only placed when a payout instruction is made. The sequence is: instruction then trade then EUR delivery then payout execution. EUR arrives and is immediately paid out. This means OpenFX does not pre-fund EUR positions or hold EUR on behalf of clients.

Collection-Funded Flow#

A client may collect EUR from their own customers (invoices, marketplace settlements) into their Schuman EUR IBAN. That balance sits in the account until the client initiates a payout instruction against it. No FX conversion occurs.

Schuman API Endpoints Referenced#

Other Useful Schuman Endpoints#

Resource Model

EUR payouts use the unified /payments resource with the sepa_bank payment method type. The platform API is aligned with Tyler McIntyre's v1 Platform API architecture. Six core resources are involved, each with a typed ID prefix for traceability.

Core Resources#

Money Format#

All monetary amounts use string-based decimal values:

{ "currency": "EUR", "value": "10000.00" }

This avoids floating-point issues and is consistent across all amount fields: source, destination, fees, and balances.

SEPA Variant#

The sepaType field on the payment specifies the SEPA variant:

Both use the same endpoints, state machine, and webhook events. The difference is settlement speed and potentially fee. SEPA Instant availability on client VIBANs to be confirmed with Schuman during sandbox testing.

Endpoints

EUR payouts use three payment creation patterns. The staged intent flow is the default for EUR payouts because clients need to review the FX quote and CoP result before committing.

Payment Creation Patterns#

Staged Intent Flow (Primary)#

Cross-Currency Fields#

amountInputSide controls quoting direction:

• send - client specifies the source amount (funding currency)
• receive - client specifies the destination amount (EUR to beneficiary)

This replaces the previous source_amount / destination_amount split.

Beneficiary Validation#

Balances#

Balance check 1 (at payment creation): Verify the client has sufficient funding currency (USDC/USD/GBP) in their OpenFX account. This is the available balance on the funding acc_.

Balance check 2 (before payout submission to Schuman): Verify EUR has landed in the client's Schuman IBAN. Proxied from Schuman's GET /1p-3p/balance/{customerId} and mapped into the four-bucket model on the EUR acc_.

Idempotency#

All POST endpoints require an Idempotency-Key header (client-generated UUID, unique per client, valid for 48 hours). On duplicate submission, the API returns the original response without re-executing.

Engineering owns the detailed request/response schemas. The fund flow defines what data is needed at each step.

Fee Model

Fees are returned in the intent response as a feeComponents array with typed entries, plus a totalDebitAmount showing what the client actually pays (source amount + all fees).

Fee Types#

Response Structure#

{
  "feeComponents": [
    { "type": "fx_markup", "amount": { "currency": "EUR", "value": "12.50" } },
    { "type": "processing_fee", "amount": { "currency": "EUR", "value": "2.00" } },
    { "type": "sepa_fee", "amount": { "currency": "EUR", "value": "0.50" } }
  ],
  "totalDebitAmount": { "currency": "USD", "value": "10015.00" }
}

The feeComponents array is extensible for future fee types.

Payment State Machine

The client sees a simplified state machine. Internal orchestration granularity is hidden behind processing. Internal stages are exposed via processingStage on the payment object and via timeline events.

Client-Facing States#

requiresActionReason Enum#

Internal Processing Stages#

Not client-facing. Exposed via processingStage on the payment object and via timeline events for clients that want granular visibility.

Tracking & Reconciliation

Every payment object carries a trackingIdentifiers object for end-to-end traceability across all three legs. The three-leg reconciliation model links FX conversion, EUR funding, and Schuman payout into a single traceable chain.

Tracking Identifiers#

Three-Leg Reconciliation Model#

Each EUR payout has three legs that must be traceable:

Reconciliation Surfaces#

Two reconciliation surfaces:

1. OpenFX ledger vs. Schuman IBAN balance: Every EUR delivery to Schuman must match a corresponding debit on OpenFX's side. Use GET /transfer/{customerId}/bank-transfers for Schuman's view.
2. Payout instructions vs. Schuman execution: Every POST /1p-3p/payment/3p must result in a matching transaction in GET /1p-3p/transactions/{customerId}.

Beneficiary Validation

Pre-validate beneficiaries before payment creation via VoP/CoP. Validation lives on the counterparty/payment-method path and wraps Schuman's IBAN validation API. This runs before FX conversion - invalid IBANs are rejected before any money moves.

Endpoint#

POST /counterparties/{cpt_id}/payment-methods/{pm_id}/validate

Wraps Schuman's POST /1p-3p/iban/validation.

Validation Sequence#

CoP Result Handling#

Webhooks

Webhook event naming follows the platform convention: payment.{state}. Webhook payload always includes the full payment object. Clients should not need to poll after receiving a webhook.

Event Reference#

Resource Mapping

How each client-facing resource maps to Schuman's API objects. Key point: Schuman has no concept of counterparties or payment methods. It receives raw beneficiary details (IBAN, name) on each payout call. OpenFX owns the identity layer entirely.

Provider Abstraction Principle#

Schuman is never exposed to API consumers. Clients interact exclusively with Tyler's unified /payments resource. Schuman is one provider behind the SEPA rail.

Every Schuman-specific integration must be designed as swappable. No Schuman concepts, IDs, or terminology should leak into the client-facing API surface. The provider interface for Schuman is implemented behind Schuman's EMI entity, Salvus SAS.

Design rule: Every piece of Schuman-specific logic - API calls, status mappings, polling cadences, balance construction - must be isolated behind the provider interface. No Schuman assumptions should be baked into the orchestration layer or the client-facing API.

Mapping Table#

ID Mapping to Store#

Provisioning

When a new client is activated for EUR payouts, Tyler's Layer 0 (Identity/Entities) provisioning triggers the following Schuman calls in sequence. This is a one-time setup per client.

Four-Step Provisioning Sequence#

Manual Onboarding Flow (v1)#

Target: Client goes from "I want EUR payouts" to "first payout executed" within 5 business days, assuming docs are ready.

Payment Lifecycle

Orchestration logic for payment execution. Two flows: staged intent (FX-funded, primary) and collection-funded. Both converge at Schuman payout submission.

Staged Intent Flow (Primary)#

Standard flow: client holds a non-EUR balance and wants to pay out EUR via SEPA.

Step 1 - Create Intent#

POST /payments/intents

• OpenFX generates a quote (qte_)
• Check 1: Verify available balance on funding acc_ covers the source amount
• Returns preview: FX rate, fee breakdown, net amount to beneficiary
• No Schuman call. Nothing is committed.

Step 2 - Submit Payment#

POST /payments/{id}/submit

Triggers the execution pipeline in sequence:

Collection-Funded Flow#

Client already holds EUR in their Schuman IBAN (from a prior pay-in or collection). Skip steps 2a-2c:

• Check 2: GET /1p-3p/balance/{customerId} to confirm sufficient EUR available
• Payout submission (step 2d)
• Transaction status polling (step 2e)

No FX conversion, no cnv_ created. The payment object's exchangeRate field is null.

VoP/CoP Validation#

Triggered by: POST /counterparties/{cptId}/payment-methods/{pmId}/validate

Internally calls: POST /1p-3p/iban/validation (Schuman)

When CoP acknowledgement is required, the client must explicitly acknowledge the mismatch via POST /payments/{id}/actions before the payment can proceed.

Internal State Machine

Full mapping from client-facing state to OpenFX internal stage to Schuman API state. The client sees simplified states; OpenFX tracks granular processing stages internally.

Full State Mapping#

Balance Proxy

Tyler's v1 API exposes a four-bucket balance model. Schuman's balance API returns a single figure. OpenFX constructs the four buckets by overlaying internal state on Schuman's reported balance.

Four-Bucket Construction#

Why OpenFX Must Maintain Its Own View#

Schuman only reports a single balance number. It does not distinguish between available, pending, or held. OpenFX tracks pending (EUR deliveries in flight) and held (EUR committed to active payouts) based on its own internal state machine. The available bucket comes from Schuman. The rest is OpenFX's overlay.

Polling Cadence for Balance Refresh#

TBD during sandbox testing. Balance updates from Schuman may have latency. Initial assumption: poll on demand (when needed for a payment check) rather than continuously.

Polling Service

Schuman has no webhooks. OpenFX must poll for two things: balance arrival after EUR delivery, and transaction status after payout submission. Both loops are designed as a shared polling service.

Balance Polling (Post-EUR-Delivery)#

Endpoint: GET /1p-3p/balance/{customerId}

Purpose: Detect when EUR lands in the client's Schuman IBAN after FX conversion and delivery.

Transaction Status Polling (Post-Payout-Submission)#

Endpoint: GET /1p-3p/transactions/{customerId}/{transactionId}

Purpose: Track payout through to terminal state.

Shared Polling Service Design#

Design both polling loops as a shared polling service rather than ad-hoc per-payment logic.

Responsibilities:

• Manage poll schedules per payment (register, tick, deregister on terminal state)
• Handle Schuman rate limits (back off if rate-limited)
• Emit internal events when state changes are detected
• Internal events trigger webhook delivery to clients via Tyler's webhook infrastructure
• Track and log all poll attempts for debugging

Reconciliation Linkage

Every EUR payout has up to three legs. All three must be traceable from the pmt_ object. This section defines the identifier chain and how to reconcile against Schuman.

Three-Leg Tracing#

Cross-Reconciliation Against Schuman#

Fee Passthrough

Fees are determined at quote time and locked into the payment object. All three fee components appear in the feeComponents array.

Fee Component Sources#

Total Debit Calculation#

totalDebitAmount = source amount + fx_markup + processing_fee + sepa_fee

Migration Path

When OpenFX's NL PI licence transfers via the Embed acquisition, EUR volume migrates off Schuman. The provider abstraction makes this a backend swap, not a client migration.

What Stays the Same#

• Client-facing API: Zero changes. Same POST /payments, same state machine, same webhooks, same balance model.
• Reconciliation: Three-leg model stays. "Schuman Payout" leg becomes "OpenFX Payout" with direct SEPA access.
• Fee structure: Same feeComponents array, same fields. Underlying cost may change.

What Changes#

Design Implication#

Every piece of Schuman-specific logic (API calls, status mappings, polling cadences, balance construction) must be isolated behind the provider interface. No Schuman assumptions should be baked into the orchestration layer or the client-facing API. This is not optional - it is the enabling condition for a zero-client-impact migration.

Sandbox Validation

Week 1 items to confirm during Schuman sandbox testing. These are blockers for the build phase - each item affects implementation decisions.

Week 1 Items#

Full Open Questions (from PRD)#