> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Nuvei

> Configure a Nuvei Disputes integration so Payrails processes your chargebacks, covering the Nuvei site and merchant site IDs.

<Note>
  **Who should use this guide**

  This guide is intended for merchants who:

  * Use **Payrails** as a chargeback
  * Use **Nuvei Disputes**
</Note>

***

## Create and configure a Nuvei integration in Payrails

1. Log in to the **Payrails** portal.
2. Go to **Settings** → **Integrations**.
3. Select **Add instance** to create a new Nuvei integration configuration.
4. Select the **workspaces** where this integration should be available.

<Note>
  **About workspaces**

  Workspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces.
</Note>

***

## Step 1: Choose the integration type

* Select **Dispute** and continue to the next step.

<img className="mx-auto block rounded-lg object-cover" src="https://mintcdn.com/payrails-42074109/N5LDTYq2WBxzPAfv/images/docs/chargebacks/integrations/nuvei-chargeback-integration-1.png?fit=max&auto=format&n=N5LDTYq2WBxzPAfv&q=85&s=6c2cd495ae3083e4ff6c2df308817ba0" alt="Payrails integration type selection set to dispute" width="80%" data-path="images/docs/chargebacks/integrations/nuvei-chargeback-integration-1.png" />

## Step 2: Choose the provider

* Select **Nuvei** and continue to the next step.

<img className="float-left mr-4 mb-1 mt-0 rounded-lg object-cover" src="https://mintcdn.com/payrails-42074109/N5LDTYq2WBxzPAfv/images/docs/chargebacks/integrations/nuvei-chargeback-integration-2.png?fit=max&auto=format&n=N5LDTYq2WBxzPAfv&q=85&s=bd4e2889c6f6b1a4f5d7898a04c2c413" alt="Payrails provider selection set to Nuvei" width="80%" data-path="images/docs/chargebacks/integrations/nuvei-chargeback-integration-2.png" />

***

## Step 3: Configure your Nuvei integration

<Tip>
  **What you’ll need from Nuvei**

  Before you begin, make sure you have access to:

  * Nuvei site ID
  * Nuvei merchant site ID
  * Nuvei processing entity ID
  * Nuvei API key
  * Nuvei Dispute Rest 2.0 API key

  Log in to your Nuvei dashboard to complete this step.
</Tip>

### Integration instance name

**In Payrails**

* Enter an **Instance name** for your integration.

<img className="mx-auto block rounded-lg object-cover" src="https://mintcdn.com/payrails-42074109/N5LDTYq2WBxzPAfv/images/docs/chargebacks/integrations/nuvei-chargeback-integration-3.png?fit=max&auto=format&n=N5LDTYq2WBxzPAfv&q=85&s=33b5c58e8fd07a5e17ada1e08f5b6494" alt="Nuvei integration instance name field" width="100%" data-path="images/docs/chargebacks/integrations/nuvei-chargeback-integration-3.png" />

***

### Merchant Nuvei site ID and merchant site ID

**In Nuvei**

* Go to **Settings** → **Business**.
* On the **Account details** tab, copy the **client ID** and** site ID**.

  <img className="mx-auto block rounded-lg object-cover" src="https://mintcdn.com/payrails-42074109/N5LDTYq2WBxzPAfv/images/docs/chargebacks/integrations/nuvei-chargeback-integration-4.png?fit=max&auto=format&n=N5LDTYq2WBxzPAfv&q=85&s=e12eb0f92668553a4d0db6df784c5f34" alt="Nuvei account details with client ID and site ID" width="80%" data-path="images/docs/chargebacks/integrations/nuvei-chargeback-integration-4.png" />

**In Payrails**

* Paste the value into the** merchant site ID **and** site ID** fields.

***

### Processing entity ID

**In Nuvei**

1. With **Developer** role, locate **Settings** and select **Rest 2.0 API credentials**.
2. Copy the **entity ID**.

<img className="mx-auto block rounded-lg object-cover" src="https://mintcdn.com/payrails-42074109/N5LDTYq2WBxzPAfv/images/docs/chargebacks/integrations/nuvei-chargeback-integration-5.png?fit=max&auto=format&n=N5LDTYq2WBxzPAfv&q=85&s=b240cc8635de81f2f48b1c33503b7234" alt="Nuvei Rest 2.0 API credentials showing entity ID" width="100%" data-path="images/docs/chargebacks/integrations/nuvei-chargeback-integration-5.png" />

**In Payrails**

* Paste the value into the**  Processing enity **field.

***

### API key and Dispute Rest 2.0 API key

<Tip>
  Use a restricted API key to limit access scope and reduce blast radius if the key is compromised.
</Tip>

**In Nuvei**

1. With **Developer** role, locate **Settings** and select **Rest 2.0 API credentials**.
2. Generate the keys** API key **and** Dispute API key**.
3. Copy the generated **API key **and** Dispute API key**.

<img className="mx-auto block rounded-lg object-cover" src="https://mintcdn.com/payrails-42074109/N5LDTYq2WBxzPAfv/images/docs/chargebacks/integrations/nuvei-chargeback-integration-6.png?fit=max&auto=format&n=N5LDTYq2WBxzPAfv&q=85&s=0d0d7ecf6395499e3dc43ee2f600211d" alt="Nuvei API key and dispute API key generation" width="100%" data-path="images/docs/chargebacks/integrations/nuvei-chargeback-integration-6.png" />

**In Payrails**

* Paste the value into the** API key** and **Dispute API key** fields.

***

### DMN

<Note>
  Payrails uses Nuvei DMN to receive asynchronous chargeback status updates.
</Note>

**In Nuvei**

1. Go to **Settings** → **My Account** → **Events configuration** → **Client level configuration**.
2. Select the **Client**.

**In Payrails**

* Copy the **Notification URL** from the **Account configuration** section.

<img className="mx-auto block rounded-lg object-cover" src="https://mintcdn.com/payrails-42074109/N5LDTYq2WBxzPAfv/images/docs/chargebacks/integrations/nuvei-chargeback-integration-7.png?fit=max&auto=format&n=N5LDTYq2WBxzPAfv&q=85&s=18b608f33ede18deecabbe75c8f4b84c" alt="Payrails notification URL field for Nuvei DMN" width="100%" data-path="images/docs/chargebacks/integrations/nuvei-chargeback-integration-7.png" />

In **Nuvei**

1. Configure the destination:
   1. Paste the Payrails **Notification URL** in **Chargebacks** events settings
   2. Enable the **Chargebacks** events settings

      <img className="mx-auto block rounded-lg object-cover" src="https://mintcdn.com/payrails-42074109/N5LDTYq2WBxzPAfv/images/docs/chargebacks/integrations/nuvei-chargeback-integration-8.png?fit=max&auto=format&n=N5LDTYq2WBxzPAfv&q=85&s=e2a200031380ae3dcd7cf34a34e66798" alt="Nuvei events configuration for chargebacks notification" width="100%" data-path="images/docs/chargebacks/integrations/nuvei-chargeback-integration-8.png" />

***

## Enable the integration

**In Payrails**

* Select **Save account** to enable the integration.

The **Enabled** status indicates that the Nuvei integration is active.

<img className="mx-auto block rounded-lg object-cover" src="https://mintcdn.com/payrails-42074109/N5LDTYq2WBxzPAfv/images/docs/chargebacks/integrations/nuvei-chargeback-integration-9.png?fit=max&auto=format&n=N5LDTYq2WBxzPAfv&q=85&s=1648696c691189a47195df40d5fefce6" alt="Payrails Nuvei integration enabled status" width="80%" data-path="images/docs/chargebacks/integrations/nuvei-chargeback-integration-9.png" />

Your Nuvei integration is now ready to process chargebacks.

***

## Next steps

1. Run a test payment triggering a chargeback using a Nuvei test card.
2. Verify that:
   * The dispute appears in Nuvei.
   * The chargeback status updates correctly in Payrails.
3. Once verified in test mode, repeat the setup in live mode.


## Related topics

- [FawryPay](/docs/orchestration/payment-methods/fawrypay.md)
- [Cards](/docs/orchestration/payment-methods/cards/index.md)