Review Your Provider Integration With Formance
Walk through your cross-border payments provider integration with our team.
The provider dashboard shows the payment as completed, the beneficiary's account shows no figures, and support explains that their service-level agreement (SLA) covered only the hop to the beneficiary's bank.
Engineering, finance, and compliance teams evaluating a cross-border payments application programming interface (API) find that provider marketing pages read the same: coverage, speed, compliance, pricing, and developer experience.
The differences that matter live in the API contract. What actually determines whether money lands and reconciles lives one layer deeper? Which settlement states does it expose? What happens on a retry after a timeout? What does a quote response itemize? What evidence does it emit when a correspondent deducts fees mid-flight?
These are questions that matter more in 2026. This guide covers what to look for in a cross-border payments API, and how to test each requirement in a provider sandbox before you sign.
A cross-border payments API hides three things behind a single endpoint: the payment's settlement state, the correspondent fees deducted in flight, and the rail that carried the money.
All three get hidden because the API sits one layer above the payment rails, foreign exchange (FX), compliance, and settlement networks that move the money. A cross-border payments API hides the rail underneath, and the rail underneath still determines what happens to the money.
A provider may collapse provider acceptance, rail confirmation, funds availability, and irreversible settlement into a single "completed" status. However, it hides the discrepancy between money reaching the beneficiary bank and money crediting the beneficiary account.
When a fee isn't exposed as its own field, a correspondent deduction appears only as a slightly smaller credited amount. The instructed amount and the credited amount diverge. The divergence is unrecoverable downstream unless the API returns both numbers and the charge code (BEN, SHA, or OUR).
A provider may omit the rail of origin, including cases where the provider routes through stablecoins. The underlying rail still determines what happens to the money, including its finality guarantees, fee mechanics, and failure modes.
Multi-rail cross-border payments break at exactly this point of carry. The multi-rail money-movement architecture sits behind the provider API. Whichever rail carried the money must preserve its state transitions and fee reports, or those reports become unrecoverable downstream.
A settlement state machine must expose two states the provider usually hides: funds availability at the beneficiary account and the point of irreversible settlement (or settlement finality). Those are the states your obligations hang on, and bank-to-bank delivery time understates your exposure against both.
Beneficiary credit lags bank receipt because the beneficiary bank posts on its own cycle after the funds land. Compliance holds, cut-off times, batch posting windows, and weekends or local holidays all sit between money arriving at the bank and money appearing in the customer's account. None are visible to the sending provider, so a delivery-to-bank SLA cannot predict them.
The lag between bank receipt and beneficiary credit is measurable. 90% of payments reach the beneficiary bank within one hour, but only 43% are credited to the final account within an hour. A provider SLA quoted against the first number tells you nothing about the crediting time your customer experiences.
Industry progress will not close the crediting lag. The Group of Twenty (G20) targets call for 75% of wholesale cross-border payments credited within one hour and 75% of retail payments with funds available within one hour by end-2027, and the October 2025 assessment found the targets unlikely to be met globally.
The API must expose provider acceptance, rail confirmation, funds availability at the beneficiary account, and irreversible settlement as distinct states.
Every webhook payload must also carry a Society for Worldwide Interbank Financial Telecommunication (SWIFT) Unique End-to-end Transaction Reference (UETR) or an equivalent unique transaction identifier. Each state transition ties back to one payment across your ledger, the provider, and the correspondent chain.
A cross-border payments API must accept an idempotency key, commit its idempotency record with the payment itself, and keep both visible in a ledger you own.
The contract must require an idempotency key on every payment initiation endpoint, a documented lifetime for that key, and an idempotency store that commits with the payment.
Every endpoint needs the key because one unprotected path is enough to double-charge a customer when a retry lands there.
Document the lifetime because your retry logic needs to know how long the key still works. If the provider forgets the key before you retry, the request looks new and gets processed twice.
The store must commit with the payment because separate writes create duplicates when one succeeds, and the other fails.
The contract only counts as payment API idempotency if the same key returns the same result across every retry inside the lifetime, and from every layer that can fire one: your SDK, any tool wrapper, an agent runtime, and the model itself. Agent-driven workloads hit all four at rates payment code was never designed for.
Duplicate detection must live in a ledger you own, because the provider cannot see the second posting inside your books. A ledger that records fiat and digital-asset postings under the same rules, the shape Formance is built around, catches a provider-side retry whichever rail it lands on.
On 25 December 2021, a scheduling issue caused Santander UK to process payments twice for roughly 2,000 business accounts, and the bank covered the £130 million from its own reserves. Santander absorbed the loss because it owned the ledger that revealed the duplicates.
However, a fintech reconciling only against a provider dashboard would not see the second posting until the correspondent statement arrived days later, by which point the money is gone.
A cross-border payments API must expose FX markup as three separate rate fields on every fiat quote response, and itemized on-ramp and off-ramp cost fields on every stablecoin leg.
The mid-market reference rate is the neutral benchmark. The applied rate is what the provider actually used to convert the payment. The markup is the difference.
Splitting them into three fields lets an automated check compare markup corridor by corridor at the moment of quoting, without pulling a separate market-data feed. Collapse them into one applied rate, and spread drift only surfaces during quarterly FX reconciliation.
FX markup is frequently the largest cost component a provider does not itemize, which is why the global average cost of sending $200 was 6.36% in Q3 2025.
Stablecoin legs must expose the on-ramp fee, the off-ramp fee, and any spread on each conversion as separate fields per leg, rather than netting it all into the delivered amount.
The stablecoin sandwich breaks the two legs out in full, and the digital-asset leg needs the same funds-state separation as the fiat legs, because on-chain confirmation is not the same event as settlement.
Two SWIFT changes reshape what a provider integration has to prove before you sign. Coexistence between legacy MT and ISO 20022 messages on SWIFT ended 22 November 2025, removing the MT fallback that used to hide a flattened outbound message. From November 2026, payments with fully unstructured postal addresses will be rejected outright.
Therefore, provider integrations must prove that MT-to-MX translation preserves structured address fields on the outbound message, and that payee verification returns a result before initiation.
MT-to-MX translation breaks structured addresses by collapsing fields into free text, truncating to legacy line limits, or dropping diacriticals during character-set conversion.
You inherit the provider's translation behavior whether it exposes it or not, so your ISO 20022 API requirements must cover the outbound message, and not the request you send.
Verify structured-address preservation by inspecting the outbound message, and verify payee checks by requiring the provider to return a verification result before you commit the payment. Address preservation and payee verification now sit on a single compliance surface, so a provider that handles one but not the other still fails the check.
A cross-border payments API must emit six kinds of evidence for a settled payment to be reconcilable, but the evidence is only useful if you have a transactional language, like Numscript, that turns it into ledger postings that match the correspondent statement by construction.
For a payment to produce reconcilable payment records, the API must emit:
These six fields let your ledger reconstruct every payment end to end.
The identifiers tie the record to the provider and correspondent, while the two amounts plus the charge code explain any deduction. The sanctions metadata proves the screening ran, and the replayable events plus timestamped exports let you rebuild the state at any point after the fact.
Once the API emits both the instructed and credited amounts, Numscript is what turns those two numbers into ledger postings that match the correspondent statement without a manual break.
A correspondent deduction is modeled as one transaction with two postings. The instructed amount leaves the source account, the credited amount lands on the beneficiary, and the difference posts to a fee account. Suppose you instruct a €250,000 supplier payment and the correspondent deducts €45 under SHA.
Accounts
| Real-world party | Ledger account | Holds |
| Platform funds held with the provider | @platform:paymentProviders:provider:settlement | Prefunded €EUR used for settlement |
| Supplier beneficiary | @counterparties:suppliers:supplier:settlement | Amount credited to the supplier |
| Correspondent bank | @fees:correspondent:sha | Fee deducted by the correspondent |
€250,000.00 leaves the platform's provider settlement account. €249,955.00 is credited to the supplier, and €45.00 is recorded as the correspondent's fee.
// CROSS_BORDER_SETTLEMENT
// Event: settle a supplier payment and record a EUR 45.00 correspondent fee
send [EUR/2 25000000] (
source = @platform:paymentProviders:provider:settlement
destination = {
max [EUR/2 24995500] to @counterparties:suppliers:supplier:settlement
remaining to @fees:correspondent:sha
}
)
set_tx_meta("event_type", "cross_border_settlement")
set_tx_meta("payment_id", "pmt001")
The €45 deduction becomes a first-class posting on @fees:correspondent:sha rather than an unexplained break.
The 2026 stack (post-coexistence SWIFT, the November structured-address rule, and idempotency under retry load) means a provider integration that looked acceptable last year can now break payments, reject them at the network, or double-charge under load.
Seven tests against the provider's sandbox verify the API produces the evidence and behavior your core ledger will depend on:
Run the seven tests, and the shortlist narrows to providers that already treat these behaviors as baseline requirements. Whichever provider you pick, the evidence it emits still has to land in a ledger you own. That is where reconciliation, duplicate detection, and the lifting-fee posting from this article actually live.