NeroPay API v2

Professional API reference for payments, platforms and merchant tools.

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

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 17 Apr 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 and 18 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 →

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

Use NeroPay with Odoo eCommerce, Website and Invoicing apps. The integration uses NeroPay payment endpoints and keeps order or invoice state inside Odoo.

Odoo 16 app Odoo 17 app Odoo 18 app

Odoo App Store

Install the version that matches your Odoo branch, then enable NeroPay under Invoicing → Configuration → Payment Providers.

Supported environments

Odoo 16
Odoo 17
Odoo 18

Prerequisites

Access to Invoicing → Configuration → Payment Providers.
Active NeroPay merchant account.
Public and Secret API keys.
HTTPS endpoint for IPN callbacks.

1. Install the moduleUpload the neropay_payment module to Odoo add-ons or install it via Apps.

2. Enable providerRestart Odoo, update the Apps list, then select or create the NeroPay payment provider.

3. Configure keysEnter public and secret keys, choose sandbox or live mode and enable the provider.

4. Reconcile with IPNUse the NeroPay callback to mark invoices/orders paid after signature verification.

Flow	Description
eCommerce checkout	Create a hosted payment and redirect the customer to the checkout URL.
Invoice payment	Use the Odoo invoice number as `identifier` for reconciliation.
Sandbox testing	Use sandbox endpoint and test credentials before live deployment.
Troubleshooting	Check provider visibility, IPN reachability and HMAC signature configuration.

Odoo payment request

{
  "public_key": "YOUR_PUBLIC_KEY",
  "identifier": "ORDER12345",
  "currency": "GBP",
  "amount": 120.00,
  "details": "Sale of item #SKU1001",
  "ipn_url": "https://yourdomain.com/payment/neropay/ipn",
  "success_url": "https://yourdomain.com/payment/neropay/success",
  "cancel_url": "https://yourdomain.com/payment/neropay/cancel",
  "customer_name": "Jane Doe",
  "customer_email": "jane@example.com"
}

Response

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

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

Authentication

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.

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."
  }
}

Idempotency

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.

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 resellers use the same API v2 key. NeroConnect endpoints expose platform settings, connected account lists and operational reporting without giving access to unrelated merchants.

GET/neroconnect/settings

Returns platform notification handling, default application fee context and supported settings.

PATCH/neroconnect/settings

Updates safe platform settings such as notification handling and default application fee values.

GET/neroconnect/accounts

Lists only connected accounts assigned to the authenticated NeroConnect platform.

GET/neroconnect/accounts/{account_id}

Returns one connected account assigned to the platform.

GET/neroconnect/reports/overview

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

Security: platform API keys cannot query arbitrary merchants. All account routes are scoped to the authenticated platform and the connected account must be assigned to that platform.

PATCH /neroconnect/settings attributes

Field	Type	Required	Description
`notification_handle`	enum	Optional	`neropay` or `platform`. Controls merchant-facing email/SMS handling where enabled.
`connect_application_fee_defaults.fixed`	decimal	Optional	Default fixed platform application fee in major currency units.
`connect_application_fee_defaults.percent`	decimal	Optional	Default platform application fee percentage.

Get platform settings

curl https://eu.neropay.app/v2/neroconnect/settings \
  -H "Authorization: Bearer neropay_secret_..."

Overview report

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

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 payment success, failure or pending updates.
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 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=..."
  }
}

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

Subscriptions API

Create recurring customer subscription checkout links from API v2, using an existing subscription price or a supplied amount, currency and interval.

GET/subscriptions

Lists subscriptions created for the merchant account.

POST/subscriptions

Creates a subscription request and returns checkout and portal URLs.

GET/subscriptions/{id}

Retrieves one subscription.

PATCH/subscriptions/{id}

Updates customer snapshot or status where the subscription is not cancelled/expired.

DELETE/subscriptions/{id}

Cancels or removes a subscription request where allowed.

GET /subscriptions query attributes

Field	Type	Required	Description
status	enum	Optional	Filter by `pending`, `active`, `past_due`, `cancelled` or `expired`.
q	string	Optional	Search customer name, email, subscription reference or product name.
page / per_page	integer	Optional	Pagination controls.

GET /subscriptions response attributes

Field	Type	Description
id	integer/string	Subscription ID or reference.
customer_name, customer_email	string	Customer snapshot.
product_name	string	Subscription product/service name.
amount, currency, interval, quantity	decimal/string	Recurring charge details.
trial_days	integer	Trial period before the first charge.
checkout_url	url	Customer checkout/start URL.
portal_url	url	Customer management/cancellation URL where available.
status	enum	Current subscription status.

POST /subscriptions request attributes

Field	Type	Required	Description
customer_name	string	Required	Customer name.
customer_email	email	Required	Customer email address.
customer_phone	string	Optional	Customer phone number.
product_name	string	Required without price_id	Name shown to the customer and on subscription records.
price_id	string	Optional	Existing merchant subscription price ID.
amount	decimal	Required without price_id	Recurring amount when creating from API payload.
currency	string	Required without price_id	Currency code such as `GBP`.
interval	enum	Required without price_id	`day`, `week`, `month` or `year`.
quantity	integer	Optional	Subscription quantity. Defaults to 1.
trial_days	integer	Optional	Trial period before first charge.
start_date	date	Optional	Requested subscription start date where supported.
metadata	object	Optional	Your own reference data.
account_id	string	Platform only	Connected merchant account for NeroConnect routing.

PATCH /subscriptions/{id} request attributes

Field	Type	Description
customer_name, customer_email, customer_phone	string	Update customer snapshot where the subscription can still be edited.
status	enum	Update/cancel where allowed by lifecycle rules.
metadata	object	Replace or update stored metadata.

Account readiness: subscription checkout requires the merchant account to be active and connected. Provider errors are logged server-side and returned as NeroPay-safe messages.

Create subscription request

POST /v2/subscriptions
{
  "customer_name": "Demo Customer Ltd",
  "customer_email": "accounts@example.com",
  "customer_phone": "07700000000",
  "product_name": "Monthly support",
  "amount": 49.99,
  "currency": "GBP",
  "interval": "month",
  "quantity": 1,
  "trial_days": 7,
  "metadata": {
    "customer_ref": "CUST-1001"
  }
}

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 and reserve 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
available_balance	decimal	Funds available for use.
instant_available	decimal	Instant payout availability.
standard_available	decimal	Standard payout availability.
reserve_balance	decimal	Funds held in reserve due to proof/risk/compliance.
currency	enum	Wallet currency.

Balances response

{
  "success": true,
  "data": {
    "account_id": "NPVesdTGASO23_547878",
    "wallets": [
      {
        "currency": "GBP",
        "available_balance": 50.01,
        "pending_balance": 0,
        "instant_available": 0,
        "standard_available": 50.01,
        "reserve_balance": 0
      }
    ]
  }
}

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

Disputes belong under Money Movement because they affect payment risk, settlement and operational review.

GET/disputes

Lists disputes.

GET/disputes/{id}

Retrieves one dispute.

Dispute response attributes

Field	Type	Description
trx_number	string	Related transaction reference.
payment_number	string	Payment identifier.
dispute_reason	string	Reason code or description.
dispute_status	enum	open, won, lost, under_review etc.
customer_email	string	Customer email when available.

Disputes are read-only in API v2. Use dashboards or operational flows for evidence submission if enabled.

List disputes

GET /v2/disputes?status=open&per_page=25

Dispute response

{
  "success": true,
  "data": [
    {
      "id": 120,
      "trx_number": "NP-EGQX9271-cf013",
      "payment_number": "pi_...",
      "dispute_reason": "fraudulent",
      "dispute_status": "under_review",
      "customer_email": "buyer@example.com"
    }
  ]
}

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 requested documents and submit evidence back to NeroPay.

GET/compliance/requests

Lists compliance document requests.

GET/compliance/requests/{id}

Retrieves one compliance request.

POST/compliance/requests/{id}/documents

Uploads requested compliance documents.

POST compliance document request attributes

Field	Type	Required	Description
document_file	file	Required	Requested file.
document_type	string	Optional	Type requested by staff/compliance.
notes	text	Optional	Merchant or platform notes.
metadata	object	Optional	Optional developer metadata.

Compliance is not NeroConnect-only. If a direct merchant uses API v2, the same endpoints can be used for document request fulfilment. Webhooks notify document requested/submitted/approved/rejected.

List compliance requests response

{
  "success": true,
  "data": {
    "account_id": "NPVesdTGASO23_547878",
    "requests": []
  },
  "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

document_file=@proof-of-address.pdf
notes=Latest proof of address attached.
metadata[case_reference]=CASE-1001

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 account updates, KYC, compliance, proof, reserve release and support events.

GET/webhooks

Lists configured endpoints.

GET/webhook-deliveries

Lists delivery attempts.

transaction.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.
signature	string	Use your endpoint signing secret where configured.

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"
    }
  }
}

List deliveries

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

Sandbox

Sandbox write endpoints under /sandbox return realistic JSON and do not create live payment, terminal, payout or local records.

POST/sandbox/hosted-payments

Dry-run hosted checkout.

POST/sandbox/payment-links

Dry-run LinkPay payment link.

POST/sandbox/terminal/payments

Dry-run terminal payment.

POST/sandbox/terminal/locations

Dry-run terminal location.

POST/sandbox/terminal/readers

Dry-run reader registration.

POST/sandbox/bank-accounts

Dry-run bank account.

POST/sandbox/payouts

Dry-run payout.

PATCH/sandbox/payout-schedule

Dry-run schedule update.

POST/sandbox/resources/{resource}

Dry-run resource create.

Sandbox is designed for API clients and Postman tests. Use /sandbox/hosted-payments for checkout testing; direct sandbox card payments are not available in the public API.

Sandbox hosted payment

POST /v2/sandbox/hosted-payments
{
  "identifier": "SANDBOX-ORDER-1001",
  "amount": 15.99,
  "currency": "GBP",
  "details": "Sandbox checkout test",
  "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"
}

Sandbox response

{
  "success": true,
  "data": {
    "sandbox": true,
    "environment": "sandbox",
    "status": "pending",
    "amount": 15.99,
    "currency": "GBP",
    "checkout_url": "https://eu.neropay.app/v2/sandbox/checkout/NP-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}