Overview

This document provides information for understanding the partner-model solution, choosing the right integration approach, and planning and estimating a build.

Nuvei Connect is a platform that enables onboarding of a merchant to Nuvei, for quick payment processing. Nuvei Connect automatically runs identity, business, and compliance checks in the background to provide live status-updates at every stage. A consistent process is applied for the EU and UK.

End-to-end integration includes:

• Merchant Onboarding (Nuvei Connect) – Create, manage, and submit a merchant application via a hosted solution, Web SDK, or API.
• Payment Processing – Process card and alternative payment after a merchant is approved. For more information, see **(add link to nuvei docs)**.
• Webhook Integration – Receive a real-time notification for an application status change and other events.

(from Word doc – Sections 2 to 4 give you the conceptual picture — how the model works, what your options are, and the journey a merchant travels from invitation to go-live. Sections 5 to 10 are the technical reference. Section 11 helps you scope effort, and Sections 12 to 13 cover getting started and support.)

Partner Model Solution

With the partner-model solution, onboarding to Nuvei is via Nuvei Connect where a partner introduces and manages merchants. **check meaning – ‘introduces’ was in original Word draft**

Key Benefits

The partner-model solution provides the following benefits:

• Each merchant a partner introduces is onboarded through the same Nuvei Connect pipeline. **introduces?**
• Screening and underwriting of identity (KYC), business (KYB), and AML are run automatically.
  
  The underlying pipeline for KYB, KYC, AML, and underwriting is identical for every integration type; the owner of the front-end user experience and the owner merchant-data handling (PII) can vary between integration types.

• Funds are settled to a merchant bank account on a clear schedule. **clear??**
• Partner reporting is available via the Nuvei Control Panel (back-office) and the Partner Dashboard.
• Residuals, invoicing, and settlement reporting are managed via a dedicated partner dashboard.

Functionality

The partner-model solution platform enables a partner to:

• Submit a merchant through a simple link, the partner platform, or a direct API connection.
• Request that a merchant completes a single guided application, with identity and business checks run automatically in the background.
• Auto-approve and auto-configure a low-risk business with no manual intervention.
• Track every application in real-time and immediately receive a notification if a merchant goes live.
• Process payments and reconcile a settlement and a commission, from one location.

Integration Modes

Nuvei Connect offers three integration modes for the partner-model solution.

Nuvei-Hosted (Digital)

With the Nuvei-hosted digital merchant application, Nuvei manages the entire flow, from form presentation to document collection, under the partner brand.

Key Benefits

• Quick time-to-live – A partner does not need to develop an onboarding user-interface; the merchant performs onboarding via Nuvei-hosted pages.
• Partner branding – Customizable logo, favicon, colors, fonts, section titles, and tooltips.
• No handling of PII or GDPR – A partner never handles or stores sensitive-data (PII) of a merchant. Nuvei hosts the pages and processes all sensitive data.
• Branded invitation – A personalized, pre-populated invitation link is provided for the merchant.

Web SDK (Embedded)

With the Nuvei Web SDK, white-label components are embedded directly into a partner platform for a seamless native user-experience, without any redirect to an external page.

Key Benefits

• Native, end-to-end look-and-feel – Pre-built components render inside the partner web application.
• Minimal development – Embed the Web SDK, then focus on placement and styling. Nuvei manages form-logic and validation.
• Real-time callbacks – Front-end event callbacks per form state, plus server-side webhooks for application status.
• Shared PII model – PII is captured in the partner domain and transmitted directly to the secure Nuvei backend governed by a Data Processing Agreement (DPA).

REST API-based

A complete onboarding API suite for the partner to build a unique user-experience, including full field-level control and real-time validation.

Key Benefits

• Maximum flexibility – The partner designs, builds, and maintains the entire user-interface, thereby owning the journey, layout, and interaction.
• SMB and Enterprise flows – Submit data incrementally or via batch, as a merchant progresses.
• Real-time validation – Field-level validation is returned in an API response.
• Webhooks – Webhook statuses (received, in progress, approved, requires action, declined) drive the partner dashboard and workflow.
• Shared responsibility for PII and GDRP – The partner handles PII directly as per the partner data-processing agreement (DPA), consent management, and retention policies. Nuvei processes and stores data downstream under a DPA.

Integration Mode Comparison

	Nuvei-hosted (Digital)	Web SDK (embedded)	REST API-based
User-interface owner	Nuvei	Nuvei and partner. Embedded by partner.	partner
Partner build-effort	low	low to medium	high
Time-to-live	fastest	fast	longest
Branding control	theme and branding	native in-app	Full (unlimited)
PII handling	Nuvei	Nuvei and partner (as per DPA)	partner (as per DPA)
Recommended for	Quick launch with low development effort.	Native look-and-feel with medium-level development effort.	Full control and complex flows.

Stages in the End-to-end Onboarding Journey

In order to go live, every merchant follows the same six-stage journey that starts with the initial invitation of a partner, regardless of the integration mode. The stages of the onboarding journey are:

Stage 1 – Discovery and Invitation

1. The partner selects a region and template, pre-fills known merchant data, and sends a branded invite.
2. Nuvei Connect generates a secure, time-limited onboarding link.

Stage 2 – Sign-up and Application

1. The merchant receives the invite, signs up, completes the (partly pre-filled) application, and accepts the terms.
   The partner can track the application status in real- time.

Stage 3 – KYB/KYC and Compliance

1. Merchant runs automated KYB, KYC, AML screening, and identity checks include UBO verification and a liveness/selfie match. Data can be pre-filled from KYB/KYC sources, with bank checks via open banking and real-time validation. **check wording/meaning** ‘vendor’ changed to merchant – correct?

Stage 4 – Underwriting and Risk Assessment

1. An automated underwriting engine combines vendor results, AML and credit scores, and risk tiering to reach a decision.
2. Additional documents are requested if a check fails.

Stage 5 – Provisioning

1. MID provisioning, gateway and billing configuration, and credential issuance are performed automatically.

Stage 6 – Go Live

1. The merchant is activated.
2. The merchant receives go-live confirmation and Control Panel access for reporting, settlements, and disputes.

** to HERE in editing**

5. Merchant Onboarding — API Integration
The Nuvei Connect API lets you programmatically create, update, submit, and manage merchant applications. It follows RESTful conventions and uses JSON for request and response payloads. This section is the core technical reference and also underpins the Embedded and Hosted modes.
5.1 Authentication
All API requests (except the authentication endpoint itself) require a valid access token, obtained by authenticating with your clientId and clientSecret.
Endpoint:
POST /auth/clients/{clientId}/authenticate
Request body:
• clientSecret (required) — your client secret.
• noTokenExpiry (optional) — set to true for non-expiring tokens (system-to-system integrations only).
The response returns an accessToken and region. Include the token in the Authorization header of all subsequent calls:
Authorization: Bearer {accessToken}
To revoke a token:
POST /auth/access-token/revoke
5.2 Base URL
• UAT / Sandbox: https://ignite-preprod-api.nuvei.com/uat2/v1
• Production: provided by your Nuvei Integration Manager upon go-live.
5.3 Application Lifecycle
An application moves through the following statuses:
Status Description
IN_PROGRESS Application created but not yet submitted. Can be updated.
SUBMITTED Application submitted for review. No further data updates allowed.
PENDING_REVIEW Submitted and queued, awaiting the start of review.
IN_REVIEW Currently being reviewed by the underwriting / compliance team.
ADDITIONAL_INFO_REQUESTED Further information or documents are required before review can continue.
PENDING_APPROVAL Review complete; awaiting a final approval decision.
CONDITIONALLY_APPROVED Approved subject to conditions that must be met.
APPROVED Application approved. Final state.
DECLINED Application declined. Final state.
WITHDRAWN Application withdrawn by the partner. Final state.

5.4 API Endpoints Overview
Category Method Endpoint Description
Authentication POST /auth/clients/{clientId}/authenticate Authenticate and obtain access token
Authentication POST /auth/access-token/revoke Revoke an access token
Applications POST /applications Create a new application
Applications POST /applications/{applicationId} Update an application
Applications GET /applications/{applicationId} Retrieve an application
Applications POST /applications/{applicationId}/submit Submit an application
Applications POST /applications/{applicationId}/withdraw Withdraw an application
Documents POST /applications/{applicationId}/documents Upload documents
Documents GET /applications/{applicationId}/documents Retrieve document metadata
Documents GET /applications/{applicationId}/documents/{id} Download a single document
Notifications POST /applications/{applicationId}/notification-subscribers/configure Configure notification subscribers
Notifications POST /applications/{applicationId}/notification-subscribers/delete Delete notification subscribers
Notif. Config POST /notifications/configurations Create notification configuration
Notif. Config GET /notifications/configurations List notification configurations
Notif. Config GET /notifications/configurations/{configurationId} Retrieve a configuration
Notif. Config POST /notifications/configurations/{configurationId}/delete Delete a configuration
White Label POST /white-labelling/configurations Create white-labelling config
White Label GET /white-labelling/configuration Retrieve white-labelling config
White Label POST /white-labelling/configurations/{configurationId} Update white-labelling config

5.5 Application Data Structure
The Create Application request body includes the following key sections:
• businessInformation — legal name, DBA, registration number, contact details, address.
• salesProfile — expected transaction volume, revenue, average ticket size.
• bankingInformation — bank account details for settlements.
• ownerInformation — details of business owners / stakeholders.
• mcc — Merchant Category Code.
Refer to the full API schema (swagger.json) for all available fields, validation rules, and accepted values.

Illustrative create request:
POST /v1/onboarding/applications
{
“businessType”: “COMPANY”,
“businessStructure”: “COMPANY_LLC”,
“legalName”: “Seaside Rooms Ltd”,
“registrationNumber”: “08123456”,
“merchantCategoryCode”: 7011,
“prefill”: true
}
-> 201  application.received
-> webhook  verification.in_progress
5.6 Auto-Submit Feature
When creating an application, if all required fields and documents are provided, the application can be auto-submitted. The response indicates:
• applicationStatus: SUBMITTED — auto-submission successful.
• applicationStatus: IN_PROGRESS — auto-submission failed due to missing required documents.
5.7 Document Upload
Documents can be uploaded at any stage before a final decision (approved / declined / withdrawn).
• Accepted formats: PDF, JPEG, PNG, JPG.
• Maximum size: 10 MB total per request (20 MB per individual file).
Document categories include:
• Identification — DRIVERS_LICENSE, PASSPORT, GOVERNMENT_ISSUED_ID.
• Banking — BANK_STATEMENT, VOID_CHECK, STAMPED_BANK_LETTER.
• Address verification — UTILITY_BILL, RENTAL_LEASE_AGREEMENT, MORTGAGE_STATEMENT.
• Non-grouped — AUDITED_FINANCIALS, TAX_RETURNS, PROCESSING_STATEMENTS, and many more.
5.8 Notification Management
Nuvei Connect supports two notification types:
• WEBHOOK — HTTP POST to your endpoint URL.
• EMAIL — email notifications to specified recipients.
Notifications can be configured at multiple levels:
• Channel level — applies to all applications under the channel.
• Partner level — applies to a specific partner under a channel.
• Application level — overrides channel / partner config for a specific application.
Supported event types include:
• APPLICATION_UPDATED
• ADDITIONAL_INFORMATION_REQUIRED
• APPLICATION_SUBMITTED (email only)
• APPLICATION_APPROVED (email only)
• APPLICATION_DECLINED (email only)
5.9 White Labelling
You can customise the branding of the onboarding experience, including:
• Logos, favicons, and colour themes.
• Custom email templates for notifications.
• Custom DNS domains for portals and APIs.
• Document upload app branding.

6. Hosted Solution — Implementation Notes
The Hosted Solution provides a pre-built, Nuvei-hosted onboarding UI that you redirect or invite merchants to. It is the lowest-effort path to a live pilot.
Typical implementation tasks:
1. Configure your white-labelling settings (logo, colours, fonts, domains) via the White Label endpoints in Section 5.4.
2. Generate a branded, pre-populated invitation link for each merchant (optionally pre-filling known data).
3. Stand up a webhook endpoint to receive status updates (see Section 9).
4. Display application status to your internal teams from the webhook events or by polling the GET application endpoint.

Because Nuvei hosts the pages and processes all sensitive data, you never store merchant PII in this mode. Detailed page-flow documentation is available from your Nuvei Integration Manager.
7. Web SDK — Implementation Notes
The Web SDK lets you embed white-labelled onboarding components directly in your own UI for a native experience, without redirecting merchants to an external page.
Typical implementation tasks:
1. Install and initialise the SDK in your web application.
2. Place and style the pre-built components (e.g. business details, owner information, banking details); Nuvei manages form logic and validation.
3. Handle front-end event callbacks for form state (progress, validation, completion).
4. Stand up a webhook endpoint for server-side application-status events (see Section 9).
5. Put a Data Processing Agreement (DPA) in place, since PII is captured in your domain before being transmitted to Nuvei’s back end.

The SDK is distributed as white-labelled components for modern web stacks. Confirm the current component list and versioning with your Nuvei Integration Manager.

8. Payment Processing
Once a merchant is approved through Nuvei Connect, payment processing is integrated using Nuvei’s payment APIs. Full documentation lives on the Nuvei developer portal.
Documentation: https://docs.nuvei.com
• API Reference — available on the Nuvei Developer Portal.
Payment processing integration covers:
• Card payments (Visa, Mastercard, and others).
• Alternative payment methods (APMs).
• Recurring payments and subscriptions.
• Refunds and voids.
• 3D Secure authentication.

9. Webhook Integration
Webhooks provide real-time notifications about application status changes and other events. This is the recommended way to stay informed about onboarding progress, and is needed in all three integration modes.
Webhook delivery is secured with mutual TLS (mTLS) over HTTPS. Because the connection is mutually authenticated and encrypted at the transport layer, the payload is not additionally encrypted at the application layer — the merchant secretKey is no longer separately encrypted (JWE) with a partner certificate, as that would add no security benefit on top of mTLS.
9.1 How it works
1. You configure a webhook endpoint URL and notification preferences via the Notification Configuration API, and complete the mTLS certificate setup with Nuvei (see 9.4).
2. When a relevant event occurs (e.g. an application status change), Nuvei opens a mutually authenticated TLS connection to your endpoint and sends an HTTP POST.
3. The payload is a signed JWT (JWS) delivered over the mTLS channel. It is not JWE-encrypted; the merchant secretKey, when present, is carried in the payload and protected by the mTLS channel.
4. Your server validates the Nuvei client certificate, verifies the JWT signature, processes the payload, and returns HTTP 200.
9.2 Webhook payload structure
The payload is delivered as a signed JWT with the following structure:
• Header — the signing algorithm (e.g. RS256) and a certificate reference.
• Payload — event data including applicationId, eventType, applicationStatus, the merchant secretKey (when applicable, carried within the mTLS channel rather than JWE-encrypted), and a timestamp.
• Signature — RSA signature for verification.
9.3 Processing steps
1. Accept the inbound mTLS connection and validate that it presents a valid Nuvei client certificate; reject connections that do not.
2. Receive the HTTP POST at your configured endpoint.
3. Extract the JWT from the request body.
4. Verify the JWT signature using Nuvei’s public certificate (.crt).
5. Decode the JWT payload to extract the event data (including the secretKey when present — no decryption step is required).
6. Process the event data according to your business logic.
7. Return HTTP 200 to acknowledge receipt.
9.4 Certificate exchange (mTLS)
Webhook security relies on a mutual TLS handshake. Nuvei acts as the TLS client (it initiates the connection to your endpoint) and your server acts as the TLS server. Both sides present and validate certificates:
What Who provides Purpose
Nuvei client certificate (public) Nuvei → Partner So your endpoint can authenticate that inbound webhook connections genuinely originate from Nuvei (mTLS client auth).
Partner endpoint (server) certificate Partner → Nuvei Your HTTPS endpoint’s TLS server certificate; share the certificate or issuing CA with Nuvei if certificate pinning is used.
Nuvei signing certificate (public) Nuvei → Partner To verify the JWT/JWS signature on the payload at the application layer (if signing is retained).

Your endpoint:
• Present a valid TLS server certificate on your HTTPS endpoint.
• Configure your server to request and validate Nuvei’s client certificate, rejecting connections that do not present it.
• Provide Nuvei with your endpoint certificate or issuing CA if certificate pinning is required.
The partner no longer provides a certificate for Nuvei to encrypt the merchant secretKey — that step has been removed now that delivery is over mTLS.
Nuvei’s certificates:
To obtain Nuvei’s client certificate (and signing certificate, if used), email your Nuvei Integration Manager or [email protected] with your Partner ID / company name, the environment(s) needed (Production, Sandbox/UAT, or both), and the technical contact who will handle the integration. Nuvei responds with the certificate file(s) via secure email; please allow up to one business day, and request early to avoid delays.
9.5 Webhook best practices
• Enforce mTLS — reject any connection that does not present a valid Nuvei client certificate.
• Verify the JWT signature before processing any payload (if application-layer signing is retained).
• Return HTTP 200 promptly and perform heavy processing asynchronously.
• Implement idempotency — you may receive the same event more than once.
• Ensure TLS is terminated where client-certificate validation is enforced — take care that reverse proxies or load balancers do not strip the mTLS client certificate.
• Store and rotate certificates securely; support multiple valid certificates during rotation.
• Log all received webhooks for debugging and audit, and set up monitoring/alerting for delivery failures.
10. Error Handling
All API errors follow a consistent format:
Field Description
errorType Always ‘api_error’.
errorCode Machine-readable code (e.g. invalid_request, auth_error, system_error).
errorDescription Human-readable description, or an array of field-level errors.

Common HTTP status codes:
Status Meaning
200 OK — request succeeded.
400 Bad Request — invalid or missing fields.
401 Unauthorized — invalid or expired access token.
403 Forbidden — insufficient permissions.
404 Not Found — resource does not exist.
422 Unprocessable Content — business logic error (e.g. incompatible status).
500 Internal Server Error — retry later.

11. Planning & Effort Estimation
This section is a planning aid to help you scope the work and estimate effort. The ranges below are indicative for a small integration team (1–2 engineers) and assume sandbox access and credentials are in place. Your actual effort will depend on team size, the complexity of your existing platform, and how much branding and automation you want. Treat these as starting points for your own estimate, not commitments.

11.1 Indicative effort by integration mode
Mode Indicative effort Main work items
Hosted / Digital ~1–2 weeks White-label configuration, invitation-link generation, webhook receiver, status display. No onboarding UI to build.
Embedded / Web SDK ~2–4 weeks SDK install and initialisation, component placement and styling, front-end callbacks, webhook receiver, DPA in place.
API-based ~4–6+ weeks Full UI build, field-level data mapping to the application schema, document upload, incremental validation handling, webhooks, DPA and consent/retention handling.

11.2 Cross-cutting work (applies to all modes)
Budget for these regardless of which mode you choose:
Task Indicative effort Task decription
Authentication & secrets handling ~1–2 days ClientId / clientSecret storage, token lifecycle
Webhook receiver & certificate exchange ~3–5 days Endpoint, JWT signature verification, JWE decryption, idempotency, logging; plus the certificate request/exchange (allow up to 1 business day for Nuvei’s cert).
Payment processing integration Plan this as its own workstream Scoped separately via docs.nuvei.com; depends on the payment methods and flows you need (cards, APMs, 3DS, recurring, refunds).
Testing & end-to-end validation ~3–5 days. Sandbox application creation, document upload, submission, webhook receipt, and a full dry run
Production readiness ~1–2 days plus Nuvei lead time production credentials, production certificates, go-live checklist sign-off.

11.3 Suggested phasing
1. Foundations — obtain credentials, authenticate, create a test application in sandbox.
2. Onboarding flow — implement your chosen mode end to end in sandbox (create, upload documents, submit).
3. Notifications — stand up the webhook receiver, complete the certificate exchange, verify a test webhook.
4. Payments — integrate payment processing for a single payment method, then expand.
5. Hardening & go-live — full end-to-end test, request production credentials, switch over.

A pragmatic pilot approach is to launch on the Hosted Solution first (fastest path to a live merchant and real webhooks), then layer in Embedded or API once the basics are proven.

12. Getting Started Checklist
Use this checklist to track your integration progress:
☐  Obtain your clientId and clientSecret from your Nuvei Integration Manager.
☐  Authenticate and obtain an access token.
☐  Decide your integration mode (Hosted, Embedded/SDK, or API) — see Section 3.
☐  Create a test application in the Sandbox environment.
☐  Upload required documents to your test application.
☐  Submit the test application.
☐  Request Nuvei’s webhook signing certificate (see Section 9.4).
☐  Generate your RSA key pair and share your public .crt with Nuvei.
☐  Configure your webhook endpoint via the Notification Configuration API.
☐  Receive and verify a test webhook notification.
☐  Integrate payment processing via docs.nuvei.com.
☐  Complete end-to-end testing.
☐  Request production credentials from your Nuvei Integration Manager.
☐  Go live.

13. Support & Contacts during the Pilot phase
Need Contact
Development teams Amit Behera
Ivaylo Nikolov
Emilian Padurariu
Travis Rogers
API Documentation https://docs.nuvei.com

 

14. Support & Contacts after the Pilot phase
Need Contact
Integration Support [email protected]
API Documentation https://docs.nuvei.com
Webhook Signing Certificate Contact your Nuvei Integration Manager
Production Credentials Contact your Nuvei Integration Manager