Neosurf

Prepaid voucher payment method. The user is redirected to Neosurf's hosted page to redeem their voucher — no bank account or card required.

Operations: Pay-In ✓ | Pay-Out - | Webhook ✓
Processing: Asynchronous - redirect user to Neosurf's hosted page; final status via webhook
Payment type: Prepaid voucher

Fields marked with * are required.

Configuration (Mozarto back office)

Field	Description
`accountName` *	Display name for this account
`apiKey` *	Neosurf API key - used to sign the request hash and verify webhook signatures
`siteUrl` *	Your site URL - used to build the success, failure, and pending redirect URLs
`merchantId` *	Your Neosurf merchant ID
`webhookUrl` *	Your HTTPS endpoint for the final transaction status (required — the redirect returns a `PENDING` status only)

Pay-In

POST /v1/api/mozarto/cashier

Request body

Field	Type	Description
`pspType` *	string	Always `"NEOSURF"`
`type` *	string	Always `"PAYIN"`
`baseamount` *	number	Amount to redeem as a number (e.g. `50.00`)
`currency` *	string	Currency code (e.g. `"EUR"`)
`currencyCode` *	string	Currency code
`userId` *	string	Your internal user/player identifier
`email` *	string	User's email address
`siteUrl`	string	Per-transaction redirect URL. Overrides the `siteUrl` from your configuration for the success, failure, and pending return URLs

Example request

{
  "pspType": "NEOSURF",
  "type": "PAYIN",
  "baseamount": 50.00,
  "currency": "EUR",
  "currencyCode": "EUR",
  "userId": "user_123",
  "email": "player@example.com"
}

Response

{
  "status": "success",
  "message": "Successfully",
  "isSuccess": true,
  "data": {
    "url": "https://webpayment.neosurf.com/...",
    "transactionId": "64a1f2b3c4d5e6f7a8b9c0d1",
    "amount": 50,
    "merchantReference": ""
  }
}

Redirect the user to data.url — Neosurf's hosted page where they enter their voucher. The transaction stays PENDING until the final status arrives via the webhook.

Field	Description
`data.url`	Neosurf hosted payment page - redirect the user here
`data.transactionId`	Mozarto transaction ID - use for status queries and idempotency
`data.amount`	Transaction amount as a number
`data.merchantReference`	Your reference, echoed back - empty string if not set

Webhook

Neosurf notifies Mozarto once the voucher is redeemed; Mozarto verifies the signature (hash) and then calls your configured webhookUrl. The method field will be NEOSURF_PAYIN.

Payload example

{
  "transaction_id": "64a1f2b3c4d5e6f7a8b9c0d1",
  "user_id": "000000000000000000000001",
  "status": "success",
  "transaction_status": "Approved",
  "message": "Transaction completed successfully",
  "amount": 50,
  "currency": "eur",
  "merchantReference": ""
}

Field	Description
`transaction_id`	Mozarto transaction ID - matches `data.transactionId` from the Pay-In response
`user_id`	The user ID associated with the transaction
`status`	Raw status (`success` / `pending` / other) - do not use for business logic
`transaction_status`	Normalized Mozarto status - use this for all business logic (`Approved` / `Pending` / `Declined`)
`message`	Human-readable description of the outcome
`amount`	Transaction amount as a number
`currency`	Currency, lowercase (as sent by Neosurf)
`merchantReference`	The merchant reference passed in the original request - empty string if not set

Neosurf raw status maps to transaction_status as: ok → Approved, pending → Pending, anything else → Declined.

Error codes

Neosurf transport failures are mapped to normalized Mozarto errorCode values. Use errorCode for programmatic handling rather than parsing raw response fields.

Mozarto `errorCode`	PSP raw signal	When
`INVALID_PSP_CREDENTIALS`	HTTP 404 / 401 / 403	API key, merchant ID, or site URL is missing or rejected by Neosurf
`PSP_TIMEOUT`	HTTP 408 or response body contains `"timeout"`	Neosurf did not respond in time - safe to retry
`PSP_UNAVAILABLE`	HTTP 5xx	Neosurf service error - safe to retry with backoff
`PSP_RATE_LIMITED`	HTTP 429	Too many requests - retry after a delay
`UNKNOWN_PSP_ERROR`	Any other response	Unrecognised error - check `data.error` for the raw message and contact support if it persists

Voucher-level rejections (invalid voucher, declined amount) are returned by Neosurf with an HTTP 200 and a populated data.error / data.errorcode; these surface in the standard error response with the raw message.

For the full list of errorCode values and retryability guidance, see Errors.

Configuration (Mozarto back office)#

Pay-In#

Request body#

Example request#

Response#

Webhook#

Payload example#

Error codes#