Ellipse Gradient for Header

Nuvei Integration Guide

Nuvei integrates with enterprise systems primarily through REST APIs, signed payment requests, session-based operations, and selected webhook-style notifications.

Nuvei integration options at a glance

Nuvei’s primary integration mechanism is its REST API, which supports session management, payment initiation, authorization, 3-D Secure flows, transaction status, settlement, voids, refunds, and payment-method operations. Nuvei also supports webhook-style or server-to-server notifications for selected events, depending on the product and merchant configuration. Requests commonly use merchant credentials, merchant and request identifiers, checksum signing, timestamps, and session tokens where required. Martini can orchestrate these calls, receive supported notifications through an API, normalize payment responses, apply business rules, and synchronize transaction or reporting data with commerce, ERP, finance, and customer-service applications.

Integration pointSupported by Nuvei?Common use casesHow Martini supports it
REST APIsYesNuvei’s primary integration method for session management, payment initiation, authorization, 3-D Secure flows, transaction status, settlement, voids, refunds, and payment-method operations.Martini can consume Nuvei REST endpoints, map request and response JSON, orchestrate multi-step operations, and expose normalized APIs to internal applications.
Webhooks / outbound callbacksLimitedSelected payment, transaction, risk, dispute, or financial events may be delivered as server-to-server notifications depending on the Nuvei product and merchant configuration.Martini can expose an API endpoint to receive notifications, validate and correlate them, apply idempotency checks, and trigger reconciliation workflows.
AuthenticationYesCore payment API requests commonly use merchant credentials, merchantId, merchantSiteId, clientRequestId, timeStamp, checksum, and sessionToken where required.Martini can store merchant secrets in protected configuration, generate request signatures, manage session-opening calls, and prevent credentials from being embedded in workflows.
Bulk / async / batch APIsLimitedPayment processing may involve asynchronous or multi-step status handling, but a general-purpose bulk API for the core payment API was not confirmed.Martini can orchestrate asynchronous status queries, scheduled reconciliation, bounded retries, and high-water-mark processing without assuming a bulk endpoint.
SDKs and pluginsLimitedNuvei may provide product-specific SDKs, hosted-payment options, and commerce-platform integrations, which should be evaluated separately from direct API integration.Martini can call the underlying HTTP APIs directly when an SDK or plugin is not appropriate and can expose reusable APIs for adjacent systems.
File / attachment APIsNot confirmedA general-purpose file or attachment API was not confirmed for the core payment API; receipts, dispute evidence, and settlement reports require product-specific verification.Martini can process supported files or reports if Nuvei provides them through a verified endpoint, but the core integration should not assume file upload support.
Database / analytics accessNoDirect database access to Nuvei operational data was not confirmed. Reporting, settlement, and reconciliation should use supported APIs, reports, exports, or merchant-portal capabilities.Martini can consume supported reporting interfaces and write normalized results to enterprise databases without connecting directly to Nuvei’s database.

How Nuvei exposes data and business events

Nuvei REST APIs

Nuvei’s REST APIs provide the primary integration surface for session management, payment initiation, authorization, 3-D Secure flows, transaction status, settlement, voids, refunds, and payment-method operations.

Martini implementation pattern

Martini implementation pattern: a Martini API or workflow receives an internal payment request, validates business fields, opens or reuses a Nuvei session where required, generates the checksum, calls Nuvei, transforms the response, and returns a normalized result while recording transaction identifiers.

Implementation sequence

Receive the internal payment or transaction request
Validate amount, currency, order, and customer references
Open or reuse a Nuvei session where required
Generate the request checksum using protected configuration
Call the applicable Nuvei REST operation
Map the response into the internal payment model

Nuvei Webhook Notifications

Nuvei supports webhook-style or server-to-server notifications for selected payment and transaction events, with coverage determined by product and merchant configuration.

Martini implementation pattern

Martini implementation pattern: a Martini API receives the notification, validates its structure and authentication requirements, correlates the transaction, performs an idempotency check, and queries Nuvei for authoritative status when the notification is incomplete or financially significant.

Implementation sequence

Receive the Nuvei notification
Validate the notification and authentication requirements
Extract order and transaction correlation identifiers
Check whether the notification was already processed
Retrieve current Nuvei status when required
Update downstream order or finance systems asynchronously

Nuvei Asynchronous Processing

Nuvei payment operations can involve multiple stages, including session creation, payment submission, 3-D Secure authentication, authorization, settlement, and later status changes.

Martini implementation pattern

Martini implementation pattern: workflows distinguish pending, successful, declined, failed, and unknown outcomes, use notifications or follow-up status queries, and prevent a timeout from causing an unsafe duplicate payment or refund.

Implementation sequence

Submit the operation with a stable request identifier
Classify the immediate Nuvei response
Route pending or unknown outcomes to status reconciliation
Process supported notification events
Apply fulfillment or accounting rules only for permitted states
Record unresolved cases for review

Nuvei Reconciliation Data

Nuvei transaction or reporting data can support settlement and payment reconciliation, although the appropriate reporting or export interface depends on the Nuvei product and merchant configuration.

Martini implementation pattern

Martini implementation pattern: a scheduled workflow retrieves supported data, processes pages or report intervals with an overlap window, maps monetary and status fields, matches Nuvei identifiers to internal records, and emits exceptions for discrepancies.

Implementation sequence

Start the scheduled reconciliation workflow
Retrieve the supported transaction or reporting data
Process pages or intervals using a persisted high-water mark
Map amounts, currencies, statuses, and identifiers
Match results to internal orders and finance records
Write reconciliation outcomes and exception records

Common Nuvei integration patterns

Pattern 1: Orchestrate payment authorization

When to use this pattern

Use this pattern when a commerce or order-management application needs a controlled payment API without embedding Nuvei-specific session, signing, status, and error logic in the calling application.

Integration direction
Shopify
Martini
Nuvei
Example Mapping
Nuvei FieldCanonical FieldTarget Field
orderIdorder.referencemerchantOrderId
amountpayment.amountamount
currencypayment.currencycurrency
transactionStatuspayment.statusinternalPaymentStatus
Martini implementation pattern

A Martini API accepts the checkout request, validates amount and currency, opens or reuses a session, generates the checksum, submits the payment or authorization, and maps the response into a normalized status. It stores Nuvei order and transaction identifiers and routes pending or failed outcomes for reconciliation or review.

Martini capabilities used
  • APIs
  • workflows
  • API consumption
  • data mapping
  • business rules
  • secrets management
  • error handling

Pattern 2: Process Nuvei payment notifications

When to use this pattern

Use this pattern when payment status changes must update orders or fulfillment systems, while treating notifications as signals that may require authoritative status retrieval.

Integration direction
Nuvei
Martini
SAP S/4HANA
Example Mapping
Nuvei FieldCanonical FieldTarget Field
transactionIdpayment.providerTransactionIdPaymentDocument.ProviderTransactionId
orderIdorder.referenceSalesOrder.ExternalPaymentReference
statuspayment.statusPaymentDocument.Status
amountpayment.amountPaymentDocument.Amount
Martini implementation pattern

Martini receives the supported callback, validates it, checks notification idempotency, retrieves current transaction status when appropriate, and applies fulfillment rules only for authorized or settled states. Transient downstream failures are retried and unresolved cases are routed to an exception workflow.

Martini capabilities used
  • APIs
  • workflow triggers
  • workflows
  • data mapping
  • business rules
  • idempotency
  • error handling

Pattern 3: Manage refunds and voids

When to use this pattern

Use this pattern when customer-service, ERP, or order-management applications need to request refunds or voids through a consistent internal API and avoid duplicate financial actions.

Integration direction
Oracle NetSuite
Martini
Nuvei
Example Mapping
Nuvei FieldCanonical FieldTarget Field
internalOrderIdorder.referencemerchantOrderId
refundAmountrefund.amountamount
providerTransactionIdpayment.providerTransactionIdtransactionId
operationResultrefund.statusinternalRefundStatus
Martini implementation pattern

Martini validates user authorization and refund constraints, checks the current transaction before retrying an unknown result, calls the Nuvei refund or void operation with a stable request identifier, and maps the result back to the source system. Partial refunds and deterministic declines are handled separately from transient failures.

Martini capabilities used
  • APIs
  • workflows
  • business rules
  • data mapping
  • secrets management
  • error handling
  • retry handling

Pattern 4: Reconcile Nuvei settlements

When to use this pattern

Use this pattern for scheduled finance operations that compare Nuvei transaction or reporting data with internal orders, invoices, settlements, refunds, and disputes.

Integration direction
Nuvei
Martini
Oracle NetSuite
Example Mapping
Nuvei FieldCanonical FieldTarget Field
transactionIdpayment.providerTransactionIdTransaction.ExternalId
settledAmountsettlement.amountDeposit.Amount
currencysettlement.currencyDeposit.Currency
transactionStatuspayment.statusTransaction.Status
Martini implementation pattern

A scheduled Martini workflow retrieves supported Nuvei data, processes pagination or report intervals with a persisted checkpoint and overlap window, maps monetary values using decimal-safe handling, matches provider identifiers to NetSuite records, and creates exception records for missing, duplicated, or inconsistent results.

Martini capabilities used
  • scheduler triggers
  • workflows
  • API consumption
  • data mapping
  • SQL/database integration
  • business rules
  • monitoring

Applications commonly integrated with Nuvei

Nuvei can be integrated with commerce, billing, customer-service, and finance applications using REST API orchestration and supported notification mechanisms. The exact implementation depends on the Nuvei product, merchant configuration, and capabilities of the adjacent application.

Application Scenario Direction Martini Pattern
Shopify Process checkout payments, synchronize payment status, and support refunds for Shopify orders. Shopify → Martini → Nuvei Martini exposes or consumes the required application endpoints, validates order and payment data, signs Nuvei requests, maps transaction statuses, and processes supported Nuvei notifications back into Shopify.
Adobe Commerce Authorize, capture, refund, and reconcile payments associated with Adobe Commerce orders. Adobe Commerce → Martini → Nuvei A Martini workflow receives payment actions, opens or reuses a Nuvei session where required, calls the appropriate transaction operation, and returns normalized payment results while retaining correlation identifiers.
Salesforce Commerce Cloud Connect storefront checkout and order-payment status with Nuvei processing. Salesforce Commerce Cloud → Martini → Nuvei Martini mediates checkout requests, transforms commerce payloads into Nuvei API structures, handles asynchronous status changes, and routes approved results to order processing.
Salesforce Associate payment outcomes, refunds, and customer-service payment actions with Salesforce customer and order data. Salesforce → Martini → Nuvei Martini exposes controlled APIs for Salesforce actions, applies authorization and idempotency rules, calls Nuvei, and synchronizes normalized payment statuses and exceptions back to Salesforce.
SAP S/4HANA Transfer payment, settlement, refund, and reconciliation information into finance and order processes. SAP S/4HANA → Martini → Nuvei Scheduled and API-led workflows retrieve or process Nuvei transaction data, map amounts and statuses to SAP structures, and create exception records for unmatched or inconsistent settlements.
Oracle NetSuite Reconcile Nuvei transactions and settlements with invoices, sales orders, cash application, and refunds. Nuvei → Martini → Oracle NetSuite Martini retrieves supported Nuvei transaction or reporting data, maps transaction identifiers and monetary values to NetSuite objects, and exposes a controlled path for approved refund or payment actions.
Microsoft Dynamics 365 Synchronize customer orders, payment status, refunds, and financial reconciliation data. Microsoft Dynamics 365 → Martini → Nuvei Martini orchestrates bidirectional API calls, converts Nuvei states into Dynamics payment statuses, applies fulfillment rules, and retries transient failures without repeating completed transactions.
Zuora Connect subscription billing events with Nuvei recurring-payment processing and payment-status updates. Zuora → Martini → Nuvei A Martini workflow maps billing actions and subscription references to the applicable Nuvei product, tracks session and transaction identifiers, and processes supported notifications or status queries back into Zuora.

How to build a Nuvei integration in Martini

Objective

Establish Nuvei credentials, signing configuration, and any session requirements without exposing merchant secrets or sensitive payment data.

Instructions in Martini

  • Configure merchantId and merchantSiteId in protected environment configuration
  • Store the Nuvei secret key in Martini secrets
  • Implement the required checksum field order and timestamp rules
  • Open a session where the selected operation requires a sessionToken

Objective

Select an API-led, notification-driven, or scheduled entry point based on the payment or reconciliation use case.

Instructions in Martini

  • Expose a Martini API for internal payment, refund, or void requests
  • Configure a Martini API to receive supported Nuvei notifications
  • Use a scheduler for transaction or settlement reconciliation
  • Verify event coverage for the specific Nuvei product and merchant account

Objective

Call Nuvei using the operation-specific request model and preserve identifiers needed for correlation and retries.

Instructions in Martini

  • Validate order, amount, currency, and customer references
  • Call the appropriate Nuvei REST endpoint
  • Capture clientRequestId, Nuvei order identifiers, and transaction identifiers
  • Use follow-up status queries when notifications or immediate responses are incomplete

Objective

Coordinate session management, payment stages, status handling, downstream writes, and asynchronous processing in a maintainable workflow.

Instructions in Martini

  • Separate synchronous payment responses from pending or asynchronous outcomes
  • Route 3-D Secure and later status changes according to the selected Nuvei operation
  • Apply fulfillment and accounting rules only to approved states
  • Move long-running notification work to asynchronous processing when appropriate

Objective

Convert Nuvei request and response structures into stable internal models and target-application payloads.

Instructions in Martini

  • Map orders, transactions, payment methods, customers, subscriptions, and disputes as applicable
  • Normalize Nuvei statuses into the organization’s payment-state model
  • Use decimal-safe handling for amounts and validate currencies and minor units
  • Preserve source identifiers and selected raw responses for audit

Objective

Protect financial operations with validation, idempotency, authorization, and state-transition rules.

Instructions in Martini

  • Use stable request identifiers for payment and refund operations
  • Check existing transaction status before retrying unknown outcomes
  • Prevent fulfillment for pending, failed, or unverified states
  • Mask payment data and exclude secrets from logs

Common Nuvei data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
OrdersRepresent a payment or checkout context containing amount, currency, merchant information, and related transaction data.Shopify, Adobe Commerce, Salesforce Commerce Cloud, SAP S/4HANA, Oracle NetSuiteMartini validates order identifiers, amounts, and currencies, maps order data into Nuvei requests, and persists the relationship between internal and Nuvei identifiers.
TransactionsRepresent payment operations such as authorization, sale, settlement, void, refund, and other transaction actions.ERP, finance platforms, order-management systems, Salesforce, databasesMartini orchestrates transaction calls, normalizes statuses, applies idempotency and retry rules, and stores authoritative identifiers and response details.
Payment MethodsRepresent cards, alternative payment methods, bank transfers, wallets, and other supported payment instruments.Commerce platforms, checkout applications, subscription systemsMartini maps tokenized or non-sensitive payment-method references and avoids passing raw cardholder data unless PCI responsibilities and controls are explicitly established.
CustomersContain customer information and payment-related profiles used for recurring or repeat payments where enabled.Salesforce, Shopify, Zuora, commerce platformsMartini maps permitted customer attributes, protects sensitive identifiers, and links customer references to orders and transactions.
SubscriptionsRepresent recurring-payment arrangements and related billing or transaction activity where Nuvei subscription capabilities are enabled.Zuora, commerce platforms, ERP and billing systemsMartini coordinates subscription actions, maps billing references, and reconciles recurring transaction outcomes through supported Nuvei operations.
Chargebacks and DisputesRepresent dispute, chargeback, representment, and related financial-event information where enabled by the merchant’s Nuvei product configuration.SAP S/4HANA, Oracle NetSuite, Salesforce, finance databasesMartini processes supported dispute data, preserves source responses, maps financial states, and creates exception or review workflows.

Authentication and security considerations

Signed requests and protected credentials

Nuvei core payment API requests commonly use merchant credentials, merchantId, merchantSiteId, clientRequestId, timeStamp, checksum, and sessionToken where required. The exact signing inputs and session requirements depend on the API product and operation.

  • Store merchant secrets in Martini secrets or protected environment configuration.
  • Generate checksums using the exact field order, casing, timestamp format, and concatenation rules required by Nuvei.
  • Do not log secret keys, session tokens, complete authorization payloads, or sensitive payment data.

Payment data protection

Prefer hosted or tokenized payment flows where possible. Passing raw cardholder data through Martini can create significant PCI DSS responsibilities and should be evaluated with the organization’s security and compliance teams.

Operational considerations for Nuvei integrations

Reliability and state management

  • Use stable request identifiers and persist Nuvei order and transaction relationships.
  • Check transaction status before retrying a payment or refund with an unknown outcome.
  • Treat notifications as triggers for reconciliation when they do not contain a complete authoritative result.
  • Verify Nuvei rate limits, timeouts, retry behavior, event coverage, and authentication requirements for the selected product.

Reconciliation and data quality

  • Use decimal-safe monetary values and validate currency minor-unit rules.
  • Process transaction or reporting pages with persisted high-water marks and an overlap window for late updates.
  • Handle duplicate notifications and overlapping imports idempotently.
  • Test authorizations, 3-D Secure, alternative payment methods, refunds, voids, declined payments, and asynchronous status changes separately.

Schema and operational monitoring

Keep mappings for payment, transaction, refund, settlement, and dispute statuses under version control. Monitor API-version changes, preserve useful source responses for audit, and route unresolved failures to review workflows without exposing sensitive payment data.

Why use Martini instead of scripts or point-to-point integrations?

Centralized orchestration

Martini provides a controlled layer between Nuvei and commerce, ERP, billing, finance, and customer-service applications. Workflows can coordinate sessions, signed requests, payment stages, callbacks, status queries, downstream writes, and scheduled reconciliation.

Maintainable integration logic

Instead of duplicating Nuvei-specific signing, status, retry, and mapping logic across point-to-point scripts, Martini centralizes transformations, business rules, idempotency, error handling, and reusable APIs.

Operational control

  • Expose normalized APIs that hide provider-specific details from internal applications.
  • Apply consistent retry, exception, logging, and monitoring policies.
  • Keep secrets and environment-specific configuration outside workflow logic.
  • Extend workflows with custom logic when Nuvei product-specific behavior requires it.

Frequently asked questions

How can Nuvei be integrated with enterprise systems?

Nuvei is primarily integrated through its REST APIs for sessions, payment operations, authorizations, 3-D Secure flows, refunds, voids, settlements, and status queries. Selected payment or transaction events can be delivered through webhook-style notifications, depending on the Nuvei product and merchant configuration.

Can Martini integrate with Nuvei?

Yes. Martini can consume Nuvei REST APIs, generate request-signing fields, manage session-based operations, expose APIs for internal applications, receive supported Nuvei notifications, and synchronize payment or reconciliation data with enterprise systems.

Do I need a connector to integrate Nuvei with Martini?

No. A dedicated Nuvei connector is not required. Martini can integrate using Nuvei’s confirmed REST APIs, merchant authentication and checksum mechanisms, session tokens, and supported notification endpoints.

Is there any extra Lonti cost to integrate Nuvei with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate Nuvei. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Nuvei, cloud infrastructure, or other third-party systems depending on subscriptions, usage, and deployment model.

Which Nuvei integration methods should be used?

Use Nuvei REST APIs as the primary method for payment and transaction operations. Use webhook-style notifications for supported events, with coverage verified for the relevant product and merchant account. Core Nuvei authentication commonly uses merchant credentials, request fields, checksum signing, and session tokens rather than assuming OAuth.

Can Martini receive Nuvei webhooks or callbacks?

Yes. Martini can expose an API endpoint or workflow for supported Nuvei notifications. Because notification coverage is product- and event-dependent, the workflow should validate the event, apply idempotency, and query Nuvei for authoritative status when the payload is incomplete or financially significant.

How does synchronization with Nuvei work?

Real-time synchronization can use payment APIs and supported notifications, while scheduled workflows can retrieve supported transaction or reporting data for reconciliation. Martini maps Nuvei orders, transactions, statuses, amounts, and identifiers into commerce, ERP, billing, or finance models and can maintain checkpoints and overlap windows.

How does Martini handle Nuvei errors, retries, and duplicate payments?

Martini can separate transport failures, API errors, deterministic declines, and unknown outcomes; apply bounded retries to transient failures; and route unresolved cases to exception workflows. Stable request identifiers, persisted transaction relationships, idempotency checks, and status queries help avoid duplicating authorizations, captures, refunds, or notification processing.

Related Martini documentation

APIs

Workflows

Data

Security

Operations

Connect Nuvei with Martini

Use Martini to orchestrate Nuvei payment APIs and supported notifications across commerce, finance, ERP, billing, and customer-service systems.

EXPLORE MARTINI
BOOK A DEMO