US bank transfer (ACH) via PayModum, using PayModum Hosted Link. The payer verifies their identity, links their bank, and is screened for risk on PayModum-hosted pages, so no identity documents or bank credentials pass through the Mozarto API. A single Pay-In call returns a hosted-page URL; the multi-step flow (identity verification → AML screening → bank linking → ACH risk decision → processor token) runs server-side and reports progress and the final outcome by webhook.Operations: Pay-In ✓ | Pay-Out ✓ | Webhook ✓ Processing: Asynchronous - redirect the payer to the hosted page, then receive step and final events by webhook Payment type: Bank transfer (US ACH), fund movement handed off to Sponsor BankFields marked with * are required.
A Pay-In moves through these steps. The payer only ever sees PayModum-hosted pages; Mozarto orchestrates the steps and emits a webhook at each meaningful point.
#
Step
What happens
Merchant webhook
1
Identity Verification
Payer verifies identity on PayModum Hosted Link. Skipped when the same payer's latest verification already passed and their first name, last name, email, and phone match
identity_verification.failed on decline
2
AML / watchlist screening
Standalone PayModum Monitor screening (runs on every transaction)
watchlist.failed if not cleared
3
Bank linking
Mozarto creates the bank Hosted Link and hands its URL to the merchant; payer links their bank on PayModum
bank_link.required (action needed), bank_link.failed on definitive link failure
4
ACH risk decision (Signal)
PayModum Signal scores the transaction against the configured ruleset - ACCEPT proceeds, REROUTE / REVIEW decline
risk_check.declined on decline
5
Processor token
On accept, Mozarto creates a Sponsor Bank processor token and hands off. Fund movement is executed by Sponsor Bank (separate)
payment.initiated
Every failure path also has the generic payment.failed fallback. See Webhook.
PayModum secret for the environment (stored encrypted)
idvTemplateId*
PayModum Identity Verification template id (idvtmp_...)
watchlistProgramId
PayModum Monitor program id (prg_...) for AML/watchlist screening. When empty, screening is skipped
accountName*
Display name shown on the PayModum hosted pages
webhookUrl*
Your HTTPS endpoint for step and final webhooks
siteUrl
Fallback return URL for the payer after the hosted flow
Signal ruleset: the ACH risk decision uses the PayModum Signal ruleset whose key is default. Create a Signal Transaction Score ruleset in the PayModum Dashboard and assign it to your environment; otherwise /signal/evaluate returns scores but no ACCEPT/REROUTE/REVIEW decision and the transaction proceeds on scores alone.
Authentication is required on every cashier call. See Authentication.
The cashier call does not move money. It creates a transaction and returns a paymentUrl (a PayModum Hosted Link URL). Redirect the payer to that URL; the identity, bank-linking, and risk steps run on PayModum-hosted pages and are orchestrated by Mozarto. Track progress and the outcome through the webhooks.
Amount in the currency's main unit, up to 2 decimals (e.g. 200 = 200 USD)
currency*
string
ISO 4217 currency code ("USD")
country*
string
ISO 3166-1 alpha-2 country ("US")
firstName*
string
Payer first name - used to prefill Identity Verification and to match a prior verification
lastName*
string
Payer last name
email*
string
Payer email
phone
string
Payer phone in E.164 (e.g. "+14155550123")
dob
string
Date of birth, YYYY-MM-DD
ssn
string
US SSN (9 digits) - prefills the KYC data-source check
address
string
Street address
city
string
City
state
string
State / region
zipCode
string
ZIP / postal code
merchantReference
string
Your order reference, echoed back on every webhook
webhookUrl
string
HTTPS endpoint for this transaction's webhooks. Overrides the configured webhookUrl
siteUrl
string
Return URL for the payer after the hosted flow. Overrides the configured siteUrl
Identity re-use / skip: a returning payer whose latest Identity Verification already passed skips step 1 - but only when firstName, lastName, email, and phone all match the previously verified identity. Any mismatch (or a first-time payer) runs verification.
{"pspType":"PAYMODUM","type":"PAYIN","baseamount":200,"currency":"USD","country":"US","firstName":"Leslie","lastName":"Knope","email":"leslie.knope@example.com","phone":"+14155550123","dob":"1975-01-18","ssn":"123456789","address":"123 Main St","city":"San Francisco","state":"CA","zipCode":"94111","merchantReference":"ORDER-4821","webhookUrl":"https://example.com/f2e721ba-0ceb-40ea-a388-56e2f584bb7a"}
PayModum Hosted Link URL - redirect the payer here
transaction_id
string
Mozarto transaction identifier. Use it to match webhooks
merchantReference
string
Your reference from the request, or an empty string if none was sent
amount
number
The transaction baseamount
transaction_status
string
Always "Initiated" at this point. Progress and the final outcome arrive by webhook
Redirect the payer to paymentUrl. When Identity Verification passes and the bank Hosted Link is ready, Mozarto also sends a bank_link.required webhook carrying the bank URL (see below).
Set type to "PAYOUT". Pay-Out skips Identity Verification (the payee is an existing user) and links the payee's bank to produce a Sponsor Bank processor token; the actual credit is executed by Sponsor Bank. The request returns a paymentUrl and transaction_status: "Initiated" exactly like Pay-In.
Amount to credit, in the currency's main unit (e.g. 200 = 200 USD)
currency*
string
ISO 4217 currency code ("USD")
country*
string
Payer's country - full name, ISO 3166-1 alpha-2, or alpha-3 (e.g. "Germany", "DE", "DEU"). Matched against the account's Processing Scope. Omit it and Mozarto geo-locates the caller's IP instead - see Country
merchantReference
string
Your reference, echoed back on every webhook
webhookUrl
string
HTTPS endpoint for this transaction's webhooks. Overrides the configured webhookUrl
siteUrl
string
Return URL for the payee after linking their bank. Overrides the configured siteUrl
Mozarto calls your webhookUrl at each meaningful step and at the final outcome. Every webhook uses one self-describing envelope: read event and step to know what happened, data for step-specific detail, and status / transaction_status for the outcome. The flat transaction fields are always present for backward compatibility.
Superseded verifications are silent. When a payer starts a new transaction that supersedes an in-progress verification, PayModum reports the old attempt as canceled. Mozarto closes that old transaction internally but does not send a webhook for it, so you won't receive a spurious failure for an abandoned attempt.
Not every step produces a webhook - some are decided synchronously and returned in the Pay-In/Pay-Out response instead. Which path a step takes depends on whether Identity Verification runs:
First-time payer (verification runs): the cashier response returns the IDV hosted URL. Identity, screening, and the bank-link hand-off are then decided asynchronously and reported by webhook (identity_verification.failed, watchlist.failed, bank_link.required).
Returning verified payer (verification skipped): identity is re-used and screening runs at cashier time, so the cashier response returns the bank hosted URL directly. There is noidentity_verification.failed, watchlist.failed, or bank_link.required webhook - a screening decline is returned synchronously as a cashier error instead.
Both paths converge at the bank step: once the payer links their bank, bank_link.failed, risk_check.declined, payment.initiated, or payment.failed is delivered by webhook.
Pay-Out skips identity, screening, and Signal - the cashier response returns the bank URL, then payment.initiated (or bank_link.failed / payment.failed) by webhook.
bank_link.failed - the bank Link session ended with an unrecoverable error and no linked account:
{"event":"bank_link.failed","step":"bank_link","psp":"PAYMODUM","timestamp":"2026-09-07T12:24:11.446Z","data":{"reason":"Bank linking failed: INSTANT_MATCH_FAILED","error_code":"INSTANT_MATCH_FAILED","error_message":"Item cannot be verified through Instant Match."},"transaction_id":"6a9eacabd5324bac369295ee","psp_transaction_id":"","user_id":"66f2612b330f684f99a633cb","status":"failed","transaction_status":"Failed","amount":200,"currency":"USD","merchantReference":"ORDER-4821"}
risk_check.declined - Signal returned REROUTE or REVIEW:
Every step transition is guarded by an atomic claim, so each event is emitted once even when PayModum delivers overlapping webhooks (e.g. STEP_UPDATED + STATUS_UPDATED) or the payer's browser and PayModum's webhook race.
Treat webhooks as at-least-once: dedupe on transaction_id + event, and use transaction_status as the source of truth for the outcome.
bank_link.required carries an action_required status - it is an interim prompt, not a terminal state; the transaction is still Initiated.
The request carries an Authorization header with a Mozarto-generated signature token. Verify it before applying any balance or state change. See Webhook setup.
Created and progressing (verified/tokenized). Real settlement statuses arrive from the fund-movement layer (Sponsor Bank) separately
Failed
Declined at any step (identity, screening, bank link, or risk) or a processing error
Risk scores from the Signal step are stored on the transaction and shown in the transaction grid and detail view as Customer Return Risk and Bank Return Risk.
Leslie Knope - DOB 1975-01-18, phone +12345678909, SSN 123456789
Bank login (Auth-friendly)
Institution First Platypus Bank / Tartan Bank, username user_good, password pass_good, OTP 1234
Forced Auth failure
Institution First Gingham Credit Union triggers INSTANT_MATCH_FAILED (tests the bank_link.failed path)
Gated products: PayModum Monitor (watchlist screening) and Signal rulesets must be enabled/created for your environment. Leave watchlistProgramId empty to skip screening while Monitor access is pending.
Configuration and provider transport failures are mapped to normalized Mozarto errorCode values.
Mozarto errorCode
When
PSP_NOT_CONFIGURED
clientId, secret, or idvTemplateId not set for this brand
Step-level declines (identity, screening, bank link, risk) are reported through the webhook event catalog above rather than as cashier error codes. For the full list of errorCode values and retryability guidance, see Errors.
