Examples

NeroPay API v2

Build with NeroPay

Build hosted payments, connected accounts, money movement, NeroDisburse, Terminal, NeroCard, NeroTrade, NeroPOS, NeroWeb, bookings, identity, compliance, proof workflows, support tickets and webhooks from one v2 API.

/v2Live base path

HMACSigned writes

ProductsPayment, POS, Web, Card, Trade, Disburse

Risk-readyKYC, compliance, proof, reserve

NeroConnect Partner API →Partner accounts, pricing and commission collection NeroConnect Sales Agent API →Agent profiles, merchant assignments and reports

Quick start

Use the live v2 base URL for production. Sandbox endpoints are dry-run and do not create live payment, terminal, payout or local records.

https://eu.neropay.app/v2

Merchant mode

Use a merchant secret key to operate directly on that merchant account. Identity, compliance, proof, payments, support and resources are available for direct merchant integrations.

Platform mode

Use the platform key. Send NeroPay-Account to operate on a connected merchant. Keep your own customer-facing dashboard while NeroPay manages regulated flows.

Recommended platform flow: create connected account, create identity verification link, listen for KYC/compliance/proof webhooks, handle support tickets and only release marketplace UX once account and reserve states are safe.

Base request

curl https://eu.neropay.app/v2/account \
  -H "Authorization: Bearer neropay_secret_..." \
  -H "Accept: application/json"

Connected account request

curl https://eu.neropay.app/v2/balances \
  -H "Authorization: Bearer neropay_secret_platform_..." \
  -H "NeroPay-Account: NPVesdTGASO23_547878" \
  -H "Accept: application/json"

Updated 16 Sep 2026

Ready-to-Use Plugins

Use official NeroPay plugins when you want a faster launch without building every checkout, invoice, webhook and order status workflow manually.

NeroPay for WooCommerce

Accept card and wallet payments directly in WooCommerce, receive real-time status updates and support refunds from the store workflow. Download link is inside the section.

Open WooCommerce section →

NeroPay for Wix

Install NeroPay from the official Wix marketplace, configure public keys and redirect URLs, then test with sandbox checkout.

Open Wix section →

NeroPay for Odoo

Connect NeroPay to Odoo eCommerce, Website and Invoicing apps using the Odoo payment provider flow. Odoo 16, 17, 18 and 19 app links are inside.

Open Odoo section →

NeroPay for Perfex CRM

Enable invoice payments, IPN callbacks and reconciliation inside Perfex CRM without building a custom gateway. Module download is inside.

Open Perfex CRM section →

NeroPay for Zapier

Create payment links and automate payment workflows between NeroPay and thousands of apps without code through Zapier.

Open Zapier section → Direct install · RC1

NeroPay for OpenCart 3

Download directly from NeroPay. Marketplace not required. Hosted checkout; staging acceptance required.

Installation and download → Direct install · RC1

NeroPay for PrestaShop

Download directly from NeroPay. Marketplace not required. Hosted checkout; staging acceptance required.

Installation and download → Direct install · RC1

NeroPay for WHMCS

Download directly from NeroPay. Marketplace not required. Hosted checkout; staging acceptance required.

Installation and download → Direct install · RC1

NeroPay for Magento 2 / Adobe Commerce

Download directly from NeroPay. Marketplace not required. Hosted checkout; staging acceptance required.

Installation and download →

Plugins are recommended for standard store, invoice and no-code workflows. Use the API Reference when you need full platform control, connected accounts, custom onboarding, identity, compliance, proof and support flows.

Choose integration type

{
  "simple_storefront": "WooCommerce or Wix",
  "erp_or_invoice_flow": "Odoo or Perfex CRM",
  "automation": "Zapier",
  "custom_platform": "NeroPay API v2 + NeroConnect"
}

NeroPay for WooCommerce

Use the WooCommerce plugin to add secure NeroPay checkout to a WordPress store without building the hosted-payment, order-status and webhook flow from scratch.

Download WooCommerce plugin Use Payments instead

Plugin package

Download the WooCommerce ZIP package and upload it from WordPress Admin → Plugins → Add New, or upload it manually by FTP.

Key features

Quick setup from the WordPress plugin area.
Secure processing through NeroPay APIs.
Real-time payment status updates through webhooks.
Refund support from the WooCommerce workflow where enabled.

Best for

Retail stores that need a standard checkout integration, payment confirmation, order reconciliation and optional advanced API checks.

1. Install and activateUpload the NeroPay WooCommerce plugin through WordPress Admin or FTP, then activate it from Plugins.

2. Configure credentialsOpen WooCommerce → Settings → Payments → NeroPay and enter your API key, merchant details and secret key.

3. Confirm webhooksKeep the webhook/IPN URL reachable so WooCommerce can move orders from pending to paid after NeroPay confirms payment.

Setting	Type	Required	Description
public_key	string	Required	Identifies the merchant account.
secret_key	string	Required	Server-side key used by the plugin for secure API actions.
webhook_url	string	Required	Receives payment success, failure or pending updates.
currency	enum	Required	Store currency such as GBP or EUR.

Typical WooCommerce payment

POST /v2/hosted-payments
{
  "identifier": "wc_order_1042",
  "amount": 49.99,
  "currency": "GBP",
  "details": "WooCommerce order #1042",
  "success_url": "https://store.example/checkout/order-received/1042",
  "cancel_url": "https://store.example/checkout/pay/1042",
  "ipn_url": "https://store.example/wp-json/neropay/webhook"
}

Order paid webhook

{
  "type": "transaction.succeeded",
  "data": {
    "transaction": {
      "identifier": "wc_order_1042",
      "status": "succeeded",
      "amount": 49.99,
      "currency": "GBP"
    }
  }
}

NeroPay for Wix

Use the Wix integration for a fast marketplace-style setup. Configure keys, redirect URLs and IPN URL, then send customers to NeroPay checkout.

Open official Wix app Use hosted payment links

Marketplace installation

Install NeroPay from the official Wix marketplace link, then configure Public Key, success URL, cancel URL and IPN URL.

1. Install from the marketplaceInstall the official NeroPay app, then connect it to your NeroPay merchant account.

2. Add API keysCopy the Public Key and Secret Key from the NeroPay dashboard. Keep secret keys out of browser code.

3. Configure URLsSet success, cancel and IPN URLs so payment status can return to the store.

4. Test in sandboxUse sandbox mode before switching to live keys and live checkout.

Field	Type	Required	Description
public_key	string	Required	NeroPay public key configured in the Wix app.
success_url	string	Required	Page shown after successful payment.
cancel_url	string	Required	Page shown when checkout is cancelled.
ipn_url	string	Required	Endpoint that receives payment confirmation.

For custom Wix backend flows, create hosted payments server-side. Browser-only flows should never expose the secret key.

Frontend checkout request

const payload = {
  public_key: "neropay_public_...",
  identifier: "WEB-" + Date.now(),
  currency: "GBP",
  amount: 100.00,
  details: "Purchase via NeroPay",
  ipn_url: "https://yourdomain.com/ipn",
  success_url: "https://yourdomain.com/success",
  cancel_url: "https://yourdomain.com/cancel",
  customer_name: "John Doe",
  customer_email: "john@example.com"
};

IPN signature check

const expected = crypto
  .createHmac("sha256", secret)
  .update(data.amount + identifier)
  .digest("hex")
  .toUpperCase();

NeroPay for Odoo

Choose the module matching your Odoo major version. The Odoo 19 native provider supports hosted online checkout and customer invoice payments.

Odoo 16 app Odoo 17 app Odoo 18 app Odoo 19 app

Download Odoo 19 ZIP · RC1

Odoo 19 requirements

Odoo 19.0 with custom Python add-on support: self-hosted or Odoo.sh.
Not installable on Odoo Online saas-19.4.
HTTPS, Python requests, the API v2 secret and exact receiving account ID.

Odoo 19 scope

Website / eCommerce and customer invoice hosted payments.
Verified payment status and scheduled recovery.
No POS terminal, automatic subscription debit, initiated refunds or settlement reconciliation.

1. Install matching versionAdd neropay_payment to the add-ons path, install dependencies, restart Odoo and update the Apps list.

2. Configure providerOpen Accounting → Configuration → Payment Providers → NeroPay. Set credentials, receiving account and clearing journal.

3. Test and enableOdoo 19 is a release candidate. Perform native installation and authorised live acceptance testing before production use. Its Test state remains intentionally blocked in this plugin release; do not assume compatibility with the Developer sandbox.

Odoo 16–18 are separate existing packages. Do not install an Odoo 19 module into an older version or assume all versions have identical capabilities.

NeroPay for Perfex CRM

Enable NeroPay as a payment gateway inside Perfex CRM so clients can pay invoices online and Perfex can update invoice status from IPN callbacks.

Download Perfex CRM module Invoice API reference

Perfex module package

Download the module ZIP, extract it into the Perfex modules directory, then enable NeroPay Payment Gateway from Setup → Payments.

Features

Online invoice payments.
GBP and EUR support where enabled.
Instant Payment Notification updates.
Success and failure redirects.
API credentials managed inside Perfex CRM.

Prerequisites

Running Perfex CRM instance.
NeroPay merchant account with API credentials.
Admin access to Perfex CRM.

1. Upload moduleExtract the NeroPay payment module and upload it to the Perfex modules directory.

2. Enable gatewayGo to Setup → Payments → Payment Gateways and enable the NeroPay gateway.

3. Configure credentialsEnter public and secret API keys and define supported currencies.

4. Verify IPNPerfex should listen at {your_perfex_url}/neropay_gateway/ipn and mark invoices paid after verification.

If invoices do not update, confirm the IPN URL, secret key and server logs before retrying payment creation.

Perfex invoice payment

POST /v2/hosted-payments
{
  "identifier": "perfex_invoice_8731",
  "amount": 120.00,
  "currency": "GBP",
  "details": "Perfex CRM invoice #8731",
  "success_url": "https://crm.example/invoices/8731?paid=1",
  "cancel_url": "https://crm.example/invoices/8731",
  "ipn_url": "https://crm.example/neropay_gateway/ipn"
}

IPN handling result

if signature_is_valid:
    record_payment(invoice_id)
    mark_invoice_as_paid()
else:
    log_invalid_ipn()

NeroPay for Zapier

Automate payment workflows between NeroPay and 5,000+ apps without code. Merchants can trigger workflows when a payment is received or create payment links from tools such as Sheets and CRMs.

Open Zapier integration Payment link API

No-code automation

Use Zapier to create payment links, log transactions, notify teams and sync payment events with CRMs, spreadsheets and 5,000+ apps.

1. Connect accountLog in to NeroPay, copy your Public API Key and paste it into the Zapier connection window.

2. Choose modeSelect Sandbox or Live mode depending on whether the workflow should test or process real payment links.

3. Create actionUse the Create Payment Request action to return a checkout URL instantly.

4. Automate follow-upSend payment notifications to Slack, log rows in Sheets, update CRM records or create invoices automatically.

Action field	Type	Required	Description
public_key	string	Required	NeroPay Public API key.
identifier	string	Required	Unique ID for the payment.
currency	enum	Required	Currency code such as GBP, EUR or IDR.
amount	decimal	Required	Payment amount.
details	string	Required	Description or order details.
ipn_url	string	Required	Instant payment notification URL.
customer_phone	string	Optional	Customer phone number.
customer_address	string	Optional	Billing address.

Zapier action response

{
  "success": "ok",
  "message": "Payment Initiated. Redirect to url.",
  "url": "https://eu.neropay.app/checkout?payment_id=EJX123"
}

Example automations

- Generate a payment link when a form is submitted
- Log each transaction in Google Sheets
- Send Slack or email notifications for successful payments
- Create invoices or notes in a CRM

Direct install · Pilot release RC1

NeroPay for OpenCart 3

Hosted checkout with server-side payment verification and missed-notification recovery. Marketplace installation is not required.

Download OpenCart 3

Target environment

OpenCart 3.0.3.x / 3.0.4.x; default store; PHP 7.4–8.3 as supported by the store.

1. InstallBack up the store, then open Extensions → Installer and upload the .ocmod.zip package.

2. ConfigureOpen Extensions → Extensions → Payments. Install NeroPay API v2, then open Edit.

3. ReviewEnter the receiving account ID and API v2 secret. Choose an unpaid Pending status and a paid Processing / Complete status.

4. VerifyConfigure the recovery schedule shown on the settings page. Enable real payments only after acceptance testing.

Scope: Not an OpenCart 4 package. Default store only; recurring profiles are not supported. Custom one-page checkout modules need separate testing.

Validation status: local API-contract and payment-lifecycle checks are included in the release validation, but these packages have not completed full installation and live payment acceptance tests on native stores. Use staging first; this is not a production-certification claim.

Direct download

https://docs.neropay.app/pluginsV2/neropay-opencart3.ocmod.zip

Payment safety

1. Save the order and payment intent.
2. Create one signed hosted checkout.
3. Reuse the existing checkout after a decline.
4. Verify merchant, reference, amount and currency.
5. Record payment once, only on verified success.

An IPN or browser redirect alone is not proof of payment.
Check this plugin release for sandbox support before using test credentials. Sandbox outcomes never confirm a real paid order.

Direct install · Pilot release RC1

NeroPay for PrestaShop

Hosted checkout with server-side payment verification and missed-notification recovery. Marketplace installation is not required.

Download PrestaShop

Target environment

PrestaShop 8.x / 9.x API target; single shop; single-package carts; platform-compatible PHP 7.4–8.3.

1. InstallBack up the shop. Open Modules → Module Manager → Upload a module, then select this ZIP.

2. ConfigureConfigure NeroPay API v2 in Module Manager. Enter the receiving account ID and API v2 secret.

3. ReviewReview payment currency, customer-group, country and carrier restrictions. Configure the recovery schedule displayed by the module.

4. VerifyComplete acceptance tests before enabling real payments. Checkout creates an unpaid order before redirecting.

Scope: Single-shop only. Split-shipment / multi-package carts are blocked. The module is configured in Module Manager even if it is not listed in the marketplace payment catalogue.

Direct download

https://docs.neropay.app/pluginsV2/neropay-prestashop.zip

Payment safety

1. Save the order and payment intent.
2. Create one signed hosted checkout.
3. Reuse the existing checkout after a decline.
4. Verify merchant, reference, amount and currency.
5. Record payment once, only on verified success.

An IPN or browser redirect alone is not proof of payment.
Check this plugin release for sandbox support before using test credentials. Sandbox outcomes never confirm a real paid order.

Direct install · Pilot release RC1

NeroPay for WHMCS

Hosted checkout with server-side payment verification and missed-notification recovery. Marketplace installation is not required.

Download WHMCS

Target environment

Self-hosted WHMCS 8.x / 9.x gateway API target; PHP 7.4–8.3 as supported by the installed WHMCS version.

1. InstallExtract the ZIP and upload its modules and includes directories into the WHMCS installation root. Preserve existing files.

2. ConfigureOpen System Settings → Payment Gateways and activate NeroPay API v2.

3. ReviewEnter the receiving account ID and API v2 secret. Do not enable WHMCS gateway currency conversion for this release.

4. VerifyKeep the standard WHMCS cron running. Customers must sign in as the invoice owner; an unpaid invoice must use NeroPay as its payment method.

Scope: Pays the current invoice balance. No stored-card capture, automatic recurring debit or automatic refund operation. Invoice changes after checkout creation require manual review; the connector will not create a second link.

Direct download

https://docs.neropay.app/pluginsV2/neropay-whmcs.zip

Payment safety

1. Save the order and payment intent.
2. Create one signed hosted checkout.
3. Reuse the existing checkout after a decline.
4. Verify merchant, reference, amount and currency.
5. Record payment once, only on verified success.

An IPN or browser redirect alone is not proof of payment.
Check this plugin release for sandbox support before using test credentials. Sandbox outcomes never confirm a real paid order.

Direct install · Pilot release RC1

NeroPay for Magento 2 / Adobe Commerce

Hosted checkout with server-side payment verification and missed-notification recovery. Marketplace installation is not required.

Download Magento 2 / Adobe Commerce

Target environment

Magento Open Source / Adobe Commerce 2.4.x API target; standard Magento checkout; PHP 8.1–8.3 subject to the platform version.

1. InstallBack up the site and database, then extract app/code/NeroPay/Payments into the Magento root in a development/staging environment.

2. ConfigureRun the Magento module enable and setup commands below as the Magento filesystem owner, not as root.

3. ReviewOpen Stores → Configuration → Sales → Payment Methods → NeroPay API v2. Enter the receiving account ID and API v2 secret.

4. VerifyKeep Magento cron running. Order currency must equal the website base currency, and must be GBP, EUR or USD.

Scope: Standard Knockout/Luma-style checkout only. Hyvä Checkout, PWA/GraphQL, express checkout and custom checkout implementations are not included. No vault, automatic refunds or recurring billing.

Magento setup commands

bin/magento module:enable NeroPay_Payments
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Payment safety

1. Save the order and payment intent.
2. Create one signed hosted checkout.
3. Reuse the existing checkout after a decline.
4. Verify merchant, reference, amount and currency.
5. Record payment once, only on verified success.

An IPN or browser redirect alone is not proof of payment.
Check this plugin release for sandbox support before using test credentials. Sandbox outcomes never confirm a real paid order.

Authentication

Subscription writes: /v2/subscriptions* uses a signature that binds the method, path, retry key, account and exact JSON bytes. Follow the subscription signing examples; the legacy timestamp.body examples below do not apply to these routes.

New management writes: NeroConnect Management & Partners uses a method/path/idempotency-bound HMAC message, not the legacy timestamp.body format. Follow that section's signing and durable retry examples when calling /v2/neroconnect/management/*.

API v2 uses bearer authentication. Unsafe methods also require a timestamped HMAC signature and an idempotency key.

Header	Type	Required	Description
Authorization	string	Required	`Bearer {secret_key}`.
Accept	string	Required	Always `application/json`.
Content-Type	string	Required	Use `application/json` for JSON writes or multipart/form-data for file upload endpoints.
X-NeroPay-Timestamp	unix timestamp	Required	Required for POST/PATCH/PUT/DELETE.
X-NeroPay-Signature	string	Required	HMAC SHA-256 of `timestamp.raw_body` using the secret key.
Idempotency-Key	string	Required	Required for writes that create or mutate state.

Never expose secret keys in browser code. Use server-side calls for signed writes.

Node.js signature

const timestamp = Math.floor(Date.now() / 1000).toString();
const rawBody = JSON.stringify(payload);
const signature = crypto
  .createHmac('sha256', secretKey)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex');

Signed POST headers

POST /v2/hosted-payments
Authorization: Bearer neropay_secret_...
Accept: application/json
Content-Type: application/json
Idempotency-Key: order_1001_attempt_1
X-NeroPay-Timestamp: 1777411120
X-NeroPay-Signature: 9ea0...

Headers

Headers control JSON responses, connected account scoping, public/client key context and retry safety.

Header	Type	Required	Description
NeroPay-Account	string	Optional	Connected account ID such as NPVesdTGASO23_547878. Platforms use it to act on a connected merchant.
X-NeroPay-Client-Key	string	Optional	Dashboard-visible account client key. If supplied, it must match the authenticated merchant or the NeroPay-Account connected account id.
X-NeroPay-Public-Key	string	Optional	Public key from API credentials.
Idempotency-Key	string	Required	Unique per business operation. Reuse only for exact retries.

Connected account scoping works with payments, balances, identity, compliance, proof, support and resource APIs where enabled.

Connected account header

curl https://eu.neropay.app/v2/account \
  -H "Authorization: Bearer neropay_secret_platform_..." \
  -H "NeroPay-Account: NPVesdTGASO23_547878" \
  -H "X-NeroPay-Client-Key: NPVesdTGASO23_547878" \
  -H "Accept: application/json"

Pagination

List endpoints use page-based pagination when the underlying controller returns a collection.

Query	Type	Default	Description
page	integer	1	Page number.
per_page	integer	25	Number of records per page.
q/search	string	—	Search by supported columns.
status	enum	—	Filter by status where supported.
from / to	date/datetime	—	Filter by created date where supported.
sort	string	-id	Use leading minus for descending order where supported.

Pagination appears inside meta.pagination. Some single-object APIs return only data.

Pagination response

{
  "success": true,
  "data": {
    "account_id": "NPVesdTGASO23_547878",
    "requests": []
  },
  "meta": {
    "pagination": {
      "current_page": 1,
      "per_page": 25,
      "total": 0,
      "last_page": 1
    }
  }
}

Errors

Errors return a consistent JSON object with an application code and human-readable message. Provider terminology is normalised to NeroPay-safe wording before it is returned.

HTTP	Code	Meaning
400	bad_request	Malformed request.
400	missing_idempotency_key	A required Idempotency-Key header is missing.
401	unauthenticated	Missing or invalid API key.
401	invalid_signature	Write request signature verification failed.
403	forbidden	The authenticated account cannot access the resource.
404	endpoint_not_found / not_found	Route or object was not found.
405	resource_read_only	Resource exists but the requested write method is not enabled.
409	idempotency_conflict	The same idempotency key was reused with a different body.
409	connected_account_duplicate	A connected account with the same email or username already exists.
409	duplicate_resource	A resource with the same unique fields already exists for this account.
422	validation_error	Invalid fields.
429	rate_limited	Too many requests.
500	resource_scope_misconfigured	The resource is not safely account-scoped on this installation.

Authentication and account scope errors

HTTP	Code	Meaning
401	missing_credentials	No secret key was supplied.
401	invalid_credentials	The secret key was not recognised.
401	account_key_mismatch	The supplied public key, client key or account id does not match the authenticated account context.
401	invalid_signature	The HMAC signature is missing, malformed or invalid.
403	account_not_allowed	The authenticated account cannot access the supplied connected account.
403	account_inactive	The merchant account is not active.
403	neroconnect_not_enabled	NeroConnect platform access is not enabled for this account.
404	account_not_found	The connected account id was not found for this platform.
422	invalid_account_id	Use the full NeroPay account id format, for example NPVesdTGASO23_547878.

Connected account errors

HTTP	Code	Meaning
409	connected_account_duplicate	A connected account with the same email or username already exists.
422	connected_account_create_failed	The connected account could not be created.
422	invalid_idempotency_key	The supplied idempotency key has an invalid format.
409	duplicate_request	A request with the same idempotency key is still being processed.

Payment and transaction errors

HTTP	Code	Meaning
403	account_banned	The account cannot process the requested operation.
403	payments_paused	The account cannot accept payments right now.
422	currency_not_supported	The requested currency is not enabled or supported.
422	invalid_connect_application_fee	The platform fee is invalid or exceeds the transaction amount.
422	not_cancelable	The transaction can no longer be cancelled.
422	not_refundable	The transaction is not eligible for refund.
422	invalid_refund_amount	The refund amount must be greater than zero.
422	refund_exceeds_transaction	The requested refund exceeds the original transaction amount.
422	insufficient_balance	The wallet balance is not enough to complete the operation.
422	provider_reference_missing	The provider payment reference is missing.
422	cancel_failed / refund_failed	The cancellation or refund could not be processed.

NeroTrade errors

HTTP	Code	Meaning
402	nerotrade_subscription_required	NeroTrade is not active for this account. Activate the NeroTrade plan before calling NeroTrade endpoints.
404	endpoint_not_found	The requested NeroTrade API path under https://eu.neropay.app/v2/nerotrade was not found.
404	unknown_nerotrade_resource	The requested NeroTrade resource name is not recognised.
404	resource_unavailable	The requested NeroTrade table or resource is not available on this installation.
404	not_found	The requested NeroTrade record was not found for this merchant.
404	customer_not_found	The trade account supplied for an invoice, delivery, payment or statement could not be found.
404	invoice_not_found	The invoice supplied for a payment could not be found.
405	use_products	Inventory records should be created as products first, then stock can be updated through the inventory endpoint.
422	empty_payload	No writable NeroTrade fields were supplied for an update request.
422	validation_error	A required field is missing or a supplied field is invalid.
503	nerotrade_schema_missing	NeroTrade database tables are not installed or the NeroTrade SQL update has not been applied.

Terminal errors

HTTP	Code	Meaning
404	location_not_found	The location was not found for this account.
422	location_required	A location id is required.
422	location_bridge_missing	The location is not ready for terminal reader registration.
409	reader_already_registered	The location already has a linked reader.
422	reader_limit_reached	The account has reached its reader limit.
422	invalid_registration_code	The reader registration code is missing or invalid.
404	reader_not_found	The reader does not belong to this account.
422	reader_register_failed	The reader could not be registered.
422	terminal_payment_failed	The terminal payment could not be created.
422	reader_cancel_failed	The reader action could not be cancelled.
500	provider_not_configured	The NeroPay payment bridge is not configured.

Payout and NeroDisburse errors

HTTP	Code	Meaning
403	payouts_paused	Transfers are paused for this account.
403	kyc_required	KYC verification is required before transfers.
404	bank_account_not_found	The bank account was not found for this merchant.
422	bank_account_required	A bank account id is required.
422	bank_account_disabled	The bank account is disabled.
409	duplicate_bank_account	The bank account is already linked to this merchant.
422	bank_account_create_failed	The bank account could not be created.
404	payout_not_found	The payout was not found for this account.

Validation error

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "details": {
      "amount": ["The amount field is required."]
    }
  }
}

NeroTrade subscription error

HTTP/1.1 402 Payment Required
{
  "success": false,
  "error": {
    "code": "nerotrade_subscription_required",
    "message": "NeroTrade is not active for this account. Activate the £99.95/month NeroTrade plan before using NeroTrade API endpoints."
  }
}

NeroPay account id error

HTTP/1.1 422 Unprocessable Entity
{
  "success": false,
  "error": {
    "code": "invalid_account_id",
    "message": "Use the full NeroPay account id format, for example NPVesdTGASO23_547878, or send the numeric connected merchant_id for legacy integrations."
  }
}

NeroTrade endpoint error

HTTP/1.1 404 Not Found
{
  "success": false,
  "error": {
    "code": "endpoint_not_found",
    "message": "The requested NeroTrade API endpoint was not found. Use https://eu.neropay.app/v2/nerotrade with a supported record endpoint."
  }
}

NeroTrade not found error

HTTP/1.1 404 Not Found
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "NeroTrade resource was not found."
  }
}

Immediate payment error

HTTP/1.1 422 Unprocessable Entity
{
  "success": false,
  "error": {
    "code": "terminal_payment_failed",
    "message": "Reader is currently offline. Please make sure the reader is powered on, connected to the internet and try again."
  }
}

Idempotency

Subscriptions: completed writes replay their saved response. Preserve the same key and data after an uncertain result, and refresh the signature. See subscription retries and limits for key scope and review requirements.

Use an idempotency key for each write operation that creates or changes financial state. All write requests must also include a valid HMAC signature.

Good

order_1001_payment_attempt_1 reused only when retrying the same body.

Avoid

Do not reuse one key for different payments, payouts, refunds or proof submissions.

Safe retry

curl https://eu.neropay.app/v2/payouts \
  -X POST \
  -H "Authorization: Bearer neropay_secret_..." \
  -H "Idempotency-Key: payout_1001_attempt_1" \
  -H "Content-Type: application/json" \
  -d '{"amount":1.00,"currency":"GBP","bank_account_id":"ba_123"}'

Account API

Retrieve the authenticated merchant account, create connected merchants and manage core NeroConnect onboarding state.

GET/account

Returns the authenticated merchant or the connected merchant when NeroPay-Account is supplied.

GET/connected-accounts

Lists connected merchants for a NeroConnect platform.

GET response attributes

Attribute	Type	Required	Description
account_id	string	Read-only	Public API account ID.
business_company_name	string	Optional	Company or trading name.
email	string	Required	Primary merchant email.
status	enum	Read-only	active, pending, banned or review state.
kyc_status	enum	Read-only	pending, verified or rejected.
neroconnect_email_sms_handle	enum	Optional	neropay or platform. Controls merchant-facing notification delegation.
neroconnect	object	Read-only	Returned for NeroConnect platform responses. Includes fee payer, platform safety limit, merchant pricing and default connect application fee context.
neroconnect.fee_payer	enum	Read-only	`connected_account` or `platform`. Controls where NeroPay processing fees are charged for connected account payments.
neroconnect.platform_safety_limit	object\|null	Read-only	Returned when the fee payer is platform balance. `null` when the connected account pays NeroPay processing fees.
neroconnect.merchant_pricing	object	Read-only	Shows API, card and keyed/manual fee rates that apply to the connected merchant. In platform balance mode, platforms may manage merchant-specific pricing in the dashboard.

POST/connected-accounts

Creates a connected merchant. Terms acceptance, authorised legal name and the supported-country fields are required before the account is created.

POST /connected-accounts request attributes

Field	Type	Required	Description
`business_company_name`	string	Required	Company or trading name for the connected merchant.
`firstname`	string	Required	Authorised representative first name.
`lastname`	string	Required	Authorised representative last name.
`email`	email	Required	Primary email for the connected merchant.
`country_code`	enum	Required	Supported NeroPay country code such as GB. Must be selected from the supported-country list, not typed freely.
`mobile_code`	string	Required	Dial code for the selected country, for example 44 for GB. Should be supplied from the supported-country list.
`mobile`	string	Required	Representative or merchant contact mobile number.
`business_type`	enum	Required	Business structure such as company, individual or sole_trader where supported.
`nationality`	enum	Required	Representative nationality country code from the supported-country list.
`company_registration_number`	string	Required for companies	Company registration number where the business type requires it.
`representative_job_title`	string	Required	Role/title of the authorised representative, for example Director.
`rep_is_director`	boolean	Required	Confirms whether the representative is a company director.
`rep_is_executive`	boolean	Required	Confirms whether the representative is an executive/control person.
`rep_is_owner`	boolean	Required	Confirms whether the representative is an owner.
`rep_ownership_percent`	number	Required when owner	Ownership percentage, for example 100.
`company_declaration`	boolean	Required	Confirms the company declaration has been accepted.
`address`	string	Required	Registered or trading address line.
`city`	string	Required	City/town.
`postcode`	string	Required	Postcode.
`dob`	date	Required	Representative date of birth in YYYY-MM-DD format.
`industry`	string	Required	Industry/MCC-style code accepted by NeroPay onboarding.
`merchant_website_or_product_description`	text	Required	Website URL or clear description of the products/services sold.
`terms_accepted`	boolean	Required	Must be true. API-created connected accounts are not created without terms acceptance.
`terms_accepted_at`	datetime	Required	Time the connected merchant/authorised person accepted the terms.
`terms_ip`	ip	Required	IP address captured when terms were accepted.
`legal_name`	string	Required	Authorised legal name used to generate the stored electronic signature when a PNG signature is not supplied.
`signature_png_base64`	string\|null	Optional	Base64 PNG signature. If omitted, NeroPay stores a generated typed-signature image from legal_name.
`neroconnect_email_sms_handle`	enum	Optional	neropay or platform. Controls who handles merchant-facing email/SMS communication.
`metadata`	object	Optional	Platform reference data, external IDs or onboarding notes.

Activation reminder: creating a connected account does not complete onboarding. After creation, create an Identity verification link through the NeroPay API, ensure the merchant adds a business bank account, monitor KYC/compliance webhooks and use the Compliance Proof API for proof or document requests before treating the account as fully ready.

Legal acceptance is required: API-created connected accounts must include terms acceptance and an authorised legal name or signature. If terms_accepted is not true, or the legal acceptance data is missing, the account is not created.

Owner and director validation: when rep_is_owner is true, rep_ownership_percent is required and must be between 25 and 100. Use company_has_other_owners and the optional owners[] array only for additional natural-person owners or directors; do not duplicate the authorised representative. Each owners[].email must be unique within the array and different from the connected account's primary email. Supported owner attributes are first_name, last_name, email, dob (YYYY-MM-DD), percent_ownership, is_owner, is_director and is_executive.

GET/connected-accounts/{account_id}

Retrieves one connected merchant.

PATCH/connected-accounts/{account_id}

Updates connected account fields and can trigger account.update webhooks.

PATCH /connected-accounts request attributes

Field	Type	Required	Description
`business_company_name`	string	Optional	Updates the connected merchant company/trading name.
`mobile`	string	Optional	Updates the connected merchant mobile number where allowed.
`neroconnect_email_sms_handle`	enum	Optional	neropay or platform.
`neroconnect_status`	enum	Optional	Dashboard/API operational status such as active, paused or review where enabled.
`metadata`	object	Optional	Platform reference data or internal notes.

Create connected account request

POST /v2/connected-accounts
{
  "business_company_name": "Demo Connected Merchant Ltd",
  "firstname": "Jane",
  "lastname": "Merchant",
  "email": "connected.demo@example.com",
  "country_code": "GB",
  "mobile_code": "44",
  "mobile": "7700000000",
  "business_type": "company",
  "nationality": "GB",
  "company_registration_number": "12345678",
  "representative_job_title": "Director",
  "rep_is_director": true,
  "rep_is_executive": true,
  "rep_is_owner": true,
  "rep_ownership_percent": 100,
  "company_declaration": true,
  "address": "1 Demo Street",
  "city": "London",
  "postcode": "SW1A 1AA",
  "dob": "1990-01-01",
  "industry": "5812",
  "merchant_website_or_product_description": "Online retail platform merchant",
  "terms_accepted": true,
  "terms_accepted_at": "2026-06-12T10:30:00Z",
  "terms_ip": "203.0.113.42",
  "legal_name": "Jane Merchant",
  "signature_png_base64": null
}

Connected account response

{
  "success": true,
  "data": {
    "account": {
      "id": "NPVesdTGASO23_547878",
      "business_company_name": "Demo Connected Merchant Ltd",
      "email": "connected.demo@example.com",
      "status": "pending",
      "kyc_status": "pending",
      "created_at": "2026-04-28T18:00:00.000000Z",
      "neroconnect": {
        "fee_payer": "connected_account",
        "platform_safety_limit": null,
        "merchant_pricing": {
          "api_fixed_fee": 0.00,
          "api_percent_fee": 0.30,
          "card_fixed_fee": 0.00,
          "card_percent_fee": 0.30,
          "keyed_fixed_fee": 0.00,
          "keyed_percent_fee": 0.30,
          "status": "first_month_rate",
          "help": "First month NeroPay processing rate."
        },
        "connect_application_fee_defaults": {
          "fixed": 0.00,
          "percent": 0.50
        }
      }
    }
  }
}

NeroConnect connected accounts

Platforms can create merchants, view balances, manage default platform fees and operate by sending the connected account header.

Concept	Type	Description
Connected account ID	string	Format is unique_account_id + underscore + merchant_id.
NeroPay-Account header	string	Scopes API calls to a connected merchant.
Notification handling	enum	neropay means NeroPay sends email/SMS; platform means platform handles merchant-facing notifications from webhooks.
KYC, bank & compliance	workflow	Must be completed after create account. Use the Identity API to create verification links, ensure a business bank account is added, and use Compliance Proof API plus webhooks for proof/document requests.

Activation reminder: connected accounts should not be treated as fully ready until KYC identity verification, business bank account setup, compliance requests and reserve/proof checks are clear. Partners can create identity verification links through the NeroPay API and should use the compliance proof endpoints whenever NeroPay requests supporting evidence.

Fee payer and pricing context

Mode	NeroPay processing fee payer	Platform safety limit	Notes
`connected_account`	The connected merchant pays NeroPay processing fees.	Not shown. `platform_safety_limit` returns `null`.	This is the default mode. Platform balance is not debited for NeroPay processing fees.
`platform`	The platform balance pays NeroPay processing fees.	Shown in the API response and dashboard.	The connected merchant sees NeroPay processing fee as zero. If the platform balance or outstanding debt reaches the safety threshold, restricted platform actions may be blocked until the balance is restored.

Important: NeroPay fee payer is separate from connect_application_fee. The fee payer setting controls who pays NeroPay processing fees. connect_application_fee is your platform's own application fee and can still be supplied per payment or configured as a dashboard default.

Response compatibility: This is an additive v2 response update. Existing requests do not need a new required parameter. Integrations should safely ignore unknown fields.

Duplicate protection: POST /connected-accounts is idempotent when an Idempotency-Key is supplied. Reusing the same key with the same payload returns the original result. Reusing the same key with a different payload returns 409 idempotency_conflict. A platform cannot create another connected account with an email or username that already exists; duplicate requests return 409 connected_account_duplicate.

Post-create activation checklist

1. POST /v2/connected-accounts
2. POST /v2/identity/verification-links
3. Ask the merchant to add a business bank account
4. Use /v2/compliance/requests and proof endpoints when requested
5. Listen for kyc.*, compliance.* and connected_account.* webhooks

Get connected account

GET /v2/connected-accounts/NPVesdTGASO23_547878

Update connected account

PATCH /v2/connected-accounts/NPVesdTGASO23_547878
{
  "neroconnect_status": "active",
  "metadata": {
    "source": "platform-admin"
  }
}

NeroConnect fee payer context

{
  "neroconnect": {
    "fee_payer": "platform",
    "platform_safety_limit": {
      "blocked": false,
      "limit": 500.00,
      "lowest_wallet_balance": 560.45,
      "outstanding_debt": 4.00
    },
    "merchant_pricing": {
      "api_fixed_fee": 0.00,
      "api_percent_fee": 0.30,
      "card_fixed_fee": 0.00,
      "card_percent_fee": 0.30,
      "keyed_fixed_fee": 0.00,
      "keyed_percent_fee": 0.30
    },
    "connect_application_fee_defaults": {
      "fixed": 0.00,
      "percent": 0.50
    }
  }
}

NeroConnect settings, reports and account operations

API-integrated platforms use their existing API v2 credentials. These endpoints expose platform defaults, connected account records and aggregate reporting without granting access to unrelated merchants or NeroPay-controlled pricing.

GET/neroconnect/settings

Returns notification handling, merchant-facing pricing defaults, reward programme configuration, payout-limit defaults and read-only NeroPay cost context.

PATCH/neroconnect/settings

Updates allow-listed platform defaults. Partial updates are supported.

GET/neroconnect/accounts

Lists only connected accounts assigned to the authenticated NeroConnect platform.

GET/neroconnect/accounts/{account_id}

Returns one assigned connected account and its selected, NeroPay hard-cap and effective payout limits.

GET/neroconnect/reports/overview

Returns account counts and transaction totals for the platform’s own connected merchants.

Security boundary: platform API keys cannot query arbitrary merchant IDs. Account ownership is resolved server-side. NeroPay processing costs and fee-payer responsibility are read-only. Payout defaults can only tighten connected-account behaviour; the effective values never exceed the limits set by NeroPay Admin for that merchant.

Reward scope: API v2 can enable the connected-account reward programme and set its public name. Reward catalogue create, edit, pause and remove operations remain dashboard-only to keep the public write surface small.

PATCH /neroconnect/settings attributes

Field	Type	Required	Description
`notification_handle`	enum	Optional	`neropay` or `platform`.
`pricing_defaults.{channel}.fixed`	decimal	Optional	Fixed merchant-facing default. Channels: `api`, `card`, `manual_keyed`, `application_fee`, `sms`, `card_origin`, `extra_payment_method`, `instant_payout`, `transaction_refund`.
`pricing_defaults.{channel}.percent`	decimal	Optional	Percentage default, 0–100. Available for API, card, manual keyed, application fee, card origin, extra payment method and instant payout channels.
`rewards.enabled`	boolean	Optional	Shows or hides the platform reward programme for connected accounts.
`rewards.name`	string	Optional	Public programme name, 1–120 characters.
`payout_limit_defaults.*`	decimal/integer	Optional	Supported keys: `standard_min`, `standard_max`, `instant_min`, `instant_max`, `weekly_standard_max`, `weekly_instant_max`, `daily_transfer_count`, `nerodisburse_daily_max`. Send `null` to clear one platform default.

Legacy connect_application_fee_defaults.fixed and .percent remain supported aliases for pricing_defaults.application_fee.

Update safe platform defaults

PATCH /v2/neroconnect/settings
Authorization: Bearer neropay_secret_...
Idempotency-Key: nc-settings-20260907-01
X-NeroPay-Timestamp: 1788757200
X-NeroPay-Signature: <hmac_sha256>
Content-Type: application/json

{
  "pricing_defaults": {
    "extra_payment_method": {"fixed": 0.10, "percent": 0.75},
    "card_origin": {"fixed": 0.25, "percent": 3.50}
  },
  "rewards": {"enabled": true, "name": "Kepos Rewards"},
  "payout_limit_defaults": {"instant_max": 2500, "daily_transfer_count": 5}
}

Overview report

GET /v2/neroconnect/reports/overview?from=2026-06-01&to=2026-06-30

Partner commissions & cash-order billing

Charge a service fee per sale, track its allocation, and bill completed cash orders without a monthly subscription. Commerce endpoints use /v2/neroconnect/commerce.

Card orders: continue using connect_application_fee on hosted payments or terminal payments. For a GBP 10.00 payment and GBP 0.50 commission, send amount: 10.00 and connect_application_fee: 0.50. Processing costs and any parent-platform share follow your existing agreement. Do not create another transfer or report that card order as cash usage.

Choose the right operation

Need	Use
Commission on a card sale	Existing payment creation with `connect_application_fee`; automatic existing settlement.
Track commission	`GET /commissions` or `GET /commissions/{transaction_id}`.
Cash-order service fee	Set signup pricing once, then `POST /usage-events` after merchant registration.
Move an agreed amount between parent and partner	Existing `/v2/neroconnect/management/partners/{partnerId}/funds`. This is separate from charging a connected shop for an order.

Authentication and signed writes

Use live server-side credentials over HTTPS. Select one connected shop with NeroPay-Account. Account, destination, fee, provider identifiers and credential overrides in JSON are rejected. The platform may access only its own linked shops. A shop can read its own records, stop future cash fees, and request collection of fees already due. Use the platform account (omit NeroPay-Account) to configure signup pricing.

Every write requires JSON, an 8–100 character Idempotency-Key, X-NeroPay-Timestamp within five minutes and X-NeroPay-Signature. Commerce uses the following newline-separated HMAC message; it differs from legacy payment signing:

Example

timestamp + "\n" + METHOD + "\n" + exact_path + "\n"
+ idempotency_key + "\n" + exact_NeroPay_Account_header + "\n" + raw_json_body

Sign with HMAC-SHA256 using the authenticated secret, as lowercase hexadecimal. Include the full path, e.g. /v2/neroconnect/commerce/usage-events. Use an empty account-header line when configuring pricing on the platform account. Write query parameters are rejected. Send exactly the body that was signed.

Retry the same operation with the same key and body, and a fresh timestamp/signature. Saved responses return Idempotency-Replayed: true. Reusing a key for a different path, shop or body returns 409. An order ID is also unique across pricing versions and retry keys. Keep the same completed timestamp on retries.

POST /pricing uses the platform credentials with no connected-account header. It sets prices displayed to new merchants on the existing branded registration page. It does not send a contract or move money. All fields below are required:

Field	Meaning
`currency`	`GBP`.
`fixed_minor`	Integer pence per completed cash order, 0–100000.
`percent_bps`	Integer basis points, 0–5000; 500 means 5%.
`max_order_fee_minor`	Per-order cap, 1–100000 pence; must cover the fixed fee.
`daily_cap_minor`	Maximum new fees recorded per shop per application-calendar day, 1–1000000 pence. Applies across agreement versions; cancellation does not replenish the cap.
`collection_interval`	`daily` or `weekly`. A recorded order becomes due after one or seven days.
`terms_reference`	Your immutable terms/version reference, 1–100 ASCII letters, digits, dots, colons, hyphens or underscores.

Fee = fixed fee + percentage rounded to the nearest penny, capped by the agreed per-order maximum. The resulting fee must be positive and less than the order amount. At least one of fixed fee or percentage must be non-zero.

2. Registration activates pricing automatically

The merchant sees the fixed fee, percentage, per-order maximum, daily limit and collection schedule on the existing branded signup form. Submitting that registration records the displayed price and balance-collection authorisation automatically. There is no separate contract email, acceptance page or API acceptance step.

GET /pricing with the platform credentials and no account header returns the current signup default. With a connected merchant account header it returns that merchant's active pricing. Changing signup defaults affects future registrations only. A changed price invalidates an already-open signup form; the merchant must reload to see the current price.

The existing parent/EPOS partner acceptance recorded at /neroconnect/{platform}/partner/register is reused for parent allocation. It is separate from the shop's own registration. Cash fees are collected from the connected shop's eligible balance. Existing accounts without recorded cash pricing are not silently activated; usage returns 403. Existing compatibility agreement endpoints remain available for integrations already using them, but are not part of this signup flow.

nc_commerce_agreements is internal versioned pricing/registration evidence. It retains the price and parent allocation snapshot that applied to each order; it does not initiate document sending. Previously registered shops retain their accepted price. Revoking a pricing record stops new orders, while accrued fees remain due.

Parent allocation: the existing partner registration acceptance is retained. Revenue-share terms continue to apply. For the Rate Model, the parent must configure a Cash order service fees rate through existing partner pricing controls; changing that pricing does not require a second partner signup.

3. Record completed cash usage

POST /usage-events is available to the linked platform. Required fields: unique order_id, integer amount_minor (1–10000000 pence), currency: GBP, payment_method: cash, and completed_at as UTC YYYY-MM-DDTHH:MM:SSZ. The active pricing recorded at signup is selected automatically. agreement_id is optional for existing integrations. The order must be completed after the pricing activation, within the past 30 days, and no more than five minutes ahead.

The response contains the server-calculated fee, state: accrued, and due_at. This is a service-fee receivable, not a customer card payment or proof that cash was physically collected. Send only completed orders your merchant has authorised you to report. GET /usage-events lists them.

POST /usage-events/{id}/cancel with {} cancels an order fee before collection has been reserved. Once assigned to a collection it returns 409; reconcile that collection before making a fee adjustment. Card refunds continue to use the existing transaction refund endpoint.

4. Collection and allocation

The existing NeroConnect web cron groups due fees under their registered pricing version. Each collection contains at most 200 orders and GBP 10,000 in fees; at least GBP 1.00 is required. POST /collections with {} requests preparation of a due collection and returns 202. It cannot override the amount, recipient or due date. If none qualifies, the response has state: not_due.

Automatic collection currently requires eligible UK GBP connected payment accounts, verified active merchants, legally effective merchant authorisation, and sufficient unrestricted local and provider balance. It is a payment-balance debit, not a bank-account Direct Debit. Cash-only shops without a funded eligible payment balance remain pending; this API does not charge their customer or invent funds.

Collection costs follow the platform's existing transfer tariff and are deducted from its fee income. Parent allocation is applied before the partner net credit. GET /collections and GET /collections/{id} return the latest state:

State	Meaning
`pending`	Due fees grouped; waiting for the scheduler or eligible funds.
`reserved`	Local balance reserved; provider collection awaits confirmation.
`collected`	Provider confirmed collection; allocation is still pending.
`settled`	Required transfers confirmed and partner income recorded. This does not mean a bank payout has arrived.
`review`	An earlier outcome needs reconciliation; no fresh debit is created.

The optional pending_reason explains waits such as insufficient_available_balance, account_not_eligible, balance_or_account_restriction, allocation_pending or reconciliation_required. A lost response retains its original provider operation. An unresolved operation beyond its safe retry window stops for reconciliation. Never send replacement orders or funding requests to bypass a pending collection. Reading a collection does not retry money movement.

Card commission reporting and events

Commission IDs are the existing numeric transaction IDs. application_fee_minor is the saved requested commission; recorded_fee_minor requires the fee ledger; transferred_net_minor is returned only when the exact net allocation is known. A null amount means unconfirmed or unavailable, not zero.

allocation_state is pending, recorded, transferred, adjustment_pending, reversed, not_earned or review. Refunding the customer does not itself prove a commission transfer was reversed. Existing refund and dispute handling remains authoritative.

Subscribe in your existing webhook settings to commerce.commission.updated and commerce.collection.settled. Events use the existing webhook secret and timestamp.body HMAC verification. Delivery is retried through the existing notification outbox; deduplicate by event ID. Public HTTPS destinations are validated and DNS-pinned on every attempt, with redirects and private networks blocked.

Commission events reflect a bounded cron sweep of payments from the past 30 days. For older payments or immediate reconciliation, retrieve the commission directly. Collection events go only to the original merchant and platform; commission events go to the original platform.

Dashboard visibility

In Transactions, confirmed cash commission income appears in the receiving platform's own ledger. Open transaction details to see the shop, fee total, your collected income, collection state and included order references. A reserved merchant debit remains clearly marked with its collection state. Pending usage without a ledger movement is available through the usage/collection APIs rather than appearing as received income.

In NeroConnect API Logs, choose API requests to inspect commerce request references, HTTP results, replay status and returned operation identifiers. Registered commerce webhook attempts remain in Webhook deliveries. Requests never log credentials or signatures. Only scoped account records and authorised staff financial details are visible.

Pagination, errors and limits

Paginated list endpoints (excluding GET /pricing) accept limit (1–50, default 25) and after from the prior next_cursor. Cursors are opaque except numeric commission IDs. Results are ordered by ID, not by date. Read requests have no body. All other query/body fields are rejected.

Limits: 64 KB request body, 2048-character request URI, 60 writes per minute per principal and target, 120 reads per minute, plus the existing shared IP throttle. Handle 429 using Retry-After. Common errors: 401 invalid signature/credentials; 403 account, consent or policy restriction; 404 scoped record not found; 409 conflicting order/key or reserved collection; 422 invalid fields/cap/date; 503 schema/provider service unavailable.

These commerce endpoints are live-only. Test keys cannot enter them. Validate your integration and use a small agreed live amount before enabling automatic cash-order billing. Existing payment sandbox endpoints remain separate.

Card sale: GBP 10, commission GBP 0.50

POST /v2/terminal/payments
Authorization: Bearer PLATFORM_SECRET
NeroPay-Account: NPexample002_2
Content-Type: application/json

{
  "amount": 10.00,
  "currency": "GBP",
  "reader_id": "YOUR_MERCHANT_READER_ID",
  "reference": "CARD-1001",
  "connect_application_fee": 0.50
}

Use the existing Terminal API signing rules for this existing endpoint. For hosted checkout use the same fee parameter with the required hosted payment fields.

POST /v2/neroconnect/commerce/pricing
Authorization: Bearer PLATFORM_SECRET

{
  "currency": "GBP",
  "fixed_minor": 50,
  "percent_bps": 0,
  "max_order_fee_minor": 50,
  "daily_cap_minor": 5000,
  "collection_interval": "weekly",
  "terms_reference": "EPOS-CASH-2026-01"
}

Read the registered merchant price

GET /v2/neroconnect/commerce/pricing
Authorization: Bearer PLATFORM_SECRET
NeroPay-Account: NPexample002_2

The merchant registration has already activated this pricing. No acceptance request is needed.

Completed cash order

POST /v2/neroconnect/commerce/usage-events
NeroPay-Account: NPexample002_2

{
  "order_id": "CASH-1001",
  "amount_minor": 1000,
  "currency": "GBP",
  "payment_method": "cash",
  "completed_at": "2026-10-16T12:30:00Z"
}

Use the actual completion time. One GBP 10.00 cash order records a 50p service fee under this registered price; it does not trigger a GBP 10.00 card charge.

Node.js: sign a commerce write

import { createHmac, randomUUID } from 'node:crypto';

const secret = process.env.NEROPAY_SECRET;
const path = '/v2/neroconnect/commerce/usage-events';
const account = 'NPexample002_2';
const key = randomUUID(); // Save with this order; reuse on retries.
const body = JSON.stringify(order);
const timestamp = String(Math.floor(Date.now() / 1000));
const message = [timestamp, 'POST', path, key, account, body].join('\n');
const signature = createHmac('sha256', secret).update(message).digest('hex');

const response = await fetch('https://eu.neropay.app' + path, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${secret}`,
    'Content-Type': 'application/json',
    'NeroPay-Account': account,
    'Idempotency-Key': key,
    'X-NeroPay-Timestamp': timestamp,
    'X-NeroPay-Signature': signature
  },
  body
});
const result = await response.json();
if (!response.ok) throw new Error(result.error?.message || 'Request failed');

Collection response

{
  "success": true,
  "data": {
    "id": "COLLECTION_ID",
    "currency": "GBP",
    "fee_minor": 100,
    "order_count": 2,
    "state": "pending",
    "pending_reason": "awaiting_schedule",
    "collected": false,
    "allocated": false,
    "created_at": "2026-10-23T12:30:00+00:00",
    "settled_at": null,
    "partner_net_minor": 99
  }
}

The example assumes a 1% collection tariff and no parent share. Your actual net follows your account tariff and accepted partner terms. partner_net_minor is shown only to the platform; while pending, it is the frozen expected allocation.

Management authentication

Shared authentication, signing and retry rules for the NeroConnect Partner API and Sales Agent API. Both use the /v2/neroconnect/management prefix.

Authority: use the authenticated platform's own secret API key on your server. Never give it to sales agents or put it in browser/mobile code. Agent logins remain restricted panel memberships, not management API credentials. Parent controls and account moves require a main platform with NeroConnect Partner enabled; a second-tier partner cannot manage its parent, siblings or create a further tier. Child platforms can manage their own agents only when their active agreement, API, account and report policies permit it.

Partner API →Partners, pricing, account moves and funding Sales Agent API →Profiles, assignments and commission reports

Signed writes and retry rules

Every POST, PUT and PATCH requires Bearer authentication, Content-Type: application/json, an Idempotency-Key of 8–100 letters, digits or ._:-, and timestamp/signature headers. Write bodies must be JSON objects, at most 64 KB, with no query parameters or uploads. Unknown fields are rejected. GET uses Bearer authentication and allow-listed query filters.

For these management endpoints only, sign the following UTF-8 bytes with HMAC-SHA256 using your secret key, returning lowercase hexadecimal. Use a Unix timestamp within five minutes. Do not reformat the JSON after signing. The exact path includes /v2; do not include a host, query or trailing slash. Existing API endpoints retain their existing signature format.

Management signature input

timestamp + "\n" + UPPERCASE_METHOD + "\n" + PATH
          + "\n" + IDEMPOTENCY_KEY + "\n" + RAW_JSON_BODY

A repeated HTTP retry key for the same method/path/platform returns 409 duplicate_request for 24 hours, not a cached success response. Inspect the current resource before retrying with a new HTTP key. For a move reuse the original preview_id; for funding reuse the original request_id. These durable operation IDs prevent a second move or second debit even when the HTTP key changes. Invalid submissions also consume their HTTP retry key.

Limits and safety: 60 requests/minute per IP before authentication, plus 60 reads or 20 writes/minute per platform. Maximum list page size 100; commission reports cover at most 31 calendar days. Ownership, merchant status, parent policies, KYC requirements, debt restrictions and version tokens are checked server-side. No client field can change identity verification, activate a partner, override NeroPay tariffs or choose a settlement account.

Error handling

Responses use {"success": true, "data": ...} with pagination meta where applicable, or {"success": false, "error": {"code": ..., "message": ...}}. Expect 401 for credentials/signatures, 403 for restricted management, 404 for unavailable/foreign resources, 409 for duplicate keys or changed controls, 413 for body size, 422 for invalid/stale fields, 429 for throttling, and 503 for unavailable setup. Treat 5xx and timeouts as an unknown result; inspect the same durable operation ID before doing anything else. Public failures do not expose SQL, credentials, stack traces or upstream exception messages.

NeroConnect Sales Agent API

Manage your platform’s sales-agent profiles, merchant assignments and commission reports. Agent panel logins do not grant management API credentials.

Base path: /v2/neroconnect/management · Authentication & signed requests ↗

Reporting and access: all agent resources belong to the authenticated platform. Commission reports do not trigger payouts. Child platforms need the active agreement and applicable API, account and report permissions.

Sales agents

GET/sales-agents

Own platform profiles. Optional limit (1–100) and page (1–10000).

POST/sales-agents

Create a profile for an existing active team membership belonging to this platform. Fields: integer staff_id, name (max 150), decimal-string commission_percent (0–100, at most two decimal places), boolean active. Email matching never grants authority.

PATCH/sales-agents/{agentId}

Send name, commission_percent, active and the last read integer revision. Do not send staff_id on updates. Existing historical commission periods are preserved.

PUT/accounts/{merchantId}/sales-agent

Assign an own connected merchant: agent_id (integer or null to unassign), override_percent (decimal string or null for the profile default), and expected_assignment (current assignment ID, or 0 if unassigned). All three fields are required.

GET/sales-agents/{agentId}/accounts

Only accounts currently assigned to this own-platform agent, with assignment IDs and rates. Optional limit, page.

GET/sales-agents/{agentId}/commission-report

Optional inclusive from/to in YYYY-MM-DD, default last seven days. Calculates a percentage of the platform's recorded net income, not the merchant's gross sales; child income uses its retained share after parent allocation. Amounts are integer minor units, grouped by currency. Unreconciled income remains pending. This report does not automatically pay agents.

PHP signed management request

$secret = getenv('NEROPAY_SECRET_KEY'); // server only
$path = '/v2/neroconnect/management/sales-agents';
$method = 'POST';
$body = json_encode([
    'staff_id' => 463,
    'name' => 'Sales agent',
    'commission_percent' => '20.00',
    'active' => true
], JSON_UNESCAPED_SLASHES);
$timestamp = (string) time();
$httpKey = 'agent-create-' . bin2hex(random_bytes(12));
$signature = hash_hmac('sha256',
    $timestamp . "\n" . $method . "\n" . $path
    . "\n" . $httpKey . "\n" . $body, $secret);
$curl = curl_init('https://eu.neropay.app' . $path);
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => $method,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $secret,
        'Content-Type: application/json',
        'Idempotency-Key: ' . $httpKey,
        'X-NeroPay-Timestamp: ' . $timestamp,
        'X-NeroPay-Signature: ' . $signature
    ]
]);
$result = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

NeroConnect Partner API

Manage platform partners, connected account moves, partner pricing and funded transfers. Use the main platform’s server credentials for parent operations.

Base path: /v2/neroconnect/management · Authentication & signed requests ↗

Connected account moves

GET/account-moves

Eligible family platforms and source accounts. Optional integer source_id (defaults to the authenticated parent), q (max 100), page, channel (all, terminal, ecommerce, mixed).

POST/account-moves/preview

Required integer source_id, different integer destination_id and 1–20 distinct integer account_ids. Returns preview_id, expires_in: 300 and an ownership/pricing preview. No mutation at preview time.

POST/account-moves/commit

Required UUID preview_id, api_key_acknowledged: true and ownership_acknowledged: true. Signed API confirmation replaces browser password entry. The preview must belong to this platform and API actor; browser/staff previews cannot be consumed by the API. Changed ownership, pricing, agreements, balances or expired previews require a new preview.

Move consequences: merchant identity and transaction history remain the same. Historical ownership and commissions are retained. No wallet balance is transferred. Future payments use the destination platform. Update merchant websites/integrations to its API key; the previous platform key loses access. Destination keys are never returned by this API.

Partner controls

GET/partners

Parent-owned partners only. Optional limit, page, state (pending, active, suspended).

GET/partners/{partnerId}

Safe agreement terms/policies and opaque pricing_version/management_version. Read immediately before saving. Does not return secret keys, identity documents or provider account identifiers.

PATCH/partners/{partnerId}/pricing

Direct Save, not Send proposal. Required pricing_version and model (rate or revenue_share); revenue_share requires decimal-string share_percent. Optional rates and products as described below. An accepted initial agreement is required; pricing never activates a partner or creates consent. New rates are effective-dated; historical income is unchanged.

PUT/partners/{partnerId}/policies

Required current management_version plus a complete policies object. This replaces the permitted controls; it cannot bypass NeroPay's own restrictions.

POST/partners/{partnerId}/suspend

Required current management_version. Suspends an own partner without changing balances, historical commissions or KYC.

GET/partner-settings

Parent signup defaults, revision and existing signup status.

PUT/partner-settings

Required expected_revision, pricing-model input, and complete policies. Updates future defaults only. Existing signup enablement and legal URLs are retained; existing agreements are not rewritten.

GET/partner-agreement

A second-tier platform reads its own safe agreement. No sending, accepting, activating or replacing a legal agreement is exposed by this management API.

Pricing and policy inputs

Send monetary/percentage inputs as decimal strings, not floats or internal minor-unit fields. Fixed partner charges and product prices use GBP. Responses use integer minor units and basis points (100 bps = 1%). Currency totals are never combined without conversion.

rates is keyed by api, card, keyed, origin, extra_method, sms, cellular, instant_payout, refund, monthly_account or monthly_terminal; values accept fixed and percent. Percentages are 0–100. Monthly account/terminal charges cannot carry a percentage. Omitted categories become zero in the saved replacement pricing. products maps server-recognised catalogue slugs to GBP decimal strings; unknown slugs are rejected.

A complete policies object requires booleans accounts, pricing, branding, invoices, dashboard, store, reports, api, funds, view_as, settings, hide_share_entries, integer max_accounts (0–100000) and GBP decimal-string max_transfer. Responses return this limit as max_transfer_minor; convert it when constructing an input.

Funded partner movements

POST/partners/{partnerId}/funds

Parent-only. Required direction (send or pull), positive GBP decimal-string amount (max seven whole digits, two decimals), and stable UUID request_id. Requires an active, accepted agreement, funds policy, verified active parties and the agreed transfer cap. No arbitrary destination, provider account, currency, fee or negative amount is accepted.

GET/funding/{fundsId}

Read the 64-character opaque ID returned by the funding response. Only this parent's discretionary funding rows are visible; internal recovery and store allocation rows are excluded.

No unfunded payouts: funding uses registered parent/partner settlement accounts only, never the payment service's operating account. The source wallet is reserved without overdraft; unrestricted available settlement funds must be collected and confirmed before the recipient transfer. Existing debt, reconciliation and policy safeguards still apply. Fees follow the server's existing parent tariff: send debits amount + fee and credits amount; pull debits amount and credits amount − fee. No API endpoint creates a balance, overrides a tariff, withdraws to arbitrary bank accounts or pays sales-agent commission automatically.

Funding returns HTTP 200 only when state=settled and confirmed=true; otherwise HTTP 202 means reserved/awaiting confirmation or review, not paid. Poll the funding ID. Do not submit a new UUID after a timeout: retry with the same request_id and unchanged details (a newly signed HTTP retry key is allowed). Reservations survive uncertain responses and are reconciled by the existing worker. A changed request amount/direction cannot reuse an existing UUID.

Move preview body

{
  "source_id": 26302,
  "destination_id": 36697,
  "account_ids": [36499]
}

Move commit body

{
  "preview_id": "<UUID returned by preview>",
  "api_key_acknowledged": true,
  "ownership_acknowledged": true
}

Direct partner pricing save

PATCH /v2/neroconnect/management/partners/36697/pricing

{
  "model": "revenue_share",
  "share_percent": "50.00",
  "pricing_version": "<read current opaque token>"
}

Funded partner send (GBP)

POST /v2/neroconnect/management/partners/36697/funds

{
  "direction": "send",
  "amount": "100.00",
  "request_id": "<generate and persist one UUID per transfer>"
}

// HTTP 202 is NOT proof of payment:
{
  "success": true,
  "data": {
    "id": "<64-character funding ID>",
    "source_id": 26302,
    "destination_id": 36697,
    "currency": "GBP",
    "debit_minor": 10150,
    "credit_minor": 10000,
    "fee_minor": 150,
    "state": "reserved",
    "confirmed": false
  }
}
// Fee example assumes the existing 1.5% tariff.
// Poll GET /v2/neroconnect/management/funding/{id}.

NeroPay Store API checkout links

Create a secure NeroPay Store checkout link for terminal, EPOS, scanner, scale and accessory orders. The API creates a pending hardware order and returns a hosted checkout URL; card details are collected only on NeroPay-hosted checkout.

GET/neropay-store/products

Lists available NeroPay Store hardware product slugs and prices.

POST/neropay-store/checkout-links

Creates a hosted checkout link for the authenticated merchant or a connected account.

GET/neropay-store/orders/{id}

Reads a NeroPay Store order created for the authenticated account context.

Abuse prevention: the API never accepts custom card data or arbitrary item prices. Product slugs and prices are resolved server-side from the NeroPay Store catalogue. Use NeroPay-Account or account_id only for connected accounts assigned to your platform.

GET /neropay-store/products response attributes

Field	Type	Description
`slug`	string	Stable catalogue slug used for ordering.
`product_code`	string	Ordering code for API integrations. This is currently the same value as `slug`.
`code`	string	Short alias for `product_code`.
`name`	string	Product name displayed on the hosted checkout.
`price`	decimal	Server-side NeroPay Store catalogue price. Resellers cannot override this in API requests.
`category`	string	Hardware, terminal, EPOS, scale, printer or accessory grouping.

Product codes: call GET /neropay-store/products for the live catalogue. Send the returned product_code in items[].product_code. Current public codes are shown below.

product_code	Name	Category	Base price	Optional checkout options
`pro-plus`	Card Terminal PRO+	terminal	£295.00	None
`ccd-tablet`	Card Terminal CCD	terminal	£135.00	`options.device`: `no_device`, `fire8`, `ipadair11`
`epos`	NeroPay EPOS Kit	epos	£799.95	None
`nerokiosk`	NeroPay Self-Service Kiosk	kiosk	£800.00	`options.size`: `21_5`, `23_6`, `32`; optional `floor_standing`, `ads=ad_free`
`nerokds`	NeroKDS	kds	£450.00	`options.size`: `21_5`, `24`
`pro-plus-charging-dock`	PRO+ Charging Dock	accessory	£60.00	None
`ccd-charging-dock`	CCD Charging Dock	accessory	£60.00	None
`charger`	Additional Charger	accessory	£20.00	None
`caller-id-unit`	NeroPay Caller ID Unit	accessory	£110.00	None
`neroscale1`	NeroPay Manual Scale	accessory	£75.00	None
`neroscalepro`	NeroPay Barcode Scale Pro	accessory	£375.00	None
`neroscan1`	NeroPay Wireless 1D/2D Barcode Scanner	accessory	£65.00	None
`neroscanpro`	NeroPay Desktop Barcode Scanner Pro	accessory	£95.00	None
`neromini`	NeroPay Mini Bluetooth Barcode Scanner	accessory	£45.00	None
`receipt-printer-80mm`	80mm Thermal Receipt Printer	accessory	£155.00	`options.connection`: `usb`, `lan`, `wifi`, `bluetooth`
`cash-drawer-rj11`	Cash Drawer Base with RJ11 Connector	accessory	£55.00	None
`thermal-paper-rolls`	Thermal Paper Rolls	accessory	£20.00	`options.pack`: `5`, `10`, `20`; `options.roll_size`: `58x58`, `80x80`

POST /neropay-store/checkout-links attributes

Field	Type	Required	Description
`account_id`	string	Platform only	Connected merchant account. You may also send `NeroPay-Account`.
`items[].product_code`	string	Required*	Product code returned by `GET /neropay-store/products`. You may send `items[].slug` or `items[].code` instead.
`items[].slug`	string	Alias	Catalogue slug returned by the products endpoint.
`items[].quantity`	integer	Optional	Quantity, 1 to 99. Defaults to 1.
`billing`	object	Required	Billing contact and billing address. Required keys: `name`, `email`, `phone`, `line1`, `city`, `postcode`, `country`. Optional keys: `line2`, `county`.
`shipping`	object	Required	Delivery contact and shipping address. Required keys: `name`, `phone`, `line1`, `city`, `postcode`, `country`. Optional keys: `email`, `line2`, `county`.
`reference`	string	Optional	Your reseller/order reference stored in metadata.

Required address details: checkout-link requests are rejected unless both billing and shipping are supplied. NeroPay Store API v2 does not fall back to the merchant profile address for hardware checkout links.

Order scope: GET /neropay-store/orders/{id} only returns an order when the order belongs to the authenticated merchant or the connected merchant supplied with NeroPay-Account/account_id. It does not list all orders or expose another merchant’s orders.

Create terminal checkout link

curl https://eu.neropay.app/v2/neropay-store/checkout-links \
  -X POST \
  -H "Authorization: Bearer neropay_secret_..." \
  -H "Idempotency-Key: store-checkout-order-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "NPVesdTGASO23_547878",
    "reference": "STORE-ORDER-1001",
    "items": [
      {"product_code": "pro-plus", "quantity": 1},
      {"product_code": "pro-plus-charging-dock", "quantity": 1}
    ],
    "billing": {
      "name": "Customer Name",
      "email": "customer@example.com",
      "phone": "+447700900123",
      "line1": "1 High Street",
      "city": "London",
      "postcode": "SW1A 1AA",
      "country": "United Kingdom"
    },
    "shipping": {
      "name": "Customer Name",
      "phone": "+447700900123",
      "line1": "1 High Street",
      "city": "London",
      "postcode": "SW1A 1AA",
      "country": "United Kingdom"
    }
  }'

Response

{
  "success": true,
  "data": {
    "order": {
      "id": 12345,
      "reference": "API-STORE-ORDER-1001-AB12C",
      "total": 355.00,
      "status": "pending",
      "checkout_url": "https://eu.neropay.app/neropay-store/pay/12345/..."
    },
    "checkout": {
      "url": "https://eu.neropay.app/neropay-store/pay/12345/...",
      "payment_collection": "hosted_checkout_only"
    }
  }
}

Payments

Recommended for online checkout, online ordering and website payments. Create a NeroPay-hosted checkout URL and redirect the customer there. Card details are collected by NeroPay-hosted checkout and are never submitted through your API payload.

POST/hosted-payments

Creates a hosted checkout URL for an order or invoice.

POST/payment-links

Creates a simple LinkPay checkout link when you only need a payment URL.

POST/terminal/payments

Sends an in-person card-present payment action to a terminal reader.

POST payment request attributes

Field	Type	Required	Description
identifier	string	Required	Your unique order, invoice or checkout reference.
amount	decimal	Required	Payment amount in major units, e.g. 15.99.
currency	enum	Required	Currency such as GBP or EUR.
details	text	Required	Customer-facing or internal checkout description.
ipn_url	url	Required	Receives hosted-payment outcome updates, including a declined attempt and a later success. The initial API response is not proof of payment.
success_url	url	Required	Where the customer is returned after a successful payment.
cancel_url	url	Required	Where the customer is returned after cancellation.
customer_name	string	Required	Customer name shown on the checkout record.
customer_email	email	Required	Customer email shown on the checkout record.
customer_phone	string	Optional	Customer phone number, if collected.
account_id	string	Platform only	Connected merchant account for NeroConnect routing. You may also send the `NeroPay-Account` header.
connect_application_fee	decimal	Optional	Platform fee charged for a connected account payment.
metadata	object	Optional	Additional key/value data returned in responses and webhooks where supported.

Use hosted checkout by default: do not send card number, CVC, expiry date or cardholder payment details to the API. NeroPay-hosted checkout keeps sensitive card data outside your server.

NeroConnect routing: when a platform API key creates a checkout for a connected merchant, send NeroPay-Account or account_id with that connected merchant account on every request.

Hosted checkout is the recommended online payment flow: direct card payment creation is not part of the public API. Use /v2/hosted-payments for online checkout or /v2/payment-links for a simple payment link.

Hosted-payment result lifecycle

Request rejected immediately

The API returns HTTP 4xx/5xx with success: false and an error object. Do not create or confirm the order as paid.

A payment attempt is declined

NeroPay may post status=failed with an error object to the payment's ipn_url. This describes that attempt: the customer may retry the same checkout and subsequently pay successfully.

Failed IPN attributes

Field	Type	Description
status	enum	`failed` for an unsuccessful payment attempt. A later `success` notification may follow for the same checkout.
identifier	string	Your original order or invoice identifier.
signature	string	Uppercase HMAC-SHA256 of `amount + identifier` using the merchant secret API key.
error.code	string	Stable machine-readable category, such as `card_declined` or `payment_failed`.
error.message	string	Provider-neutral support message safe to display or log.
error.decline_code	string	Optional more specific decline reason, such as `insufficient_funds`.
data	object	Payment reference, status, amount, customer, currency and a repeated error object for existing IPN consumers.

IPN transport: hosted-payment IPNs use application/x-www-form-urlencoded for compatibility with existing integrations. The example is shown as the decoded object. Use identifier or data.payment_trx to find the order, not to discard every later update. Process each outcome safely and fulfil the order only once after confirmed success.

Registered webhooks: platforms using the reusable Webhooks API must subscribe to both transaction.succeeded and transaction.failed. This is separate from the per-payment ipn_url.

A failed attempt is not necessarily the final order outcome.

For example, an attempt may be declined for insufficient_funds, then succeed when the customer retries using another payment method. Reopen the original NeroPay checkout URL and keep the same order identifier. Where the existing payment remains retryable, NeroPay reuses its PaymentIntent internally. Do not create another checkout or change the identifier simply because an attempt failed, a request timed out or a callback has not arrived.

If you repeat a creation request, keep the same merchant account, identifier, amount, currency and callback URL, and reuse the original Idempotency-Key for that same request. Retrieve the payment's current status if the response is uncertain. A cancelled, expired or conflicting payment needs verification before a replacement is created; never assume that money has not moved.

Payment listener and order reconciliation

Incoming update	Order handling
Initial API request accepted / pending	Save the reference and checkout URL. Do not mark the order as paid or print a paid order.
Declined attempt / failed	Record the attempt and show an appropriate retry message. Keep the listener active for a later successful payment on the same order.
Confirmed success after a failure	Update the same order to paid, and queue fulfilment or printing once. Do not discard success because the order already has a failed record.
Duplicate delivery or an older failure after success	Acknowledge the delivery without repeating fulfilment. Never change an already-paid order back to failed because of a payment-attempt event. Refunds are separate events.

Delivery and verification: callbacks can be retried and can arrive out of order. Verify the applicable signature, save the event durably, then return HTTP 2xx promptly. Process printing and other slow work asynchronously. For registered JSON webhooks, verify the timestamp and HMAC against the unmodified body; use X-NeroPay-Event-Id to identify a delivery stream and also protect fulfilment with a unique order-level guard. For legacy form IPNs, verify the documented signature and retrieve the current payment status through the authenticated API before fulfilment, as the legacy signature covers the amount and identifier rather than the complete outcome payload. Do not treat a browser redirect as payment confirmation.

Important distinction: the per-payment form IPN uses status=success or status=failed; registered JSON webhooks use transaction.succeeded or transaction.failed. These are separate delivery channels. Use one authoritative fulfilment path, or deduplicate across both channels using the same merchant/order reference.

Hosted payment request

POST /v2/hosted-payments
NeroPay-Account: NPVesdTGASO23_547878
{
  "identifier": "ORDER-1001",
  "amount": 15.99,
  "currency": "GBP",
  "details": "Online order #1001",
  "customer_name": "Jane Guest",
  "customer_email": "jane@example.com",
  "success_url": "https://example.com/order/success",
  "cancel_url": "https://example.com/checkout",
  "ipn_url": "https://example.com/webhooks/neropay",
  "connect_application_fee": 0.30,
  "metadata": {
    "cart_id": "cart_1001"
  }
}

Hosted payment response

{
  "success": true,
  "data": {
    "id": 208198,
    "account_id": "NPVesdTGASO23_547878",
    "identifier": "ORDER-1001",
    "payment_reference": "NP-EHPS4218-ba542",
    "status": "pending",
    "amount": 15.99,
    "currency": "GBP",
    "connect_application_fee": 0.30,
    "checkout_url": "https://eu.neropay.app/initiate/payment/checkout?payment_id=..."
  }
}

Failed hosted-payment IPN (decoded)

{
  "status": "failed",
  "identifier": "ORDER-1001",
  "signature": "A6E6...",
  "error": {
    "code": "card_declined",
    "message": "Your card was declined.",
    "decline_code": "insufficient_funds"
  },
  "data": {
    "payment_trx": "NP-EHPS4218-ba542",
    "status": "failed",
    "amount": 15.99,
    "account_holder": "Jane Guest",
    "payment_type": "hosted",
    "currency": {"code": "GBP", "symbol": "£"},
    "error": {
      "code": "card_declined",
      "message": "Your card was declined.",
      "decline_code": "insufficient_funds"
    }
  }
}

Payment Links / LinkPay

Create and inspect LinkPay checkout links. LinkPay records are separated from generic API payments.

GET/payment-links

Lists LinkPay records.

POST/payment-links

Creates a payment link.

GET/payment-links/{id}

Retrieves one payment link.

POST /payment-links request attributes

Field	Type	Required	Description
currency	enum	Required	Payment currency.
amount	decimal	Required	Amount in major units.
details	text	Required	Description shown to the buyer.
customer_name	string	Optional	Pre-filled customer name.
customer_email	string	Optional	Pre-filled customer email.
success_url	string	Optional	Redirect URL after success.
cancel_url	string	Optional	Redirect URL after cancellation.
ipn_url	string	Optional	Webhook/IPN URL for this payment link.

Create payment link

POST /v2/payment-links
{
  "currency": "GBP",
  "amount": 9.99,
  "details": "Product or service",
  "customer_name": "Jane Guest",
  "customer_email": "jane@example.com",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "ipn_url": "https://example.com/webhooks/neropay"
}

Payment link response

{
  "success": true,
  "data": {
    "payment_link": {
      "id": 1042,
      "amount": 9.99,
      "currency": "GBP",
      "status": "pending",
      "checkout_url": "https://pay.neropay.app/link/np_..."
    }
  }
}

Contracts

Contracts API

Create merchant contracts, store contract rules, require full or deposit payments and send customers to a secure NeroPay contract review page.

GET/contracts

Lists contracts for the authenticated merchant or connected merchant when NeroPay-Account is supplied.

POST/contracts

Creates a contract with customer details, formatted content, signature rules and optional full or upfront payment.

GET/contracts/{id}

Retrieves one contract by internal ID or public contract reference where supported.

PATCH/contracts/{id}

Updates contract fields, customer details, signature rules, status or payment settings.

DELETE/contracts/{id}

Deletes an unpaid draft/sent contract where the merchant account is allowed to do so.

POST/contracts/{id}/payment-link

Creates a secure NeroPay checkout link for the required contract payment.

GET/contracts/{id}/form

Returns the contract intake/customer form definition.

GET/contracts/{id}/form-submissions

Lists customer form submissions for the scoped contract.

POST/contracts/{id}/form-submissions

Stores a validated form submission against the scoped contract.

GET /contracts query attributes

Field	Type	Required	Description
status	enum	Optional	Filter by `draft`, `sent`, `signed`, `completed`, `cancelled` or `expired`.
payment_status	enum	Optional	Filter by `not_required`, `unpaid`, `partially_paid`, `paid` or `failed`.
q	string	Optional	Search contract reference, title, customer name or customer email.
page	integer	Optional	Pagination page number.
per_page	integer	Optional	Items per page. Keep this sensible for dashboard performance.

GET /contracts response attributes

Field	Type	Description
id	integer	Internal contract ID.
contract_ref	string	Merchant-facing reference such as `CTR-260612-ABC123`.
public_url	url	Secure customer review/sign/payment page.
title, summary, content_html	string/html	Contract title, customer-facing summary and formatted contract content.
customer_* fields	string	Customer name, email, phone and address snapshot.
contract_amount	decimal	Total contract value.
payment_amount	decimal	Amount due now if online payment is required.
status	enum	Current lifecycle status.
payment_status	enum	Current payment status.
signature_required	boolean	Whether the customer must provide an electronic signature.
signed_at	datetime	Set when the customer signs/accepts the contract.
cc_emails	array	Optional CC recipients used for contract communications.
fee_items	array	Optional fee breakdown shown in the contract summary.
intake_form	object	Customer form definition, including enabled status and field list.
intake_form_submissions_count	integer	Number of saved form submissions for this contract.

POST /contracts request attributes

Field	Type	Required	Description
title	string	Required	Contract title shown to the customer.
customer_name	string	Required	Customer or business name.
customer_email	email	Required	Customer email address used for send/resend.
customer_phone	string	Optional	Customer phone number.
customer_address	string	Optional	Billing/service address snapshot.
currency	enum	Required	Currency code such as `GBP` or `EUR`. You may also send `currency_id`.
contract_amount	decimal	Optional	Total contract value. Required if `payment_mode=full`.
show_contract_amount	boolean	Optional	Controls whether the total amount is shown in the public summary. If payment is required, the amount due now is always shown.
payment_required	boolean	Optional	When true, the public contract page can show a Pay button.
payment_mode	enum	Optional	`none`, `full`, `deposit` or `custom`. `full` collects the contract amount; `deposit/custom` collects `deposit_amount`.
deposit_amount	decimal	Optional	Upfront amount due now when using `deposit` or `custom`.
signature_required	boolean	Optional	Require customer electronic signature before the contract is treated as signed.
customer_details_editable	boolean	Optional	Allow the customer to correct their name, email, phone or address before signing.
content_html	html	Required	Main contract body. Script tags and inline event handlers are removed server-side.
summary	string	Optional	Short customer-facing summary for the contract list and email.
cc_emails[]	email[]	Optional	Up to five CC recipients. Customer email is not duplicated.
fee_items[]	array	Optional	Up to eight fee rows with `label`, `fee_type`, `amount` and `notes`.
intake_form.enabled	boolean	Optional	Enable customer form before signing.
intake_form.fields[]	array	Optional	Up to 20 questions. Types: `text`, `date`, `textarea`, `dropdown`, `radio`, `checkbox`.
intake_form.fields[].condition	object	Optional	Optional show/hide rule using `field`, `operator`, `value` and `action`.
expires_at	datetime	Optional	Optional expiry date/time for the public review link.
send_email	boolean	Optional	Send the contract email immediately after saving. Resend is rate-limited.
account_id	string	Platform only	Connected merchant account for NeroConnect routing. You may also send the `NeroPay-Account` header.

PATCH /contracts/{id} request attributes

Field	Type	Description
title, summary, content_html	string/html	Update contract content while the contract is not completed/cancelled.
customer_name, customer_email, customer_phone, customer_address	string	Update customer details snapshot.
contract_amount, payment_required, payment_mode, deposit_amount	decimal/boolean/enum	Update payment rules. Paid contracts cannot be changed in a way that breaks payment history.
signature_required, customer_details_editable, show_contract_amount	boolean	Update customer signing and display rules.
status	enum	`draft`, `sent`, `signed`, `completed`, `cancelled` or `expired`.

Contract form endpoints

Endpoint	Purpose	Security
`GET /contracts/{id}/form`	Read the public/customer form definition for a scoped contract.	Account-scoped; other merchants’ contracts return `contract_not_found`.
`GET /contracts/{id}/form-submissions`	Read saved customer form submissions.	Account-scoped and never searchable across all merchants.
`POST /contracts/{id}/form-submissions`	Save answers against the contract form using an `answers` object keyed by field key.	Requires signed write security and validates required/conditional fields server-side.

Contract form safety: form fields are stored inside the contract meta_json. API v2 strips scripts/unsafe HTML, limits questions/options/submissions and rejects raw card, PIN, password or bank-account fields.

POST /contracts/{id}/payment-link request attributes

Field	Type	Required	Description
success_url	url	Optional	Where the customer is returned after payment. Defaults to the public contract page.
cancel_url	url	Optional	Where the customer is returned after cancelling checkout.
metadata	object	Optional	Extra reference data stored against the payment request.

Payment routing: when a contract requires payment, POST /contracts/{id}/payment-link creates a NeroPay hosted checkout using the merchant account. This is separate from generic LinkPay links and is tied back to the contract payment status.

HTML safety: send formatted HTML from your own editor, but never include scripts, external trackers or card data. The API sanitises unsafe HTML before it is shown to customers.

Create contract request

POST /v2/contracts
{
  "title": "Service agreement",
  "customer_name": "Demo Customer Ltd",
  "customer_email": "customer@example.com",
  "customer_phone": "07700000000",
  "currency": "GBP",
  "contract_amount": 1200.00,
  "show_contract_amount": true,
  "payment_required": true,
  "payment_mode": "deposit",
  "deposit_amount": 300.00,
  "signature_required": true,
  "customer_details_editable": true,
  "summary": "Website setup and monthly support agreement.",
  "content_html": "<h2>Agreement</h2><p>The customer agrees to...</p>",
  "fee_items": [
    {"label": "Setup", "fee_type": "one_off", "amount": "£300"}
  ],
  "intake_form": {
    "enabled": true,
    "fields": [
      {"key": "medical_conditions", "label": "Do you have any medical conditions?", "type": "radio", "required": true, "options": ["Yes", "No"]},
      {"key": "details", "label": "Please provide details", "type": "textarea", "condition": {"enabled": true, "field": "medical_conditions", "operator": "equals", "value": "Yes", "action": "show"}}
    ]
  },
  "send_email": true
}

Create payment link

POST /v2/contracts/123/payment-link
{
  "success_url": "https://example.com/thanks",
  "cancel_url": "https://example.com/cancelled"
}

NeroGYM

NeroGYM overview

NeroGYM API v2 exposes gym operations in the same menu-led style as NeroTrade: settings, clients, plans, memberships, sessions, classes, staff, programmes, check-ins and payment records.

Security model: every request is scoped to the authenticated merchant. Platform/reseller keys must use NeroPay-Account or account_id for an allowed connected merchant only. Write calls require HMAC signing and an Idempotency-Key.

GET/nerogym/overview

Returns dashboard-safe totals and recent activity for the scoped gym account.

GET /nerogym/overview query attributes

Field	Type	Required	Description
`account_id`	string	Platform only	Connected merchant account. You may also send `NeroPay-Account`.
`date_from` / `date_to`	date	Optional	Optional reporting window for revenue, attendance and session counts.

GET /nerogym/overview response attributes

Field	Type	Description
`account_id`	string	Scoped merchant account.
`settings_enabled`	boolean	Whether NeroGYM is enabled for the merchant.
`stats.clients`	integer	Total active/known clients.
`stats.memberships`	integer	Active membership count.
`stats.sessions`	integer	Sessions in the selected period.
`stats.classes`	integer	Classes in the selected period.
`stats.checkins`	integer	Check-ins in the selected period.
`stats.revenue`	decimal	Payment records total for the selected period.
`recent_activity[]`	array	Recent sessions, check-ins or payments with safe public fields.

Overview

GET /v2/nerogym/overview?date_from=2026-07-01&date_to=2026-07-31

Overview response

{
  "success": true,
  "data": {
    "account_id": "NPVesdTGASO23_547878",
    "settings_enabled": true,
    "stats": {
      "clients": 124,
      "memberships": 93,
      "sessions": 212,
      "classes": 41,
      "checkins": 684,
      "revenue": 8420.50
    },
    "recent_activity": []
  }
}

NeroGYM

Settings

Read and update safe NeroGYM portal, billing and booking settings for a merchant.

GET/nerogym/settings

Reads NeroGYM settings.

PATCH/nerogym/settings

Updates supported settings only.

GET /nerogym/settings query attributes

Field	Type	Required	Description
`account_id`	string	Platform only	Connected merchant account. You may also send `NeroPay-Account`.

GET /nerogym/settings response attributes

Field	Type	Description
`enabled`	boolean	NeroGYM feature status.
`portal_url`	url	Merchant public NeroGYM portal URL.
`booking_enabled`	boolean	Allows clients to book available sessions/classes online.
`member_portal_enabled`	boolean	Allows member portal access.
`parq_required`	boolean	Whether PAR-Q/health form is required during onboarding.
`currency`	string	Currency used for plans and payment records.
`timezone`	string	Timezone used for calendar/session rendering.

PATCH /nerogym/settings request attributes

Field	Type	Required	Description
`account_id`	string	Platform only	Connected merchant account. You may also send `NeroPay-Account`.
`enabled`	boolean	Optional	Enable or disable NeroGYM.
`booking_enabled`	boolean	Optional	Enable online booking.
`member_portal_enabled`	boolean	Optional	Enable member portal access.
`parq_required`	boolean	Optional	Require health/PAR-Q form before training.
`timezone`	string	Optional	IANA timezone, for example `Europe/London`.

Update settings

PATCH /v2/nerogym/settings
Idempotency-Key: gym-settings-20260701-001
{
  "booking_enabled": true,
  "member_portal_enabled": true,
  "parq_required": true,
  "timezone": "Europe/London"
}

NeroGYM

Clients

Create and manage gym clients. Client IDs are always scoped to the authenticated merchant.

GET/nerogym/clients

Lists clients.

GET/nerogym/clients/{id}

Retrieves one client.

POST/nerogym/clients

Creates a client.

PATCH/nerogym/clients/{id}

Updates a client.

DELETE/nerogym/clients/{id}

Deletes or deactivates a client where allowed.

GET /nerogym/clients query attributes

Field	Type	Required	Description
`account_id`	string	Platform only	Connected merchant account.
`q`	string	Optional	Search name, email or phone.
`status`	enum	Optional	Filter by `active`, `inactive`, `blocked` or local configured status.
`page` / `per_page`	integer	Optional	Pagination controls.

GET /nerogym/clients response attributes

Field	Type	Description
`id`	integer	Client ID.
`name`	string	Client full name.
`email`	email	Client email address.
`phone`	string	Client phone number.
`status`	enum	Current client status.
`notes`	text	Internal notes where available.
`created_at`, `updated_at`	datetime	Record timestamps.

POST /nerogym/clients request attributes

Field	Type	Required	Description
`name`	string	Required	Client full name.
`email`	email	Optional	Unique email for this merchant where provided.
`phone`	string	Optional	Client phone number.
`status`	enum	Optional	Defaults to `active`.
`notes`	text	Optional	Internal client note.

PATCH /nerogym/clients/{id} request attributes

Field	Type	Description
`name`, `email`, `phone`, `status`, `notes`	mixed	Only supplied fields are updated. Client must belong to the scoped merchant.

DELETE /nerogym/clients/{id} response attributes

Field	Type	Description
`deleted`	boolean	True when the record was deleted/deactivated.

Create client

POST /v2/nerogym/clients
Idempotency-Key: gym-client-20260701-001
{
  "name": "Jane Member",
  "email": "jane@example.com",
  "phone": "07700000000",
  "status": "active"
}

List clients

GET /v2/nerogym/clients?q=jane&status=active&per_page=25

NeroGYM

Plans

Create and maintain membership packages, one-off session packs and public plan terms.

GET/nerogym/plans

Lists plans.

GET/nerogym/plans/{id}

Retrieves one plan.

POST/nerogym/plans

Creates a plan.

PATCH/nerogym/plans/{id}

Updates a plan.

DELETE/nerogym/plans/{id}

Deletes/deactivates a plan where no active dependencies block removal.

GET /nerogym/plans query attributes

Field	Type	Required	Description
`q`	string	Optional	Search plan name.
`status`	enum	Optional	Filter active/inactive plans.
`page` / `per_page`	integer	Optional	Pagination controls.

GET /nerogym/plans response attributes

Field	Type	Description
`id`	integer	Plan ID.
`name`	string	Plan name.
`price`	decimal	Plan price.
`billing_cycle`	enum	`monthly`, `weekly`, `one_off` or local cycle.
`session_limit`	integer/null	Included session limit if configured.
`general_terms`	html/text	Customer-facing plan terms.
`status`	enum	Plan status.

POST /nerogym/plans request attributes

Field	Type	Required	Description
`name`	string	Required	Plan name.
`price`	decimal	Required	Plan price, server validated as a non-negative amount.
`billing_cycle`	enum	Required	`monthly`, `weekly`, `one_off` or supported cycle.
`session_limit`	integer	Optional	Included session allowance.
`general_terms`	text/html	Optional	Plan terms shown to customers before checkout/acceptance.
`status`	enum	Optional	Defaults to active.

PATCH /nerogym/plans/{id} request attributes

Field	Type	Description
`name`, `price`, `billing_cycle`, `session_limit`, `general_terms`, `status`	mixed	Only supplied fields are updated. Plan must belong to the scoped merchant.

Create monthly plan

POST /v2/nerogym/plans
Idempotency-Key: gym-plan-20260701-001
{
  "name": "Monthly PT Plan",
  "price": 49.99,
  "billing_cycle": "monthly",
  "session_limit": 4,
  "general_terms": "Client agrees to the gym membership terms."
}

NeroGYM

Memberships

Link clients to plans and manage membership lifecycle. Cross-merchant client_id or plan_id values are rejected.

GET/nerogym/memberships

Lists memberships.

GET/nerogym/memberships/{id}

Retrieves one membership.

POST/nerogym/memberships

Creates a membership.

PATCH/nerogym/memberships/{id}

Updates a membership.

DELETE/nerogym/memberships/{id}

Cancels/deletes a membership where allowed.

GET /nerogym/memberships query attributes

Field	Type	Required	Description
`client_id`	integer	Optional	Filter by client belonging to the scoped merchant.
`plan_id`	integer	Optional	Filter by plan belonging to the scoped merchant.
`status`	enum	Optional	`active`, `paused`, `cancelled`, `expired` or local status.
`page` / `per_page`	integer	Optional	Pagination controls.

GET /nerogym/memberships response attributes

Field	Type	Description
`id`	integer	Membership ID.
`client_id`, `client`	integer/object	Linked client ID and safe client summary.
`plan_id`, `plan`	integer/object	Linked plan ID and safe plan summary.
`status`	enum	Membership status.
`starts_at`, `ends_at`	date	Membership date range.
`next_payment_at`	date/null	Next expected payment date when used.

POST /nerogym/memberships request attributes

Field	Type	Required	Description
`client_id`	integer	Required	Client ID from the same scoped merchant.
`plan_id`	integer	Required	Plan ID from the same scoped merchant.
`status`	enum	Optional	Defaults to active.
`starts_at`	date	Required	Membership start date.
`ends_at`	date	Optional	Membership end date.
`next_payment_at`	date	Optional	Next expected billing/payment date.

PATCH /nerogym/memberships/{id} request attributes

Field	Type	Description
`plan_id`, `status`, `starts_at`, `ends_at`, `next_payment_at`	mixed	Only supplied fields are updated. Linked IDs must belong to the same merchant.

Create membership

POST /v2/nerogym/memberships
Idempotency-Key: gym-membership-20260701-001
{
  "client_id": 123,
  "plan_id": 8,
  "status": "active",
  "starts_at": "2026-07-01",
  "next_payment_at": "2026-08-01"
}

NeroGYM

Sessions & classes

Manage one-to-one sessions and group classes. Staff and client references are validated against the scoped merchant.

GET/nerogym/sessions

Lists PT sessions.

POST/nerogym/sessions

Creates a PT session.

PATCH/nerogym/sessions/{id}

Updates a PT session.

DELETE/nerogym/sessions/{id}

Deletes/cancels a session where allowed.

GET/nerogym/classes

Lists group classes.

POST/nerogym/classes

Creates a group class.

PATCH/nerogym/classes/{id}

Updates a group class.

DELETE/nerogym/classes/{id}

Deletes/cancels a class where allowed.

GET /nerogym/sessions or /classes query attributes

Field	Type	Required	Description
`client_id`	integer	Sessions optional	Filter sessions by client. ID must belong to the scoped merchant.
`staff_id`	integer	Optional	Filter by trainer/staff member.
`date_from` / `date_to`	date	Optional	Calendar window filter.
`status`	enum	Optional	`scheduled`, `completed`, `cancelled` or local status.

GET response attributes

Field	Type	Description
`id`	integer	Session/class ID.
`name`	string	Class name or generated session title.
`client_id`	integer/null	Client for PT sessions.
`staff_id`	integer/null	Assigned trainer/staff member.
`starts_at`	datetime	Start date/time.
`duration_minutes`	integer	Duration in minutes.
`capacity`	integer/null	Class capacity where applicable.
`status`	enum	Current status.

POST /nerogym/sessions request attributes

Field	Type	Required	Description
`client_id`	integer	Required	Client ID from the scoped merchant.
`staff_id`	integer	Optional	Trainer/staff ID from the scoped merchant.
`starts_at`	datetime	Required	Session start date/time.
`duration_minutes`	integer	Optional	Defaults to merchant/session setting.
`status`	enum	Optional	Defaults to scheduled.

POST /nerogym/classes request attributes

Field	Type	Required	Description
`name`	string	Required	Class name.
`staff_id`	integer	Optional	Trainer/staff ID from the scoped merchant.
`starts_at`	datetime	Required	Class start date/time.
`duration_minutes`	integer	Optional	Class duration.
`capacity`	integer	Optional	Max attendees.
`status`	enum	Optional	Defaults to scheduled/active.

PATCH /nerogym/sessions/{id} or /classes/{id} request attributes

Field	Type	Description
`client_id`, `staff_id`, `name`, `starts_at`, `duration_minutes`, `capacity`, `status`	mixed	Only supplied fields are updated. Linked IDs must belong to the same merchant.

Create PT session

POST /v2/nerogym/sessions
Idempotency-Key: gym-session-20260701-001
{
  "client_id": 123,
  "staff_id": 14,
  "starts_at": "2026-07-10T14:00:00+01:00",
  "duration_minutes": 60,
  "status": "scheduled"
}

Create class

POST /v2/nerogym/classes
Idempotency-Key: gym-class-20260701-001
{
  "name": "Strength Class",
  "staff_id": 14,
  "starts_at": "2026-07-11T18:00:00+01:00",
  "duration_minutes": 45,
  "capacity": 12
}

NeroGYM

Staff & programmes

Manage trainers/staff records and client training programmes. The API accepts both programmes and programs as resource aliases.

GET/nerogym/staff

Lists gym staff.

POST/nerogym/staff

Creates gym staff.

PATCH/nerogym/staff/{id}

Updates gym staff.

DELETE/nerogym/staff/{id}

Deletes/deactivates gym staff where allowed.

GET/nerogym/programmes

Lists training programmes.

POST/nerogym/programmes

Creates a programme.

PATCH/nerogym/programmes/{id}

Updates a programme.

DELETE/nerogym/programmes/{id}

Deletes/deactivates a programme where allowed.

GET query attributes

Field	Type	Required	Description
`q`	string	Optional	Search staff/programme name and supported text fields.
`client_id`	integer	Programmes optional	Filter programmes by client.
`status`	enum	Optional	Filter active/inactive/status values.
`page` / `per_page`	integer	Optional	Pagination controls.

GET response attributes

Field	Type	Description
`id`	integer	Record ID.
`name`	string	Staff/programme name.
`email`, `phone`	string	Staff contact details where applicable.
`role`	string	Staff role where applicable.
`client_id`	integer/null	Programme client where applicable.
`starts_at`, `ends_at`	date	Programme date range where applicable.
`status`, `is_active`	enum/boolean	Current active/status value.

POST /nerogym/staff request attributes

Field	Type	Required	Description
`name`	string	Required	Staff full name.
`email`	email	Optional	Staff email address.
`phone`	string	Optional	Staff phone number.
`role`	string	Optional	Trainer, coach, manager or local role.
`is_active`	boolean	Optional	Defaults to true.

POST /nerogym/programmes request attributes

Field	Type	Required	Description
`name`	string	Required	Programme name.
`client_id`	integer	Optional	Client ID from the scoped merchant.
`description`	text	Optional	Programme details.
`starts_at`, `ends_at`	date	Optional	Programme start/end dates.
`status`	enum	Optional	Programme status.

PATCH request attributes

Field	Type	Description
`name`, `email`, `phone`, `role`, `is_active`, `client_id`, `description`, `starts_at`, `ends_at`, `status`	mixed	Only supplied fields are updated. Linked IDs must belong to the same merchant.

Create staff

POST /v2/nerogym/staff
Idempotency-Key: gym-staff-20260701-001
{
  "name": "Alex Trainer",
  "email": "trainer@example.com",
  "role": "Personal Trainer",
  "is_active": true
}

Create programme

POST /v2/nerogym/programmes
Idempotency-Key: gym-programme-20260701-001
{
  "name": "8 Week Strength Programme",
  "client_id": 123,
  "starts_at": "2026-07-01",
  "ends_at": "2026-08-26",
  "status": "active"
}

NeroGYM

Check-ins & payments

Record attendance and gym payment ledger events. Check-in/payment audit records are intentionally protected from API delete.

GET/nerogym/checkins

Lists check-ins.

POST/nerogym/checkins

Creates a check-in.

PATCH/nerogym/checkins/{id}

Updates a safe check-in field where allowed.

GET/nerogym/payments

Lists gym payment records.

POST/nerogym/payments

Creates a manual gym payment record. Raw card details are not accepted.

PATCH/nerogym/payments/{id}

Updates safe payment metadata/status only.

GET query attributes

Field	Type	Required	Description
`client_id`	integer	Optional	Filter by client from the scoped merchant.
`membership_id`	integer	Optional	Filter by membership from the scoped merchant.
`date_from` / `date_to`	date	Optional	Filter by checked-in or paid date.
`status`	enum	Payments optional	Filter payment status.
`page` / `per_page`	integer	Optional	Pagination controls.

GET response attributes

Field	Type	Description
`id`	integer	Record ID.
`client_id`, `membership_id`	integer/null	Linked client and membership IDs.
`checked_in_at`	datetime	Check-in timestamp for check-in records.
`source`	enum	Check-in source such as `manual`, `qr` or `api`.
`amount`, `currency`	decimal/string	Payment amount and currency for payment records.
`method`	enum	Payment method such as `cash`, `bank`, `card`, `link` or `manual`.
`paid_at`	datetime	Payment timestamp.
`status`	enum	Payment status where applicable.

POST /nerogym/checkins request attributes

Field	Type	Required	Description
`client_id`	integer	Required	Client ID from the scoped merchant.
`membership_id`	integer	Optional	Membership ID from the scoped merchant.
`checked_in_at`	datetime	Optional	Defaults to now.
`source`	enum	Optional	Defaults to `api`.

POST /nerogym/payments request attributes

Field	Type	Required	Description
`client_id`	integer	Required	Client ID from the scoped merchant.
`membership_id`	integer	Optional	Membership ID from the scoped merchant.
`amount`	decimal	Required	Manual payment amount.
`currency`	string	Optional	Defaults to merchant currency.
`method`	enum	Required	`cash`, `bank`, `card`, `link` or `manual`. Raw card data is rejected.
`paid_at`	datetime	Optional	Defaults to now.
`status`	enum	Optional	Defaults to paid/recorded.
`reference`	string	Optional	Your integration payment reference.

PATCH request attributes

Field	Type	Description
`checked_in_at`, `source`, `status`, `reference`, `notes`	mixed	Only safe metadata/status fields are updated. Audit deletes are not exposed in API v2.

Abuse protection: payment writes reject raw card numbers, PINs, CVV, bank credentials, access tokens and secret keys. Use hosted NeroPay checkout links for card collection.

Create check-in

POST /v2/nerogym/checkins
Idempotency-Key: gym-checkin-20260701-001
{
  "client_id": 123,
  "membership_id": 44,
  "checked_in_at": "2026-07-10T09:30:00+01:00",
  "source": "api"
}

Create manual payment

POST /v2/nerogym/payments
Idempotency-Key: gym-payment-20260701-001
{
  "client_id": 123,
  "membership_id": 44,
  "amount": 49.99,
  "currency": "GBP",
  "method": "cash",
  "paid_at": "2026-07-10T10:00:00+01:00",
  "reference": "PT payment"
}

Invoices

Invoices API

Create professional merchant invoices with customer details, VAT lines, discounts, due dates and a secure NeroPay payment page.

GET/invoices

Lists invoices for the merchant or connected merchant account.

POST/invoices

Creates a professional invoice and returns the public payment/review URL.

GET/invoices/{id}

Retrieves one invoice with line items.

PATCH/invoices/{id}

Updates an unpaid invoice. Paid/refunded invoices are locked.

DELETE/invoices/{id}

Deletes a draft/unpaid invoice where no payment has been recorded.

GET /invoices query attributes

Field	Type	Required	Description
status	enum	Optional	Filter by `draft`, `unpaid`, `paid`, `cancelled`, `refunded` or your configured invoice status.
q	string	Optional	Search invoice number, customer name, email or reference.
date_from / date_to	date	Optional	Limit by invoice creation date or issue date.
page / per_page	integer	Optional	Pagination controls.

GET /invoices response attributes

Field	Type	Description
id	integer	Internal invoice ID.
invoice_number	string	Merchant/customer-facing invoice number.
public_url	url	Public invoice review and payment page.
invoice_to, email, address	string	Customer billing details.
items[]	array	Invoice line items with name, quantity, unit amount, VAT and row total.
subtotal_amount, vat_amount, discount_amount, shipping_amount, total_amount	decimal	Calculated invoice totals.
payment_required, partial_payment_allowed, deposit_amount	boolean/decimal	Payment collection settings.
status, paid_at	enum/datetime	Current invoice status and payment timestamp when available.

POST /invoices request attributes

Field	Type	Required	Description
invoice_to	string	Required	Customer or company name.
email	email	Required	Customer email address.
address	string	Required	Customer billing address.
invoice_title	string	Optional	Short title/subject for the invoice.
reference	string	Optional	Your internal reference.
po_number	string	Optional	Customer purchase order number.
currency	string	Optional	Currency code such as GBP. You may send `currency_id` instead.
items[]	array	Required	Each item requires `name` and `unit_amount`. `qty`, `description` and `vat_rate` are optional.
discount_amount	decimal	Optional	Flat invoice discount.
shipping_amount	decimal	Optional	Shipping, delivery or service amount added to the invoice.
due_date	date	Optional	Invoice due date.
payment_required	boolean	Optional	When true, the public invoice includes NeroPay checkout.
partial_payment_allowed	boolean	Optional	Allows the customer to pay a deposit/partial amount first.
deposit_amount	decimal	Optional	Deposit or upfront amount when partial payments are allowed.
invoice_note	text	Optional	Customer-facing invoice note.
footer_note	text	Optional	Optional footer shown on the invoice.
send_email	boolean	Optional	Send the invoice email after creation.
account_id	string	Platform only	Connected merchant account for NeroConnect routing.

PATCH /invoices/{id} request attributes

Field	Type	Description
invoice_to, email, address, invoice_title, reference, po_number	string	Update customer and reference details.
items[]	array	Replace line items and recalculate totals. Paid/refunded invoices are locked.
discount_amount, shipping_amount, due_date	decimal/date	Update invoice totals and due date.
payment_required, partial_payment_allowed, deposit_amount	boolean/decimal	Update payment collection rules before payment is recorded.
status	enum	Update status only where allowed by the invoice lifecycle.

Safety: paid and refunded invoices cannot be edited through API v2. Provider errors are logged server-side and returned as NeroPay-safe messages.

Create invoice request

POST /v2/invoices
{
  "invoice_to": "Demo Customer Ltd",
  "email": "accounts@example.com",
  "address": "1 Demo Street, London",
  "currency": "GBP",
  "invoice_title": "Website setup",
  "po_number": "PO-1001",
  "due_date": "2026-06-30",
  "items": [
    {"name": "Setup fee", "qty": 1, "unit_amount": 500.00, "vat_rate": 20},
    {"name": "Monthly support", "qty": 3, "unit_amount": 75.00, "vat_rate": 20}
  ],
  "discount_amount": 25.00,
  "shipping_amount": 0.00,
  "payment_required": true,
  "partial_payment_allowed": true,
  "deposit_amount": 150.00,
  "invoice_note": "Please pay by the due date.",
  "send_email": true
}

Subscriptions · advanced billing · live API

Subscriptions & recurring pricing

Use the same products, prices, discounts and usage ledger as Merchant → Subscriptions. Create monthly or annual prices, quantity tiers and agreed future price changes, then send the customer to hosted review and card authorisation.

Live only: these routes are not part of the Developer sandbox simulator. They require the installed subscription workspace and its existing database setup. Never expose secret API keys in a browser, mobile app or public repository.

Signed writes and account access

Every request uses HTTPS and a live Bearer secret. GET/HEAD use the Bearer credential; POST/PATCH/PUT also require a current timestamp, an Idempotency-Key and the bound signature below. For a permitted NeroConnect account, send its exact NeroPay-Account header. Body/query account aliases are rejected. Each record must belong to that selected account and the existing partner API policy must permit access.

HMAC-SHA256(timestamp + "\n" + METHOD + "\n" + path + "\n" + Idempotency-Key + "\n" + NeroPay-Account + "\n" + exact_raw_JSON, secret_key)

Use the uppercase HTTP method and path including /v2, without a query string or trailing slash. Use an empty account line when the header is omitted. The timestamp is Unix seconds within five minutes. The signature is a 64-character hexadecimal digest. Encode once, sign those exact UTF-8 bytes, then send them unchanged.

This subscription signature differs from the older timestamp.body signature. It binds the method, endpoint, retry key and selected account, so a signature cannot be moved to a different operation. The Node.js and PHP examples remain complete server-side examples when the page’s language selector changes.

Retries and limits

Persist one 8–100 character key per logical write (letters, digits, dot, underscore, colon, hyphen). Reuse the same key and data with a fresh timestamp/signature after a timeout; do not automatically generate a new key.
A completed request replays its original status and body with Idempotency-Replayed: true. The scope is authenticated merchant, selected account, HTTP method and path. A changed payload under the same key is rejected. A replay is a saved result; GET the subscription for its latest status.
Request references remain in the database ledger. An unconfirmed request older than 23 hours requires a billing review and returns 409; it is not blindly sent again. Invalid attempts can reserve their key; use a new key after correcting a validation-only error.
20 writes and 120 reads per minute per authenticated account and selected account, plus IP/global API limits. A 429 response includes Retry-After: 60.
JSON object only for writes, maximum 64 KB/depth 16; no query parameters, uploads, raw cards, credentials, custom provider URLs or unknown fields. GET filters are explicitly allow-listed; pages contain at most 100 records.

Endpoints

GET/subscriptions

List this account’s subscription snapshots, with pagination.

POST/subscriptions

Create an agreement with billing phases, an existing price, or a simple new price. Returns a hosted customer review link; no automatic activation or email/SMS.

GET/subscriptions/{id}

Read one owned subscription and its agreed phases.

PATCH / PUT/subscriptions/{id}

Change name/email only before an advanced agreement has been reviewed. Billing status and agreed pricing are not writable.

POST/subscriptions/{id}/sync

Refresh verified billing status. Does not authorise a card or activate an unsigned agreement.

POST/subscriptions/{id}/cancel

Confirm immediate cancellation through the billing workflow. No automatic refund, invoice settlement or proration.

GET/subscriptions/products

List product IDs and names. This is the recurring catalogue, separate from /products (NeroPOS).

POST/subscriptions/products

Create a product with up to six prices, or add prices to an owned product_id. Existing prices/agreements stay unchanged.

GET/subscriptions/prices

List full pricing rules. Optional product_id and active=0/1 filters.

POST/subscriptions/prices/{priceId}/archive

Archive an owned price for new agreements. Send {}. Existing agreements keep their price.

GET/subscriptions/discounts

List owned discount codes and availability.

POST/subscriptions/discounts

Create a percentage/amount code with duration, product, expiry and redemption limits.

PATCH/subscriptions/discounts/{discountId}

Enable/disable a code using {"active":true/false}; discountId is the id returned by creation/listing.

GET/subscriptions/{id}/usage

List that subscription’s usage ledger. accepted means recorded for processing, not paid.

POST/subscriptions/{id}/usage

Record measured usage for the current open billing period. Returns HTTP 202.

Products and prices

Field	Type	Rules
product_name	string	Required; 1–190 characters. For additional prices, product_id must belong to the selected account.
prices	array	1–6 price objects. Fixed, per_unit, volume, graduated or metered.
prices[].model	enum	flat: one fixed amount; per_unit: amount × quantity; volume: total quantity chooses one tier; graduated: each band is priced separately; metered: measured units billed in arrears.
prices[].label / unit	string	Required; label up to 80 characters, unit up to 40.
prices[].currency	enum	GBP, EUR or USD. Amounts are major currency units, not pennies/cents.
prices[].interval / interval_count	enum / integer	day (1–365), week (1–52), month (1–12), year (1). Required; billing periods cannot exceed one year.
prices[].amount	decimal	Required for flat/per_unit/metered. 0–9,999,999; flat has up to two decimal places, other unit rates up to four. Decimal strings are recommended.
prices[].tiers	array	Required for volume/graduated: 2–8 ordered tiers with up_to, amount and optional flat_amount. Increasing integer limits up to 1,000,000,000; final up_to is "inf". Flat tier fees support two decimal places.
prices[].metered	boolean	Optional for volume/graduated: true uses measured usage in arrears. The metered model is always measured usage.

Create an agreement

Field	Type	Rules
customer_name / customer_email	string / email	Required; maximum 190 characters each.
phases	array	1–6 phases, all using active prices from this account, the same product, currency and billing period. Do not mix measured usage with quantity pricing.
phases[].price_id	string	Required; use an ID returned by /subscriptions/prices or product creation.
phases[].quantity	integer	Required; 1–1,000,000. Fixed and measured-usage prices use quantity 1; licensed prices multiply by the agreed quantity.
phases[].cycles	integer / null	Introductory phases: 1–36 billing periods. Final phase: null or omitted, continuing until cancellation.
start_date	YYYY-MM-DD	Optional: today or a future date less than one year away, using the application’s configured timezone. Omit for activation after customer authorisation.
offer_code	string	Optional; 3–24 letters/digits. Code eligibility is checked again when the customer reviews the agreement.
Simple creation	alternative	Instead of phases, send an existing price_id with optional quantity, or product_name/amount/currency/interval with optional interval_count/quantity. Do not mix these forms. Both return the same hosted consent flow.

For “£10 now, £20 from next month”, create two monthly prices on one product, then use cycles=1 on the £10 phase and cycles=null on the £20 phase. “Now” means after customer authorisation, unless a future start date was agreed. The rules are fixed in the agreement; catalogue changes do not silently change an existing customer’s terms.

Discount codes

Field	Type	Rules
code	string	Required; 3–24 letters/digits, normalised to uppercase. Code terms cannot be overwritten; create a new code for new terms.
type / value	enum / decimal	percent: greater than 0 and at most 100. amount: positive major currency amount with two decimals, at most 9,999,999.
currency	enum	Required: GBP/EUR/USD. For amount discounts it must match the agreement currency.
cycles	integer	Required: 1–36 monthly bills, or 0 for ongoing. These codes apply only to interval=month, interval_count=1 agreements.
product_id	string / null	Optional; restrict to one product belonging to this account.
max_redemptions	integer / null	Optional; 1–1,000,000, enforced when the offer is redeemed.
expires_at	YYYY-MM-DD / null	Optional; today or later, valid through the end of that day in the application’s configured timezone.
Presets	examples	First month free: percent/100/cycles=1. Three months free: percent/100/cycles=3. First month half price: percent/50/cycles=1.

Disabling a code prevents new uses. Existing agreements keep their agreed discount. When limited cycles end, the agreed undiscounted phase price resumes automatically. Use offer_code on creation, or let the customer enter an eligible code during review.

Usage events

Field	Type	Rules
quantity	integer	Required; 1–1,000,000,000 measured units. The API never accepts a caller-supplied charge amount.
reference	string	Required; 3–80 letters, digits, dot, underscore or hyphen. Unique business-event reference across this merchant. Retrying the same event does not bill twice, including with a new HTTP key.
used_at	ISO 8601 timestamp	Required with timezone, e.g. 2026-10-15T12:00:00+00:00. Within the past 34 days and the current open billing period; future/closed-period events are rejected.
Eligibility	rule	Only active, unpaused subscriptions whose current price uses measured usage. Negative adjustments and retroactive closed-period billing are not supported.

Read results and lifecycle

List endpoints return {success, data: [...], meta: {current_page, per_page, total, last_page}}. Use page (1–10,000) and per_page (1–100). Subscriptions accept q (up to 190 characters) and a supported status; prices accept product_id and active=0/1.

Subscription results expose nested customer, current price and period fields, checkout_url, portal_url, invoice_status, and, for advanced agreements, the agreed phases, start date and offer code. Tiered/metered billing cannot be represented by the top-level amount alone; use pricing rules and the final invoice. A subscription’s active status is not proof that its latest invoice was paid.

The customer must review the agreement, authorise their card and confirm activation in the hosted flow. API creation and sync do not bypass that flow. Checkout/portal URLs contain private customer tokens; give them only to that customer and do not put them in public logs or analytics. Subscription status is read from the billing workflow; it cannot be set to paid/active/canceled with PATCH.

Compatibility with the previous subscription API

GET/list paths and simple amount/price creation remain available. New requests always use the advanced hosted agreement flow. Writes now require the bound signature. PATCH/PUT permit only customer_name/customer_email on a new, unreviewed agreement. Existing legacy records remain readable but are not silently migrated. Use POST /{id}/cancel with {"confirm":true} for cancellation; DELETE is not supported.

Use start_date, billing phases and discount codes instead of legacy trial_days, first_charge_date or bill_day_of_month. Unsupported fields such as body account routing, metadata, customer_phone, caller-supplied status, provider IDs and return URLs are rejected rather than silently ignored. Update older clients before switching these routes to this contract.

HTTP results

Status	Meaning	Action
200 / 201 / 202	Success	Read/update, creation, or accepted usage respectively.
400 / 401	Request / authentication	Missing retry key, HTTPS/signature/timestamp/key failure.
403 / 404	Access / ownership	Account access denied or resource not found in the selected account.
409	Conflict	Different data for a used key, an immutable/consented agreement, or an old unconfirmed write requiring review.
413 / 415 / 422	Input	Size, content type, unknown fields, invalid pricing/offer/usage or lifecycle constraints.
429	Rate limit	Retry after the documented delay, preserving the operation key.
503	Unconfirmed / unavailable	The outcome is not confirmed. Check the response reference; retry only the same logical operation/key. Provider exceptions and secrets are not returned.

Server-side Node.js · signed product creation

// Server-side Node.js (.mjs). Never place this secret in browser code.
import { createHmac } from 'node:crypto';
const secret = process.env.NEROPAY_SECRET_KEY;
if (!secret) throw new Error('Missing NEROPAY_SECRET_KEY');

async function subscriptionWrite(method, path, payload, idempotencyKey, account = '') {
  const rawBody = JSON.stringify(payload);
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const message = [timestamp, method, path, idempotencyKey, account, rawBody].join('\n');
  const signature = createHmac('sha256', secret).update(message, 'utf8').digest('hex');
  const response = await fetch('https://eu.neropay.app' + path, {
    method, redirect: 'error',
    headers: {
      Authorization: `Bearer ${secret}`,
      'Content-Type': 'application/json', Accept: 'application/json',
      'Idempotency-Key': idempotencyKey,
      'X-NeroPay-Timestamp': timestamp,
      'X-NeroPay-Signature': signature,
      ...(account ? {'NeroPay-Account': account} : {})
    },
    body: rawBody
  });
  const result = await response.json();
  if (!response.ok) throw new Error(`${response.status}: ${result.error?.code}`);
  return result.data;
}

// Persist this key before sending. Reuse it with the exact same logical request on retry.
const created = await subscriptionWrite('POST', '/v2/subscriptions/products', {
  product_name: 'Monthly membership',
  prices: [
    {model:'flat', label:'Introductory', unit:'membership', amount:'10.00',
     currency:'GBP', interval:'month', interval_count:1},
    {model:'flat', label:'Standard', unit:'membership', amount:'20.00',
     currency:'GBP', interval:'month', interval_count:1}
  ]
}, 'catalog-operation-0001');
// Store created.product_id and created.price_ids for the agreement request.

Server-side PHP · signed agreement creation

<?php
// Server-side PHP. Sign and send the same exact raw JSON bytes.
function subscriptionWrite(string $method, string $path, array $payload,
    string $key, string $account = ''): array {
    $secret = getenv('NEROPAY_SECRET_KEY');
    if (!$secret) throw new RuntimeException('Missing NEROPAY_SECRET_KEY');
    $raw = json_encode($payload ?: (object) [], JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR);
    $timestamp = (string) time();
    $message = implode("\n", [$timestamp, $method, $path, $key, $account, $raw]);
    $headers = ['Authorization: Bearer '.$secret, 'Content-Type: application/json',
        'Accept: application/json', 'Idempotency-Key: '.$key,
        'X-NeroPay-Timestamp: '.$timestamp,
        'X-NeroPay-Signature: '.hash_hmac('sha256', $message, $secret)];
    if ($account !== '') $headers[] = 'NeroPay-Account: '.$account;
    $curl = curl_init('https://eu.neropay.app'.$path);
    curl_setopt_array($curl, [CURLOPT_CUSTOMREQUEST=>$method,
        CURLOPT_HTTPHEADER=>$headers, CURLOPT_POSTFIELDS=>$raw,
        CURLOPT_RETURNTRANSFER=>true, CURLOPT_FOLLOWLOCATION=>false,
        CURLOPT_CONNECTTIMEOUT=>10, CURLOPT_TIMEOUT=>60]);
    $body = curl_exec($curl);
    $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
    if ($body === false) { curl_close($curl); throw new RuntimeException('Unknown result; retry the same key.'); }
    curl_close($curl);
    $result = json_decode($body, true, 32, JSON_THROW_ON_ERROR);
    if ($status >= 400) throw new RuntimeException($status.': '.($result['error']['code'] ?? 'request_failed'));
    return $result['data'];
}

$agreement = subscriptionWrite('POST', '/v2/subscriptions', [
    'customer_name'=>'Alex Example', 'customer_email'=>'alex@example.com',
    'phases'=>[
        ['price_id'=>'price_intro', 'quantity'=>1, 'cycles'=>1],
        ['price_id'=>'price_standard', 'quantity'=>1, 'cycles'=>null]
    ]
], 'agreement-operation-0001');
// Replace the example price IDs with returned catalogue IDs.
// Present $agreement['checkout_url'] to this customer for explicit review/authorisation.

£10 first month, then £20 · HTTP payload

POST /v2/subscriptions
Content-Type: application/json
Authorization: Bearer <server-secret>
Idempotency-Key: <persisted-unique-operation-key>
X-NeroPay-Timestamp: <current-unix-seconds>
X-NeroPay-Signature: <bound-hmac-sha256>

{
  "customer_name": "Alex Example",
  "customer_email": "alex@example.com",
  "phases": [
    {
      "price_id": "price_intro",
      "quantity": 1,
      "cycles": 1
    },
    {
      "price_id": "price_standard",
      "quantity": 1,
      "cycles": null
    }
  ]
}

Usage-based graduated price · HTTP payload

POST /v2/subscriptions/products
Content-Type: application/json
Authorization: Bearer <server-secret>
Idempotency-Key: <persisted-unique-operation-key>
X-NeroPay-Timestamp: <current-unix-seconds>
X-NeroPay-Signature: <bound-hmac-sha256>

{
  "product_name": "API requests",
  "prices": [
    {
      "model": "graduated",
      "label": "Requests",
      "unit": "request",
      "currency": "GBP",
      "interval": "month",
      "interval_count": 1,
      "metered": true,
      "tiers": [
        {
          "up_to": 1000,
          "amount": "0.05",
          "flat_amount": "0"
        },
        {
          "up_to": "inf",
          "amount": "0.02",
          "flat_amount": "0"
        }
      ]
    }
  ]
}

Three months free · HTTP payload

POST /v2/subscriptions/discounts
Content-Type: application/json
Authorization: Bearer <server-secret>
Idempotency-Key: <persisted-unique-operation-key>
X-NeroPay-Timestamp: <current-unix-seconds>
X-NeroPay-Signature: <bound-hmac-sha256>

{
  "code": "WELCOME3",
  "type": "percent",
  "value": 100,
  "currency": "GBP",
  "cycles": 3,
  "max_redemptions": 100
}

Usage event · HTTP payload

POST /v2/subscriptions/123/usage
Content-Type: application/json
Authorization: Bearer <server-secret>
Idempotency-Key: <persisted-unique-operation-key>
X-NeroPay-Timestamp: <current-unix-seconds>
X-NeroPay-Signature: <bound-hmac-sha256>

{
  "quantity": 250,
  "reference": "order-1045-requests",
  "used_at": "2026-10-15T12:00:00+00:00"
}

Cancel an agreement · HTTP payload

POST /v2/subscriptions/123/cancel
Content-Type: application/json
Authorization: Bearer <server-secret>
Idempotency-Key: <persisted-unique-operation-key>
X-NeroPay-Timestamp: <current-unix-seconds>
X-NeroPay-Signature: <bound-hmac-sha256>

{
  "confirm": true
}

Public agreement response · excerpt

{
  "success": true,
  "data": {
    "id": 123,
    "status": "pending",
    "customer": {
      "name": "Alex Example",
      "email": "alex@example.com",
      "phone": null
    },
    "checkout_url": "https://eu.neropay.app/s/subscription/agreement/<customer-token>",
    "agreement": {
      "state": "pending",
      "start_date": null,
      "offer_code": "",
      "phases": [
        {
          "price_id": "price_intro",
          "quantity": 1,
          "cycles": 1,
          "pricing": {
            "model": "flat",
            "amount": "10",
            "currency": "GBP",
            "interval": "month",
            "interval_count": 1
          }
        },
        {
          "price_id": "price_standard",
          "quantity": 1,
          "cycles": null,
          "pricing": {
            "model": "flat",
            "amount": "20",
            "currency": "GBP",
            "interval": "month",
            "interval_count": 1
          }
        }
      ]
    }
  }
}

Transactions

List, retrieve, refund and cancel transactions. High-risk transactions can expose proof and reserve state, so check transaction state before treating funds as fully available.

POST/transactions

Legacy alias for creating hosted/API transaction where enabled.

Note: for new online checkout integrations, use POST /hosted-payments or POST /payment-links. The transaction table below describes transaction records returned by list/retrieve/refund/cancel flows.

GET/transactions

Lists transactions.

GET/transactions/{id}

Retrieves one transaction.

POST/transactions/{id}/refund

Refunds a transaction.

POST/transactions/{id}/cancel

Cancels a pending transaction.

Transaction response attributes

Field	Type	Description
id	integer	Internal transaction ID.
account_id	string	Merchant or connected account ID.
reference	string	NeroPay or merchant reference.
np_main_trx	string	Processor/payment identifier where available.
status	enum	pending, succeeded, failed, cancelled, refunded.
is_reserve	boolean	Whether funds are currently held in reserve.
reserve_amount	decimal	Amount held from available balance.
proof_status	enum	requested, submitted, approved, rejected or null.

A succeeded transaction can still have reserve/proof state. Do not show funds as fully available until reserve_amount is zero and proof status is clear.

List transactions

GET /v2/transactions?per_page=25&status=succeeded

Transaction response

{
  "success": true,
  "data": {
    "transaction": {
      "id": 5663230,
      "account_id": "NPVesdTGASO23_547878",
      "reference": "NP-EGQX9271-cf013",
      "np_main_trx": "pi_3TENnmPwvCBPpp9M1H3YZnSr",
      "status": "succeeded",
      "amount": 1.00,
      "currency": "GBP",
      "is_reserve": false,
      "reserve_amount": 0,
      "proof_status": "approved",
      "created_at": "2026-03-24T05:47:00.000000Z"
    }
  }
}

Refund request

POST /v2/transactions/5663230/refund
{
  "amount": 1.00,
  "reason": "requested_by_customer"
}

Transaction Proof API

Submit proof files and buyer/shipping details when a transaction is flagged by high-value or risk logic. This API is available for merchants and connected accounts.

GET/transactions/{id}/proof

Returns proof request and transaction reserve state.

POST/transactions/{id}/proof

Submits proof details and invoice/shipping file.

POST proof upload request attributes

Field	Type	Required	Description
invoice_file	file	Optional	JPG, PNG, PDF or WEBP. Required when staff/platform requested an invoice file.
courier_company	string	Optional	Shipping courier.
tracking_number	string	Optional	Tracking number.
buyer_firstname	string	Optional	Buyer first name.
buyer_lastname	string	Optional	Buyer last name.
buyer_phone	string	Optional	Buyer phone number.
buyer_email	string	Optional	Buyer email.
merchant_notes	text	Optional	Merchant notes for the review team.

Submitting proof publishes transaction.proof_submitted. Staff approval/rejection publishes transaction.proof_approved or transaction.proof_rejected. Approved reserve releases can publish balance.reserve_released.

Get proof request response

{
  "success": true,
  "data": {
    "transaction": {
      "id": 5663230,
      "account_id": "NPVesdTGASO23_547878",
      "reference": "NP-EGQX9271-cf013",
      "np_main_trx": "pi_3TENnmPwvCBPpp9M1H3YZnSr",
      "status": "succeeded",
      "amount": 1,
      "remark": "make_payment",
      "details": "Payment successful via Online | PI: pi_3TENnmPwvCBPpp9M1H3YZnSr",
      "is_reserve": false,
      "reserve_amount": 0,
      "created_at": "2026-03-24T05:47:00.000000Z"
    },
    "proof_request": {
      "id": 925,
      "transaction_id": 5663230,
      "status": "approved",
      "courier_company": null,
      "tracking_number": null,
      "buyer": {
        "firstname": null,
        "lastname": null,
        "phone": null,
        "email": null
      },
      "has_invoice_file": false,
      "merchant_notes": null,
      "staff_notes": "test"
    }
  }
}

Submit proof multipart

POST /v2/transactions/5663230/proof
Content-Type: multipart/form-data

invoice_file=@invoice.pdf
courier_company=Royal Mail
tracking_number=RM123456789GB
buyer_firstname=Jane
buyer_lastname=Customer
buyer_phone=+447700900000
buyer_email=jane@example.com
merchant_notes=Invoice and delivery information attached.

Balances

Read available, pending, instant, standard, reserve and NeroBusiness balances. Reserve balance is important for high-risk and proof-held funds.

GET/balances

Returns wallet balances.

GET/balance

Alias of /balances.

Balance response attributes

Field	Type	Description
`wallets[].currency`	object	Wallet currency `id`, ISO `code` and display `symbol`.
`wallets[].available`	decimal	Current main wallet balance.
`wallets[].pending_funds`	decimal	Funds still subject to settlement timing.
`wallets[].standard_available`	decimal	Main wallet balance after pending settlement funds are excluded.
`wallets[].instant_available`	decimal	Current instant availability reported for the wallet.
`wallets[].reserve_balance`	decimal	Funds held in reserve due to proof, risk or compliance controls.
`wallets[].nerobusiness_balance`	decimal	Latest locally recorded available balance for the merchant's NeroBusiness Financial Account in this wallet currency.
`nerocard` / `issuing`	object	Read-only card programme summaries where available.

Balance integrity: balance values are read-only snapshots scoped to the authenticated merchant or the connected account selected by NeroPay-Account. Never accept a client-supplied balance as proof of funds and never attempt to change balances through generic resource endpoints; use the documented money-movement endpoints and reconcile completed operations.

Balances response

{
  "success": true,
  "data": {
    "account_id": "NPVesdTGASO23_547878",
    "wallets": [
      {
        "id": 91,
        "account_id": "NPVesdTGASO23_547878",
        "currency": { "id": 1, "code": "GBP", "symbol": "£" },
        "available": 50.01,
        "reserve_balance": 0,
        "nerobusiness_balance": 1250.75,
        "pending_funds": 0,
        "standard_available": 50.01,
        "instant_available": 50.01,
        "updated_at": "2026-09-03T10:15:00+01:00"
      }
    ]
  }
}

Wallet Transactions

Audit wallet movement separately from payment transactions. Use this for balance ledger reconciliation.

GET/wallet-transactions

Lists wallet balance transactions.

GET/wallet-transactions/{id}

Retrieves one wallet ledger row.

Wallet ledger response attributes

Field	Type	Description
txn_id	string	Ledger transaction ID.
type	enum	credit/debit/hold/release depending on implementation.
amount	decimal	Amount moved.
balance_before	decimal	Balance before movement where available.
balance_after	decimal	Balance after movement where available.
notes	text	Internal or merchant-facing notes.

Wallet transactions request

GET /v2/wallet-transactions?per_page=25

Wallet transaction response

{
  "success": true,
  "data": [
    {
      "id": 901,
      "txn_id": "wb_901",
      "currency": "GBP",
      "amount": 15.99,
      "type": "credit",
      "status": "completed",
      "notes": "Payment received",
      "created_at": "2026-04-28T18:00:00.000000Z"
    }
  ]
}

Payouts & Schedule

Create and inspect payout requests and manage payout schedule. Payout creation can trigger proof/risk checks and Perfex review tasks.

GET/payouts

Lists payouts.

POST/payouts

Creates a payout request.

POST/payouts/request

Legacy alias for create payout.

GET/payouts/{id}

Retrieves one payout.

GET/payout-schedule

Gets payout schedule.

PATCH/payout-schedule

Updates payout schedule.

GET/transfer-schedule

Legacy alias of payout schedule.

PATCH/transfer-schedule

Legacy alias of update payout schedule.

POST/PATCH payout request attributes

Field	Type	Required	Description
amount	decimal	Required	Payout amount.
currency	enum	Required	Currency.
transfer_speed	enum	Optional	instant or standard.
bank_account_id	string	Optional	Destination bank reference.
reference	string	Optional	Statement or internal reference.

Transfers and payouts should not bypass risk controls. High-risk payout requests can create proof requirements, risk flags, tasks and webhooks.

Create payout

POST /v2/payouts
{
  "amount": 25.00,
  "currency": "GBP",
  "transfer_speed": "instant",
  "bank_account_id": "ba_123",
  "reference": "PAYOUT-1001"
}

Schedule response

{
  "success": true,
  "data": {
    "mode": "manual",
    "instant_enabled": true,
    "standard_enabled": true
  }
}

Disputes

List and inspect payment disputes, submit final counter evidence or explicitly accept a claim. Responses use NeroPay case IDs and never expose processor account IDs, provider object IDs, storage paths or internal ledger fields.

GET/disputes

Lists account-scoped cases. Filters: status, action_required, q and per_page (maximum 50).

GET/disputes/{case_id}

Retrieves one case such as DISPUTE-1057.

POST/disputes/{case_id}/counter

Submits final counter-dispute evidence to NeroPay.

POST/disputes/{case_id}/accept

Accepts the claim. This action is final and cannot be reversed.

Connected accounts: a platform may send NeroPay-Account: {connected_account_id}. NeroPay verifies that the account belongs to the authenticated platform. Supplying another merchant ID returns not found/forbidden rather than cross-account data.

Mandatory write protection: counter and accept requests require a unique Idempotency-Key, a timestamp no more than five minutes old and X-NeroPay-Signature = HMAC-SHA256(timestamp + "." + exact_raw_body, secret_key). They are additionally limited to six attempts per minute. Reusing an idempotency key returns 409 duplicate_request.

Counter evidence attributes

Field	Type	Required	Description
`product_description`	string	Required	What was sold or delivered; maximum 20,000 characters.
`evidence_statement`	string	Required	Clear explanation supporting the counter dispute; maximum 20,000 characters.
`service_date`	date	Optional	ISO date, for example `2026-09-01`.
`shipping_tracking_number`	string	Optional	Carrier tracking reference; maximum 255 characters.
`proof_file`	file	Optional	PDF, JPG or PNG, maximum 4.5 MB. Use `multipart/form-data` and sign the exact multipart body.
`confirm_submission`	boolean	Required	Must be `true`. Evidence is submitted as final.

For accept requests, send {"confirm_accept":true}. Original cardholder claim artefacts remain available only in the authenticated dashboard secure viewer; API v2 does not proxy or publish provider-hosted claim documents.

List action-required cases

GET /v2/disputes?action_required=true&per_page=25
Authorization: Bearer neropay_secret_...
NeroPay-Account: NPVesdTGASO23_547878

Safe dispute response

{
  "success": true,
  "data": [
    {
      "case_id": "DISPUTE-1057",
      "transaction_reference": "NP-EGQX9271-cf013",
      "reason": "fraudulent",
      "status": "needs_response",
      "amount": 42.00,
      "currency": "GBP",
      "action_required": true,
      "response_deadline": "2026-09-15T00:59:00+01:00",
      "merchant_action": "none",
      "evidence_files": []
    }
  ]
}

Submit counter evidence

POST /v2/disputes/DISPUTE-1057/counter
Authorization: Bearer neropay_secret_...
Idempotency-Key: dispute-1057-counter-v1
X-NeroPay-Timestamp: 1788757200
X-NeroPay-Signature: <hmac_sha256>
Content-Type: application/json

{
  "product_description": "Order #1842, delivered goods",
  "evidence_statement": "Delivery was completed and acknowledged.",
  "service_date": "2026-09-01",
  "shipping_tracking_number": "TRACK-1842",
  "confirm_submission": true
}

Loans

Loans and financing records are grouped under Money Movement and are read-only through API v2.

GET/loans

Lists loan/financing records.

GET/loans/{id}

Retrieves one loan record.

Loan response attributes

Field	Type	Description
offer_id	string	Financing offer identifier.
status	enum	offer, active, paid, declined etc.
campaign_type	string	Campaign/category.
financing_type	string	Financing type.
created_at	datetime	Record creation time.

List loans

GET /v2/loans?per_page=25

Loan response

{
  "success": true,
  "data": [
    {
      "id": 88,
      "offer_id": "offer_123",
      "status": "active",
      "campaign_type": "working_capital",
      "financing_type": "merchant_cash_advance"
    }
  ]
}

NeroDisburse Bank Accounts

Bank accounts are documented under NeroDisburse. API responses never expose full account numbers, sort codes, IBANs or routing numbers.

GET/bank-accounts

Lists safe payout bank references.

POST/bank-accounts

Adds a payout bank account through the NeroDisburse bridge.

GET/nerodisburse/bank-accounts

Lists NeroDisburse bank accounts.

POST/nerodisburse/bank-accounts

Creates a NeroDisburse bank account.

POST bank-account request attributes

Field	Type	Required	Description
account_name	string	Required	Display name for the destination.
bank_name	string	Optional	Bank name.
sort_code	string	Optional	GB sort code for GB bank accounts.
account_number	string	Optional	GB account number for GB bank accounts.
iban	string	Optional	IBAN for supported international accounts.
currency	enum	Required	Currency.
use_for	enum	Optional	supplier, payout, merchant etc.
is_default	boolean	Optional	Set as default destination.

Create GB bank account

POST /v2/nerodisburse/bank-accounts
{
  "account_name": "Main payout account",
  "bank_name": "Demo Bank",
  "sort_code": "000000",
  "account_number": "00012345",
  "currency": "GBP",
  "use_for": "supplier",
  "is_default": true,
  "full_name": "Jane Merchant",
  "email": "jane@example.com",
  "country": "GB"
}

Create IBAN account

POST /v2/nerodisburse/bank-accounts
{
  "account_name": "EUR payout account",
  "iban": "LT121000011101001000",
  "currency": "EUR",
  "use_for": "supplier",
  "full_name": "Jane Merchant",
  "email": "jane@example.com",
  "country": "LT"
}

NeroDisburse Payouts

Create supplier or connected disbursement payouts using saved bank accounts.

GET/nerodisburse/payouts

Lists NeroDisburse payouts.

POST/nerodisburse/payouts

Creates pending NeroDisburse payout.

GET/nerodisburse/payouts/{id}

Retrieves one NeroDisburse payout.

POST payout request attributes

Field	Type	Required	Description
amount	decimal	Required	Amount.
currency	enum	Required	Currency.
transfer_speed	enum	Optional	instant or standard.
bank_account_id	string	Required	Saved bank account reference.
reference	string	Optional	Payout reference.
note	text	Optional	Supplier payout note.

Create NeroDisburse payout

POST /v2/nerodisburse/payouts
{
  "amount": 10.00,
  "currency": "GBP",
  "transfer_speed": "instant",
  "bank_account_id": "ba_123",
  "reference": "ND1001",
  "note": "Supplier payout"
}

NeroDisburse payout response

{
  "success": true,
  "data": {
    "payout": {
      "id": 3021,
      "status": "pending",
      "amount": 10.00,
      "currency": "GBP",
      "reference": "ND1001"
    }
  }
}

NeroDisburse Payments

Create disbursement payment records where enabled by the NeroDisburse controller.

POST/nerodisburse/payments

Creates a NeroDisburse payment/disbursement request.

Use this endpoint where your integration needs NeroDisburse payment creation rather than a standard payout request. Risk and payout availability rules still apply.

Create NeroDisburse payment

POST /v2/nerodisburse/payments
{
  "amount": 10.00,
  "currency": "GBP",
  "recipient": {
    "name": "Supplier Ltd",
    "email": "supplier@example.com"
  },
  "bank_account_id": "ba_123",
  "reference": "SUP-1001"
}

Terminal Payments

Send in-person payment actions to a registered terminal reader.

POST/terminal/payments

Creates and sends a terminal payment action.

POST/terminal/readers/{reader_id}/cancel-action

Cancels the current reader action.

POST terminal payment request attributes

Field	Type	Required	Description
amount	decimal	Required	Amount.
currency	enum	Required	Currency.
reader_id	string	Required	Terminal reader ID.
location_id	string	Required	Terminal location ID.
description	text	Optional	Payment description.
reference	string	Optional	Reference shown in transaction history.

Create terminal payment

POST /v2/terminal/payments
{
  "amount": 12.50,
  "currency": "GBP",
  "reader_id": "tmr_123",
  "location_id": "tml_123",
  "description": "Counter payment",
  "reference": "TERM-1001"
}

Cancel reader action

POST /v2/terminal/readers/tmr_123/cancel-action
{}

Terminal Locations

Create, list and manage terminal locations. Location creation uses the terminal bridge route.

GET/locations

Lists terminal/NeroPOS locations.

POST/locations

Legacy alias to create terminal location.

GET/terminal/locations

Lists terminal locations.

POST/terminal/locations

Creates a terminal location.

GET/locations/{id}

Retrieves one location.

PATCH/locations/{id}

Updates a location.

DELETE/locations/{id}

Deletes where enabled.

POST/PATCH location request attributes

Field	Type	Required	Description
display_name	string	Required	Location display name.
line1	string	Required	Address line 1.
city	string	Required	City.
postal_code	string	Required	Postal code.
country	enum	Required	ISO country code.
is_default	boolean	Optional	Set default location.
tipping_enabled	boolean	Optional	Enable tipping for terminal/POS flows.

Create location

POST /v2/terminal/locations
{
  "display_name": "Main Store",
  "line1": "1 Demo Street",
  "city": "London",
  "postal_code": "SW1A 1AA",
  "country": "GB",
  "is_default": true
}

Location response

{
  "success": true,
  "data": {
    "id": 100,
    "display_name": "Main Store",
    "neropay_location_id": "tml_...",
    "city": "London",
    "country": "GB"
  }
}

Terminal Readers

GET/readers

Lists readers.

POST/readers

Legacy alias to register reader.

GET/terminal/readers

Lists terminal readers.

POST/terminal/readers

Registers a reader.

DELETE/terminal/readers/{id}

Deletes/unlinks a reader.

POST reader registration request attributes

Field	Type	Required	Description
label	string	Required	Reader label.
location_id	string	Required	Location ID.
registration_code	string	Required	Pairing/registration code from device.
reader_serial_number	string	Read-only	Device serial where available.
reader_status	enum	Read-only	online/offline/unknown.

Create reader

POST /v2/terminal/readers
{
  "label": "Front counter",
  "location_id": "tml_123",
  "registration_code": "simulated-wpe"
}

Reader response

{
  "success": true,
  "data": {
    "id": 44,
    "label": "Front counter",
    "reader_id": "tmr_123",
    "status": "online"
  }
}

Devices

Read-only terminal/device records for fleet visibility.

GET/devices

Lists device rows.

GET/devices/{id}

Retrieves one device.

Device response attributes

Field	Type	Description
device_id	string	Internal device ID.
reader_id	string	Linked reader ID.
reader_serial	string	Serial number.
reader_label	string	Display label.
status	enum	Device status.

NeroCard Cards

NeroCard card records are read-only in API v2 and are separate from payment cards.

GET/nerocards

Lists NeroCard cards.

GET/nerocards/{id}

Retrieves one NeroCard card.

Card response attributes

Field	Type	Description
cardholder_name	string	Cardholder name.
brand	string	Card brand.
last4	string	Last four digits.
status	enum	active, inactive, cancelled, blocked etc.
card_pin	hidden	Never returned.

List NeroCards

GET /v2/nerocards?status=active

NeroCard response

{
  "success": true,
  "data": [
    {
      "id": 77,
      "cardholder_name": "Jane Merchant",
      "brand": "Visa",
      "last4": "4242",
      "status": "active"
    }
  ]
}

NeroCard Cardholders

Read NeroCard cardholder records.

GET/nerocardholders

Lists cardholders.

GET/nerocardholders/{id}

Retrieves one cardholder.

Cardholder response attributes

Field	Type	Description
name	string	Cardholder name.
email	string	Email.
phone	string	Phone.
neropay_cardholder_id	string	NeroPay cardholder identifier when present.
created_at	datetime	Creation time.

List cardholders

GET /v2/nerocardholders?per_page=25

Cardholder response

{
  "success": true,
  "data": [
    { "id": 5, "name": "Jane Merchant", "email": "jane@example.com", "phone": "+447700900000" }
  ]
}

NeroCard Transactions

Read NeroCard issuing transactions separately from wallet and payment transactions.

GET/nerocard-transactions

Lists issuing/NeroCard transactions.

GET/nerocard-transactions/{id}

Retrieves one NeroCard transaction.

NeroCard transaction response attributes

Field	Type	Description
neropay_issuing_transaction_id	string	NeroPay issuing transaction ID.
merchant_name	string	Merchant name on the card transaction.
amount	decimal	Transaction amount.
merchant_amount	decimal	Original merchant amount where different.
platform_fee_amount	decimal	Platform fee amount if applied.
net_amount	decimal	Net ledger amount.
status	enum	pending, posted, reversed etc.
type	enum	purchase, refund, adjustment etc.

List NeroCard transactions

GET /v2/nerocard-transactions?per_page=25

NeroCard transaction response

{
  "success": true,
  "data": [
    {
      "id": 1901,
      "neropay_issuing_transaction_id": "ipi_...",
      "merchant_name": "Demo Store",
      "amount": 12.50,
      "status": "posted",
      "type": "purchase"
    }
  ]
}

NeroTrade API

NeroTrade API v2 lets eligible merchants create, retrieve, list and update wholesale trade records from their own systems.

Subscription required: NeroTrade endpoints require an active NeroTrade subscription and return 402 nerotrade_subscription_required when the plan is not active for the merchant.

Records covered

Trade accounts, product categories, products, inventory stock fields, drivers, deliveries, invoices, collections, statement views, campaign records, route plans and driver check-ins.

Response envelope

Successful calls return { success: true, data: ... }. List calls also include pagination meta. Failed calls return { success: false, error: { code, message } }.

GET/nerotrade/dashboard

Returns NeroTrade summary, subscription status, stock alerts and operational totals.

GET/nerotrade/{resource}

Lists supported NeroTrade records for the authenticated merchant.

POST/nerotrade/{resource}

Creates a supported NeroTrade record where the resource supports creation.

GET/nerotrade/{resource}/{id}

Retrieves one supported NeroTrade record.

PATCH/nerotrade/{resource}/{id}

Updates one supported NeroTrade record.

Dashboard response

GET /v2/nerotrade/dashboard
{
  "success": true,
  "data": {
    "account_id": "NPVesdTGASO23_547878",
    "nerotrade_active": true,
    "subscription": {
      "id": 12,
      "account_id": "NPVesdTGASO23_547878",
      "status": "active",
      "current_period_end": "2026-06-18T00:00:00Z"
    },
    "stats": {
      "outstanding": 1280.50,
      "overdue": 210.00,
      "customers": 18,
      "drivers": 3,
      "products": 142,
      "due_this_week": 480.00,
      "stop_supply": 1,
      "failed_collections": 0,
      "campaigns": 4,
      "routes_today": 2
    },
    "inventory_alerts": []
  }
}

List response envelope

GET /v2/nerotrade/trade-accounts?limit=2
{
  "success": true,
  "data": [
    {
      "id": 104,
      "account_id": "NPVesdTGASO23_547878",
      "business_name": "Acme Builders Ltd",
      "contact_name": "Jane Smith",
      "email": "accounts@acme.example",
      "phone": "+447700900000",
      "payment_terms": "30_days",
      "credit_limit": "2500.00",
      "current_balance": "149.94",
      "overdue_balance": "0.00",
      "collection_method": "payment_link",
      "risk_status": "good",
      "stop_supply": 0,
      "created_at": "2026-07-18T10:00:00Z",
      "updated_at": "2026-07-18T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 2,
    "total": 1,
    "last_page": 1
  }
}

NeroTrade entitlement error

HTTP/1.1 402 Payment Required
{
  "success": false,
  "error": {
    "code": "nerotrade_subscription_required",
    "message": "NeroTrade is not active for this account. Activate the £99.95/month NeroTrade plan before using NeroTrade API endpoints."
  }
}

NeroTrade Trade Accounts

Create and maintain wholesale customer accounts, credit terms, collection preferences and account risk status.

GET/nerotrade/trade-accounts

Lists trade accounts. Alias: /nerotrade/customers.

POST/nerotrade/trade-accounts

Creates a trade account.

GET/nerotrade/trade-accounts/{id}

Retrieves one trade account.

PATCH/nerotrade/trade-accounts/{id}

Updates account details, limits, terms, collection method or supply status.

POST/PATCH trade account request attributes

Field	Type	Description
business_name	string	Required on create. Trade customer business name.
contact_name	string	Main contact name.
email	string	Billing or account email.
phone	string	Contact phone number.
billing_address	string	Billing address.
delivery_address	string	Default delivery address.
payment_terms	enum	cod, 7_days, 14_days, 30_days, weekly or monthly.
credit_limit	decimal	Approved trade account credit limit.
opening_balance	decimal	Optional opening balance on create.
collection_method	enum	Collection preference such as payment_link or bank_transfer.
risk_status	string	Internal account risk label, for example good or watch.
stop_supply	boolean	Stops supply for the account when true.

Create trade account

POST /v2/nerotrade/trade-accounts
{
  "business_name": "Acme Builders Ltd",
  "contact_name": "Jane Smith",
  "email": "accounts@acme.example",
  "phone": "+447700900000",
  "billing_address": "10 Trade Road, Manchester, M1 1AA",
  "delivery_address": "10 Trade Road, Manchester, M1 1AA",
  "payment_terms": "30_days",
  "credit_limit": 2500.00,
  "opening_balance": 0,
  "collection_method": "payment_link",
  "risk_status": "good",
  "notes": "Preferred delivery before 12pm"
}

Create trade account response

HTTP/1.1 201 Created
{
  "success": true,
  "data": {
    "id": 104,
    "account_id": "NPVesdTGASO23_547878",
    "business_name": "Acme Builders Ltd",
    "contact_name": "Jane Smith",
    "email": "accounts@acme.example",
    "phone": "+447700900000",
    "billing_address": "10 Trade Road, Manchester, M1 1AA",
    "delivery_address": "10 Trade Road, Manchester, M1 1AA",
    "payment_terms": "30_days",
    "credit_limit": "2500.00",
    "current_balance": "0.00",
    "overdue_balance": "0.00",
    "collection_method": "payment_link",
    "risk_status": "good",
    "stop_supply": 0,
    "notes": "Preferred delivery before 12pm",
    "created_at": "2026-07-18T10:00:00Z",
    "updated_at": "2026-07-18T10:00:00Z"
  }
}

Update trade account response

PATCH /v2/nerotrade/trade-accounts/104
{
  "credit_limit": 3500.00,
  "payment_terms": "45_days",
  "risk_status": "good",
  "stop_supply": false
}

HTTP/1.1 200 OK
{
  "success": true,
  "data": {
    "id": 104,
    "account_id": "NPVesdTGASO23_547878",
    "business_name": "Acme Builders Ltd",
    "payment_terms": "45_days",
    "credit_limit": "3500.00",
    "risk_status": "good",
    "stop_supply": 0,
    "updated_at": "2026-07-18T11:10:00Z"
  }
}

NeroTrade Products & Pricing

Manage trade product categories, SKUs, wholesale pricing, VAT settings and stock-tracked product records.

GET/nerotrade/product-categories

Lists trade product categories. Alias: /nerotrade/categories.

POST/nerotrade/product-categories

Creates a product category.

PATCH/nerotrade/product-categories/{id}

Updates a product category.

GET/nerotrade/products

Lists trade products and pricing.

POST/nerotrade/products

Creates a trade product.

GET/nerotrade/products/{id}

Retrieves one trade product.

PATCH/nerotrade/products/{id}

Updates product details, stock settings or pricing.

POST/PATCH product and pricing request attributes

Field	Type	Description
name	string	Required product name.
base_unit	string	Required unit such as pcs, box, case or pallet.
unit_price	decimal	Required default trade unit price.
category_id	integer	Linked NeroTrade product category.
category_name	string	Creates or links a category by name when supplied.
sku	string	Stock keeping unit.
description	string	Product description.
vat_rate	decimal	VAT rate applied to the product.
vat_included	boolean	Whether price includes VAT.
track_stock	boolean	Enables inventory tracking for the product.
stock_qty	decimal	Current available stock.
reorder_level	decimal	Manual reorder threshold.
preferred_supplier	string	Supplier reference.

Create product category response

POST /v2/nerotrade/product-categories
{
  "name": "Wholesale Boxes",
  "description": "Bulk trade products",
  "sort_order": 10,
  "active": true
}

HTTP/1.1 201 Created
{
  "success": true,
  "data": {
    "id": 12,
    "account_id": "NPVesdTGASO23_547878",
    "name": "Wholesale Boxes",
    "description": "Bulk trade products",
    "sort_order": 10,
    "active": 1,
    "created_at": "2026-07-18T10:05:00Z",
    "updated_at": "2026-07-18T10:05:00Z"
  }
}

Create product

POST /v2/nerotrade/products
{
  "category_id": 12,
  "name": "Trade Box 10kg",
  "sku": "TB-10KG",
  "description": "10kg wholesale box",
  "base_unit": "box",
  "unit_price": 24.99,
  "vat_rate": 20,
  "vat_included": false,
  "pack_unit": "case",
  "pack_quantity": 1,
  "track_stock": true,
  "stock_qty": 120,
  "reorder_level": 25,
  "preferred_supplier": "Acme Supply"
}

Create product response

HTTP/1.1 201 Created
{
  "success": true,
  "data": {
    "id": 501,
    "account_id": "NPVesdTGASO23_547878",
    "category_id": 12,
    "name": "Trade Box 10kg",
    "sku": "TB-10KG",
    "description": "10kg wholesale box",
    "base_unit": "box",
    "unit_price": "24.99",
    "vat_rate": "20.00",
    "vat_included": 0,
    "pack_unit": "case",
    "pack_quantity": "1.0000",
    "track_stock": 1,
    "stock_qty": "120.0000",
    "reorder_level": "25.0000",
    "preferred_supplier": "Acme Supply",
    "active": 1,
    "source": "api",
    "created_at": "2026-07-18T10:08:00Z",
    "updated_at": "2026-07-18T10:08:00Z"
  }
}

Product list response

GET /v2/nerotrade/products?q=box&limit=1
{
  "success": true,
  "data": [
    {
      "id": 501,
      "account_id": "NPVesdTGASO23_547878",
      "name": "Trade Box 10kg",
      "sku": "TB-10KG",
      "base_unit": "box",
      "unit_price": "24.99",
      "vat_rate": "20.00",
      "stock_qty": "120.0000",
      "active": 1
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 1,
    "total": 1,
    "last_page": 1
  }
}

NeroTrade Inventory

Read stock-tracked products and update stock quantity, reorder level, supplier and active status.

GET/nerotrade/inventory

Lists products where stock tracking is enabled.

GET/nerotrade/inventory/{id}

Retrieves one stock-tracked product.

PATCH/nerotrade/inventory/{id}

Updates stock quantity, reorder level, preferred supplier or active status.

Create inventory items by creating products with track_stock enabled. Stock fields can then be updated through the inventory endpoint.

PATCH inventory request attributes

Field	Type	Description
track_stock	boolean	Enables stock tracking.
stock_qty	decimal	Current stock quantity.
reorder_level	decimal	Manual reorder threshold.
preferred_supplier	string	Supplier reference.
active	boolean	Whether the product is active.

Update stock response

PATCH /v2/nerotrade/inventory/501
{
  "track_stock": true,
  "stock_qty": 85,
  "reorder_level": 20,
  "preferred_supplier": "Acme Supply"
}

HTTP/1.1 200 OK
{
  "success": true,
  "data": {
    "id": 501,
    "account_id": "NPVesdTGASO23_547878",
    "name": "Trade Box 10kg",
    "sku": "TB-10KG",
    "track_stock": 1,
    "stock_qty": "85.0000",
    "reorder_level": "20.0000",
    "preferred_supplier": "Acme Supply",
    "active": 1,
    "updated_at": "2026-07-18T11:20:00Z"
  }
}

Inventory create guard response

HTTP/1.1 405 Method Not Allowed
{
  "success": false,
  "error": {
    "code": "use_products",
    "message": "Create inventory items with POST /v2/nerotrade/products, then update stock with PATCH /v2/nerotrade/inventory/{id}."
  }
}

NeroTrade Drivers & Deliveries

Manage driver records and delivery note workflows for trade orders. Delivery creation supports line items and can optionally create a linked invoice.

GET/nerotrade/drivers

Lists delivery drivers.

POST/nerotrade/drivers

Creates a driver record.

GET/nerotrade/drivers/{id}

Retrieves one driver record.

PATCH/nerotrade/drivers/{id}

Updates driver details or active status.

GET/nerotrade/deliveries

Lists deliveries and delivery notes.

POST/nerotrade/deliveries

Creates a delivery record.

GET/nerotrade/deliveries/{id}

Retrieves one delivery record with items.

PATCH/nerotrade/deliveries/{id}

Updates delivery status, driver, proof name, notes or line items.

POST/PATCH driver and delivery request attributes

Field	Type	Description
customer_id	integer	Required linked trade account.
driver_id	integer	Assigned driver.
delivery_number	string	Optional delivery reference. Generated if omitted.
status	enum	scheduled, delivered, invoiced, failed or cancelled.
delivered_at	datetime	Delivery timestamp.
proof_name	string	Recipient name for proof of delivery.
create_invoice	boolean	Creates an invoice from the delivery items when true.
items	array	Line items with item_name, quantity, unit, unit_price, vat_rate and optional product_id.

Create driver response

POST /v2/nerotrade/drivers
{
  "name": "Alex Driver",
  "phone": "+447700900111",
  "email": "alex.driver@example.com",
  "vehicle_registration": "AB12 CDE",
  "default_route": "North Manchester",
  "notes": "Morning deliveries",
  "active": true
}

HTTP/1.1 201 Created
{
  "success": true,
  "data": {
    "id": 9,
    "account_id": "NPVesdTGASO23_547878",
    "name": "Alex Driver",
    "phone": "+447700900111",
    "email": "alex.driver@example.com",
    "vehicle_registration": "AB12 CDE",
    "default_route": "North Manchester",
    "notes": "Morning deliveries",
    "active": 1,
    "created_at": "2026-07-18T10:12:00Z",
    "updated_at": "2026-07-18T10:12:00Z"
  }
}

Create delivery

POST /v2/nerotrade/deliveries
{
  "customer_id": 104,
  "driver_id": 9,
  "delivery_number": "ND-1001",
  "status": "scheduled",
  "delivered_at": "2026-07-20T10:00:00Z",
  "create_invoice": true,
  "notes": "Leave with goods-in team",
  "items": [
    {
      "product_id": 501,
      "item_name": "Trade Box 10kg",
      "quantity": 5,
      "unit": "box",
      "unit_price": 24.99,
      "vat_rate": 20
    }
  ]
}

Create delivery response

HTTP/1.1 201 Created
{
  "success": true,
  "data": {
    "id": 7001,
    "account_id": "NPVesdTGASO23_547878",
    "customer_id": 104,
    "driver_id": 9,
    "delivery_number": "ND-1001",
    "status": "invoiced",
    "delivered_at": "2026-07-20T10:00:00Z",
    "total_net": "124.95",
    "total_vat": "24.99",
    "total_gross": "149.94",
    "notes": "Leave with goods-in team",
    "items": [
      {
        "id": 1,
        "account_id": "NPVesdTGASO23_547878",
        "delivery_id": 7001,
        "product_id": 501,
        "item_name": "Trade Box 10kg",
        "quantity": "5.0000",
        "unit": "box",
        "unit_price": "24.99",
        "vat_rate": "20.00",
        "line_total": "149.94"
      }
    ],
    "invoice": {
      "id": 3301,
      "account_id": "NPVesdTGASO23_547878",
      "customer_id": 104,
      "source_delivery_id": 7001,
      "invoice_number": "NT-A1B2C3D4",
      "status": "sent",
      "total_gross": "149.94",
      "balance_due": "149.94"
    }
  }
}

Update delivery response

PATCH /v2/nerotrade/deliveries/7001
{
  "status": "delivered",
  "proof_name": "Alex Customer",
  "delivered_at": "2026-07-20T14:22:00Z"
}

HTTP/1.1 200 OK
{
  "success": true,
  "data": {
    "id": 7001,
    "account_id": "NPVesdTGASO23_547878",
    "status": "delivered",
    "proof_name": "Alex Customer",
    "delivered_at": "2026-07-20T14:22:00Z",
    "updated_at": "2026-07-20T14:22:05Z",
    "items": []
  }
}

NeroTrade Invoices & Collections

Create trade invoices, record payment collections and keep outstanding trade account balances in sync.

GET/nerotrade/invoices

Lists trade invoices.

POST/nerotrade/invoices

Creates a trade invoice with line items.

GET/nerotrade/invoices/{id}

Retrieves one trade invoice with items and payments.

PATCH/nerotrade/invoices/{id}

Updates invoice status, dates, terms, collection method, notes or items.

GET/nerotrade/collections

Lists collection/payment records. Alias: /nerotrade/payments.

POST/nerotrade/collections

Creates a collection/payment record.

PATCH/nerotrade/collections/{id}

Updates collection amount, method, invoice link, paid date or reference.

POST/PATCH invoice and collection request attributes

Field	Type	Description
customer_id	integer	Required linked trade account.
invoice_number	string	Optional merchant invoice reference. Generated if omitted.
status	enum	sent, part_paid, paid, overdue or collection_failed.
issue_date	date	Invoice issue date.
due_date	date	Invoice due date. Calculated from terms if omitted.
payment_terms	enum	cod, 7_days, 14_days, 30_days, weekly or monthly.
collection_method	string	Collection preference.
items	array	Line items with item_name, quantity, unit, unit_price, vat_rate and optional product_id.
amount	decimal	Required collection amount.
method	string	Required payment method for collections.
reference	string	External collection reference.
paid_at	datetime	Payment received timestamp.

Create invoice

POST /v2/nerotrade/invoices
{
  "customer_id": 104,
  "invoice_number": "NT-INV-1001",
  "status": "sent",
  "issue_date": "2026-07-18",
  "due_date": "2026-06-17",
  "payment_terms": "30_days",
  "collection_method": "payment_link",
  "notes": "May wholesale order",
  "items": [
    {
      "product_id": 501,
      "item_name": "Trade Box 10kg",
      "quantity": 5,
      "unit": "box",
      "unit_price": 24.99,
      "vat_rate": 20
    }
  ]
}

Create invoice response

HTTP/1.1 201 Created
{
  "success": true,
  "data": {
    "id": 3301,
    "account_id": "NPVesdTGASO23_547878",
    "customer_id": 104,
    "invoice_number": "NT-INV-1001",
    "status": "sent",
    "issue_date": "2026-07-18",
    "due_date": "2026-06-17",
    "payment_terms": "30_days",
    "collection_method": "payment_link",
    "total_net": "124.95",
    "total_vat": "24.99",
    "total_gross": "149.94",
    "paid_amount": "0.00",
    "balance_due": "149.94",
    "items": [
      {
        "id": 1,
        "account_id": "NPVesdTGASO23_547878",
        "invoice_id": 3301,
        "product_id": 501,
        "item_name": "Trade Box 10kg",
        "quantity": "5.0000",
        "unit": "box",
        "unit_price": "24.99",
        "vat_rate": "20.00",
        "line_total": "149.94"
      }
    ],
    "payments": []
  }
}

Collection response

POST /v2/nerotrade/collections
{
  "customer_id": 104,
  "invoice_id": 3301,
  "amount": 149.94,
  "method": "bank_transfer",
  "reference": "BACS-1001",
  "paid_at": "2026-07-21T10:15:00Z",
  "notes": "Paid in full"
}

HTTP/1.1 201 Created
{
  "success": true,
  "data": {
    "id": 601,
    "account_id": "NPVesdTGASO23_547878",
    "customer_id": 104,
    "invoice_id": 3301,
    "amount": "149.94",
    "method": "bank_transfer",
    "reference": "BACS-1001",
    "paid_at": "2026-07-21T10:15:00Z",
    "notes": "Paid in full",
    "created_at": "2026-07-21T10:15:03Z"
  }
}

NeroTrade Statements

Read statement-style account summaries, outstanding balances, invoices and payments for trade accounts.

GET/nerotrade/statements

Lists trade accounts in statement format. Use outstanding_only=1 to return accounts with balance due.

GET/nerotrade/statements/{customer_id}

Retrieves one trade account statement with invoices and payments.

Statement response attributes

Query / Field	Type	Description
outstanding_only	boolean	Only return trade accounts with outstanding balances.
limit	integer	Number of records to return. Maximum 100 for the list endpoint and 200 for invoice/payment lines.
customer	object	Trade account details.
summary	object	Current balance, overdue balance, invoice count and payment count.
invoices	array	Recent invoices for the trade account.
payments	array	Recent payment/collection records.

Statements list response

GET /v2/nerotrade/statements?outstanding_only=1&limit=2
{
  "success": true,
  "data": [
    {
      "id": 104,
      "account_id": "NPVesdTGASO23_547878",
      "business_name": "Acme Builders Ltd",
      "current_balance": "149.94",
      "overdue_balance": "0.00",
      "payment_terms": "30_days",
      "collection_method": "payment_link"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 2,
    "total": 1,
    "last_page": 1
  }
}

Customer statement response

GET /v2/nerotrade/statements/104
{
  "success": true,
  "data": {
    "customer": {
      "id": 104,
      "account_id": "NPVesdTGASO23_547878",
      "business_name": "Acme Builders Ltd",
      "current_balance": "149.94",
      "overdue_balance": "0.00"
    },
    "summary": {
      "current_balance": 149.94,
      "overdue_balance": 0,
      "invoice_count": 1,
      "payment_count": 1
    },
    "invoices": [
      {
        "id": 3301,
        "account_id": "NPVesdTGASO23_547878",
        "invoice_number": "NT-INV-1001",
        "status": "sent",
        "total_gross": "149.94",
        "balance_due": "149.94",
        "items": [],
        "payments": []
      }
    ],
    "payments": [
      {
        "id": 601,
        "account_id": "NPVesdTGASO23_547878",
        "amount": "149.94",
        "method": "bank_transfer",
        "reference": "BACS-1001"
      }
    ]
  }
}

NeroTrade Sales & Marketing

Manage campaign records linked to trade accounts for merchant-supplied sales and marketing workflows.

GET/nerotrade/campaigns

Lists sales and marketing campaign records.

POST/nerotrade/campaigns

Creates a campaign record.

GET/nerotrade/campaigns/{id}

Retrieves one campaign record.

PATCH/nerotrade/campaigns/{id}

Updates campaign details, schedule or status.

POST/PATCH campaign request attributes

Field	Type	Description
name	string	Required campaign name.
campaign_type	string	Required campaign type, for example promotion or retention.
channel	enum	Required channel such as email, sms, phone, field_sales or manual.
target_segment	string	Target segment. Defaults to all_trade_accounts.
status	enum	draft, scheduled, active, completed or cancelled.
message	string	Merchant-supplied campaign message or note.
scheduled_at	datetime	Optional scheduled time.

Campaign response

POST /v2/nerotrade/campaigns
{
  "name": "June trade offer",
  "campaign_type": "promotion",
  "channel": "email",
  "target_segment": "all_trade_accounts",
  "status": "draft",
  "message": "Manual campaign note",
  "scheduled_at": "2026-06-03T09:30:00Z"
}

HTTP/1.1 201 Created
{
  "success": true,
  "data": {
    "id": 41,
    "account_id": "NPVesdTGASO23_547878",
    "name": "June trade offer",
    "campaign_type": "promotion",
    "channel": "email",
    "target_segment": "all_trade_accounts",
    "status": "draft",
    "message": "Manual campaign note",
    "scheduled_at": "2026-06-03T09:30:00Z",
    "created_at": "2026-07-18T10:35:00Z",
    "updated_at": "2026-07-18T10:35:00Z"
  }
}

NeroTrade Routes & Tracking

Create delivery route plans and update driver check-in records.

GET/nerotrade/route-plans

Lists planned routes. Alias: /nerotrade/routes.

POST/nerotrade/route-plans

Creates a route plan.

GET/nerotrade/route-plans/{id}

Retrieves one route plan.

PATCH/nerotrade/route-plans/{id}

Updates route name, date, status, driver, vehicle or notes.

GET/nerotrade/driver-checkins

Lists driver tracking/check-in records.

POST/nerotrade/driver-checkins

Creates a driver check-in record.

PATCH/nerotrade/driver-checkins/{id}

Updates a driver check-in record.

POST/PATCH route request attributes

Field	Type	Description
route_name	string	Required route name.
driver_id	integer	Assigned driver.
route_date	date	Route date. Defaults to today when omitted.
status	enum	planned, in_progress, completed or cancelled.
vehicle_registration	string	Vehicle registration.
start_area	string	Route start area.
end_area	string	Route end area.
estimated_stops	integer	Estimated stop count.
estimated_value	decimal	Estimated route value.
checkin_type	enum	Required check-in type such as start_route, delivery_stop, issue or end_route.
latitude / longitude	decimal	Optional GPS coordinates.

Route plan response

POST /v2/nerotrade/route-plans
{
  "driver_id": 9,
  "route_name": "North route",
  "route_date": "2026-07-20",
  "status": "planned",
  "vehicle_registration": "AB12 CDE",
  "start_area": "Manchester",
  "end_area": "Bolton",
  "estimated_stops": 8,
  "estimated_value": 1240.50,
  "notes": "Priority trade accounts first"
}

HTTP/1.1 201 Created
{
  "success": true,
  "data": {
    "id": 66,
    "account_id": "NPVesdTGASO23_547878",
    "driver_id": 9,
    "route_code": "NR-A1B2C3D4",
    "route_name": "North route",
    "route_date": "2026-07-20",
    "status": "planned",
    "vehicle_registration": "AB12 CDE",
    "start_area": "Manchester",
    "end_area": "Bolton",
    "estimated_stops": 8,
    "estimated_value": "1240.50",
    "created_at": "2026-07-18T10:40:00Z"
  }
}

Driver check-in response

POST /v2/nerotrade/driver-checkins
{
  "route_plan_id": 66,
  "driver_id": 9,
  "customer_id": 104,
  "checkin_type": "delivery_stop",
  "checked_in_at": "2026-07-20T11:05:00Z",
  "latitude": 53.4808,
  "longitude": -2.2426,
  "address": "10 Trade Road, Manchester",
  "notes": "Arrived at customer site"
}

HTTP/1.1 201 Created
{
  "success": true,
  "data": {
    "id": 901,
    "account_id": "NPVesdTGASO23_547878",
    "route_plan_id": 66,
    "driver_id": 9,
    "customer_id": 104,
    "checkin_type": "delivery_stop",
    "checked_in_at": "2026-07-20T11:05:00Z",
    "latitude": "53.480800",
    "longitude": "-2.242600",
    "address": "10 Trade Road, Manchester",
    "notes": "Arrived at customer site",
    "created_at": "2026-07-20T11:05:01Z"
  }
}

Customers

Create and manage NeroPOS/NeroPay customer records.

GET/customers

Lists customers.

POST/customers

Creates a customer.

GET/customers/{id}

Retrieves one customer.

PATCH/customers/{id}

Updates a customer.

POST/PATCH customer request attributes

Field	Type	Required	Description
name	string	Required	Customer name.
email	string	Optional	Email.
phone	string	Optional	Phone.
postcode	string	Optional	Postcode.
address1/address2	string	Optional	Address lines.
city	string	Optional	City.
instructions	text	Optional	Delivery or customer notes.

Create customer

POST /v2/customers
{
  "name": "Jane Customer",
  "email": "jane@example.com",
  "phone": "01234567890",
  "postcode": "SW1A 1AA",
  "address1": "1 Demo Street",
  "city": "London"
}

Customer response

{
  "success": true,
  "data": {
    "id": 1001,
    "name": "Jane Customer",
    "email": "jane@example.com",
    "phone": "01234567890"
  }
}

Categories & Products

Keep product catalogue data in sync for NeroPOS and NeroWeb menus.

GET/categories

Lists categories.

POST/categories

Creates category.

PATCH/categories/{id}

Updates category.

DELETE/categories/{id}

Deletes category where enabled.

GET/products

Lists products.

POST/products

Creates product.

PATCH/products/{id}

Updates product.

DELETE/products/{id}

Deletes product where enabled.

POST/PATCH category and product request attributes

Product field	Type	Required	Description
category_id	integer	Optional	Category ID.
name	string	Required	Product name.
sku	string	Optional	SKU.
price	decimal	Required	Product price.
vat_rate	decimal	Optional	VAT rate.
image_url	string	Optional	Image URL.
stock_qty	integer	Optional	Stock quantity.
description	text	Optional	Product description.

Create category

POST /v2/categories
{
  "name": "Drinks",
  "sort_order": 1,
  "is_active": 1
}

Create product

POST /v2/products
{
  "category_id": 10,
  "name": "Latte",
  "sku": "LATTE-REG",
  "price": 3.50,
  "vat_rate": 20,
  "is_active": 1,
  "description": "Regular latte"
}

Product Options & Rules

Manage product-specific options and global option groups for POS and online ordering.

GET/product-option-groups

Lists product option groups.

POST/product-option-groups

Creates product option group.

GET/product-options

Lists product options.

POST/product-options

Creates product option.

GET/global-option-groups

Lists global option groups.

POST/global-option-groups

Creates global option group.

GET/global-option-items

Lists global option items.

POST/global-option-items

Creates global option item.

GET/global-option-assignments

Lists assignments.

POST/global-option-assignments

Creates assignment.

GET/product-option-rules

Alias for assignments/rules.

POST/PATCH option request attributes

Field	Type	Description
name	string	Option or group name.
required	boolean	Require selection.
min_select / max_select	integer	Selection limits.
price_delta	decimal	Price change for selected item.
rules_json	object	Rule configuration.
scope / scope_id	enum/integer	Where a global option applies.

Create option group

POST /v2/product-option-groups
{
  "product_id": 42,
  "name": "Milk choice",
  "required": true,
  "min_select": 1,
  "max_select": 1,
  "sort_order": 1
}

Create option item

POST /v2/product-options
{
  "product_id": 42,
  "group_id": 9,
  "name": "Oat milk",
  "price_delta": 0.40,
  "sort_order": 1
}

Tables & Areas

Manage table maps, areas and table status for dine-in flows.

GET/table-areas

Lists table areas.

POST/table-areas

Creates table area.

GET/tables

Lists tables.

POST/tables

Creates table.

PATCH/tables/{id}

Updates table.

DELETE/tables/{id}

Deletes table where enabled.

POST/PATCH table and area request attributes

Field	Type	Description
area_id	integer	Area ID.
name / label	string	Display name.
seats	integer	Seat count.
status	enum	available, occupied, reserved etc.
x,y,w,h,rotation	decimal/integer	Table-map coordinates.

Create table area

POST /v2/table-areas
{
  "name": "Main Floor",
  "label": "Main Floor",
  "sort_order": 1,
  "is_active": 1
}

Create table

POST /v2/tables
{
  "area_id": 1,
  "name": "T1",
  "label": "Table 1",
  "seats": 4,
  "status": "available",
  "x": 20,
  "y": 40,
  "w": 120,
  "h": 80
}

Cashiers, Registers & Staff

Manage POS cashiers, registers, POS staff and team members.

GET/cashiers

Lists cashiers.

POST/cashiers

Creates cashier.

GET/registers

Lists registers.

POST/registers

Creates register.

GET/pos-staffs

Lists POS staff.

POST/pos-staffs

Creates POS staff.

GET/team-members

Lists merchant team members.

POST/team-members

Creates team member.

POST/PATCH staff request attributes

Field	Type	Description
name	string	Staff/cashier name.
email / username	string	Login identifier.
password / new_password	string	Accepted on create/update but never returned.
role	enum	Role/register type.
permissions	object/array	Permission payload.
location_ids / till_ids	array	Allowed locations or tills.

Create cashier

POST /v2/cashiers
{
  "name": "Front Till",
  "email": "till@example.com",
  "phone": "01234567890",
  "role": "cashier",
  "is_active": 1,
  "permissions": ["orders:create", "refunds:view"],
  "location_ids": [1]
}

Create team member

POST /v2/team-members
{
  "name": "Manager User",
  "email": "manager@example.com",
  "password": "temporary-secret",
  "role": "manager",
  "status": "active",
  "permissions": ["neroconnect:view", "orders:view"]
}

Invoices

Create and manage merchant invoices and invoice line items.

GET/invoices

Lists invoices.

POST/invoices

Creates invoice.

GET/invoices/{id}

Retrieves invoice.

PATCH/invoices/{id}

Updates invoice.

GET/invoice-items

Lists invoice items.

POST/invoice-items

Creates invoice item.

POST/PATCH invoice request attributes

Field	Type	Description
invoice_number	string	Invoice number.
invoice_to	string	Recipient name.
invoice_email	string	Recipient email.
currency_id	integer	Currency ID.
sub_total / total_amount	decimal	Amounts.
items_json	object/array	Line items payload.
due_date	date	Due date.
status	enum	draft, sent, paid etc.

Create invoice

POST /v2/invoices
{
  "invoice_number": "INV-1001",
  "invoice_to": "Jane Customer",
  "invoice_email": "jane@example.com",
  "currency_id": 1,
  "sub_total": 100.00,
  "total_vat": 20.00,
  "total_amount": 120.00,
  "due_date": "2026-07-31",
  "status": "sent",
  "items_json": [
    { "item_name": "Consulting", "qty": 1, "amount": 100.00 }
  ]
}

NeroPOS Orders

NeroPOS order APIs are separate from NeroWeb orders and generic store orders.

GET/neropos-orders

Lists NeroPOS orders.

POST/neropos-orders

Creates NeroPOS order.

GET/neropos-orders/{id}

Retrieves order.

PATCH/neropos-orders/{id}

Updates order.

GET/neropos-order-items

Lists order items.

POST/neropos-order-items

Creates order item.

GET/orders

Generic orders resource.

GET/store-orders

Read-only NeroPay Store orders.

POST/PATCH order request attributes

Field	Type	Description
order_number / order_ref	string	Order reference.
status	enum	Order status.
fulfilment_type	enum	dine_in, takeaway, delivery etc.
payment_method / payment_status	enum	Payment fields.
customer_*	string	Customer details.
subtotal, total, tip_fee	decimal	Money fields.
location_id / table_id / staff_id	integer	Operational links.
meta_json	object	Extra order metadata.

Create NeroPOS order

POST /v2/neropos-orders
{
  "order_ref": "POS-1001",
  "status": "open",
  "fulfilment_type": "dine_in",
  "payment_method": "card",
  "payment_status": "pending",
  "customer_name": "Jane Customer",
  "subtotal": 10.00,
  "tax_fee": 2.00,
  "total": 12.00,
  "location_id": 1,
  "table_id": 3
}

Create order item

POST /v2/neropos-order-items
{
  "order_id": 1001,
  "product_id": 42,
  "name": "Latte",
  "qty": 2,
  "unit_price": 3.50,
  "total_price": 7.00,
  "options_json": [{"name":"Oat milk","price_delta":0.40}]
}

NeroPOS Payment Settings

Manage POS payment, tax, service fee, cashiers, tables and receipt defaults.

GET/payment-settings

Lists POS payment settings.

POST/payment-settings

Creates settings where no row exists.

GET/payment-settings/{id}

Retrieves settings.

PATCH/payment-settings/{id}

Updates settings.

POST/PATCH payment settings request attributes

Field	Type	Description
default_tax_fee	decimal	Default tax fee.
default_service_fee	decimal	Default service fee.
default_tip_fee	decimal	Default tip fee.
pos_mode / default_channel	enum	POS operating mode.
enable_tables / enable_cashiers	boolean	Feature toggles.
receipt_footer / receipt_logo_url	text/string	Receipt branding. Use `receipt_logo_url` for the logo image URL.
min_card_charge	decimal	Minimum card charge.

Update payment settings

PATCH /v2/payment-settings/1
{
  "default_tax_fee": 20,
  "default_service_fee": 0,
  "default_tip_fee": 0,
  "enable_tables": true,
  "enable_cashiers": true,
  "receipt_width": "80mm",
  "receipt_logo_url": "https://eu.neropay.app/assets/images/logoIcon/logo.png",
  "min_card_charge": 1.00
}

NeroWeb Settings

Configure online ordering storefront settings separately from POS resources.

GET/neroweb-settings

Lists NeroWeb settings.

POST/neroweb-settings

Creates settings.

GET/neroweb-settings/{id}

Retrieves settings.

PATCH/neroweb-settings/{id}

Updates settings.

POST/PATCH NeroWeb settings request attributes

Field	Type	Description
store_name	string	Online store name.
slug	string	Store slug.
is_active	boolean	Enable store.
disable_delivery / disable_collect	boolean	Fulfilment toggles.
enable_card / enable_cash	boolean	Payment toggles.
working_hours_json	object	Working hours.
delivery_bands_json	object	Delivery pricing/areas.
theme_json	object	Brand/theme settings, including `logo_url`.

Update NeroWeb settings

PATCH /v2/neroweb-settings/1
{
  "store_name": "Demo Store",
  "slug": "demo-store",
  "is_active": true,
  "disable_delivery": false,
  "disable_collect": false,
  "enable_card": true,
  "working_hours_json": {
    "monday": [{"from":"09:00","to":"17:00"}]
  },
  "theme_json": {
    "logo_url": "https://eu.neropay.app/assets/images/logoIcon/logo.png"
  }
}

NeroWeb Pages

Manage public pages used by the NeroWeb storefront builder.

GET/neroweb-pages

Lists pages.

POST/neroweb-pages

Creates page.

GET/neroweb-pages/{id}

Retrieves page.

PATCH/neroweb-pages/{id}

Updates page.

GET/nerowebpages

Legacy alias for pages.

POST/PATCH NeroWeb page request attributes

Field	Type	Description
title	string	Page title.
slug	string	URL slug.
page_type	enum	home, content, legal etc.
is_home / is_published / show_in_nav	boolean	Page flags.
nav_label / nav_order	string/integer	Navigation settings.
html_content / content / css_content	text	Page content.
builder_json	object	Builder state.
meta_title / meta_description	string/text	SEO metadata.

Create NeroWeb page

POST /v2/neroweb-pages
{
  "title": "About us",
  "slug": "about",
  "page_type": "content",
  "is_published": true,
  "show_in_nav": true,
  "nav_label": "About",
  "html_content": "<h1>About us</h1>",
  "meta_title": "About Demo Store"
}

NeroWeb Orders

NeroWeb orders are separate from NeroPOS orders and store orders.

GET/neroweb-orders

Lists NeroWeb orders.

POST/neroweb-orders

Creates NeroWeb order.

GET/neroweb-orders/{id}

Retrieves order.

PATCH/neroweb-orders/{id}

Updates order.

GET/neroweb-order-items

Lists order items.

POST/neroweb-order-items

Creates order item.

POST/PATCH NeroWeb order request attributes

Field	Type	Description
order_ref	string	Order reference.
status	enum	Order status.
fulfilment_type	enum	delivery, collect etc.
payment_method / payment_status	enum	Payment fields.
subtotal_pence / total_pence	integer/decimal	Money fields.
customer_name / email / phone	string	Customer fields.
meta_json	object	Extra metadata.

Create NeroWeb order

POST /v2/neroweb-orders
{
  "order_ref": "WEB-1001",
  "status": "pending",
  "fulfilment_type": "delivery",
  "payment_method": "card",
  "payment_status": "pending",
  "customer_name": "Jane Customer",
  "customer_email": "jane@example.com",
  "subtotal_pence": 1000,
  "delivery_fee_pence": 250,
  "total_pence": 1250
}

Booking Settings

Booking settings are separate from booking transactions and should appear under the Booking menu.

GET/booking-settings

Lists booking settings.

POST/booking-settings

Creates booking settings.

GET/booking-settings/{id}

Retrieves booking settings.

PATCH/booking-settings/{id}

Updates booking settings.

POST/PATCH booking settings request attributes

Field	Type	Description
booking_company_name	string	Booking brand/company name.
booking_type	enum	Booking mode/type.
weekly_hours	object	Weekly opening hours.
auto_approve_booking	boolean	Auto approve bookings.
slot_duration	integer	Minutes per slot.
max_bookings_per_slot / max_guests	integer	Capacity.
services	object/array	Bookable services.
holiday_days	array	Closed dates.
staff_enabled / staff	boolean/object	Staff booking assignment.

Update booking settings

PATCH /v2/booking-settings/1
{
  "booking_company_name": "Demo Booking",
  "booking_type": "appointment",
  "slot_duration": 30,
  "max_bookings_per_slot": 1,
  "max_guests": 4,
  "auto_approve_booking": true,
  "weekly_hours": {
    "monday": [{"from":"09:00","to":"17:00"}]
  },
  "services": [
    {"name":"Consultation","duration":30,"price":25.00}
  ]
}

Bookings

Create and manage booking transactions.

GET/bookings

Lists bookings.

POST/bookings

Creates booking.

GET/bookings/{id}

Retrieves booking.

PATCH/bookings/{id}

Updates booking.

POST/PATCH booking request attributes

Field	Type	Required	Description
booking_date	date	Required	Booking date.
booking_time	time	Required	Booking time.
guest_count	integer	Optional	Guests.
service	string	Optional	Service name.
amount	decimal	Optional	Booking amount.
staff_id / staff_name	integer/string	Optional	Staff assignment.
location_id	integer	Optional	Location.
customer_name / phone / email	string	Required	Customer details.
customer_note	text	Optional	Customer note.
status	enum	Optional	pending, confirmed, cancelled etc.

Create booking

POST /v2/bookings
{
  "booking_date": "2026-07-10",
  "booking_time": "14:00",
  "guest_count": 2,
  "service": "Consultation",
  "amount": 25.00,
  "customer_name": "Jane Customer",
  "customer_phone": "+447700900000",
  "customer_email": "jane@example.com",
  "status": "pending"
}

KYC / Identity API

Identity API is not only for NeroConnect. Direct merchants can also use it to create verification links and read verification sessions.

POST/identity/verification-links

Creates a document verification link.

GET/identity/verification-sessions

Lists verification sessions.

GET/identity/verification-sessions/{id}

Retrieves one verification session.

POST identity verification-link request attributes

Field	Type	Required	Description
type	enum	Optional	document or supported verification type.
return_url	string	Optional	Where the user should return after verification.
first_name / last_name	string	Optional	Prefill name if known.
country	enum	Optional	ISO country code.
metadata	object	Optional	Developer metadata.

NeroPay should not expose the underlying verification provider in your customer-facing copy. Use the returned short_url or verification_url in your own dashboard.

Create verification link

POST /v2/identity/verification-links
{
  "type": "document",
  "return_url": "https://platform.example.com/kyc/return",
  "first_name": "Jane",
  "last_name": "Merchant",
  "country": "GB",
  "metadata": {
    "user_id": "user_1001"
  }
}

List verification sessions response

{
  "success": true,
  "data": {
    "account_id": "NPVesdTGASO23_547878",
    "sessions": [
      {
        "id": 54484,
        "verification_id": "vs_1TJS0MLWX9o5cjig2zgdWrN7",
        "status": "requires_input",
        "type": "document",
        "verification_url": "https://verify.example/start/...",
        "short_url": "https://verify.neropay.app/7d06xoyeop3nv",
        "first_name": null,
        "last_name": null,
        "country": null,
        "document_type": null,
        "created_at": "2026-04-07T05:16:50.000000Z",
        "updated_at": "2026-04-07T05:16:50.000000Z"
      },
      {
        "id": 49138,
        "verification_id": "vs_1SSkwHLWX9o5cjig03xCd6c9",
        "status": "verified",
        "type": "document",
        "verification_url": null,
        "short_url": "https://verify.neropay.app/sarbz424yicb3",
        "first_name": "HASAN",
        "last_name": "BOZKUS",
        "country": "GB",
        "document_type": "driving_license",
        "created_at": "2025-11-12T20:46:49.000000Z",
        "updated_at": "2026-03-30T21:04:11.000000Z"
      }
    ]
  }
}

Compliance API

Compliance APIs let merchants or platforms read file and information requests, then submit requested document evidence back to NeroPay.

GET/compliance/requests

Lists compliance requests, including each request's response_type.

GET/compliance/requests/{id}

Retrieves one compliance request.

POST/compliance/requests/{id}/documents

Uploads evidence for a request whose response_type is file.

Compliance request response attributes

Field	Type	Description
response_type	enum	`file` or `text`. Text requests appear as Information needed in the merchant dashboard.
docs_number	integer	Maximum required file slots for file requests.
has_text_response	boolean	Whether the merchant has submitted the requested information.
text_submitted_at	datetime\|null	ISO 8601 submission time for a text response, when present.
has_file_1 / has_file_2 / has_file_3	boolean	Whether each available upload slot contains a file.

POST compliance document attributes

Field	Type	Required	Description
file_1	file	Required*	First requested file. At least one of `file_1`, `file_2` or `file_3` is required.
file_2 / file_3	file	Optional	Additional files when the request allows multiple upload slots.
note	text	Optional	Submission note, maximum 2,000 characters.

Text requests are completed through the secure NeroPay merchant Compliance panel and the document upload endpoint rejects them with text_response_required. Live account-requirement updates create a NeroForce review task automatically; document requirements also create a file request, while value requirements appear as Information needed. Locally disabled merchant accounts are logged and skipped. Webhooks notify document requested/submitted/approved/rejected.

List compliance requests response

{
  "success": true,
  "data": {
    "account_id": "NPVesdTGASO23_547878",
    "requests": [
      {
        "id": 123,
        "type": "Account information",
        "title": "Confirm legal owner name",
        "status": "Pending",
        "response_type": "text",
        "docs_number": 1,
        "has_text_response": false,
        "text_submitted_at": null,
        "has_file_1": false,
        "has_file_2": false,
        "has_file_3": false
      }
    ]
  },
  "meta": {
    "pagination": {
      "current_page": 1,
      "per_page": 25,
      "total": 0,
      "last_page": 1
    }
  }
}

Submit compliance document

POST /v2/compliance/requests/123/documents
Content-Type: multipart/form-data

file_1=@proof-of-address.pdf
note=Latest proof of address attached.

Support Tickets

White-label support APIs allow a platform to create tickets for NeroPay staff while keeping the platform as the customer-facing brand.

GET/support/tickets

Lists tickets.

POST/support/tickets

Creates ticket.

GET/support/tickets/{id}

Retrieves ticket.

POST support ticket request attributes

Field	Type	Required	Description
subject	string	Required	Ticket subject.
message	text	Required	Initial message.
priority	enum	Optional	low, normal, high, urgent.
category	string	Optional	Support category.
attachments[]	file	Optional	Optional files where supported. Max 2mb. PNG, JPG, WEBP or PDF

When NeroPay answers a ticket, your platform can receive support.ticket_updated and support.message_created webhooks and display the answer in your own UI.

Create support ticket

POST /v2/support/tickets
{
  "subject": "Customer payout question",
  "message": "The connected merchant needs help with a payout.",
  "priority": "normal",
  "category": "payouts"
}

Ticket response

{
  "success": true,
  "data": {
    "ticket": {
      "id": 501,
      "subject": "Customer payout question",
      "status": "open",
      "priority": "normal",
      "created_at": "2026-04-28T18:00:00.000000Z"
    }
  }
}

Webhooks

Use webhooks for payment outcomes, account updates, KYC, compliance, proof, reserve release and support events.

GET/webhooks

Lists configured endpoints.

GET/webhook-deliveries

Lists delivery attempts.

transaction.succeededtransaction.failedtransaction.proof_requestedtransaction.proof_submittedtransaction.proof_approvedtransaction.proof_rejectedpayout.proof_requestedtransfer.proof_requestedbalance.reserve_releasedcompliance.document_requestedcompliance.document_submittedcompliance.document_approvedcompliance.document_rejectedkyc.pendingkyc.verifiedkyc.rejectedaccount.updateaccount.updatedconnected_account.createdconnected_account.updatedsupport.ticket_createdsupport.ticket_updatedsupport.message_created

Webhook response attributes

Field	Type	Description
id	string	Webhook event ID.
type	enum	Event type.
created_at	datetime	Event creation time.
account	object	Merchant or connected account payload.
data	object	Event-specific payload. Failed transaction events include `data.error.code`, `data.error.message` and optional `data.error.decline_code`.
signature	string	Use your endpoint signing secret where configured.

Payment failures: subscribe to transaction.failed to receive asynchronous terminal or hosted-payment failures. Treat delivery as an event notification: acknowledge the webhook with HTTP 2xx, then use data.status and data.error for the payment result.

If the platform handles email/SMS, NeroPay skips delegated merchant-facing messages and publishes webhooks so the platform can send branded communication.

Webhook payload

{
  "id": "evt_np_01HX...",
  "type": "transaction.proof_requested",
  "created_at": "2026-04-28T18:00:00.000000Z",
  "account": {
    "id": "NPVesdTGASO23_547878",
    "business_company_name": "Demo Connected Merchant Ltd"
  },
  "data": {
    "transaction": {
      "id": 5663230,
      "amount": 5000.00,
      "currency": "GBP",
      "is_reserve": true,
      "reserve_amount": 5000.00
    },
    "proof_request": {
      "id": 925,
      "status": "requested"
    }
  }
}

Failed transaction webhook

{
  "id": "evt_78d..._12",
  "type": "transaction.failed",
  "created_at": "2026-09-04T21:30:00.000000Z",
  "merchant_id": 34321,
  "account_id": "NPVesdTGASO23_547878",
  "data": {
    "status": "failed",
    "payment_reference": "NP-EHPS4218-ba542",
    "identifier": "ORDER-1001",
    "error": {
      "code": "card_declined",
      "message": "Your card was declined.",
      "decline_code": "insufficient_funds"
    }
  },
  "transaction": {
    "reference": "NP-EHPS4218-ba542",
    "status": "failed",
    "amount": 15.99
  }
}

List deliveries

GET /v2/webhook-deliveries?status=failed&per_page=25

Sandbox environment

The Developer sandbox uses separate test keys and isolated simulated payments. It is not a full live-API replica.

Use the 10-2026 selector above to open the dedicated Sandbox reference, including supported endpoints, request fields, checkout outcomes, callbacks and limits. Balances, payouts, transfers, refunds, terminals and generic resource writes are unavailable in sandbox.

Resource Reference

API v2 exposes explicit controller endpoints plus direct resource aliases. Resources are grouped by product area in this documentation; they are not all hidden under NeroPOS.

Core

accountconnected-accountsbalancesbalanceapi-logs

Payments

hosted-paymentspayment-linkscontractsinvoicessubscriptionstransactionstransaction proof

Money Movement

wallet-transactionspayoutspayout-scheduletransfer-scheduledisputesloans

NeroDisburse

bank-accountsnerodisburse/bank-accountsnerodisburse/payoutsnerodisburse/paymentsnerodisburse-bank-accountsnerodisburse-payoutsnerodisburse-payments

Terminal

terminal/paymentslocationsterminal/locationsreadersterminal/readersdevices

NeroCard

nerocardsnerocardholdersnerocard-transactions

NeroTrade

nerotrade/trade-accountsnerotrade/product-categoriesnerotrade/productsnerotrade/inventorynerotrade/driversnerotrade/deliveriesnerotrade/invoicesnerotrade/collectionsnerotrade/statementsnerotrade/campaignsnerotrade/route-plansnerotrade/driver-checkins

NeroPOS

customerscategoriesproductsproduct-option-groupsproduct-optionsglobal-option-groupsglobal-option-itemsglobal-option-assignmentsproduct-option-rulescashiersregisterspos-staffsteam-memberstablestable-areasinvoicesinvoice-itemsordersneropos-ordersneropos-order-itemspayment-settings

NeroWeb

neroweb-settingsneroweb-pagesnerowebpagesneroweb-ordersneroweb-order-itemsstore-orders

Bookings

booking-settingsbookings

Risk & Ops

identity/verification-linksidentity/verification-sessionscompliance/requestssupport/ticketswebhookswebhook-deliveries

Direct aliases such as /v2/disputes, /v2/bank-accounts, /v2/neroweb-orders, /v2/nerocard-transactions, /v2/nerotrade/trade-accounts and /v2/bookings should not return route-not-found when the v2 route patch is deployed and route cache is cleared.

Generic resource pattern

GET    /v2/{resource}
POST   /v2/{resource}
GET    /v2/{resource}/{id}
PATCH  /v2/{resource}/{id}
DELETE /v2/{resource}/{id}

# Explicit namespace also works:
GET    /v2/resources/{resource}
POST   /v2/resources/{resource}
GET    /v2/resources/{resource}/{id}
PATCH  /v2/resources/{resource}/{id}
DELETE /v2/resources/{resource}/{id}

10-2026 · Sandbox API reference

Test the payment journey.
No real money moves.

View Markdown ↗

Use isolated test credentials to create a simulated checkout, choose its outcome and inspect test webhooks and API logs. This is a payment-flow simulator, not a full replica of the live API.

/v2/sandboxDedicated test base path

Separate keysLive keys are not accepted

3 outcomesSuccess, failure, cancellation

No real fundsNo payouts or balance changes

Quick start

From a test key to a verified result in four steps.

Open Developer → Sandbox mode → API and generate your sandbox keys.
Create a payment from your server using the sandbox secret and a unique Idempotency-Key.
Open the returned checkout_url and select a simulated result. The checkout does not collect card details.
Read the payment back and check Developer → Webhooks / API Logs with Sandbox mode on.

Configure a separate sandbox callback endpoint. A test success must never fulfil a live order. Check livemode: false and environment: sandbox.

Create a sandbox payment

POST /v2/sandbox/hosted-payments
Authorization: Bearer YOUR_TEST_SECRET_KEY
Content-Type: application/json
Accept: application/json
Idempotency-Key: sandbox-order-0001

{
  "identifier": "sandbox-order-0001",
  "amount": 10.00,
  "currency": "GBP",
  "details": "Sandbox order"
}

Authentication & headers

Base URL: https://eu.neropay.app/v2/sandbox

Send Authorization: Bearer YOUR_TEST_SECRET_KEY. Sandbox secrets start with np_test_sk_ followed by 64 hexadecimal characters. The merchant is resolved from this key; do not send an account ID.

Header	Sandbox requirement
Authorization	Bearer sandbox secret. Alternatively, use `X-NeroPay-Secret-Key`.
Accept	`application/json`
Content-Type	`application/json` for POST requests.
Idempotency-Key	Required for create: 8–100 letters, digits or `. _ : -`.
X-NeroPay-Public-Key	Optional. If supplied, it must match the sandbox secret.
X-NeroPay-Account	Not supported for sandbox creation. No connected-account routing.

Sandbox API requests do not require the live write-signature headers. Callback signatures are separate and are described below.

Keep secrets server-side, including when using JavaScript examples. Live keys cannot authenticate in sandbox; test keys cannot authenticate against the live API. Rotating sandbox keys does not rotate live keys.

Simulated payments & payment links

Three aliases share the same isolated payment records.

POST/v2/sandbox/hosted-payments

Create a simulated hosted payment.

POST/v2/sandbox/payment-links

Create the same simulated checkout through the payment-link alias.

POST/v2/sandbox/transactions

Create the same simulated checkout through the transactions alias.

Request fields

Field	Validation
identifier	Required string, maximum 100 characters.
amount	Required number, 0.01–10,000; rounded to two decimal places.
currency	GBP, EUR or USD (lowercase is also accepted).
details	Optional string, maximum 500 characters.
ipn_url	Optional public HTTPS callback URL, maximum 1,000 characters.
success_url / cancel_url	Optional public HTTPS return URLs, maximum 1,000 characters each.

Do not send account_id, merchant_id, connected-account routing fields, on_behalf_of, card_number, cvc, cvv or payment_method. They are rejected; no real payment instrument is used.

Idempotency

The same key and same validated parameters return the existing test payment. Reusing a key with different parameters returns HTTP 409. Use a new key for a new simulated order. The aliases share this key space; repeated requests do not create separate copies.

Example create response · HTTP 201

{
  "success": true,
  "data": {
    "id": "test_pay_<64-hex-id>",
    "account_id": "test_account_123",
    "identifier": "sandbox-order-0001",
    "reference": "NP-TEST-0123456789ABCDEF",
    "payment_reference": "NP-TEST-0123456789ABCDEF",
    "amount": "10.00",
    "currency": "GBP",
    "details": "Sandbox order",
    "status": "open",
    "payment_status": null,
    "payment_link": "https://eu.neropay.app/developer-sandbox/checkout/test_pay_<64-hex-id>/<token>",
    "checkout_url": "https://eu.neropay.app/developer-sandbox/checkout/test_pay_<64-hex-id>/<token>",
    "sandbox": true,
    "livemode": false,
    "environment": "sandbox",
    "expires_at": "2026-10-02 12:00:00"
  }
}

IDs, timestamps and tokens shown here are illustrative. Use the exact URL and ID returned by your request. Checkout URLs contain a capability token; keep them private.

Lookups & pagination

GET/v2/sandbox/hosted-payments

List your test records.

GET/v2/sandbox/hosted-payments/{id}

Retrieve one test payment.

The same GET collection and GET-by-ID paths are supported under /payment-links and /transactions. The ID is test_pay_ followed by 64 hexadecimal characters. Only records belonging to the authenticated merchant are returned.

Lists are newest first, 20 records per page. Use ?page=2 for the next page. The response has data, page and last_page; it does not use the live API pagination envelope.

Retrieve a sandbox payment

GET /v2/sandbox/transactions/test_pay_<64-hex-id>
Authorization: Bearer YOUR_TEST_SECRET_KEY
Accept: application/json

Empty list response

{
  "success": true,
  "data": [],
  "page": 1,
  "last_page": 1
}

Checkout simulator

Choose one terminal outcome. Nothing is charged.

Choice	status	payment_status	Event
Success	paid	succeeded	transaction.succeeded
Failure	failed	failed	transaction.failed
Cancellation	cancelled	cancelled	transaction.cancelled

A fresh payment starts with status: open and payment_status: null. Completion is single-use: choosing a result again does not create another event. Create a new payment with a new idempotency key to test another outcome.

Checkout expires after 24 hours (HTTP 410). The simulator presents a return button instead of automatically redirecting to an external site. Do not treat arrival at a return URL as proof of payment; verify the API result or signed notification.

This flow does not test real card authorisation, 3DS, settlement, refunds, terminals or bank payouts. It does not require Stripe test-card numbers.

Sandbox webhooks & retries

Configure up to three endpoints in Developer → Sandbox mode → Webhooks. Only enabled endpoints subscribed to the selected outcome receive the JSON event.

Supported events: transaction.succeeded, transaction.failed, transaction.cancelled. Sandbox endpoint management is in the dashboard, not a public sandbox webhook-management API.

Verify JSON signatures

Compute lowercase hexadecimal HMAC-SHA256(timestamp + "." + raw_request_body, webhook_signing_secret) and compare it in constant time with X-NeroPay-Signature. Read the timestamp from X-NeroPay-Timestamp, enforce an appropriate freshness window and deduplicate X-NeroPay-Event-Id. Do not re-serialize the JSON before verifying.

Headers also include X-NeroPay-Environment: sandbox and X-NeroPay-Delivery. The event contains id, type, created_at, livemode: false, environment: sandbox and payment data. Checkout URLs and capability tokens are excluded from the callback.

Delivery behaviour

The first attempt runs after the simulator response. Failed or pending deliveries can be retried from Developer: at least one minute apart, at most five total attempts, and within ten hours of creation. Sandbox deliveries do not use the live automatic redelivery queue. A delivered event is not resent by this test retry action.

Return HTTP 2xx promptly. Test callbacks have a five-second timeout and a 64 KB response limit. Public HTTPS hostnames on port 443 with publicly routable IPv4 resolution are required; localhost, private/reserved IPs, embedded credentials, URL fragments and redirects are not supported.

Example JSON webhook headers

Content-Type: application/json
X-NeroPay-Environment: sandbox
X-NeroPay-Event-Id: evt_test_<event-hash>
X-NeroPay-Delivery: evt_test_<event-hash>
X-NeroPay-Timestamp: <unix-seconds>
X-NeroPay-Signature: <lowercase-hmac-sha256>

Use the endpoint's sandbox signing secret for JSON webhooks, not your live API key. Store callback results in a separate test system.

Hosted-payment IPN

Supplying ipn_url when creating a payment adds a form-encoded callback for the simulated outcome. This is separate from the dashboard's JSON webhook endpoints; do not process the same order twice if you enable both.

Validate the form field signature using uppercase hexadecimal HMAC-SHA256(data.amount + identifier, sandbox_API_secret). Use the exact amount string received, including eight decimal places, not a floating-point reconstruction.

Top-level status is success, failed or cancelled; success is not named succeeded in this form payload. The form includes environment=sandbox and livemode=false as strings. data.currency is an object with code and symbol.

Decoded form fields · example

status=success
identifier=sandbox-order-0001
environment=sandbox
livemode=false
signature=<UPPERCASE_HMAC_SHA256>
data[payment_trx]=NP-TEST-0123456789ABCDEF
data[amount]=10.00000000
data[currency][code]=GBP
data[currency][symbol]=£
data[account_holder]=Test Customer
data[charge]=0
data[status]=success
data[payment_type]=hosted
data[payment_timestamp]=2026-10-01 12:00:00

Limits, errors & unavailable operations

Limit	Value
API requests	30 per minute per merchant.
Request body	16 KB maximum.
New test payments	100 in the preceding 24 hours.
Stored test payments	2,000 maximum.
Webhook endpoints	3 per merchant.
Checkout validity	24 hours.

Developer → API → Clear expired test records removes expired test payments and test logs/deliveries older than seven days. It does not delete keys, webhook settings or live data. Test API logs retain up to 500 recent entries and exclude credentials and raw request bodies.

Common HTTP results

401: invalid/mismatched test credentials. 403: unsupported operation. 404: payment not found for this merchant. 409: idempotency conflict. 410: checkout expired. 413: request too large. 422: invalid fields or unsafe URL. 429: rate, payment or storage limit. 503: sandbox storage has not been installed.

Balances, transfers, payouts, refunds, bank accounts, connected-account routing, terminals and live resource changes are unavailable. Requests outside the supported paths/methods fail closed; they do not fall back to the live API. Old generic dry-run resource and terminal endpoints are not supported by this sandbox.

Blocked operation response · HTTP 403

{
  "success": false,
  "error": {
    "code": "sandbox_operation_disabled",
    "message": "Sandbox supports simulated hosted payments and payment links only. Balances, transfers, payouts, refunds, account changes and live resources are unavailable."
  }
}

Ready plugins & going live

Prefer an existing integration? Browse ready-to-use plugins. Supported plugin flows do not require custom API development, but installation, account setup and credentials may still be required. Check each plugin's own sandbox compatibility; this simulator does not automatically add sandbox support to every plugin.

When ready, switch this reference to LIVE and follow the live authentication and endpoint contract. Configure separate production credentials and callbacks. Sandbox records and outcomes are not migrated into real transactions, and this selector does not activate live payments.

AI Reception API

Manage your business receptionist, opening hours, voices, service availability and customer follow-ups from your server.

Base URL: https://eu.neropay.app/v2/ai-reception. This is a live, merchant-owned management API. Calls, orders and bookings continue through the existing receptionist and integrated business workflows.

Access and subscription

An active AI Reception subscription is required on every request. Starter includes 100 minutes and one UK number for £49.90/month including VAT. Growth includes 250 minutes and one UK number for £99.90/month including VAT. Cancelling renewal preserves access until the paid period ends. Pending, failed or expired subscriptions do not grant API access. Explicit complimentary access grants are reported as complimentary: true; they are not paid subscriptions.

The subscription can be purchased and managed in AI Reception in the merchant dashboard. The API does not purchase, cancel or change subscription payment methods. Additional minutes on paid plans cost £1 per started minute when enabled, subject to the spending cap. SMS uses the merchant's existing SMS tariff and GBP balance. Complimentary grants have a calendar-month allowance and do not support additional-minute billing.

Authentication

Send Authorization: Bearer YOUR_LIVE_SECRET_KEY and Accept: application/json. The alternative X-NeroPay-Secret-Key header is supported; conflicting credentials are rejected. X-NeroPay-Public-Key is optional and must match when supplied. Keys remain on your server.

Use the workspace owner's credentials. NeroPay-Account, merchant/account routing fields and connected-account delegation are not supported. An active merchant account is required. These software endpoints do not require payment-account onboarding or a browser bot challenge; authentication, subscription and request limits still apply. No sandbox endpoints are provided.

Writes and retries

For every POST, PUT or PATCH, send a JSON object, Content-Type: application/json and an 8–100 character Idempotency-Key containing letters, numbers, dots, underscores, colons or hyphens. Send write fields in the body, without query parameters. Reuse the same key and exact body for a retry of the same operation. A completed result is replayed with Idempotency-Replayed: true. Reusing a key with a different method, path or body returns 409. Use a new unique key for each new operation.

If your merchant account requires signed API writes, also send X-NeroPay-Timestamp (Unix seconds, within five minutes) and X-NeroPay-Signature (hexadecimal HMAC-SHA256 of timestamp + "." + raw_json_body using your secret key). Supplied signatures are always checked, even when optional. A retry can use a fresh signature with the same body and idempotency key.

An uncertain service failure is marked for review and is not automatically run again. Inspect the dashboard state before attempting a new operation; contact support if the result is unclear. Idempotency records follow the workspace retention policy, and keys must never be recycled.

Limits and errors

Maximum body: 128 KiB. Maximum JSON depth: 32. Writes: 20/minute per merchant; reads: up to 120/minute per merchant. Application and IP limits also apply. Use Retry-After on 429. Uploads, raw card credentials and live outbound-call creation are not supported.

HTTP	Meaning
401	Missing, invalid or expired credentials/signature.
402	No active AI Reception entitlement.
403	Inactive account or operation not permitted.
404	Resource not found in this merchant workspace.
409	Workspace busy, retry-key conflict, setup incomplete or prior result needs review.
413 / 415 / 422	Oversized request, wrong content type or invalid fields.
429	Request limit reached.
503	Service or installation unavailable. Inspect workspace state before retrying writes.

Read your workspace

curl 'https://eu.neropay.app/v2/ai-reception' \
  -H "Authorization: Bearer $NEROPAY_SECRET_KEY" \
  -H 'Accept: application/json'

Example error · HTTP 402

{
  "success": false,
  "error": {
    "code": "subscription_required",
    "message": "An active AI Reception subscription is required."
  }
}

Settings, tools & MCP

GET /settings returns the settings object in data. PUT /settings saves a complete settings object. Read, edit and send it back so omitted values are not accidentally reset. This is not a partial PATCH endpoint. Voice and instructions take effect after POST /publish; integration and accepting switches apply immediately.

Fields	Rules
business_name / prompt / first_message	Required strings, up to 120 / 10,000 / 1,000 characters.
knowledge / guardrails	Optional text, up to 20,000 / 5,000 characters.
voice_id	ID returned by GET /voices; required before publishing.
language / languages	Primary language must be in the 1–11 supported languages: en, tr, de, fr, es, it, pt, nl, pl, ar, hi.
timezone / hours	IANA timezone and exactly seven objects, Monday first. Each needs closed (boolean), open and close (HH:mm). Earlier closing time means overnight. Equal times provide no open interval.
outside_hours	callback or hangup; closed_message and busy_message required, up to 500 characters each.
transfer_number / transfer_sip	Optional supported UK +44 geographic/mobile destination, or sip:user@host (optional port 5060/5061). Cannot loop to the reception number.
receipt_channel / sms_enabled	email, sms or none; SMS requires the merchant setting and recipient consent. Existing SMS fees apply.
save_customer / record_voice	Boolean preferences; existing consent and disclosure rules apply. No raw card data.
retention_days / max_call_seconds	7–90 days / 60–600 seconds. Re-publish to apply the call duration.
overage_enabled / spend_cap_pence / wallet_fallback	Boolean / integer 0–50,000 pence / boolean. Additional minutes cannot be enabled on complimentary grants.
integrations / accepting	Boolean maps for neroweb, nerobooking, nerogym, nerotrade and neroconnect. Accepting does not enable an unconfigured integration.
tools / mcp	Arrays, including empty arrays. Maximum 10 custom tools and 4 MCP connections.

Custom tools and MCP

Custom tool fields: name (custom_ followed by 1–40 lowercase letters, digits or underscores), public HTTPS url, description up to 1,000 characters, object JSON schema up to 10 KB, optional bearer token and approved: true.

MCP fields: unique name up to 80 characters, public HTTPS url, transport (SSE or STREAMABLE_HTTP), optional token and approved: true. Approval authorises the endpoint's tools to run during conversations. Private IPs, URL credentials, fragments and non-443 ports are rejected.

Tokens and internal connection identifiers are never returned. GET reports has_token. Omitting or leaving a token empty preserves the existing secret only when connection name and URL match. Remove the connection to remove its credential. The whatsapp_enabled field is read-only here; use POST /whatsapp.

Complete settings example · PUT /settings

{
  "business_name": "Example Kitchen",
  "prompt": "Be a helpful receptionist. Ask one question at a time.",
  "knowledge": "We serve collection orders during opening hours.",
  "guardrails": "Do not invent prices or availability. Offer a callback when unsure.",
  "first_message": "Hello, you are speaking with our AI receptionist. How can I help?",
  "voice_id": "VOICE_ID_FROM_VOICES",
  "language": "en",
  "languages": [
    "en"
  ],
  "timezone": "Europe/London",
  "hours": [
    {
      "closed": false,
      "open": "09:00",
      "close": "17:00"
    },
    {
      "closed": false,
      "open": "09:00",
      "close": "17:00"
    },
    {
      "closed": false,
      "open": "09:00",
      "close": "17:00"
    },
    {
      "closed": false,
      "open": "09:00",
      "close": "17:00"
    },
    {
      "closed": false,
      "open": "09:00",
      "close": "17:00"
    },
    {
      "closed": false,
      "open": "09:00",
      "close": "17:00"
    },
    {
      "closed": false,
      "open": "09:00",
      "close": "17:00"
    }
  ],
  "outside_hours": "callback",
  "transfer_number": "",
  "transfer_sip": "",
  "closed_message": "Our team is unavailable. I can take a callback request.",
  "busy_message": "We are not accepting orders or bookings right now.",
  "receipt_channel": "email",
  "sms_enabled": false,
  "save_customer": false,
  "record_voice": false,
  "retention_days": 30,
  "max_call_seconds": 300,
  "overage_enabled": false,
  "spend_cap_pence": 5000,
  "wallet_fallback": true,
  "integrations": {
    "neroweb": false,
    "nerobooking": false,
    "nerogym": false,
    "nerotrade": false,
    "neroconnect": false
  },
  "accepting": {
    "neroweb": true,
    "nerobooking": true,
    "nerogym": true,
    "nerotrade": true,
    "neroconnect": true
  },
  "tools": [],
  "mcp": []
}

Example custom tool entry

{
  "name": "custom_delivery_info",
  "url": "https://your-business.example/reception/delivery",
  "description": "Look up published delivery information",
  "schema": {
    "type": "object",
    "properties": {
      "postcode": {
        "type": "string"
      }
    },
    "required": [
      "postcode"
    ]
  },
  "approved": true
}

Publish & live availability

Paths below are relative to /v2/ai-reception. Writes require the authentication and retry headers above.

Method & path	Body / result
GET /	Active/enabled state, number, readiness, publication date, subscription, number_billing, minutes, plan definitions, SMS fee and WhatsApp availability.
GET /voices	Voice catalogue: id, name and labels. Choose a returned ID; preview is available in the dashboard.
GET /numbers?type=national&contains=0333	UK number catalogue. type: local, national or tollfree. contains: optional 2–6 digit UK prefix, e.g. 020, 0333, 0800 or 0808. Response data contains items, cursor and message. Each item contains number, label, locality, type, premium, monthly_extra_pence, currency, vat_included, quote and quote_expires_at. Pass the returned cursor with unchanged filters to refresh for different available choices. Quotes and cursors are merchant-bound and expire after 15 minutes. Numbers and prices are rechecked before purchase.
POST /number	{"number":"+442012345678","quote":"RETURNED_QUOTE"} — reserve one included UK number. The matching quote is required. Premium choices return 402 and require the merchant to approve the extra £20/month including VAT in the dashboard payment drawer. The API cannot silently start premium billing. Existing assigned numbers are not replaced by refresh. A number with unpaid premium rental cannot activate reception.
POST /publish	{} — publish current voice, prompt, hours and tools. Choose a voice first. Number selection and activating reception are separate steps.
PATCH /availability	Optional enabled boolean and/or accepting map. Activating reception requires a number and a published agent. Disabling pauses reception and a connected messaging agent.
POST /whatsapp	{"enabled":true} — connect an operations-verified WhatsApp business number. Reception must be enabled first. false disconnects.

Suggested setup sequence

Read GET / and GET /settings.
Select a voice from GET /voices, save the complete settings with PUT /settings.
Choose an included number with GET /numbers and POST /number using its returned quote. For premium choices, complete the merchant dashboard checkout first.
Publish with POST /publish and activate with PATCH /availability.
Test an inbound call, then inspect GET /calls and GET /usage.

NeroWeb orders and NeroBooking appointments use their existing validation, payment and fulfilment flows. NeroGym, NeroTrade and NeroConnect integrations currently handle information and callback enquiries. They do not create memberships or wholesale/partner orders. Caller card details must go through secure hosted checkout.

WhatsApp ownership and service configuration must be verified before connection. API activation does not register a new WhatsApp business account. Dashboard or API access alone does not allocate a phone number or make an unconfigured receptionist answer calls.

Pause ordering while keeping reception available

curl -X PATCH 'https://eu.neropay.app/v2/ai-reception/availability' \
  -H "Authorization: Bearer $NEROPAY_SECRET_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pause-orders-20261019-001' \
  --data '{"accepting":{"neroweb":false,"nerobooking":true}}'

Publish saved settings

curl -X POST 'https://eu.neropay.app/v2/ai-reception/publish' \
  -H "Authorization: Bearer $NEROPAY_SECRET_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: publish-reception-20261019-001' \
  --data '{}'

Calls, callbacks & usage

List endpoints accept page (1–10,000, default 1) and per_page (1–100, default 25). The response data contains items, page, per_page and has_more. Records are newest first. All IDs are scoped to the authenticated merchant.

Method & path	Returned fields / operation
GET /calls	id, channel, caller, state, duration_seconds, minutes, summary and created_at.
GET /calls/{id}	One call by UUID. Returns 404 for another merchant's call. No audio, raw transcript, provider identifier or call-context credential is exposed.
GET /callbacks	id, state, created_at and details. Details contain the consented callback enquiry; they are personal data.
PATCH /callbacks/{id}	{"state":"completed"} — mark one callback UUID complete. This does not place a telephone call.
GET /usage	id, call_id, minutes, amount_pence, state, payment_method and created_at. Amounts are integer GBP pence.

Phone duration is verified before final usage is recorded; in-progress calls can show zero minutes. Started minutes are rounded up. Included usage has zero amount and payment_method included. Additional paid usage follows the existing saved-card and configured balance-fallback collection flow. This endpoint cannot submit or alter billable usage.

Use the workspace overview for current-period minutes and subscription status. Data is subject to the workspace retention policy, so old summaries and enquiry details may be empty. No public receptionist tool-execution, raw payment, receipt-send or outgoing-call endpoint is exposed by this API.

Read recent calls

curl 'https://eu.neropay.app/v2/ai-reception/calls?page=1&per_page=25' \
  -H "Authorization: Bearer $NEROPAY_SECRET_KEY" \
  -H 'Accept: application/json'

Empty list response

{
  "success": true,
  "data": {
    "items": [],
    "page": 1,
    "per_page": 25,
    "has_more": false
  }
}

Build with NeroPay

Quick start

Merchant mode

Platform mode

Ready-to-Use Plugins

NeroPay for WooCommerce

NeroPay for Wix

NeroPay for Odoo

NeroPay for Perfex CRM

NeroPay for Zapier

NeroPay for OpenCart 3

NeroPay for PrestaShop

NeroPay for WHMCS

NeroPay for Magento 2 / Adobe Commerce

NeroPay for WooCommerce

Key features

Best for

NeroPay for Wix

NeroPay for Odoo

Odoo 19 requirements

Odoo 19 scope

NeroPay for Perfex CRM

Features

Prerequisites

NeroPay for Zapier

NeroPay for OpenCart 3

NeroPay for PrestaShop

NeroPay for WHMCS

NeroPay for Magento 2 / Adobe Commerce

Authentication

Headers

Pagination

Errors

Authentication and account scope errors

Connected account errors

Payment and transaction errors

NeroTrade errors

Terminal errors

Payout and NeroDisburse errors

Idempotency

Good

Avoid

Account API

GET response attributes

POST /connected-accounts request attributes

PATCH /connected-accounts request attributes

NeroConnect connected accounts

Fee payer and pricing context

NeroConnect settings, reports and account operations

PATCH /neroconnect/settings attributes

Partner commissions & cash-order billing

Choose the right operation

Authentication and signed writes

1. Set the cash-order signup price

2. Registration activates pricing automatically

3. Record completed cash usage

4. Collection and allocation

Card commission reporting and events

Dashboard visibility

Pagination, errors and limits

Card sale: GBP 10, commission GBP 0.50

Signup pricing: 50p per cash order

Read the registered merchant price

Completed cash order

Node.js: sign a commerce write

Collection response

Management authentication

Signed writes and retry rules

Error handling

NeroConnect Sales Agent API

Sales agents

NeroConnect Partner API

Connected account moves

Partner controls

Pricing and policy inputs

Funded partner movements

NeroPay Store API checkout links

GET /neropay-store/products response attributes

POST /neropay-store/checkout-links attributes

Payments