Card payment gateway with 3D Secure v2, via the emerchantpay Web Payment Form (WPF). The cardholder enters and authenticates their card on an emerchantpay-hosted page, so no card data passes through the Mozarto API. Pay-ins are submitted as sale3d transactions.Operations: Pay-In ✓ | Pay-Out - | Webhook ✓ Processing: Asynchronous - redirect the cardholder to the hosted page, then receive the final status by webhook Payment type: Cards (Visa, Mastercard) via the Genesis WPFFields marked with * are required.
Required header:x-user-token: Bearer <user-jwt> must be sent with every Pay-In request. See Authentication.
The cashier call does not charge the card directly. It creates a transaction and returns a paymentUrl. Redirect the cardholder to that URL to enter their card and complete 3DS on the emerchantpay hosted page.
Payer identity comes from the user token.firstName, lastName, email, and phone are taken from the authenticated user (x-user-token) and must not be sent in the body. The cardholder email is required (emerchantpay creates/identifies the consumer and binds saved cards to customer_email), so the authenticated user must have an email on file.
Amount in the currency's main unit, up to 2 decimals (e.g. 100 = 100 EUR)
currency*
string
ISO 4217 currency code (e.g. "EUR", "USD", "GBP")
usage
string
Transaction description/label sent to emerchantpay (usage/description). Defaults to "Card deposit"
countryCode
string
ISO 3166-1 alpha-2 billing country (e.g. "DE"). Optional - collected on the hosted page if omitted
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
address
object
Billing address. Optional - collected on the hosted page if omitted
address.line1
string
Street address
address.line2
string
Additional street address line (apartment, suite, etc.)
address.city
string
City
address.state
string
State / region
address.postalCode
string
Postal / ZIP code
webhookUrl
string
HTTPS endpoint for the status webhook. Overrides the configured webhookUrl for this transaction
hppSuccessUrl
string
URL the cardholder returns to after a successful payment. Falls back to the configured siteUrl
hppFailureUrl
string
URL the cardholder returns to after a failed payment. Falls back to the configured siteUrl
hppCancelUrl
string
Return URL when the cardholder cancels. Falls back to hppFailureUrl
No card data: the WPF flow never accepts card (PAN/CVV/expiry) or browser-fingerprint fields in the request - emerchantpay collects and secures them on its hosted page.
{"pspType":"EMERCHANTPAY","type":"PAYIN","baseamount":100,"currency":"EUR","countryCode":"AU","country":"AU","address":{"line1":"45 King Street","line2":"Unit 2","city":"Brisbane","state":"Queensland","postalCode":"4000"},"webhookUrl":"https://example.com/f2e721ba-0ceb-40ea-a388-56e2f584bb7a","hppSuccessUrl":"https://example.com/payment/success","hppFailureUrl":"https://example.com/payment/failed"}
emerchantpay hosted-page URL to redirect the cardholder to
transaction_id
string
Mozarto transaction identifier (also the WPF transaction_id Mozarto sends to emerchantpay). Use it to match the webhook
psp_transaction_id
string
emerchantpay's WPF unique_id - the PSP transaction identifier (shown in the "PSP Transaction ID" column)
status
string
emerchantpay WPF status at creation, typically "new"
merchantReference
string
Your reference from the request, or an empty string if none was sent
amount
number
The transaction baseamount
transaction_status
string
Always "Pending" at this point. The final outcome arrives by webhook
Redirect the cardholder to paymentUrl. They enter their card and complete 3DS on the hosted page, then return to the matching hpp*Url (or the configured siteUrl).
Mozarto calls your webhookUrl when the transaction reaches a final state. The payload shape is the same for approvals and declines; read transaction_status for the outcome. See Webhook Setup for the shared field reference.
{"transaction_id":"64a1f2b3c4d5e6f7a8b9c0d1","psp_transaction_id":"44177a21403427eb96664a6d7e5d5d48","user_id":"test-003","status":"SUCCESS","transaction_status":"Approved","message":"Transaction approved and successfully processed","amount":100,"merchantReference":"Test-001"}
Field
Description
transaction_id
Mozarto transaction identifier returned by the Pay-In call
psp_transaction_id
emerchantpay's WPF unique_id - the PSP transaction identifier
user_id
The cardholder identifier resolved from the Pay-In request
status
Internal lifecycle status - SUCCESS, PENDING, FAILED, or ERROR
transaction_status
Normalized outcome - Approved, Failed, or Pending. Use this for business logic
message
Human-readable summary of the result
amount
Settled amount in the transaction currency's major unit
merchantReference
The merchant reference you passed in the original request - empty string if none was sent
The request carries an Authorization header with a Mozarto-generated signature token. Verify it before applying any balance or state change. See Webhook setup.
emerchantpay transport failures are mapped to normalized Mozarto errorCode values. Use errorCode for programmatic handling rather than parsing raw XML error strings.
Mozarto errorCode
PSP raw signal
When
PSP_NOT_CONFIGURED
Missing credentials in Mozarto back office
username or password not set for this brand
INVALID_PSP_CREDENTIALS
HTTP 401 / 403, or body contains "Authentication failed", "authentication_error", "Invalid credentials", or "Unauthorized"
Genesis API credentials are wrong or expired
PSP_TIMEOUT
HTTP 408, or response body contains "timeout"
emerchantpay did not respond in time - safe to retry
PSP_UNAVAILABLE
HTTP 5xx
Genesis gateway error - safe to retry with backoff
PSP_RATE_LIMITED
HTTP 429
Too many requests - retry after a delay
UNKNOWN_PSP_ERROR
Any other HTTP error or XML-level rejection
Fallback - check data for the raw Genesis response and contact support if it persists
For the full list of errorCode values and retryability guidance, see Errors.
