• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
  • Payment Overview
    • Introduction
    • Choosing an Integration Method
  • Accept Payment
    • Payment Page
      • Quick Start
      • Input Parameters
      • Output Parameters
    • Web SDK
      • Quick Start
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments
      • Tokenization-Only Flow
      • Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • FAQs
    • Checkout
      • Quick Start
      • UI Customization
      • Payment Customization
      • Advanced Controls
      • Checkout Examples
    • Server-to-Server
    • Payment Scenarios
    • Mobile SDKs (Beta Release)
      • Android Mobile SDK (Beta Release)
      • iOS Mobile SDK (Beta Release)
    • Flow Diagrams
    • Plugins
      • Magento
        • Rebilling with Magento
      • WooCommerce
        • Rebilling with WooCommerce
      • PrestaShop
        • Rebilling with PrestaShop
      • OpenCart
      • Shopify (via AsiaBill)
      • Mirakl
      • Salesforce
      • SAP
      • WIX
    • Marketplaces
  • Features
    • Authentication
    • Financial Operations
      • Refund
      • Void
      • Auth and Settle
      • Partial Approval
      • Currency Conversion (DCC and MCP)
    • Card Operations
      • Card-on-File
      • PCI and Tokenization
      • Zero-Authorization
      • Merchant-Initiated Transactions (MIT)
      • Blocking Cards
    • Subscription (Rebilling)
    • 3D-Secure
      • 3D-Secure Explained
      • 3DS Implementations
        • 3DS MPI-Only Web SDK
        • 3DS MPI-Only REST
        • 3DS External MPI
        • 3DS Responses
      • 3DS Functions
        • 3D-Secure Fingerprinting
        • 3D-Secure Authentication Challenge
    • Callbacks (DMNs)
      • Configuring the Events API
  • Guides
    • Testing Cards, APIs and APMs
      • Testing Cards
      • Testing APIs with Postman
      • Testing APMs
    • Response Handling
    • Alternative Payment Guides (APMs)
    • Airline Ticket Guides
      • Airline Addendum
      • External Authorization Addendum
    • Payment Facilitators (PayFac)
    • Cashier
      • Cashier Events Guide
      • Cashier Features
    • Withdrawal Guide
    • Risk Guide
      • Appendix 1: Transaction Types
      • Appendix 2: Credits and Payouts
      • Appendix 3: Fraud to Sale Programs
      • Appendix 4: Compliance Programs
      • Appendix 5: Chargebacks
    • eKYC Guide
    • Server SDKs
      • Java SDK
      • .NET SDK
      • PHP SDK
      • Node.JS SDK
    • Fast Track Onboarding Developer Guide
    • Currency Conversion Guides
      • Multiple Currency Pricing (MCP)
      • Dynamic Currency Conversion (DCC)
        • DCC in Cashier or Payment Page
        • DCC in REST API Workflows
        • DCC in Web SDK Workflows
    • Website Compliance Guides
  • Additional Links
    • FAQs
    • API Reference
    • Release Notes
    • Country and Currency Codes

FAQs

On this page:
  • General
  • Payment Page
  • REST API/Web SDK

General

Why am I seeing multiple transactions for the same order in my CPanel report?

As part of the 3D-Secure v.2 flow, our system performs several transactions that are used to check the enrollment status of the customer’s card and to obtain the verification details of the card. These transactions appear in the CPanel Transaction Report under transaction types initAuth3D and Auth3D.

They have no financial value and you can filter them out when extracting your Transaction Report by going to the Transactions tab, clicking on the Transactions Type dropdown menu, and selecting only the Financial checkbox.

I am receiving an “Invalid Login” error when trying to perform a transaction. How can I check my login details?

This error points to the fact that your account is not active. Please contact your account manager.

What happens if I do not receive the server-to-server notification for deposits (DMN)?

Our system is expecting a server response to the DMN callback indicating that the callback is received successfully by the merchant. The expected response is status code 200 – OK. If we do not receive this response, we consider the callback not to be received successfully and it enters retry mode.

While in Retry mode, the DMN callback is resent every 15 minutes for 24 hours or a total of 96 times. Once all retries run out and the merchant does not respond with status code 200 to any of the retries, the system stops resending the callback and records it as failed.

I do not have any PCI-DSS level. What is the best integration option for me?

Our Payment Page is the primary option for merchants that wish to completely descope from the PCI requirements since the page is handling all secure card data.
The Nuvei Fields service allows you to descope from the PCI while still using a server-to-server transaction flow.

For more information, please refer to Nuvei Fields and PCI and Tokenization.

The Country, Email, and IP Address parameters are not needed to perform a payment. Why are they required?

These parameters are used by our Risk system to detect and prevent fraudulent transactions, therefore, they are mandatory.

My transaction or my customer's transaction has been Declined. What should I do?

In case of bank Decline, Nuvei presents the Decline reason provided by the issuer bank so that the merchant and the customer can act upon it. If a generic Decline reason is presented, the cardholder has to contact their bank for more details.

I am receiving a restriction error while performing a refund or withdrawal transaction. Why is that?

You cannot refund more than a certain percentage of your total balance on your Nuvei account at any given time. The standard limitation is that you cannot refund/payout more than 100 percent of your deposits for the past 7 days. Attempting a refund or payout above this amount triggers the “Credit amount exceeds total charges” error.

The transaction timestamps in the Transaction Report do not correspond with the time zone in which I am.

You can change the default time zone in which your reports are generated by going to the “My Profile” section in your production CPanel and changing the time zone. See Setting the Time Zone at https://support.safecharge.com/en/article/navigation-bar.

I would like to send custom data to your system, which is returned in the response. Which parameter should I use?

There are several parameters that you can use – customData, merchant_unique_id or clientUniqueId, and the customFieldX parameters. The customData, merchant_unique_id, and clientUniqueId parameters are returned in the response to your system and are visible in the transaction report in your CPanel. On the other hand, the customFieldX parameters are only returned in the response to your system.

You can find the parameters in the full list of Payment Page parameters or at the payment.do parameters list for the REST API integration at  https://www.safecharge.com/docs/API/?json#payment.

I received the following error 'Mandatory fields are missing' and it is too vague to understand. What should I do?

Whenever you encounter an error, you receive a relevant error code.

In this case, the Error Code is 1136.

A field that is mandatory for the transaction is missing or has an incorrect value. Note that per Risk configuration the following parameters must be included (besides the API mandatory fields):

  • billingAddress: country; email
  • deviceDetails: ipAddress
  • paymentOption: cardHolderName

Payment Page

I would like to make sure that my users can use each request to the Cashier page only once. How can I prevent them from reloading the cashier page and performing additional deposits?

The Nuvei Cashier page includes a validation check that prevents customers from reloading the page or storing the request and loading it later. This feature validates the Checksum value. If it was used before, the request is cancelled and the customer is shown a relevant error message.

To activate this validation, please contact Nuvei’s Integration Team.

I am trying to send the notification (DMN) URL for withdrawals dynamically in the request.

The notification URL for withdrawals cannot be sent dynamically, unlike the URL for deposits. Please provide your withdrawals notification URL to Nuvei’s Integration Team.

Is the server-to-server notification (DMN) synchronous or asynchronous?

The DMN callbacks for deposits are asynchronous. However, the pre-deposit DMN callbacks and the initial withdrawals are synchronous. The latter two types of notification are synchronous since our system is expecting a response by the merchant – acknowledgment of the request and decision.

Please refer to DMN Acknowledgment Parameters for more information.

I would like to implement Google analytics or other custom analytics on the Hosted Payment Page. How can I do that?

The Nuvei Hosted Payment Page is capable of sending analytics events to the parent frame if it is opened in an IFrame. For a full list of the events and their triggers, please see our Cashier Events Guide.

After requesting a withdrawal, the customer remains on the withdrawal cashier. I want the customer to be redirected back to my website instead.

By default, our withdrawal cashier page keeps the customer on the page after they request a withdrawal. To redirect the customer to your page, you must enable this setting for your account. Please contact Nuvei’s Integration Team to set this up. The redirect URLs can be set up statically in your account settings or can be provided dynamically via request parameters – successUrl and failUrl.

REST API/Web SDK

I am using Nuvei Fields but there is no field for Cardholder name. How can I send this parameter?

Nuvei Fields collects only the sensitive card data and the Cardholder name can be collected normally. Please collect it and pass it in the createPayment() request via the parameter “cardHolderName” as described in Step 8 in Simple Card Integration.

How can I register the card details of the customer without performing a transaction? I want to store the card details and use them later.

The approved method for storing card details for future use is to perform an Authorization transaction for amount 0. You can read more about this feature in our Zero Authorization article.

I am receiving transactionStatus = REDIRECT in the response to my payment.do request. Is this a real status and what should I do?

Yes, this is a real status and instructs you that the transaction is not completed yet. The end user needs to be redirected to a web page to complete the transaction. There are two cases in which this response is returned:

  • 3D-Secure – The user needs to be redirected to paymentOption.threeD.acsUrl. See our 3D-Secure Guide for full details.
  • An APM that requires redirection – The URL is on paymentOption.redirectURL. See our APM Guide for full details.

Should I use openOrder.do or getSessionToken.do? Both methods appear to be performing the same task – generating a sessionToken?

Both methods are used for the same purpose – to authenticate the merchant and generate a session. The openOrder.do request should be used if you intend to use sessionToken with our Web SDK solution, and the getSessionToken.do should be used if you intend to use our REST API processing methods.

When an IP address in IPv6 format is sent to the openOrder.do or payment.do methods, I am receiving a validation error.

Currently, we do not yet support IPv6 format addresses. Please use the IPv4 format addresses only.

2022 Nuvei. All rights reserved.