Neosurf

Prepaid voucher payment method. Users pay by entering a voucher PIN - no bank account or card required.

Operations: Pay-In ✓ | Pay-Out - | Webhook ✓
Processing: Synchronous voucher redemption
Payment type: Prepaid voucher (PIN-based)

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
`siteUrl` *	Your site URL - used to build the success, failure, and pending redirect URLs
`merchantId` *	Your Neosurf merchant ID
`webhookUrl`	Your HTTPS endpoint for transaction status updates

Pay-In

POST /v1/api/mozarto/cashier

The user enters their Neosurf voucher PIN in your cashier before you call this endpoint.

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
`brandId`	string	Brand identifier
`siteUrl`	string	Per-transaction redirect URL. Overrides the `siteUrl` from your configuration for the success, failure, and pending return URLs

Unlike most providers, the user does not get redirected to a hosted page. The voucher PIN is collected in your own interface and submitted directly. No data.url is returned.

Example request

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

Response

{
  "status": "success",
  "isSuccess": true,
  "data": {
    "status": "PENDING",
    "sessionId": "60a74038-5b94-427e-8cff-abc123"
  }
}

Webhook

Mozarto calls your webhookUrl with the transaction result.

The method field will be NEOSURF_PAYIN.

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#