Skip to main content

Nuvei Integration

Nuvei (SafeCharge) is a payment service provider (PSP) supported by AccruPay. When you configure Nuvei as a transaction provider, AccruPay routes payment sessions through Nuvei's SafeCharge infrastructure and the React SDK loads SafeCharge.js automatically.

Supported features​

FeatureSupported
Card checkout✓
Stored cards✓
Server charges✓
ACH✓
Auth & capture✓
Payment plans✓
Webhooks✓

Connecting Nuvei​

  1. Log in to the AccruPay dashboard.
  2. Navigate to Settings → Transaction Providers → Add Provider.
  3. Select Nuvei and enter your:
    • Merchant ID
    • Merchant Site ID
    • API key (secret key from your Nuvei dashboard)
  4. Save. AccruPay will use these credentials when routing sessions to Nuvei.

Once connected, use TRANSACTION_PROVIDER.NUVEI when starting sessions from the Node SDK.

TRANSACTION_PROVIDER enum value​

import { TRANSACTION_PROVIDER } from '@accrupay/node';

// Use this value when starting Nuvei sessions
transactionProvider: TRANSACTION_PROVIDER.NUVEI

Base config​

When you start a payment session with TRANSACTION_PROVIDER.NUVEI, AccruPay returns a baseConfig object alongside the session token. This config is consumed by the React SDK automatically — you do not need to pass it manually.

// Shape of the baseConfig returned by start() for Nuvei sessions
{
  merchantId: string;       // your Nuvei merchant ID
  merchantSiteId: string;   // your Nuvei merchant site ID
  env: 'prod' | 'int';      // 'prod' in live mode; 'int' in sandbox mode
}

The React SDK reads baseConfig from the session and initializes SafeCharge.js with these values. No extra wiring is required.

React SDK behavior​

The React SDK loads SafeCharge.js from the Nuvei CDN automatically when the session's provider resolves to NUVEI. You do not need to add a <script> tag.

https://cdn.safecharge.com/safecharge_resources/v1/websdk/safecharge.js

Because the script is injected at runtime, ensure your Content Security Policy allows it (see below).

Content Security Policy​

If your application sets a Content-Security-Policy header, add the Nuvei CDN to script-src and frame-src:

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://cdn.safecharge.com;
  frame-src 'self' https://cdn.safecharge.com;
  connect-src 'self';
  img-src 'self' data:;
  style-src 'self' 'unsafe-inline';

Both script-src and frame-src are required. SafeCharge.js renders the 3DS challenge frame as an iframe loaded from the same origin.

Sandbox setup​

To use the Nuvei sandbox environment:

  1. Enable the sandbox environment in your AccruPay SDK — environment: 'qa' for the Node SDK, environment="sandbox" for the React SDK.
  2. AccruPay will set env: 'int' in the session baseConfig.
  3. The React SDK initializes SafeCharge.js in test mode using that config.

Node SDK:

import AccruPay from '@accrupay/node';

const sdk = new AccruPay({
  apiSecret: process.env.ACCRUPAY_API_SECRET!,
  environment: 'qa',
});

React SDK:

<AccruPay
  merchantPublicId="your-merchant-public-id"
  transactionSessionId={sessionId}
  environment="sandbox"
>
  {/* payment fields */}
</AccruPay>

No Nuvei-specific configuration is needed beyond enabling the sandbox environment (environment: 'qa' for Node, environment="sandbox" for React) in AccruPay's SDKs.

Test cards​

Use these card numbers in the Nuvei sandbox. Any future expiry date and any 3-digit CVV are accepted.

Card numberBrandBehavior
4111111111111111VisaApproved
5111111111111118MastercardApproved
4444333322221111VisaApproved
4000000000000002VisaDeclined
4000000000000077Visa3DS challenge triggered

For a full list of Nuvei test card numbers including specific decline codes, see the Nuvei test documentation.

3D Secure​

3DS authentication is handled automatically by SafeCharge.js. When the issuer requires a challenge, the SafeCharge.js SDK presents the challenge UI without any code changes on your part.

You do not need to implement any 3DS flow yourself. The React SDK onSuccess callback fires only after the full authentication and payment flow completes.

Session TTL​

Session lifetime is controlled by Nuvei's SafeCharge session expiry, which is typically 20 minutes from session creation. If the customer does not complete the payment within that window, the session expires and the React SDK will surface an error. Start a new session if this happens.

ACH​

Nuvei supports ACH bank transfers. Start an ACH session with TRANSACTION_PROVIDER.NUVEI and the appropriate payment method type. ACH transactions settle asynchronously — use syncOne() or poll merchantApiTransaction to detect the final status (see Webhooks).

ACH test transactions are supported in the Nuvei sandbox environment.

Webhooks​

AccruPay registers a webhook endpoint URL with Nuvei for your merchant account. Find this URL in the AccruPay dashboard under Settings → Transaction Providers → Nuvei → Webhook URL, then configure it in your Nuvei dashboard.

Nuvei sends event notifications to AccruPay; AccruPay updates the corresponding transaction or payment plan record. Your application reads the updated state via the GraphQL API. See Webhooks for the full processing model.