emerchantpay

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 WPF

Fields marked with * are required.

Configuration (Mozarto back office)

These fields are in the locked API Credentials section of the account's Processing Scope tab. Unlock it with your 2FA code first - see Unlock API credentials.

Field	Description
`username` *	Genesis API username
`password` *	Genesis API password
`siteUrl`	Fallback redirect URL used for the success/failure/cancel/pending
`webhookUrl` *	Your HTTPS endpoint for the final transaction status

Pay-In

POST /v1/api/mozarto/cashier

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.

Request body

Field	Type	Description
`pspType` *	string	Always `"EMERCHANTPAY"`
`type` *	string	Always `"PAYIN"`
`baseamount` *	number	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"`
`country` *	string	Payer's country - full name, ISO 3166-1 alpha-2, or alpha-3 (e.g. `"Germany"`, `"DE"`, `"DEU"`). See Country codes. Matched against the account's Processing Scope, and converted to alpha-2 for the billing country sent to emerchantpay. Omit it and Mozarto geo-locates the caller's IP instead
`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.

Example request

{
  "pspType": "EMERCHANTPAY",
  "type": "PAYIN",
  "baseamount": 100,
  "currency": "EUR",
  "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"
}

Response

{
  "status": "success",
  "message": "Transaction successfully processed",
  "isSuccess": true,
  "data": {
    "status": "new",
    "psp_transaction_id": "44177a21403427eb96664a6d7e5d5d48",
    "paymentUrl": "https://wpf.emerchantpay.net/web-payment-form/...",
    "transaction_id": "64a1f2b3c4d5e6f7a8b9c0d1",
    "merchantReference": "",
    "transaction_status": "Pending",
    "amount": 100
  }
}

Field	Type	Description
`paymentUrl`	string	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).

Webhook

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.

Error codes

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.

Configuration (Mozarto back office)#

Pay-In#

Request body#

Example request#

Response#

Webhook#