Additional Services Home

Introduction

In addition to Nuvei’s main API Reference Guide, Nuvei offers additional services that can be found in their respective topics below.

Frontend Tokenization API

Use our Frontend Tokenization API as an alternative to our JavaScript SDK (Web SDK and Simply Connect).

With this API, you can get a temporary token (ccTempToken) directly to your web page by calling our cardTokenization API method. With this ccTempToken, you are able to perform a server-to-server payment by calling our payment API method directly from your server.

Merchant PCI Responsibilities:

• Though this method provides PCI descoping to some extent, you still need to complete the Moderate SAQ-A EP form, as opposed to the simpler SAQ-A form, which is sufficient when using the Web SDK method method.
• Perform quarterly scans

/cardTokenization

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "userTokenId": "230811147",
      "cardData":{
        "cardNumber": "4000027891380961",
        "cardHolderName": "John Smith",
        "expirationMonth": "12",
        "expirationYear": "2030",
        "CVV": "217"
    },
    "deviceDetails": {
        "ipAddress": "192.168.2.38"
    },
      "billingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "email": "[email protected]",
        "country": "US"
    }
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "internalRequestId": 840816528,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "version": "1.0",
    "sessionToken": "8e8feb04-f6ba-40dc-8008-c5270af1150e",
    "ccTempToken": "9bad80b9-8236-4990-a4e5-afa888851c47",
    "isVerified": false,
    "uniqueCC": "yKHZK4vGCyf0c/Se7rujEvNQtN8=",
    "cardType": "Credit",
    "issuerCountry": "GB"
}

This method enables the retrieval of a temporary card token (ccTempToken) based on card data.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/cardTokenization.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/cardTokenization.do

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
cardData ^Class ~Required	An alternative to sending the userPaymentOptionId for card payouts. Merchant has to be PCI certified to use this, as it uses clear text card numbers. NOTE: When sending cardData, you still must also send userTokenId. cardNumber (String, 20) cardHolderName (String, 70) expirationMonth (String, 2) expirationYear (String, 4) CVV (String, 4)
billingAddress ^Class ~Some parameters Required	The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters. country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30, REQUIRED) lastName (String, 40, REQUIRED) address (String, 60) address2 (String, 60) phone (String, 18) zip (String, 10) city (String, 30) state (String, 3) – ISO county/province/state/territory/union territory code. county (String, 255) These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.
userTokenId ^String(255) ^Optional	This ID uniquely identifies your consumer/user in your system. This must be sent when using the User Payment Management feature.
deviceDetails ^Class ^Optional	ipAddress (String, 15, REQUIRED) deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255)

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
internalRequestId ^Integer(20)	Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	If an error occurred on the request side, an error reason is returned in this parameter (e.g. failure in checksum validation, timeout from processing engine, etc.).
version ^String(10)	The current version of the request. The current version is 1.
ccTempToken ^String(36)	Credit card token
isVerified ^String(5)	This indicates whether this card was validated at the bank as an existing valid card or only registered on the payments provider side. Possible values: true – Card verified at the bank. false – Card not verified at the bank and only registered on the payments provider side. NOTE: A false response indicates that the card tokenization was declined by the bank and the card may not be usable for deposits.

Payment Options API

/getMerchantPaymentMethods

Definition

1
2
3
4
5
6
7
8
9
10
11
12
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1484759782197",
    "currencyCode": "GBP",
    "countryCode": "GB",
    "type": "DEPOSIT",
    "languageCode": "eng",
    "timeStamp": "20241105021120",
    "checksum": "6133d0fd12e90ff8de5d8ab5e52a8c23"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/getMerchantPaymentMethods.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
2
3
4
5
6
var response = safecharge.GetMerchantPaymentMethods(
    clientRequestId: "1484759782197",
    currencyCode: "GBP",
    countryCode: "GB",
    type: ApiConstants.PaymentMethodTypeDeposit,
    languageCode: "en");

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
{
    "sessionToken": "",
    "merchantId": "",
    "merchantSiteId": "",
    "clientRequestId": "",
    "internalRequestId": "",
    "paymentMethods":[
        {
            "paymentMethod": "apmgw_Instant_Open_Banking",
            "paymentMethodDisplayName":[
                {
                    "language": "eng",
                    "message": "Account Number"
                }
            ],
            "blockedCards":[
                "maestro", "solo", "amex"
            ],
            "isDirect": "false",
            "countries":[
                "BE"
            ],
            "currencies":[
                "USD"
            ],
            "fields":[
                {
                    "name": "ob_account_number",
                    "type": "text",
                    "caption":[
                        {
                            "language": "eng",
                            "message": "Account Number"
                        }
                    ]
                },
                {
                    "listValues":[
                        {
                            "code": "ngp-bbru",
                            "caption": "NextGenPSD2",
                            "mandatoryFields":[
                                "ob_iban"
                            ]
                        },
                        {
                            "code": "ngp-ingba",
                            "caption": "ING Austria",
                            "mandatoryFields":[
                                "personal_id"
                            ]
                        }
                    ]
                }
            ]
        }
    ],
    "type": "DEPOSIT",
    "status": "",
    "errCode": "",
    "reason": "",
    "version": ""
}

This method allows the merchant to view the names, IDs, and other information regarding the enabled payment methods and APMs, which may be filtered based on country, currency, and language.

It is used by the merchant mostly to display the available payment methods in its payment page.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/getMerchantPaymentMethods.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/getMerchantPaymentMethods.do

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
timeStamp ^String(14) ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, timeStamp, merchantSecretKey.
currencyCode ^String(20) ^Optional	The three-letter ISO currency code that the transaction is to be completed in.
countryCode ^String(2) ^Optional	The 2-letter ISO country code the transaction is to be completed in.
languageCode ^String(5) ^Optional	The language the transaction is to be completed in.
type ^String ^Optional	The type of the payment methods to be returned. Possible values: DEPOSIT, WITHDRAWAL. If no value sent, then default value is DEPOSIT.

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
internalRequestID ^Integer(20)	Nuvei’s internal unique request ID (used for reconciliation purposes).
paymentMethods ^Array	An array of payment methods and their attributes: paymentMethod (String, 50) paymentMethodDisplayName (Array) [language(String, 2), message(String, 400)] blockedCards (Array) – A list of card types that are not supported for the Merchant. isDirect (String, 5) countries [(String, 2)] currencies [(String, 3)] logoURL (String, 255) fields (Array) [  name (String, 45)  regex (String, 128)  type (String, 45)  validationMessage (Array) [language (String, 2), message (String, 400)]  caption (Array) [language (String, 2), message (String, 400)]  listValues (Array) [   code (String, 255)   caption (String)   mandatoryFields (Array) [(String, 45)]  ] ]
type ^String	The type of the payment methods to be returned. Possible values: DEPOSIT, WITHDRAWAL. If no value sent, then default value is DEPOSIT.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side then an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of your request. Current version is 1.
dualBrandConfig ^Array	The primary and secondary brand of a dual-branded card that are returned for a specific merchantSiteId.

User Payment Option Methods

Using our User Payment Option (UPO) methods, you can let Nuvei manage your user’s payment option. Nuvei securely stores and maintains your user’s payment option, saving you from the requirement to store sensitive payment information, and allowing you to use Nuvei payment option optimization.

We provide a set of methods and can create, edit, delete, and manage users and their payment options. Each user is identified by userTokenId provided and each of their payment options is identified by PaymentOptionId.

/createUser

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientRequestId": "100",
    "firstName": "John",
    "lastName": "Smith",
    "address": "some street",
    "state": "",
    "city": "",
    "zip": "",
    "countryCode": "GB",
    "phone": "",
    "locale": "en_UK",
    "email": "[email protected]",
    "dateOfBirth": "",
    "county": "",
    "timeStamp": "20240915143321",
    "checksum": "21bc2501b7857059862124a5d04c9ade"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/createUser.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": 45,
    "clientRequestId": "100",
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "version": "1",
    "userId": "259"
}

This method creates a new user. The user is stored according to their userTokenId as defined by the merchant for the user. Future calls relevant to this user require userTokenId to be sent in this request.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/createUser.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/createUser.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
countryCode ^String(2) ~Required	The 2-letter ISO country code of the user being registered.
email ^String(100) ~Required	The email address of the user being registered.
firstName ^String(30) ~Required	The first name of the user being registered.
lastName ^String(40) ~Required	The last name of the user being registered.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, userTokenId, clientRequestId, firstName, lastName, address, state, city, zip, countryCode, phone, locale, email, county, timeStamp, merchantSecretKey.
address ^String(50) ^Optional	The street address of the user being registered.
state ^String(3) ^Optional	The ISO state code of the user being registered.
city ^String(30) ^Optional	The city of the user being registered.
zip ^String(10) ^Optional	The ZIP code of the user being registered.
phone ^String(18) ^Optional	The phone number of the user being registered.
locale ^String(5) ^Optional	The user’s locale and default language (for example: en_UK).
dateOfBirth ^String(10) ^Optional	The date of birth of the user being registered.
county ^String(255) ^Optional	The county (district) of the user being registered.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(255)	The ID of the API request in the merchant system.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of the request. The current version is 1.
userId ^String(20)	Unique identifier of the user in Nuvei.

/updateUser

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
     "merchantId": "427583496191624621",
     "merchantSiteId": "142033",
     "clientRequestId": "101",
     "userTokenId": "230811147",
     "firstName": "John",
     "lastName": "Smith",
     "address": "some street",
     "state": "",
     "city": "London",
     "zip": "",
     "countryCode": "GB",
     "phone": "",
     "locale": "en_UK",
     "email": "[email protected]",
     "dateOfBirth": "",
     "county": "",
     "timeStamp": "20240915143421",
     "checksum": "b47f85bf3a06f5971b38b16e74b230a0"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/updateUser.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": 47,
    "clientRequestId": "101",
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "version": "1",
    "userId": "259"
}

This method updates a specific user’s details.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/updateUser.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/updateUser.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, userTokenId, clientRequestId, firstName, lastName, address, state, city, zip, countryCode, phone, locale, email, county, timeStamp, merchantSecretKey.
firstName ^String(30) ^Optional	The first name of the user being registered.
lastName ^String(40) ^Optional	The last name of the user being registered.
address ^String(50) ^Optional	The street address of the user being registered.
state ^String(3) ^Optional	The ISO state code of the user being registered.
city ^String(30) ^Optional	The city of the user being registered.
zip ^String(10) ^Optional	The ZIP code of the user being registered.
countryCode ^String(2) ^Optional	The 2-letter ISO country code of the user being registered.
phone ^String(18) ^Optional	The phone number of the user being registered.
locale ^String(5) ^Optional	The user’s locale and default language (for example: en_UK).
email ^String(100) ^Optional	The email address of the user being registered.
dateOfBirth ^String(10) ^Optional	The date of birth of the user being registered.
county ^String(255) ^Optional	The county (district) of the user being registered.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(255)	The ID of the API request in the merchant system.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of the request. The current version is 1.
userId ^String(20)	Unique identifier of the user in Nuvei.

/getUserDetails

Definition

1
2
3
4
5
6
7
8
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientRequestId": "101",
    "timeStamp": "20240915143921",
    "checksum": "03aab7ddc2d551ee672632c4a3c56902"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/getUserDetails.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "merchantSiteId": "39",
    "merchantsiteId": "",
    "internalRequestId": 49,
    "clientRequestId": "",
    "userDetails":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "some street",
        "phone": "",
        "zip": "",
        "city": "London",
        "countryCode": "GB",
        "state": "",
        "email": "[email protected]",
        "locale": "",
        "birthdate": "",
        "userTokenId": "230811147",
        "userId": "259",
        "county": ""
    },
    "status": " SUCCESS ",
    "errCode": 0,
    "reason": "",
    "version": "1"
}

This method returns the details of a specific existing user according to their userTokenId sent in the /createUser call.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/getUserDetails.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/getUserDetails.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
timeStamp ^String(15) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, userTokenId, clientRequestId, timeStamp, merchantSecretKey.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(255)	The ID of the API request in the merchant system.
userDetails ^Class	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) countryCode (String, 2) state (String) email (String, 100) locale String(5) birthdate (String, 10) userTokenId (String, 255) userId(String, 20) county (String, 255)
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of the request. The current version is 1.

/addUPOCreditCard

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientRequestId": "235",
    "ccCardNumber": "5101080963349948",
    "ccExpMonth": "01",
    "ccExpYear": "2020",
    "ccNameOnCard": "test name",
    "billingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "countryCode": "GB",
        "state": "",
        "email": "[email protected]",
        "county": ""
    },
    "externalTokenProvider": {
        "externalTokenProvider": "",
        "externalTokenData": "",
        "cardType": "",
        "isDecryptService": ""
    },
    "timeStamp": "20240915151435",
    "checksum": "2e9084f71d45487a417c0efbb9bdd58a"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/addUPOCreditCard.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": 52,
    "clientRequestId": "235",
    "status": " SUCCESS ",
    "errCode": 0,
    "reason": "",
    "version": "1",
    "userPaymentOptionId": "741",
    "cardType": "",
    "ccToken": "",
    "brand": "Visa",
    "uniqueCC": "aL+zlvNa84dvxQlmWz3COgkwqrE=",
    "bin": "411111",
    "last4Digits": "1111"
}

This method adds a credit card UPO for a specific user according to their userTokenId. Once a credit card UPO is added to the user’s list of UPOs, the credit card is displayed in the payment page.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/addUPOCreditCard.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/addUPOCreditCard.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
ccCardNumber ^String(20) ~Required	A valid credit card number. NOTE: Avoid sending a card that was expired, as it may cause a transaction to be declined.
ccExpMonth ^String(2) ~Required	2-digit value representing the expiration month.
ccExpYear ^String(2) ~Required	2-digit or 4-digit value representing the expiration year. When the value is two digits, the year is assumed to be 2000 + ccExpYear. The ccExpMonth and ccExpYear must be a future date. The year may not exceed 10 years in to the future.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, userTokenId, clientRequestId, ccCardNumber, ccExpMonth, ccExpYear, ccNameOnCard, billingAddress, timeStamp, merchantSecretKey.
externalSchemeDetails ^Class %%Conditional	Use this class if you want to process an MIT/recurring transaction that was initiated with another processor. Press here for more information. transactionId (String, 50) – Original transactionId for the initial payment as originated in the external system. Press here to view the structure of the parameter. brand (String, 20) – The card brand. Currently supported with the following values:  VISA  MASTERCARD  AMEX
ccNameOnCard ^String(2) ^Optional	The name of the credit card owner as it appears on the card.
billingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) countryCode (String, 2) – 2-letter ISO country code state (String, 3) – ISO state code. email (String, 100) county (String, 255)
externalTokenProvider ^Class ^Optional	The name of the external token provider (Apple Pay, Google Pay). externalTokenProvider (String, 45) isDecryptService (String, 1) – This indicates whether the payments gateway decrypted the external token data provided, which was required for processing. To work with external token providers, special configurations are required. For more information, please contact Nuvei’s Integration Team.
customData ^String(255) ^Optional	This parameter can be used to pass any type of information. If sent in request, then it is visible in Nuvei’s back office tool transaction reporting and is returned in response.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(255)	The ID of the API request in the merchant system.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of the request. The current version is 1.
userPaymentOptionId ^String(45)	Each time a consumer uses a payment method, Nuvei assigns a unique ID to it. The next time the consumer uses a payment method that Nuvei has previously assigned an ID to, the ID is returned as the value of this parameter. When a new payment method is used, the value of this parameter is left empty.
cardType ^String(50)	Value describing if the card used is a credit card or debit card.
ccToken ^String(116)	A hashed value of the credit card number.
brand ^String(50)	The brand of the credit card. Possible values: VISA AMEX MASTERCARD BANKCARD CUP DINERS DISCOVER JCB MAESTRO
uniqueCC ^String(28)	A unique identifying code for the credit card.
bin ^String(6)	The credit card’s bin number.
last4Digits ^String(4)	The last four digits of the credit card number.

/addUPOCreditCardByToken

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientRequestId": "110",
    "ccExpMonth": "12",
    "ccExpYear": "24",
    "ccNameOnCard": "John Smith",
    "ccToken": "ZQBxAEgAawBpAHEAcwBkACQAcAB2AGcAcQAlAFkAYQBcACwAdQBHAD0ATwB4AE8AKwA4AE8ALQA9ACMAZABsADgAeAArAEcAdwAvAGkAQAAzAA==",
    "brand": "Visa",
    "uniqueCC": "aL+zlvNa84dvxQlmWz3COgkwqrE=",
    "bin": "411111",
    "last4Digits": "1111",
    "billingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "countryCode": "GB",
        "state": "",
        "email": "[email protected]",
        "county": ""
    },
    "lastDepositUse": "",
    "lastDepositSuccess": "",
    "lastWithdrawalUse": "",
    "lastWithdrawalSuccess": "",
    "registrationDate": "",
    "expiryDate": "",
    "timeStamp": "20240915161438",
    "checksum": "f84c4e7e7d5aa1e83cd785100746bafc"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/addUPOCreditCardByToken.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": 69,
    "clientRequestId": "110",
    "userPaymentOptionId": "741",
    "status": "SUCCESS ",
    "errCode": 0,
    "reason": "",
    "version": "1"
}

This method adds a credit card token for a specific user according to their userTokenId. Tokens are strings of random digits, letters, and symbols characters that represent a single credit card number. When submitting a consumer’s full credit card number, Nuvei provides a token in the response that represents the consumer’s credit card. The next time the consumer completes a transaction, the merchant sends Nuvei the token instead of the consumer’s credit card information. The token value represents the consumer’s credit card number.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/addUPOCreditCardByToken.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/addUPOCreditCardByToken.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
ccExpMonth ^String(2) ~Required	2-digit value representing the expiration month.
ccExpYear ^String(4) ~Required	2-digit or 4-digit value representing the expiration year. When the value is two digits, the year is assumed to be 2000 + ccExpYear. The ccExpMonth and ccExpYear must be a future date. The year may not exceed 10 years in to the future.
ccNameOnCard ^String(70) ~Required	The name of the credit card owner as it appears on the card.
ccToken ^String(116) ~Required	A hashed value of the credit card number. Please avoid sending a card that was expired as it may cause a transaction to be declined.
brand ^String(50)	The brand of the credit card. Possible values: VISA AMEX MASTERCARD BANKCARD CUP DINERS DISCOVER JCB MAESTRO
uniqueCC ^String(28) ~Required	A unique identifying code for the credit card.
bin ^String(6) ~Required	The credit card’s bin number.
last4Digits ^String(4) ~Required	The last four digits of the credit card number.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, userTokenId, clientRequestId, ccExpMonth, ccExpYear, ccNameOnCard, ccToken, brand, uniqueCC, bin, last4Digits, billingAddress, timeStamp, merchantSecretKey.
billingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) countryCodeString, 2) – 2-letter ISO country code. state (String, 3) – ISO state code. email (String, 100) county (String, 255)
lastDepositUse ^String(14) ^Optional	The last deposit use.
lastDepositSuccess ^String(14) ^Optional	The last deposit success.
lastWithdrawalUse ^String(14) ^Optional	The last withdrawal use.
lastWithdrawalSuccess ^String(14) ^Optional	The last withdrawal success.
registrationDate ^String(14) ^Optional	The registration date.
expiryDate ^String(14) ^Optional	Indicates whether or not the UPO has expired. The default limit after a UPO has been used is 400 days. If no payment is made with the same details, the UPO expires.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(255)	The ID of the API request in the merchant system.
userPaymentOptionId ^Long(45)	On the first time a consumer uses a payment method, Nuvei assigns a unique ID to it. The next time the consumer uses a payment method that Nuvei has previously assigned an ID to, the ID is returned as the value of this parameter.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of the request. The current version is 1.

/addUPOCreditCardByTempToken

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientRequestId": "110",
    "ccTempToken": "ZQBxAEgAawBpAHEAcwBkACQAcAB2AGcAcQAlAFkAYQBcACwAdQBHAD0ATwB4AE8AKwA4AE8ALQA9ACMAZABsADgAeAArAEcAdwAvAGkAQAAzAA==",
    "billingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "[email protected]",
        "county": ""
    },
    "timeStamp": "20240915161438",
    "checksum": "f84c4e7e7d5aa1e83cd785100746bafc"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/addUPOCreditCardByTempToken.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "SessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": 69,
    "userTokenId": "",
    "clientRequestId": "110",
    "userPaymentOptionId": "741",
    "status": " SUCCESS ",
    "errCode": 0,
    "reason": "",
    "version": "1"
}

This method adds a temporary credit card token for a specific user according to their userTokenId. Tokens are strings of random digits, letters, and symbols characters that represent a single credit card number. When submitting a consumer’s full credit card number, Nuvei provides a temporary token in the response that represents the consumer’s credit card. The next time the consumer completes a transaction, the merchant sends Nuvei the temporary token instead of the consumer’s credit card information. The temporary token value represents the consumer’s credit card number.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/addUPOCreditCardByTempToken.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/addUPOCreditCardByTempToken.do

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
ccTempToken ^String(45) ~Required	A temporary card token. NOTE: Please avoid sending a card that was expired as it may cause a transaction to be declined.
timeStamp ^String(15) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, timeStamp, merchantSecretKey.
billingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) cell (String, 18) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code. state (String, 3) – ISO state code. email (String, 100) county (String, 255)

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(255)	The ID of the API request in the merchant system.
userPaymentOptionId ^Long(45)	The first time a consumer uses a payment method, Nuvei assigns a unique ID to it. The next time the consumer uses a payment method that Nuvei has previously assigned an ID to, the ID is returned as the value of this parameter.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of the request. The current version is 1.

/addUPOAPM

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientRequestId": "43",
    "paymentMethodName": "apmgw_expresscheckout",
    "apmData": {
        "email": "[email protected]"
    },
    "billingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "22 Main Street",
        "phone": "6175551414",
        "zip": "02460",
        "city": "Boston",
        "country": "US",
        "state": "MA",
        "email": "[email protected]",
        "county": "Suffolk"
    },
    "timeStamp": "20240915153043",
    "checksum": "fb4641d3abe02bc309bd746f77bbf0d3ab9fa24c405f1027e4cbce888405e053"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/addUPOAPM.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": 56,
    "clientRequestId": "43",
    "userPaymentOptionId": "742",
    "status": " SUCCESS ",
    "errCode": 0,
    "version": "1"
}

This method adds an APM UPO account for specific users according to their userTokenId. Once an APM UPO is added to a consumer’s UPO list, the APM is displayed in the user’s available payment options on the payment page.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/addUPOAPM.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/addUPOAPM.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
paymentMethodName ^String(50) ~Required	Nuvei’s unique name of the payment method (for example apmgw_Neteller). For a list of possible values, see the “API Name” column in the table in APM Payments.
apmData ^Class ~Required	List of name-value pairs that contain the parameters of the user payment option. The same parameters used in the “Payment Input Fields” column should be used in this class. For more information, refer to APM Payments.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, userTokenId, clientRequestId, paymentMethodName, apmData.xxx (for apmData.xxx, you need to concatenate all the fields in the same order they were sent in the apmData class), billingAddress, timeStamp, merchantSecretKey.
billingAddress ^Class ^Optional	country (String, 2) – 2-letter ISO country code. NOTE: For certain APMs, countryCode is used instead. email (String, 100) firstName (String, 30) lastName (String, 40) address (String, 50) cell (String, 18) phone (String, 18) zip (String, 10) city (String, 30) state (String, 3) – ISO state code. county (String, 255)

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(255)	The ID of the API request in the merchant system.
userPaymentOptionId ^String(45)	The first time a consumer uses a payment method, Nuvei assigns a unique ID to it and return it. The next time the consumer uses a payment method that Nuvei has previously assigned an ID to, the ID is returned as the value of this parameter.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of the request. The current version is 1.

/editUPOCC

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientRequestId": "4556",
    "userPaymentOptionId": "741",
    "ccExpMonth": "12",
    "ccExpYear": "24",
    "ccNameOnCard": "John Smith",
    "billingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "countryCode": "GB",
        "state": "",
        "email": "[email protected]",
        "county": ""
    },
    "timeStamp": "20240915155818",
    "checksum": "5d99ee468cd33c0b87d0dc2fc7585376"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/editUPOCC.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": 62,
    "clientRequestId": "4556",
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "version": "1"
}

This method enables the editing of the modifiable credit card details for a specific user. The card number cannot be edited. To edit a credit card number, the UPO must be deleted and then added again.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/editUPOCC.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/editUPOCC.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
userPaymentOptionId ^String(45) ~Required	The unique user payment option ID as assigned by Nuvei.
ccExpMonth ^String(2) ~Required	2-digit value representing the expiration month.
ccExpYear ^String(4) ~Required	2-digit or 4-digit value representing the expiration year. When the value is two digits, the year is assumed to be 2000 + ccExpYear; ccExpMonth and ccExpYear must be a date that is after the current date. The year may not exceed 10 years in to the future.
ccNameOnCard ^String(70) ~Required	The name of the credit card owner as it appears on the card.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, userTokenId, clientRequestId, userPaymentOptionId, ccExpMonth, ccExpYear, ccNameOnCard, billingAddress, timeStamp, merchantSecretKey.
billingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) cell (String, 18) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code. state (String, 3) – ISO state code. email (String, 100) county (String, 255)

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(255)	The ID of the API request in the merchant system.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of the request. The current version is 1.

/editUPOAPM

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientRequestId": "43",
    "userPaymentOptionId": "743",
    "apmData": {
        "account_id": "[email protected]"
    },
    "billingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "countryCode": "GB",
        "state": "",
        "email": "[email protected]",
        "county": ""
    },
    "timeStamp": "20240915160424",
    "checksum": "71b589416aba502be1521e1ce6b94726"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/editUPOAPM.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": 65,
    "clientRequestId": "43",
    "status": "SUCCESS",
    "errCode": 0,
    "reason" : "",
    "version": "1"
}

This method enables the editing of the APM UPO account details for a specific user according to their userTokenId.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/editUPOAPM.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/editUPOAPM.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
userPaymentOptionId ^String(45) ~Required	The unique user payment option ID as assigned by Nuvei.
apmData ^Class ~Required	List of name-value pairs that contain the parameters of the user payment option. The same parameters used in the “Payment Input Fields” column should be used in this class. For more information, refer to APM Payments.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, userTokenId, clientRequestId, userPaymentOptionId, apmData.XXX (for apmData.XXX need to list all depend in the current APM account fields, in the exact same order they were sent in apmData class), billingAddress, timeStamp, merchantSecretKey.
billingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) cell (String, 18) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code. state (String, 3) – ISO state code. email (String, 100) county (String, 255)

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(255)	The ID of the API request in the merchant system.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of the request. The current version is 1.

/deleteUPO

Definition

1
2
3
4
5
6
7
8
9
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientRequestId": "108",
    "userPaymentOptionId": "742",
    "timeStamp": "20240915151243",
    "checksum": "c2f1ccf85719ba0a69022c7753e9ba9b"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/deleteUPO.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": 60,
    "clientRequestId": "108",
    "status": "SUCCESS",
    "errCode": 0,
    "reason" : "",
    "version": "1"
}

This method deletes a UPO for a specific user from their list of registered UPOs. Once a UPO is deleted, it is no longer displayed on the user’s payment page. A deleted UPO may be added through any of the addUPO calls.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/deleteUPO.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/deleteUPO.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
userPaymentOptionId ^String(45) ~Required	The unique user payment option ID as assigned by Nuvei.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, userTokenId, clientRequestId, userPaymentOptionId, timeStamp, merchantSecretKey.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(255)	The ID of the API request in the merchant system.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of the request. The current version is 1.

/getUserUPOs

Definition

1
2
3
4
5
6
7
8
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientRequestId": "107",
    "timeStamp": "20240915151231",
    "checksum": "aa7566ab686602fe38a62d40d796bb01"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/getUserUPOs.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": 58,
    "clientRequestId": "107",
    "status": "SUCCESS",
    "errCode": 0,
    "reason" : "",
    "version": "1",
    "paymentMethods": [ {
        "userPaymentOptionId": "741",
        "cardSource": "NetworkToken",
        "paymentMethodName": "cc_card",
        "upoName": "(1111)",
        "upoRegistrationDate": "",
        "upoRegistrationTime": "",
        "upoStatus": "enabled",
        "expiryDate": "",
        "billingAddress":{
            "firstName": "John",
            "lastName": "Smith",
            "phone": "972502457558",
            "address": "some street",
            "zip": "",
            "city": "some city",
            "countryCode": "GB",
            "state": "",
            "email": "[email protected]",
            "county": ""
        },
        "upoData": {
            "cardType": "",
            "ccCardNumber": "4****1111",
            "ccCardNumberHash": "68bfb396f35af3876fc509665b3dc23a0930aab1",
            "ccExpMonth": "12",
            "ccExpYear": "24",
            "ccNameOnCard": "John Smith",
            "ccToken" :"",
            "brand": "Visa",
            "uniqueCC": "aL+zlvNa84dvxQlmWz3COgkwqrE=",
            "bin": "411111",
            "last4Digits": ""
            }
        },
        {
        "userPaymentOptionId": "742",
        "paymentMethodName": "apmgw_expresscheckout",
        "upoName": "[email protected]",
        "upoRegistrationDate": "",
        "upoRegistrationTime": "",
        "upoStatus ": "suspended",
        "expiryDate": "",
        "billingAddress":{
            "firstName": "John",
            "lastName": "Smith",
            "address": "some street",
            "phone": "972502457558",
            "zip": "",
            "city": "some city",
            "country": "GB",
            "state": "",
            "email": "[email protected]",
            "county": ""
        },
        "upoData": {
            "account_id": "[email protected]"
            }
        }]
}

This method returns the registered payment options for a specific user according to their userTokenId.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/getUserUPOs.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/getUserUPOs.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(255) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, userTokenId, clientRequestId, timeStamp, merchantSecretKey.
isDepositSuccessful ^String(5) ^Optional	When true, it triggers REST to return all the UPOs related to the specific userTokenId created for financial transactions with depositSuccess: “true”.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(255)	The ID of the API request in the merchant system.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of the request. The current version is 1.
paymentMethods ^Array	An array of payment methods and their attributes: userPaymentOptionId (String, 45) – The unique user payment option ID as assigned by Nuvei. cardSource (String, 50) – Indicates whether the details of the UPO returned belong to a network token.  Possible value: NetworkToken paymentMethodName (String, 50) – The unique name of the payment method (such as apmgw_Neteller).  For a list of possible values, see the “API Name” column in the tables in APM Payments. upoName (String, 255) – A name that helps identify the account.  For cards, it usually includes the card number.  For APMs it is usually one of the APM account identifier parameters, such as account_id.  In both cases, the field chosen to be used as upoName can be set per configuration.  NOTE: During UPO creation, upoName is set and it cannot be updated or changed later on. upoRegistrationDate (String, 8) – The date that the UPO was registered in the following format: YYYYMMDD. upoRegistrationTime (String, 8) – The time that the UPO was registered in the following format: HHMMSS. upoStatus (String, 20) – The status of the UPO for the user.  Possible values: suspended and enabled. expiryDate (String, 8) – Indicates whether or not the UPO has expired.  The default limit after a UPO has been used is 400 days.  If no payment is made with the same details, the UPO expires. billingAddress (Class)  firstName (String, 30)  lastName (String, 40)  address (String, 50)  cell (String, 18)  phone (String, 18)  zip (String, 10)  city (String, 30)  country (String, 2) – 2-letter ISO country code.  state (String, 3) – ISO state code.  email (String, 100)  county (String, 255) upoData (Class) – Contains the UPO details of the user.  Only the relevant parameters for a specific UPO are returned when they are stored in Nuvei’s system.  For APMs, press here for more information.  For cards, press here to see the parameters that can be returned in the upoData class.
issuerCountry ^String(2)	The ISO currency code of the card issuer’s country.

/suspendUPO

Definition

1
2
3
4
5
6
7
8
9
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientRequestId": "109",
    "userPaymentOptionId": "743",
    "timeStamp": "20240915160842",
    "checksum": "a7b8817a0b761c11c756512366305595"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/suspendUPO.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": 67,
    "clientRequestId": "109",
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "version": "1"
}

This method suspends a given payment option for a specific user. Once a UPO is suspended, the user can no longer process payments through that UPO. If the suspended payment method is a card, the user cannot add it as UPO again as long as it is suspended. The merchant can reactivate suspended UPOs through the enableUPO method. The request should be sent to the following URL:

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/suspendUPO.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/suspendUPO.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
userPaymentOptionId ^String(45) ~Required	The unique user payment option ID as assigned by Nuvei.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, userTokenId, clientRequestId, userPaymentOptionId, timeStamp, merchantSecretKey.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(255)	The ID of the API request in the merchant system.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of the request. The current version is 1.

/enableUPO

Definition

1
2
3
4
5
6
7
8
9
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientRequestId": "135",
    "userPaymentOptionId": "743",
    "timeStamp": "20240915205412",
    "checksum": " 1c5343ba85154d4416855737d4e6888a"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/enableUPO.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": 67,
    "clientRequestId": "109",
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "version": "1"
}

This method enables a suspended payment option for a specific user, which enables the user to process transactions through that UPO. The request should be sent to the following URL:

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/enableUPO.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/enableUPO.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
userPaymentOptionId ^String(45) ~Required	The unique user payment option ID as assigned by Nuvei.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, userTokenId, clientRequestId, userPaymentOptionId, timeStamp, merchantSecretKey.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(255)	The ID of the API request in the merchant system.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of the request. The current version is 1.

Advanced APM Integration

Advanced APM Integration Overview

This set of API methods provides advanced functionality for integration with certain APMs.

/addBankAccount

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
    "sessionToken": "4bbaa973-ab1a-47b8-ad79-92c42beba19d",
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "clientUniqueId": "695701003",
    "clientRequestId": "TXZZXKX5U",
    "userId": "6303323",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod": "apmgw_VIP_Preferred"
        }
    },
    "bankAccount":{
        "bankName": "American Bank",
        "accountNumber": "9920035637",
        "routingNumber": "103112976"
    },
    "userDetails":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "22 Main Street",
        "phone": "6175556309",
        "zip": "02460",
        "city": "Boston",
        "country": "US",
        "state": "MA",
        "email": "[email protected]",
        "county": "Suffolk",
        "language": "en",
        "dateOfBirth": "1972-06-02",
        "identification": "987456982"
    },
    "deviceDetails":{
        "deviceType": "DESKTOP",
        "deviceName": "iPhone 5s",
        "deviceOS": "iOS 10.2",
        "browser": "safari",
        "ipAddress": "192.168.2.38"
    }
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "bankAccount":{
        "routingNumber": "103112976",
        "bankName": "ARVEST BANK",
        "accountNumber": "9920035637"
    },
    "reason": "",
    "merchantId": "2502136204546424962",
    "clientUniqueId": "695701003",
    "errCode":0,
    "clientRequestId": "TXZZXKX5U",
    "sessionToken": "4bbaa973-ab1a-47b8-ad79-92c42beba19d",
    "internalRequestId":17483621,
    "userId": "6303323",
    "version": "1.0",
    "status": "SUCCESS",
    "merchantSiteId": "126006"
}

This method allows you to add a bank account to an account on behalf of the customer.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/addBankAccount.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/addBankAccount.do

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(45) ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
paymentOption.alternativePaymentMethod ^Class ~Required	This class represents the details on the payment method. paymentMethod (String, 50) – Specifies the payment method name of the payment option to be charged. See: APM Input Fields and APIs.
userId ^String(255) ~Required	The ID of the customer in the merchant system.
bankAccount ^Class ~Required	accountNumber (String, 30, REQUIRED) – The bank account number. routingNumber (String, 30, REQUIRED) – The bank account routing number. bankName (String, 30) – The name of the bank.
deviceDetails ^Class ^Optional	deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255) ipAddress (String, 15, CONDITIONAL) – The IP address of the user device. REQUIRED for VIP Preferred.
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code. state (String, 3) – ISO state code (for customers based in the US, Canada, and India only). email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15, CONDITIONAL) – This represents the customer’s identification number in their respective country; for example, the social security number (SSN) of United States citizens. REQUIRED for VIP Preferred.

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(45)	The unique transaction ID in the merchant system.
clientRequestId ^String(255)	The unique ID of the API request in the merchant system.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
userId ^String(255)	The ID of the customer in the merchant system.
status ^String(20)	The cashier status of merchant request. Possible values: SUCCESS, ERROR
errCode ^Integer(11)	If an error occurred on the request side then an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
paymentMethodErrorCode ^Integer(11)	If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason ^String(400)	If an error occurred on the APM side, an error reason is returned in this parameter.
bankAccount ^Class	accountNumber (String, 30) – The bank account number. routingNumber (String, 30) – The bank account routing number. bankName (String, 30) – The name of the bank.
version ^String(10)	The current version of the request. The current version is 1.

/enrollAccount

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
    "sessionToken": "69234cef-8d45-4afc-b44b-18e99f2e8633",
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "clientUniqueId": "695701003",
    "clientRequestId": "KFK1BUZJ4",
    "userId": "E677539C0C54",
    "enrollmentAction": "AccountCapture",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod": "apmgw_PlayPlus"
        }
    },
    "userDetails":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "22 Main Street",
        "phone": "6175556309",
        "zip": "02460",
        "city": "Boston",
        "country": "US",
        "state": "MA",
        "email": "[email protected]",
        "county": "Suffolk",
        "language": "en",
        "dateOfBirth": "1972-06-02",
        "identification": "987456982"
    },
    "urlDetails":{
        "notificationUrl": "https:///merchant.url/interactionsCompleted"
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
{
    "sessionToken": "26544891-c629-43b0-ab61-083ae19ee755",
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "clientUniqueId": "7HY2XQWMENHA",
    "clientRequestId": "A0V7QVWLA",
    "userId": "MD9XJRZZTP6M",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod": "apmgw_PlayPlus"
        }
    },
    "enrollmentAction": "NewRequest",
    "enrollmentType": "Standard",
    "governmentIds":[
        {
            "idType": "DriversLicense",
            "issuingGovernment":{
                "country": "US",
                "isState": "True",
                "isCountry": "True",
                "state": "GA"
            },
            "number": "112223333"
        },
        {
            "idType": "SSN",
            "issuingGovernment":{
                "country": "US",
                "isState": "True",
                "isCountry": "True",
                "state": "GA"
            },
            "number": "112223333"
        }
    ],
    "phoneNumbers":[
        {
            "number": "3126122528",
            "type": "Home"
        },
        {
            "number": "3126122548",
            "type": "Work"
        }
    ],
    "billingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "email": "[email protected]",
        "phone": "3459873345",
        "address": "222333 Peachtree Place",
        "city": "Atlanta",
        "country": "US",
        "state": "GA",
        "zip": "30318",
        "cell": "359881526527",
        "county": null,
        "homePhone": "35943277",
        "workPhone": "359237"
    },
    "userDetails":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "222333 Peachtree Place",
        "phone": "3459873345",
        "zip": "30318",
        "city": "Atlanta",
        "country": "US",
        "state": "GA",
        "email": "[email protected]",
        "dateOfBirth": "1975-02-02",
        "identification": "112223333"
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
{
    "sessionToken": "700faa58-671a-4348-acd6-5bb047e81725",
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "clientUniqueId": "PRKQQ4YFG3YU",
    "clientRequestId": "QSTUVZCT0",
    "userId": "7T31TNHGLTE7",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod": "apmgw_PlayPlus"
        }
    },
    "enrollmentAction": "KbaResponse",
    "enrollmentType": "Standard",
    "previousIdentityVerificationRequestId": "148838",
    "previousIdentityVerifierRequestId": "3549880445",
    "kbaResponses":[
        {
            "key": "current.county.b",
            "value": "FULTON"
        },
        {
            "key": "property.size",
            "value": "Over 2,500"
        },
        {
            "key": "person.known.fic",
            "value": "None of the above"
        },
        {
            "key": "city.of.residence",
            "value": "ATLANTA"
        }
    ],
    "governmentIds":[
        {
            "idType": "SSN",
            "issuingGovernment":{
                "country": "US",
                "isState": "True",
                "isCountry": "True",
                "state": "GA"
            },
            "number": "112223333"
        }
    ],
    "phoneNumbers":[
        {
            "number": "3126122528",
            "type": "Work"
        }
    ],
    "billingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "email": "[email protected]",
        "phone": "359888526527",
        "address": "222333 Peachtree Place",
        "city": "Atlanta",
        "country": "US",
        "state": "GA",
        "zip": "30318",
        "cell": "359881526527",
        "county":null,
        "addressMatch": "N",
        "addressLine2": "Billing Address Line 2",
        "addressLine3": "Billing Address Line 3",
        "homePhone": "35943277",
        "workPhone": "359237"
    },
    "userDetails":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "222333 Peachtree Place",
        "phone": "3018572175",
        "zip": "30318",
        "city": "Atlanta",
        "country": "US",
        "state": "GA",
        "email": "[email protected]",
        "county": "UCounty",
        "language": "en",
        "dateOfBirth": "1975-02-22",
        "identification": "112223333"
    }
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "reason": "",
    "redirectUrl": "https://cdn-int.safecharge.com/safecharge_resources/v1/get_to_post/index.html?eyJhbGciOiJSUzI1NiJ9.eyJ1cmwiOiJodHRwczovL2NlYXBzcGFuZXguc2xwdWF0LmNvbS9Ib3N0ZWRGdW5kaW5nIiwiTWVtYmVyTnVtYmVyIjoiRTY3NzUzOUMwQzU0IiwiRmlyc3ROYW1lIjoiSkFWQVkiLCJMYXN0TmFtZSI6Ik1PU1FVRURBIiwiUGhvbmVOdW1iZXIiOiIzMDE4NTcyMTc1IiwiRW1haWwiOiJzZ2t1eS50eml6dEBlYWJlcS5icSIsIkFkZHJlc3MiOiIyMiBBdXRvbWF0aW9uIFN0ci4iLCJDaXR5IjoiQ2hpcHJvdmNpIiwiU3RhdGUiOiJNRCIsIkNvdW50cnkiOiJVUyIsIlBvc3RhbENvZGUiOiIzMjQyMSIsIklkZW50aXR5VG9rZW4iOiJXQUEwQUZrQWRRQnhBRGdBTVFCVUFFa0FlQUJuQURjQVZBQXpBRVFBYUFCaUFETUFid0JuQUVVQU1nQXZBSFFBU2dCRUFHVUFNQUJtQUhjQWJ3QllBR29BS3dCRUFEZ0FSZ0JYQUdvQVZBQm5BRGdBZGdCRUFIZ0FWQUJ6QUVzQVNRQTNBR3dBTlFCSUFDc0FUZ0EwQUhVQVRnQXlBRklBVFFCS0FHNEFjZ0JIQUhvQVVRQjZBSEVBVWdCUEFETUFNd0JqQURrQVV3Qm9BSEFBYlFCd0FESUFiZ0F4QUdnQVVRQm1BRFFBVWdCbUFERUFTUUJwQUZVQU5BQXlBRWNBTWdBNEFESUFTZ0JrQUM4QVdBQk1BRGtBU1FBeEFFZ0Fjd0E1QUU4QVJnQnFBQ3NBWndCVEFDc0FTQUJzQUVNQVZnQTJBRzBBTndCdEFGVUFNZ0F4QUhnQVdRQldBRkFBUndCRkFHUUFTZ0JSQUhFQVFRQlNBR3NBZHdCd0FHVUFNUUIxQUZVQVNBQndBR0lBYndCWEFFc0FkZ0J6QURjQVRRQktBRkVBV0FBNUFHWUFXUUJHQUZNQWJnQnJBQ3NBWWdCb0FGa0FXZ0JKQUZjQWJ3QlVBR3dBZWdBM0FFRUFTd0JTQURJQVNRQllBRllBT0FCR0FDOEFMd0J1QUM4QU13QktBRXNBYUFCekFHRUFaZ0JMQUZvQU5BQm5BSElBTkFCb0FDOEFjQUJvQUdRQVJnQlJBQzhBU0FBd0FITUFWUUJvQUZVQU1nQk9BR2dBWkFBeUFHWUFjUUF3QURjQVNRQTVBRFlBU3dCdkFHd0FOd0JwQUZrQWJBQnVBQzhBYkFCVkFHc0FNd0FyQUdrQWJ3QkNBRGdBYndCTkFGSUFaZ0JUQUdNQU5BQkhBR3dBY0FCb0FFVUFUUUJ6QUZrQVdRQktBRXdBUXdBMUFFRUFlUUF5QUVJQWRBQk1BRUVBTVFCbkFEMEFQUUE9IiwiTWVyY2hhbnRJRCI6IlNhZmVDaGFyZ2VNZXJjaCIsIk1lcmNoYW50QXBwbGljYXRpb24iOiJTQ2gwMSIsIk1lcmNoYW50VHJhbnNhY3Rpb25JRCI6IjQ4OTExIiwiTWVyY2hhbnROYW1lIjoiU2lnaHRsaW5lIFBheW1lbnRzIiwiRE9CIjoiMTk5Mi0wNi0wMiIsIklkVHlwZSI6IjIiLCJJZFZhbHVlIjoiMDUzOTQyNjg0In0.kwFY4mUPP-Xjq29yKCrhVoAmWOsDun0Ryukp-267PEDA52pADABcerd6ifl6JfcGK2ahMnNlOyu8vS-7BVSD8-z3qIvUY446M6K4GZxuCjRPREfx9c3oJwhqpN0vU8YLfiIrf8sHKPKlapxDg0vunjppQRSijqk0hMokRoH6_5Pstm6e7yhH3SFVi_B7Qe569Ny-P1nbC3Ult2h-AbsXAanlKfO1IPGEEbtUaPZatViAmd7TIjYigB02NkOtlAr9l_kpjE0fv2CSMtVGHvy1PkzaMaYO7KCdCagV_jB56dgPoYJYwuVMv3C7FMc1OWaA_cakeSL9LHH795mP3wuXuA",
    "merchantId": "2502136204546424962",
    "clientUniqueId": "695701003",
    "errCode":0,
    "clientRequestId": "KFK1BUZJ4",
    "sessionToken": "69234cef-8d45-4afc-b44b-18e99f2e8633",
    "internalRequestId":17455361,
    "userId": "E677539C0C54",
    "version": "1.0",
    "status": "SUCCESS",
    "merchantSiteId": "126006"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "reason": "",
    "identityVerificationRequestId": "0",
    "authCode": "70419e03d7844a9c8ee5fdbad9da8ecb",
    "clientRequestId": "A0V7QVWLA",
    "internalRequestId":17762171,
    "userId": "MD9XJRZZTP6M",
    "version": "1.0",
    "merchantSiteId": "126006",
    "identityVerifierRequestId": "",
    "merchantId": "2502136204546424962",
    "clientUniqueId": "7HY2XQWMENHA",
    "errCode":0,
    "sessionToken": "26544891-c629-43b0-ab61-083ae19ee755",
    "externalTransactionId": "70419e03d7844a9c8ee5fdbad9da8ecb",
    "status": "SUCCESS"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "reason": "",
    "identityVerificationRequestId": "0",
    "authCode": "6f4e88d31968455fb754f6063bfe5865",
    "clientRequestId": "QSTUVZCT0",
    "internalRequestId": 17762541,
    "userId": "7T31TNHGLTE7",
    "version": "1.0",
    "merchantSiteId": "126006",
    "identityVerifierRequestId": "",
    "merchantId": "2502136204546424962",
    "clientUniqueId": "PRKQQ4YFG3YU",
    "errCode": 0,
    "sessionToken": "700faa58-671a-4348-acd6-5bb047e81725",
    "externalTransactionId": "6f4e88d31968455fb754f6063bfe5865",
    "status": "SUCCESS"
}

This method allows you to send or redirect the customer’s bank account details in order to enroll them into a new APM account.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/enrollAccount.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/enrollAccount.do

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(45) ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
paymentOption.alternativePaymentMethod ^Class ~Required	This class represents the details on the payment method. paymentMethod (String, 50) – Specifies the payment method name of the payment option to be charged. See: APM Input Fields and APIs.
userId ^String(255) ~Required	The ID of the customer in the merchant system. This is used as AccountIdentifier in some APMs such as Play+. Use the same value in /getDocumentUrl and /enrollAccount calls.
enrollmentAction ^String(20) %%Conditional	When generating a redirectUrl, supported value is AccountCapture. When generating a direct API request, supported values are NewRequest and KbaResponse.
enrollmentType ^String(20) %%Conditional	When generating a direct API request, supported value is Standard.
deviceDetails ^Class %%Conditional	deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255) ipAddress (String, 15, REQUIRED for certain APMs)
userDetails ^Class %%Conditional	This class is required when generating a direct API request. firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code. state (String, 3) – ISO state code (for customers based in the US, Canada, and India only). email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This represents the customer’s identification number in their respective country; for example, the social security number (SSN) of United States citizens.
billingAddress ^Class %%Conditional	The billing address related to a user payment option. This class is REQUIRED for certain APMs when generating a direct API request. firstName (String, 30) lastName (String, 40) address (String, 50) addressLine2 (String, 50) addressLine3 (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO state code. email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. cell (String, 18) homePhone (String, 18) workPhone (String, 18) addressMatch (String, 1)
governmentIds[] ^Class %%Conditional	This class is REQUIRED for certain APMs when generating a direct API request. idType (String, 20) – Supported values are: SSN, DriversLicence, Passport, MilitaryId number (String, 20) – The number of the ID document. issuingGovernment.country (String, 2) – 2-letter ISO country code. issuingGovernment.state (String, 3) – ISO state code. issuingGovernment.isCountry (String) – Specifies if this is a Country-issued ID. issuingGovernment.isState (String) – Specifies if this is a State-issued ID.
phoneNumbers[] ^Class %%Conditional	This class is REQUIRED for certain APMs when generating a direct API request. number (String, 18) type (String, 10) – Supported values are: Unknown, Home, Work, Cell
previousIdentityVerificationRequestId ^String(20) %%Conditional	This value is required for KbaResponse requests.
previousIdentityVerifierRequestId ^String(32) %%Conditional	This value is required for KbaResponse requests.
kbaResponses[] ^Class %%Conditional	This class is REQUIRED for KbaResponse requests. key (String, 50) value (String, 50)
bankAccount ^Class %%Conditional	This class is REQUIRED for certain APMs when generating a direct API request. bankName (String, 30) accountNumber (String, 30) – The bank account number. routingNumber (String, 30) – The bank account routing number.
documentDetails ^Class %%Conditional	This class is REQUIRED for certain APMs when generating a direct API request. documentNumber (String, 30, REQUIRED) – The document number of the Identification Document. type (String, 2, REQUIRED) – The type of the Identification Document. Supported Values: DL – Driving License ST – State ID MI – Military ID PP – US Passport ID TI – Tribal ID validTo (String, 4, REQUIRED) – The expiration date of the Identification Document. Expected format: MMDD issuingState (String, 4, CONDITIONAL) – The 2-letter code of the State issuing the Identification Document. REQUIRED for Driving License and State ID.
urlDetails ^Class ^Optional	notificationUrl (String, 1000) – The URL to which DMNs are sent once the customer completes the registration form. Relevant only when generating a redirectUrl.

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(45)	The unique transaction ID in the merchant system. For a direct API request, use the same value in /getDocumentUrl and /enrollAccount calls.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
userId ^String(255)	The ID of the customer in the merchant system.
redirectURL ^String	When generating a redirectUrl, the URL to which you must redirect the customer to complete the enrollment or funding process.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side then an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
paymentMethodErrorCode ^Integer(11)	If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason ^String(400)	If an error occurred on the APM side, an error reason is returned in this parameter.
version ^String(10)	The version of the API. The current version is 1.
accountNumber ^String(30)	The ID of the APM account. This displays CARDNO in some APMs such as VIP Preferred.
accountBalance ^String(12)	The available amount in the user’s APM account in USD. This displays AVAIL in some APMs such as VIP Preferred.
accountLimit ^String(12)	The customer’s account limit as set in the APM. This displays LIMIT in some APMs such as VIP Preferred.
currency ^String(3)	The ISO currency code. Currently, only USD is supported.
externalTransactionId ^String(128)	The transaction ID of the transaction in the external system.
authCode ^String(128)	The authorization code of the transaction.
identityVerificationRequestId ^String(20)	Use this value as an input for KbaResponse request.
IdentityVerifierRequestId ^String(32)	Use this value as an input for KbaResponse request.
verificationQuestions ^Array	Presents the questions to the end user and collects their answers. The answers are used as input for the KbaResponse request. prompt (String, 100) questionId (String, 100) questionType (String, 100) answers (Array) [key String(100), value String(100)]

/fundAccount

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
    "sessionToken": "72c9dab5-00b0-4d1b-8b24-a9b5e0a1a795",
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "clientUniqueId": "695701003",
    "clientRequestId": "O3V96K7EV",
    "userId": "E677539C0C54",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod": "apmgw_PlayPlus"
        }
    },
    "userDetails":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "22 Main Street",
        "phone": "6175556309",
        "zip": "02460",
        "city": "Boston",
        "country": "US",
        "state": "MA",
        "email": "[email protected]",
        "county": "Suffolk",
        "language": "en",
        "dateOfBirth": "1972-06-02",
        "identification": "987456982"
    },
    "urlDetails":{
        "notificationUrl": "https:///merchant.url/interactionsCompleted"
    }
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "reason": "",
    "redirectUrl": "https://cdn-int.safecharge.com/safecharge_resources/v1/get_to_post/index.html?eyJhbGciOiJSUzI1NiJ9.eyJ1cmwiOiJodHRwczovL2NlYXBzcGFuZXguc2xwdWF0LmNvbS9Ib3N0ZWRGdW5kaW5nIiwiTWVtYmVyTnVtYmVyIjoiRTY3NzUzOUMwQzU0IiwiRmlyc3ROYW1lIjoiSkFWQVkiLCJMYXN0TmFtZSI6Ik1PU1FVRURBIiwiUGhvbmVOdW1iZXIiOiIzMDE4NTcyMTc1IiwiRW1haWwiOiJzZ2t1eS50eml6dEBlYWJlcS5icSIsIkFkZHJlc3MiOiIyMiBBdXRvbWF0aW9uIFN0ci4iLCJDaXR5IjoiQ2hpcHJvdmNpIiwiU3RhdGUiOiJNRCIsIkNvdW50cnkiOiJVUyIsIlBvc3RhbENvZGUiOiIzMjQyMSIsIklkZW50aXR5VG9rZW4iOiJjUUJrQUhjQVdBQnVBRTRBT1FCUkFFOEFRZ0JUQUcwQVJBQTFBR01BU2dCaUFHWUFaQUJsQUZFQVJnQkRBR29BWkFCV0FFb0FPQUJVQUZVQU53Qk9BRU1BTlFCWEFFc0FNd0ExQUhVQU1BQnNBRGdBU3dCakFHTUFaQUJxQUhVQVdBQk9BRVFBV2dCU0FFd0FVZ0JrQURZQWJnQnBBRU1BVVFCTkFIY0FTZ0JNQUZRQWJnQlBBRFVBYWdBMkFIb0FSQUJLQUhnQVVnQmxBRk1BTndCc0FIUUFNQUJvQUdzQWNRQTBBRzBBU3dBM0FIa0FWQUEyQUVFQVpBQlZBREFBU0FCdEFGb0FUQUJMQUVnQVRnQlBBRThBVEFBd0FHWUFMd0JpQUd3QU1BQlJBRElBU1FCQ0FGa0FVUUJuQUZVQVpBQmhBRFVBYkFCMEFHTUFUUUJJQUdRQU1nQlpBSFFBVEFCMEFHb0Fjd0JsQUZvQVl3QXdBSG9BV2dCNUFEUUFhUUJLQUNzQVdnQnZBR2dBZUFBMkFHOEFiZ0I2QUVRQVVRQk1BRGdBVlFCcEFISUFjZ0JUQUdNQWNRQTNBRUlBVGdCREFGQUFUZ0JSQUVZQWN3QkNBRElBTUFCWkFIZ0FVZ0JWQUc0QWNBQnZBRU1BUVFCMEFFRUFXZ0FyQUM4QVZ3QlhBRTRBYlFCb0FFd0FaUUIwQURjQVlnQkNBRVVBTndCeUFGWUFTQUF6QUZFQVNBQkdBR2dBYndCU0FGb0FkUUJUQURjQVVnQTJBRUVBZHdCNkFIVUFNUUJwQURJQWR3QkxBRVFBZHdCNkFHY0FUUUJuQUZNQU1nQmpBR29BT1FCRUFIQUFUd0J5QUZFQVZBQTFBRE1BU1FCckFFRUFkZ0JPQUd3QUt3QjBBRXdBV2dCUEFEQUFaZ0JNQURnQWFnQTNBRUVBYlFCMUFHc0FXUUE0QUVRQWVRQm9BREFBUVFCbkFEMEFQUUE9IiwiTWVyY2hhbnRJRCI6IlNhZmVDaGFyZ2VNZXJjaCIsIk1lcmNoYW50QXBwbGljYXRpb24iOiJTQ2gwMSIsIk1lcmNoYW50VHJhbnNhY3Rpb25JRCI6IjUwMTkxIiwiTWVyY2hhbnROYW1lIjoiU2lnaHRsaW5lIFBheW1lbnRzIiwiRE9CIjoiMTk5Mi0wNi0wMiIsIklkVHlwZSI6IjIiLCJJZFZhbHVlIjoiMDUzOTQyNjg0In0.WPa7Hpq0f-rsr5pDvVOtz3SmFUUZg1c1dHbd9_rf5lXMKpnv23SZsH_RwG1P0uu_5JaLQoE6yyVHJ7Q_l5FX-CzNZlcOYXYwOYagz7PmL9vtdMfN1Ey6p9Z8ANs9mtub8yy-GWOhFH_wvGaN4KGll_rT35MnorBiPEJnix_ZHqI0F42cNuUj9cqVLhbe-furAmWqpa7zhvPQ1MfQ3wCZx57KgM0F4iZ75HBxIYGf3U5XTrTjTrQvEENbMsqvqvWtxFmq240zrsOdHMC8vXJp29t5CdtZEzmeAZAAUNM8I7Mho_Mg-xRHgFsu5WmPp4qHBqds-GNKTYmubCzQocXtPg",
    "merchantId": "2502136204546424962",
    "clientUniqueId": "695701003",
    "errCode":0,
    "clientRequestId": "O3V96K7EV",
    "sessionToken": "72c9dab5-00b0-4d1b-8b24-a9b5e0a1a795",
    "internalRequestId":17480361,
    "userId": "E677539C0C54",
    "version": "1.0",
    "status": "SUCCESS",
    "merchantSiteId": "126006"
}

This method generates a redirectUrl to which you must redirect the customer to complete their account funding.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/fundAccount.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/fundAccount.do

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(45) ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
paymentOption.alternativePaymentMethod ^Class ~Required	This class represents the details on the payment method. paymentMethod (String, 50) – Specifies the payment method name of the payment option to be charged. See: APM Input Fields and APIs.
userId ^String(255) ~Required	The ID of the customer in the merchant system. This is used as AccountIdentifier in some APMs such as Play+.
deviceDetails ^Class ^Optional	deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255) ipAddress (String, 15)
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code. state (String, 3) – ISO state code (for customers based in the US, Canada, and India only). email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This represents the customer’s identification number in their respective country; for example, the social security number (SSN) of United States citizens.
urlDetails ^Class ^Optional	notificationUrl (String, 1000) – The URL to which DMNs are sent once the customer completes the funding form.

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(45)	The unique transaction ID in the merchant system.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
userId ^String(255)	The ID of the customer in the merchant system. This is used as AccountIdentifier in some APMs such as Play+.
redirectUrl ^String	The URL to which you must redirect the customer to complete the enrollment or funding process.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side then an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
paymentMethodErrorCode ^Integer(11)	If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason ^String(400)	If an error occurred on the APM side, an error reason is returned in this parameter.

/getAccountDetails

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
    "sessionToken": "e0de4572-b08f-4f73-8ef4-99cc0aafdf3e",
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "clientUniqueId": "695701003",
    "clientRequestId": "R4WXUZUZ7",
    "userId": "E677539C0C54",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod": "apmgw_PlayPlus"
        }
    },
    "deviceDetails":{
        "deviceType": "TABLET",
        "deviceName": "iPad",
        "deviceOS": "iOS U",
        "browser": "safari U",
        "ipAddress": "192.168.2.38"
    },
    "userDetails":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "22 Main Street",
        "phone": "6175556309",
        "zip": "02460",
        "city": "Boston",
        "country": "US",
        "state": "MA",
        "email": "[email protected]",
        "county": "Suffolk",
        "language": "en",
        "dateOfBirth": "1972-06-02",
        "identification": "987456982"
    }
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "reason": "",
    "authCode": "2b3de42362bf49ed8f36df3ab2b3c637",
    "clientRequestId": "R4WXUZUZ7",
    "internalRequestId":17453921,
    "userId": "E677539C0C54",
    "version": "1.0",
    "merchantSiteId": "126006",
    "merchantId": "2502136204546424962",
    "clientUniqueId": "695701003",
    "errCode":0,
    "sessionToken": "e0de4572-b08f-4f73-8ef4-99cc0aafdf3e",
    "currency": "USD",
    "externalTransactionId": "2b3de42362bf49ed8f36df3ab2b3c637",
    "accountBalance": "1413.5000",
    "status": "SUCCESS"
}

This method queries the server for the customer’s available balance and/or bank account details.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/getAccountDetails.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/getAccountDetails.do

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(45) ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
paymentOption.alternativePaymentMethod ^Class ~Required	This class represents the details on the payment method. paymentMethod (String, 50) – Specifies the payment method name of the payment option to be charged. See: APM Input Fields and APIs.
userId ^String(255) ~Required	The ID of the customer in the merchant system.
deviceDetails ^Class ^Optional	deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255) ipAddress (String, 15)
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code. state (String, 3) – ISO state code (for customers based in the US, Canada, and India only). email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This represents the customer’s identification number in their respective country; for example, the social security number (SSN) of United States citizens.

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(45)	The unique transaction ID in the merchant system.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
userId ^String(255)	The ID of the customer in the merchant system.
accountBalance ^String(12)	The available amount in the user’s wallet.
currency ^String(3)	The 3-letter ISO currency code. Currently, this is always set to USD.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side then an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
paymentMethodErrorCode ^Integer(11)	If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason ^String(400)	If an error occurred on the APM side, an error reason is returned in this parameter.
version ^String(10)	The current version of the request. The current version is 1.
bankAccounts[] ^Class	bankName (String, 30) – The name of the bank. accountNumber (String, 30) – The bank account number. routingNumber (String, 30) – The bank account routing number. NOTE: This parameter is relevant only for certain APMs.
accountLimit ^String(12)	The customer’s account limit as set in the APM account.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used. NOTE: This parameter is relevant only for certain APMs.
authCode ^String(128)	The authorization code of the transaction. NOTE: This parameter is relevant only for certain APMs.

/getDocumentUrl

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "sessionToken": "aab1cbec-f9b4-40d6-8f4b-e60e0cfcc3c9",
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "clientUniqueId": "695701003",
    "clientRequestId": "HIS79GYC4",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod": "apmgw_PlayPlus"
        }
    },
    "documentType": "TermsAndConditions"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "sessionToken": "7f97c205-f683-4a25-8f2b-717a8769a0b9",
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "clientUniqueId": "695701003",
    "clientRequestId": "4LABDBTQ5",
    "userId": "E677539C0C54",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod": "apmgw_PlayPlus"
        }
    },
    "documentType": "FAQ"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "reason": "",
    "merchantId": "2502136204546424962",
    "clientUniqueId": "695701003",
    "errCode":0,
    "clientRequestId": "HIS79GYC4",
    "documentUrl": "https://ceapspanex.slpuat.com/playplusdocumentviewer/view/document/TCURL/SCh01",
    "sessionToken": "aab1cbec-f9b4-40d6-8f4b-e60e0cfcc3c9",
    "internalRequestId":17743421,
    "version": "1.0",
    "status": "SUCCESS",
    "merchantSiteId": "126006"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "reason": "",
    "merchantId": "2502136204546424962",
    "clientUniqueId": "695701003",
    "errCode":0,
    "clientRequestId": "4LABDBTQ5",
    "documentUrl": "https://ceapspanex.slpuat.com/playplusdocumentviewer/view/document/FAQURL/SCh01/E677539C0C54/SafeChargeMerch/695701003",
    "sessionToken": "7f97c205-f683-4a25-8f2b-717a8769a0b9",
    "internalRequestId":17743711,
    "userId": "E677539C0C54",
    "version": "1.0",
    "status": "SUCCESS",
    "merchantSiteId": "126006"
}

This method returns a URL to the document specified in the request.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/getDocumentUrl.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/getDocumentUrl.do

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(45) ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter. Use the same value in /getDocumentUrl and /enrollAccount calls.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
paymentOption.alternativePaymentMethod ^Class ~Required	This class represents the details on the payment method. paymentMethod (String, 50) – Specifies the payment method name of the payment option to be charged. See: APM Input Fields and APIs.
documentType ^String(20) ~Required	The type of the issued document. Possible values: TermsAndConditions, PrivacyPolicy, FAQ
userId ^String(255) %%Conditional	This ID uniquely identifies your consumer/user in your system. This is used as AccountIdentifier in some APMs such as Play+. It must be present if the request is for acceptance of the document. Use the same value in /getDocumentUrl and /enrollAccount calls. Not required for an “anonymous” request (which returns a “view-only” documentUrl.)

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(45)	The unique transaction ID in the merchant system.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
userId ^String(255)	The ID of the customer in the merchant system. This is used as AccountIdentifier in some APMs such as Play+. Use the same value in /getDocumentUrl and /enrollAccount calls.
documentUrl ^String(1000)	The URL of the specified document hosted on the server.
status ^String(20)	The cashier status of merchant request. Possible values: SUCCESS, ERROR
errCode ^Integer(11)	If an error occurred on the request side then an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of the request. The current version is 1.

Domain Registration

Domain Registration Overview

A new JSON Web Token (JWT) solution allows Nuvei to onboard merchants to Google once, renew their JWT public key annually, and dynamically enable an unlimited number of web domains without having to register each one in the Google Pay and Wallet consoles.

/registerGooglePayDomains

Endpoint URL

1
2
3
4
5
6
7
8
9
10
11
12
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "domainNames": [
        "www.example.com",
        "mobile.example.com"
    ],
    "agreedToGooglePayTermsAndConditions": "true",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "internalRequestId": 21215,
    "status": "SUCCESS",
    "errCode": 0, 
    "reason": "", 
    "merchantId": "7777777",
    "merchantSiteId": "38",
    "version": "1.0", 
    "clientRequestId": "20240325205024",
    "domains": [{ 
        "domainName": "domain1.com",
        "status": "SUCCESS" 
        },  
        { 
        "domainName": "domain4.klll...",
        "status": "ERROR",
        "errCode": 9150,
        "reason": "domainName cannot be longer than 255 characters."
        }
    ], 
    "merchantName": "MerchantKiril"
}

This method allows Nuvei to onboard merchants to Google once, renew their JWT public key annually, and dynamically enable an unlimited number of web domains without having to register each one in the Google Pay and Wallet consoles.

Press here for more information.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/registerGooglePayDomains.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/registerGooglePayDomains.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
domainNames ^String(255) ~Required	The domains from which the Google Pay call was initiated. Referred to as merchantOrigin on the Google’s API. There is no limit to the number of domains a merchant can register per request. NOTE: When providing a domain, “https://” should be excluded from the URL.
agreedToGooglePayTermsAndConditions ^Boolean ~Required	Indicates if the merchant agrees to Google’s terms and conditions.
timeStamp ^String(14) ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, domainNames, agreedToGooglePayTermsAndConditions, timeStamp, merchantSecretKey Press here to see an example.

Output Parameters

Parameter	Description
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	If an error occurred on the request side, an error reason is returned in this parameter (e.g. failure in checksum validation, timeout from processing engine, etc.).
version ^String(10)	The current version of the API method. The current version is 1.
domains ^Array	A list of the requested domains and their status. domainName (String) status (String) – Possible values: SUCCESS, ERROR errCode (String) (only relevant if status is ERROR). reason (String)(only relevant if status is ERROR).

/googlePayMerchantInfoJwt

Endpoint URL

1
"https://ppp-test.nuvei.com/ppp/api/v1/googlePayMerchantInfoJwt.do?merchantOrigin=domain4.net&sessionToken=8bc0140f-5375-4da5-bf75-0e92e83b071b"

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
{
    "merchantInfo": {
        "merchantId": "BCR2DN6TZ6DP7P3X",
        "merchantOrigin": "domain.com",
        "merchantName": "Merchant Test",
        "authJwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJpYXQiOjE3MTQ1OTQzOTgsIm1lcmNoYW50SWQiOiJCQ1IyRE42VFo2RFA3UDNYIiwibWVyY2hhbnRPcmlnaW4iOiJkb21haW4uY29tIn0.Q2xZmLc0ugbtjNxeUYL7_q2R_OBmYzr91HLgV3BBTZDkGsH8vf-sWIQl7Y1tkW6Qh1SmOU732gKYtGvKTwb4FA"
    },
    "status": "SUCCESS"
}

The merchant calls this method to receive a registered domain and JWT for each transaction. The merchant then adds the merchantInfo object (that includes the domain name and the JWT) to the Google Pay PaymentDataRequest object.

Press here for more information.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/googlePayMerchantInfoJwt.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/googlePayMerchantInfoJwt.do

Input Parameters

PARAMETER	DESCRIPTION
merchantOrigin ^String(255) ~Required	The domain from which the Google Pay call was initiated. NOTE: When providing a domain, “https://” should be excluded from the URL.
sessionToken ^String(36) ~Required	The session identifier returned. To be used as an input.

Output Parameters

Parameter	Description
merchantId ^String	A Google merchant identifier.
merchantOrigin ^String	The domain from which the Google Pay call was initiated.
merchantName ^String(25)	The merchant name, as is displayed for the transaction on the consumer’s card statement.
authJwt ^String	Base64 URL-encoded JWT in the format of header + “.” + payload + “.” + signature.
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.

/unregisterGooglePayDomains

Endpoint URL

1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "domainNames": [
        "www.example.com",
        "mobile.example.com"
    ],
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "internalRequestId": 21215,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "7777777",
    "merchantSiteId": "38",
    "version": "1.0",
    "clientRequestId": "20240325205024",
    "domains": [
        {
            "domainName": "domain1.com",
            "status": "SUCCESS"
        },
        {
            "domainName": "www.blocked-domain-name.com",
            "status": "ERROR",
            "errCode": 9151,
            "reason": "Disabled domains cannot be modified"
        }
    ],
    "merchantName": "MerchantKiril"
}

This method allows merchants to unregister domains.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/unregisterGooglePayDomains.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/unregisterGooglePayDomains.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
domainNames ^String(255) ~Required	The domains from which the Google Pay call was initiated. Referred to as merchantOrigin on the Google’s API. There is no limit to the number of domains a merchant can register per request.
timeStamp ^String(14) ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, domainNames, timeStamp, merchantSecretKey Press here to see an example.

Output Parameters

Parameter	Description
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	If an error occurred on the request side, an error reason is returned in this parameter (e.g. failure in checksum validation, timeout from processing engine, etc.).
version ^String(10)	The current version of the API method. The current version is 1.
domains ^Array	A list of the requested domains and their status. domainName (String) status (String) – Possible values: SUCCESS, ERROR errCode (String) (only relevant if status is ERROR). reason (String)(only relevant if status is ERROR).
merchantName ^String(25)	The merchant name, as is displayed for the transaction on the consumer’s card statement.

/getRegisteredGooglePayDomains

Endpoint URL

1
2
3
4
5
6
7
{
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "clientRequestId": "1C6CT7V1L", 
    "timeStamp":"20240915143321",
    "checksum":"1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "internalRequestId": 21215,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "7777777",
    "merchantSiteId": "38",
    "version": "1.0",
    "clientRequestId": "20240325205024",
    "domainNames": [
        "www.example.com",
        "mobile.example.com"
    ]
}

This method allows merchants to retrieve a list of their registered domains.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/getRegisteredGooglePayDomains.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/getRegisteredGooglePayDomains.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
domainNames ^String(255) ~Required	The domains from which the Google Pay call was initiated. Referred to as merchantOrigin on the Google’s API. There is no limit to the number of domains a merchant can register per request.
timeStamp ^String(14) ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, timeStamp, merchantSecretKey Press here to see an example.

Output Parameters

Parameter	Description
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	If an error occurred on the request side, an error reason is returned in this parameter (e.g. failure in checksum validation, timeout from processing engine, etc.).
version ^String(10)	The current version of the API method. The current version is 1.
domainNames ^String(255)	A list of the requested domains.

Rebilling

Rebilling Overview

Nuvei’s rebilling service allows you to create and manage recurring charges for products and services that you offer to your customers. You can set payment plans or subscriptions and still have the flexibility to modify, extend, or cancel them.

The service also takes advantage of the “card updaters” feature provided by card schemes (for supported cards) to ensure the frictionless charging of a running subscription in the event of card details being changed by the card issuer on the customer’s side.

The service is available through our API, Cashier, and Control Panel platforms via API methods.

Press here for more information.

API Implementation

This section introduces merchants to the following available API methods of the rebilling feature:

• /createPlan
• /editPlan
• /getPlansList
• /createSubscription
• /editSubscription
• /getSubscriptionsList
• /cancelSubscription

/createPlan

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "name": "QJCJXI5SJ7W0JI6",
    "description": "Plan 1",
    "planStatus": "ACTIVE",
    "currency": "EUR",
    "initialAmount": "15.67",
    "recurringAmount": "4.24",
    "startAfter": {
        "day": "3",
        "month": "2",
        "year": "1"
    },
    "recurringPeriod": {
        "day": "1",
        "month": "0",
        "year": "0"
    },
    "endAfter": {
        "day": "6",
        "month": "7",
        "year": "8"
    },
    "timeStamp": "20241209121236",
    "checksum": "038c3c0009081e848c4812e573fe679f" 
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
{
    "planId": 6321,
    "status": "SUCCESS"
}

This method is used for creating a charging plan to set timing and payment conditions for a certain product or service.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/createPlan.do

@Test https://ppp-test.nuvei.com/ppp/api/createPlan.do

Input Parameters

Parameter	Description
merchantId ^Long ~Required	The Merchant unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	The Merchant website’s unique identification number provided by Nuvei
name ^String(50) ~Required	Name of the plan is being created.
recurringAmount ^Double(20) ~Required	Amount that users subscribed to this plan are charged on recurring base.
currency ^String ~Required	Currency with which all the users subscribed to this plan are charged.
endAfter ^String ~Required	Period of time after which plan is deactivated for the user subscribed to it unless a different (shorter/longer) period is applied to the subscription. NOTE: These values cannot be null. Example: Day = 0 Month = 12 Year = 0 Plan conditions are no longer applied to the user after 12 months.
timeStamp ^String ~Required	The time when the method call is performed according to the GMT+2 time zone in YYYYMMDDHHmmss format.
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include the following parameters in the specific order, ending with the Secret Key value: merchantId, merchantSiteId, name, initialAmount, recurringAmount, currency, timeStamp, merchantSecretKey The resulting string is hashed using SHA-256.
initialAmount ^Double(20) ^Optional	The initial one-time amount that is applied to the users subscribed to this plan (it is a different amount than what recurring amount users is charged.
description ^String(200) ^Optional	Short description of the product.
startАfter ^String ^Optional	Period after subscription is made when first rebilling charge occurs. NOTE: These values cannot be null. Example: Day = 4 Month = 3 Year = 1 Charging starts 1 year, 3 months and 4 days after the user has been subscribed to the plan.
recurringPeriod ^String ^Optional	Recurring period users subscribed to the plan are charged. NOTE: These values cannot be null. Example: Day = 15 Month = 9 Year = 0 User is charged every 9 months and 15 days.
planStatus ^String ^Optional	ACTIVE – Users are able to subscribe to this plan INACTIVE – Users are not able to subscribe to the plan. The plan is still active for current existing subscriptions. If no specific status is sent, the plan is created in Active status.

/editPlan

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "planId": "6331",
    "name": "5JTT6T6TH7OGRTK",
    "description": "Plan 1 - Updated",
    "currency": "GBP",
    "initialAmount": "13.67",
    "recurringAmount": "3.24",
    "planStatus": "INACTIVE",
    "timeStamp": "20241209121225",
    "checksum": "0661ef048083f96bd31cbd70f4e2d6a2"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
{
    "status": "SUCCESS"
}

This method is used for editing the charging or timing conditions of a certain rebilling plan.

This method can also be used to cancel an existing plan by changing its status to ‘INACTIVE’.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/editPlan.do

@Test https://ppp-test.nuvei.com/ppp/api/editPlan.do

Input Parameters

Parameter	Description
merchantId ^Long ~Required	The Merchant unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	The Merchant website’s unique identification number provided by Nuvei
planId ^Long ~Required	Name of the product is being created.
timeStamp ^String ~Required	The time when the method call is performed according to the GMT+2 time zone in YYYYMMDDHHmmss format.
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include the following parameters in the specific order, ending with the Secret Key value: merchantId, merchantSiteId, planId, initialAmount, recurringAmount, currency, timeStamp, merchantSecretKey The resulting string is hashed using SHA-256.
name ^String(50) ^Optional	Plan name.
description ^String(200) ^Optional	Short description of the product.
currency ^String ^Optional	Currency with which all the users subscribed to this plan are charged.
initialAmount ^Double(20) ^Optional	The initial one-time amount that is applied to the users subscribed to this plan (it is a different amount than what recurring amount users is charged.
recurringAmount ^Double(20) ^Optional	Amount that the users subscribed to this plan will be charged on recurring base.
startАfter ^String ^Optional	Period after subscription is made when first rebilling charge occurs. NOTE: These values cannot be null. Example: Day = 4 Month = 3 Year = 1 Charging starts 1 year, 3 months and 4 days after the user has been subscribed to the plan.
recurringPeriod ^String ^Optional	Recurring period users subscribed to the plan are charged. NOTE: These values cannot be null. Example: Day = 15 Month = 9 Year = 0 User is charged every 9 months and 15 days.
endAfter ^String ^Optional	Period of time after which plan is deactivated for the user subscribed to it unless a different (shorter/longer) period is applied to the subscription. NOTE: These values cannot be null. Example: Day = 0 Month = 12 Year = 0 Plan conditions are no longer applied to the user after 12 months.
planStatus ^String ^Optional	ACTIVE – Users are able to subscribe to this plan INACTIVE – Users are not able to subscribe to the plan. The plan is still active for current existing subscriptions.

/getPlansList

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "planIds": ["101"],
    "planStatus": "ACTIVE",
    "currency": "EUR",
    "recurringPeriod": {
        "day": "1",
        "month": "0",
        "year": "0"
    },
    "firstResult": "0",
    "maxResults": "10",
    "timeStamp": "20241209121218",
    "checksum": "f7a0aec563dc52b41397f153f27449a3"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
    "total": 1,
    "plans": [
        {
            "recurringAmount": "4.24",
            "startAfter": {
                "month": "2",
                "year": "1",
                "day": "3"
            },
            "recurringPeriod": {
                "month": "0",
                "year": "0",
                "day": "1"
            },
            "merchantId": "2502136204546424962",
            "initialAmount": "15.67",
            "name": "8SQ1TOWCQ285KON",
            "description": "Plan 1",
            "planStatus": "ACTIVE",
            "planId": 101,
            "currency": "EUR",
            "endAfter": {
                "month": "7",
                "year": "8",
                "day": "6"
            }
        }
    ],
    "status": "SUCCESS"
}

This method is used to invoke the information of an existing plan.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/getPlansList.do

@Test https://ppp-test.nuvei.com/ppp/api/getPlansList.do

Input Parameters

Parameter	Description
merchantId ^Long ~Required	The Merchant unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	The Merchant website’s unique identification number provided by Nuvei.
timeStamp ^String ~Required	The time when the method call is performed according to the GMT+2 time zone in YYYYMMDDHHmmss format.
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include the following parameters in the specific order, ending with the Secret Key value: merchantId, merchantSiteId, planId, currency, planStatus, timeStamp, merchantSecretKey The resulting string is hashed using SHA-256.
firstResult ^String ^Optional	First result value.
maxResult ^String ^Optional	Max result value.
planIds ^Array ^Optional	An array of Plan IDs.
currency ^String ^Optional	Currency of the Plan.
recurringPeriod ^String ^Optional	Expected values per one of the parameters: Day (String) = 1 (daily), 7 (weekly) Month (String) = 1 (monthly) Year (String) = 1 (yearly) Valid value (0 included) sent to at least one of the parameters + “null” to rest of them returns all the records in DB where the valid value is available.
planStatus ^String ^Optional	Active – Users are able to subscribe to this plan. Inactive – Users are not able to subscribe to the plan. The plan is still active for current existing subscriptions.

/createSubscription

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "userTokenId": "230811147",
    "planId": "101",
    "userPaymentOptionId": "7702871",
    "currency": "EUR",
    "initialAmount": "15.67",
    "recurringAmount": "4.24",
    "startAfter": {
        "day": "3",
        "month": "2",
        "year": "1"
    },
    "recurringPeriod": {
        "day": "1",
        "month": "0",
        "year": "0"
    },
    "endAfter": {
        "day": "6",
        "month": "7",
        "year": "8"
    },
    "timeStamp": "20241209121255",
    "checksum": "2ca0a41a55128b1b5babb74cd0ff6fc0"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
{
    "subscriptionId": "935011",
    "status": "SUCCESS"
}

This method is used for creating a subscription for consumers that wish to conduct future recurring transactions to consume a certain service or a product.

In the example request in the right panel, the subscription starts within a year, 2 months, and 3 days with an initial amount of 15.67 EUR, charges the card daily with the amount of 4.24 EUR, and ends within 2 years and 5 days.
If a merchant wishes to start the subscription immediately, the startAfter class should contain 0d 0m 0y.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/createSubscription.do

@Test https://ppp-test.nuvei.com/ppp/api/createSubscription.do

Input Parameters

Parameter	Description
merchantId ^Long ~Required	The Merchant unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	The Merchant web site’s unique identification number provided by Nuvei.
planId ^Long ~Required	The ID of the plan the user is subscribed to.
userTokenId ^String ~Required	This ID uniquely identifies your consumer/user in your system.
userPaymentOptionId ^Long ~Required	Unique identifier of the user’s payment method in Nuvei.
endAfter ^String ~Required	Period of time after which plan is deactivated for the user subscribed to it unless different (shorter/longer) period is applied to the subscription: NOTE: These values cannot be null. Example: Day = 0 Month = 12 Year = 0 Plan conditions are no longer applied to the user after 12 months.
timeStamp ^String ~Required	The time when the method call is performed according to the GMT+2 time zone in YYYYMMDDHHmmss format.
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include the following parameters in the specific order, ending with the Secret Key value: merchantId, merchantSiteId, userTokenId, planId, userPaymentOptionId, initialAmount, recurringAmount, currency, timeStamp, merchantSecretKey The resulting string is hashed using SHA-256.
currency ^String ^Optional	Subscription currency. Only if the specific currency is different than the currency of the plan is defined to this subscription.
initialAmount ^Double(20) ^Optional	The initial amount of the subscription. It is only available if there is a specific initial amount defined to the subscription, different than the initial amount of the plan.
recurringAmount ^Double(20) ^Optional	Amount that user of this is charged on a recurring basis. It is a currency different than the plan currency.
startАfter ^String ^Optional	Period after subscribing when first rebilling charge occurs. If any specific period is not defined to the subscription, it is taken from the plan. NOTE: These values cannot be null. Example: Day = 4 Month = 3 Year = 1 Charging starts 1 year, 3 months and 4 days after the user has been subscribed to the plan.
recurringPeriod ^String ^Optional	Recurring period the users subscribed to the plan are charged. It is available only in case subscription period is different than the recurring period of the plan. NOTE: These values cannot be null. Example: Day = 15 Month = 9 Year = 0 User is charged every 9 months and 15 days.
initialTransactionId ^String(20) ^Optional	The transactionId of the initial payment transaction.

/editSubscription

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "userTokenId": "230811147",
    "planId": "101",
    "subscriptionId": "935021",
    "userPaymentOptionId": "6434806",
    "subscriptionStatus": "ACTIVE",
    "currency": "GBP",
    "recurringAmount": "4.24",
    "startAfter": {
        "day": "3",
        "month": "2",
        "year": "1"
    },
    "recurringPeriod": {
        "day": "1",
        "month": "0",
        "year": "0"
    },
    "endAfter": {
        "day": "6",
        "month": "7",
        "year": "8"
    },
    "timeStamp": "20241209121246",
    "checksum": "4289d93d4202bf414e07df85a09d5181"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
{
    "status": "SUCCESS"
}

This method is used for editing the payment or recurring conditions of a certain rebilling subscription.
For a card to be replaced on an existing subscription, its identifier must also be affiliated with the previous user identifier (user_token_id).

@Links URLs

@Live https://secure.safecharge.com/ppp/api/editSubscription.do

@Test https://ppp-test.nuvei.com/ppp/api/editSubscription.do

Input Parameters

Parameter	Description
merchantId ^Long ~Required	The Merchant unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	The Merchant website’s unique identification number provided by Nuvei.
subscriptionId ^Long ~Required	The ID of the user’s active subscription in Nuvei system.
timeStamp ^String ~Required	The time when the method call is performed according to the GMT+2 time zone in YYYYMMDDHHmmss format.
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include the following parameters in the specific order, ending with the Secret Key value: merchantId, merchantSiteId, subscriptionId, userPaymentOptionId, recurringAmount, currency, timeStamp, merchantSecretKey The resulting string is hashed using SHA-256.
userPaymentOptionId ^Long ^Optional	Unique identifier of the user’s payment method in Nuvei.
currency ^String	Subscription currency. Only if the specific currency different than the currency of the plan is defined to this subscription.
recurringAmount ^Double(20) ^Optional	Amount that user of this particular is charged on a recurring basis. It is a currency different than the plan currency.
startАfter ^String ^Optional	Period after subscribing when first rebilling charge occurs. If startPeriod is updated after at least one successful recurring transaction, it will be the period after the next consecutive transaction occurs. NOTE: These values cannot be null. Example: Day = 4 Month = 3 Year = 1 Charging starts 1 year, 3 months and 4 days after the user has been subscribed to the plan.
recurringPeriod ^String ^Optional	Recurring period the user of the particular subscription will be charged. It is available only in case subscription period is different than the recurring period of the plan. NOTE: These values cannot be null. Example: Day = 15 Month = 9 Year = 0 User is charged every 9 months and 15 days.
endAfter ^String ^Optional	Period of time after which plan is deactivated for the user subscribed to it unless different (shorter/longer) period is applied to the subscription. NOTE: These values cannot be null. Example: Day = 0 Month = 12 Year = 0 Plan conditions are no longer applied to the user after 12 months.
initialTransactionId ^String(20) ^Optional	The transactionId of the initial payment transaction.

/getSubscriptionsList

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "planIds": ["4431"],
    "subscriptionIds": ["929291"],
    "userTokenId": "230811147",
    "subscriptionStatuses": ["ACTIVE"],
    "recurringAmount": {
        "fromAmount": "1",
        "toAmount": "100",
        "currency": "USD"
    },
    "recurringPeriod": {
        "day": "3",
        "month": "0",
        "year": "0"
    },
    "creationDate": {
        "fromDate": "2019-01-01 00:00:00",
        "toDate": "2020-03-01 12:56:58"
    },
    "endDate": {
        "fromDate": "2019-01-01 00:00:00",
        "toDate": "2044-03-01 12:56:58"
    },
    "pmName": "cc_card",
    "firstResult": "0",
    "maxResults": "1000",
    "timeStamp": "20241209121200",
    "checksum": "336ae3123a017254b70840ff0fe62b46"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
    "status": "SUCCESS",
    "subscriptions": [
        {
            "merchantSiteId": "252798",
            "recurringAmount": "0.38",
            "currency": "USD",
            "startAfter": {
                "day": "16",
                "month": "0",
                "year": "0"
            },
            "recurringPeriod": {
                "day": "0",
                "month": "1",
                "year": "0"
            },
            "endAfter": {
                "day": "16",
                "month": "2",
                "year": "0"
            },
            "userTokenId": "5-283555",
            "planId": "25028",
            "userPaymentOptionId": "112640648",
            "planName": "contract-5-283555-2023-2024-05-22 08:50:02",
            "subscriptionId": 228078,
            "subscriptionStatus": "ACTIVE",
            "createDate": "20240522155002",
            "updateDate": "20240522155003",
            "endDate": "20240823155003"
        }
    ],
    "total": 1
}

This method is used to invoke the information of an existing subscription.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/getSubscriptionsList.do

@Test https://ppp-test.nuvei.com/ppp/api/getSubscriptionsList.do

Input Parameters

Parameter	Description
merchantId ^Long ~Required	The Merchant unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	The Merchant website’s unique identification number provided by Nuvei.
timeStamp ^String ~Required	The time when the method call is performed according to the GMT+2 time zone in YYYYMMDDHHmmss format.
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include the following parameters in the specific order, ending with the Secret Key value: merchantId, merchantSiteId, userTokenId, planId, subscriptionId, subscriptionStatus, timeStamp, merchantSecretKey The resulting string is hashed using SHA-256.
firstResults ^String ^Optional	First result value.
maxResults ^String ^Optional	Max result value. NOTE: When getSubscriptionsList is called, a maximum of 1000 results per call can be displayed at one time.
subscriptionIds ^Array ^Optional	An array of Subscription IDs.
subscriptionStatuses ^Array ^Optional	An array of the four possible statuses: INITIALIZING – The subscription is created but not all the of conditions have taken effect yet. This usually appears when a card has yet to be verified, meaning an end user has submitted a subscription, but Nuvei has not yet received confirmation for the card used. In this case subscription remains in Initialized status waiting for card validation and UPO creation. Once a card is validated and a UPO created, the subscription state is changed to “Active” status. ACTIVE – All the conditions for the particular subscription are active and the user receives the benefits of the plan to which they are subscribed. INACTIVE – The subscription has reached its end date. Subscription’s expired. CANCELLED – The subscription is no longer active and the subscription’s conditions are no longer applied to it. The “CANCELLED” state/status is similar to “INACTIVE” but is initiated by a merchant request/action. A subscription moves to “CANCELLED” per a merchant request via:  • A Nuvei REST API call  • Nuvei’s Control Panel
planIds ^Array ^Optional	An array of Plan IDs that the subscription is activated to.
userTokenId ^Long ^Optional	This ID uniquely identifies your consumer/user in your system.
creationDate ^Date ^Optional	Block from/to date of subscription creation. date. Function: { fromDate:date; toDate:date } Data is sent in format: yyyyMMdd HH:mm:ss
endDate ^Date ^Optional	Block from/to date of subscription end date. Function: { fromDate:date; toDate:date } Data is sent in format: yyyyMMdd HH:mm:ss
pmName ^String ^Optional	Payment method name on the Nuvei system (Cashier DB).
recurringAmount ^Double ^Optional	Recurring amount to or from with the currency of the subscription. If the currency is not sent to the request, the method returns the value of recurringAmount only. Function: { fromAmount:double toAmount:double, currency } Data is sent in format: yyyyMMdd HH:mm:ss
recurringPeriod ^String ^Optional	Expected values per one of the parameters: Day (String) = 1 (daily), 7 (weekly) Month (String) = 1 (monthly) Year (String) = 1 (yearly) Valid value (0 included) sent to at least one of the parameters + “null” to rest of them returns all the records in DB where the valid value is available.

/cancelSubscription

Definition

1
2
3
4
5
6
7
{
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "subscriptionId": "935031",
    "timeStamp": "20241209121259",
    "checksum": "516722e70a68e587edea4b30a6a438a2"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
{
    "status": "SUCCESS"
}

This method is used to cancel an existing subscription. The subscription is not deleted on our side, but its status is changed to “CANCELED”.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/cancelSubscription.do

@Test https://ppp-test.nuvei.com/ppp/api/cancelSubscription.do

Input Parameters

Parameter	Description
merchantId ^String ~Required	The Merchant unique identification number provided by Nuvei.
merchantSiteId ^String ~Required	The Merchant website’s unique identification number provided by Nuvei.
subscriptionId ^String ~Required	A unique relation between A user and a product in Nuvei Rebilling system meaning the respective User is subscribed to the specific Plan.
timeStamp ^String ~Required	The time when the method call is performed according to the GMT+2 time zone in YYYYMMDDHHmmss format.
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include the following parameters in the specific order, ending with the Secret Key value: merchantId, merchantSiteId, subscriptionId, timeStamp, merchantSecretKey The resulting string is hashed using SHA-256.

Cashier Implementation

This section introduces merchants to the Nuvei Cashier page, which can be used to initialize a recurring subscription for consumers that wish to conduct future recurring transactions to consume a certain service or a product. The theme that supports the recurring payment is NOVO, which is available for both desktop and mobile.

As a pre-condition for this integration, a designated merchant site must be created with the help of our Integration Team, and a recurring plan must be set in advance either via our Control Panel or by using our createPlan API method.

The subscription is successfully created via API under a selected plan for a selected userTokenId and associated UPO once the initial transaction submitted from the Cashier is approved by the issuer bank. From that moment on, our recurring engine performs the subsequent charges based on the plan with which the subscription was associated.

Creating a Subscription (Cashier)

Input Parameters

Parameter	Description
checksum ^Hexadecimal String ~Required	Checksum.
country ^String ~Required	Country.
merchant_id ^String ~Required	The ID of the merchant in Nuvei system.
currency ^String ~Required	Currency of the subscription is being created. It will override the currency of the plan the user is subscribing to.
planId ^String ~Required	The ID of the Plan to which the subscription is being created. 'PlanId’ can be retrieved by calling API method getPlansList or via the Recurring reports in the Control Panel. It will be renamed as planId in near future.
version ^String ~Required	Nuvei API version.
user_token_id ^String ~Required	This ID uniquely identifies your consumer/user in your system.
merchant_site_id ^String ~Required	The ID of the merchant site provided by Nuvei.
merchantLocale ^String ^Optional	The Merchant locale.
city ^String ^Optional	City.
theme_id ^String ^Optional	The ID of the merchant theme. Provided by Nuvei.
initial_amount ^String ^Optional	The initial amount of the subscription. This parameter overrides initialAmount of the plan, if sent.
userId ^String ^Optional	User ID in Nuvei system.
phone1 ^String ^Optional	Phone.
user_token ^String ^Optional	Auto – If there is no User created in the Nuvei system to the user_token_id, it shall automatically create one upon successful subscription in our database. If there is already an existing User in Nuvei to the same user_token_id, the system updates user details with the new ones sent in the request. Register – The Nuvei system creates a new user in its database to the same user_token_id sent in the request.
first_name ^String ^Optional	User first name.
email ^String ^Optional	User email.
zip ^String ^Optional	User ZIP code.
time_stamp ^String ^Optional	Time stamp.
address1 ^String	User address.
last_name ^String ^Optional	User last name.
dateOfBirth ^String ^Optional	User date of birth.
encoding ^String ^Optional	Encoding. Default value: UTF-8
clientRequestId ^String ^Optional	Client request ID – Value sent by the Merchant to Nuvei that will be returned in each DMN.
rebilling_amount ^String	Rebilling amount. If sent, it overrides recurringAmount of the plan the user is subscribing to.

Building a Request to the Nuvei Rebilling Page

1. Go to the URL address of the Nuvei page (provided by Nuvei):
 “https://ppp-test.nuvei.com/ppp/purchase.do” followed by the parameters in the table above.

Request Example

1
https://ppp-test.nuvei.com/ppp/purchase.do?checksum=343f93e2d1109ae75dc029020c1d6f74&country=GB&merchantLocale=en_US&customField1=meccabingo.com&customField2=a2db82db-8186-44bb-a6d9-cb9f8f7ea25e&city=London&theme_id=1805251&initial_amount=10&merchant_id=4357846757569874813&userid=UID&phone1=13094526617&currency=EUR&state=TX&planId=5931&user_token=auto&first_name=John&email=john.doe%40gmail.com&zip=12345&customField15=rnk_pr01&time_stamp=2019-07-05.15%3A01%3A28&merchant_site_id=139006&address1=Test+Address&clientRequestId=22sds3434343433&last_name=Doe&dateOfBirth=1985-01-01&encoding=utf-8&version=4.0.0&user_token_id=rebillTest111&rebilling_amount=20  

2. For each request, you should calculate the checksum using SHA-256.

 The request checksum is calculated to include the following parameters:
 “merchantSecretKey” followed by all the values of each of the parameters in the request in the order they are sent.

Request Checksum Example

1
127.0.0.1:8080/ppp/purchase.do?item_open_amount_1=true&numberofitems=1&country=GB&merchantLocale=bg_BG&merchant_unique_id=MUID&customField1=CF1&theme_id=1468106&item_name_1=money&merchant_id=4366585828215730786&userid=UID&item_max_amount_1=9999999.0&currency=GBP&user_token=auto&first_name=myFirstName&planId=2&rebillingProductId=test1rebill&rebillingTemplateId=149812&email=asd%40abv.bg&time_stamp=2019-01-24.15%3A01%3A28&merchant_site_id=155906&last_name=myLastName&item_min_amount_1=1&version=4.0.0&user_token_id=GaliaTest300&total_amount=10&item_quantity_1=1&item_amount_1=10&checksum=d9a3d119a66b8e2072ca1e917a525762

Checksum Calculation

1
YTYJDyvKpcSA7v1uRraK07V8qQ6jHMekseFrtEsf5MO8LclqhG6wumiZL0vmOtIM (merchant key) + true1GBbg_BGMUIDCF11468106money4366585828215730786UID9999999.0GBPautomyFirstName2test1rebill149812asd@abv.bg2019-01-24.15:01:28155906myLastName14.0.0GaliaTest30010110

The Cashier rebilling page presents all the plan details the end user is subscribed to:

• Recurring amount
• Initial amount (setup fee) (if any)
• Trial period, ID (if any)
• First subscription charge – The date of the first recurring charge to this subscription.
• Subscription ends on – The date subscription expires according to the plan condition (endAfter value).

Cashier Rebilling Page Example

Withdrawals API

Withdrawals Overview

Nuvei’s Withdrawal API provides you with a platform that enables your customers to withdraw funds from their accounts. The withdrawal may be in the form of a refund or winnings.

See our Withdrawal Guide for a full description of this API.

The Withdrawal API Reference follows. There are four categories of methods:

• Processing
• Requests
• Orders
• Net Deposits

Processing Methods

After you receive the DMN notification that contains the transaction details of your customer’s withdrawal request, you can process the request. There are five ways in which you can handle a withdrawal request:

ACTION	METHOD	DESCRIPTION
Approve	approveRequest	The request is approved and the funds are withdrawn and sent to the customer’s chosen payment method.
Cancel	cancelRequest	The request is cancelled and no funds are withdrawn.
Decline	declineRequest	The request is declined and no funds are withdrawn.
Split	placeWithdrawalOrder	The funds are split between several payment methods through multiple calls of this method. For partial withdrawal requests, the sealRequest method is also required.
Seal	sealRequest	When the amount of a withdrawal request to be returned to the customer is less than their original deposit, you can use this method to seal the deposit. Sealing a deposit means that in the Withdrawal API, the status of the deposit changes from “in progress” to “partial” and no further withdrawals can be made from the request.

After placing a request, Nuvei returns a response that describes the status of your request.

approveRequest

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdRequestId": 100,
    "merchantWDRequestId": "12345",
    "userAccountId": "8675309",
    "operatorName": "Admin",
    "comment": "some comment",
    "successUrl": "",
    "failUrl": "",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": 0,
    "reason": "",
    "wdRequestStatus": "Approved",
    "wdOrderStaus": "Approved",
    "wdRequestId": 8675309,
    "wdOrderId": 8675309,
    "merchantWDRequestId": "741852",
    "userAccountId": "5675306",
    "pmRedirectUrl": ""
}

When your administrator approves a request, the customer’s funds are withdrawn to their payment method account.

@Links URL

@Live https://secure.safecharge.com/ppp/api/withdrawal/approveRequest.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/approveRequest.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
wdRequestId ^Integer(20) ~Required	A unique ID generated by Nuvei returned in the DMN for the request.
merchantWDRequestId ^String ~Required	A unique ID that you generate for the withdrawal order. This value must be unique. This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
timeStamp ^String ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.
userAccountId ^String ^Optional	The customer’s Account ID on your site. The value of this parameter indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.
operatorName ^String ^Optional	The name of the administrator of the request.
comment ^String ^Optional	The administrator’s comments regarding the transaction.
successUrl ^String ^Optional	URLs used when processing with a redirect payment option. Currently, only Trustly is supported as a redirect payment option. The URLs should be used when you wish to receive the result, upon which you have the option to close the popup (if such is opened in the first place) once the end user completes the process in the third-party payment provider’s page.
failUrl ^String ^Optional	URLs used when processing with a redirect payment option. Currently, only Trustly is supported as a redirect payment option. The URLs should be used when you wish to receive the result, upon which you have the option to close the popup (if such is opened in the first place) once the end user completes the process in the third-party payment provider’s page.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
version ^String	The version of the API call.
status ^String	Indicates if the API call was successful or not: Success: Successful result. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when a withdrawal request is declined.
reason ^String	Reason an error occurred.
wdRequestStatus ^String	The current status of the withdrawal request: Pending: The initial status of all requests. This indicates the transaction has not yet been processed. Approved: The request was approved. Declined: You or the APM declined the transaction. Canceled: The customer canceled the request from the Withdraw page. Partially Approved: The request is partially approved. This is relevant for split requests only. Error: Indicates an error occurred.
wdOrderStatus ^String	The current status of the withdrawal order: Pending: The initial status of all orders. This indicates the transaction has not yet been processed. Approved: The order was approved. Settling: The status when settleOrder is called. SettlingPending: The status when the withdrawal order is being processed by the APM Gateway and the APM Gateway returns a ‘Pending’ status. This occurs when Nuvei contacts the APM provider and is waiting for a final response. Settled: The initial status of all requests. This indicates the transaction has not yet been processed. Deleted: The status of a withdrawal order that has been deleted. Error: Indicates an error occurred.
wdRequestId ^Integer(20)	ID of the withdrawal request generated by Nuvei.
wdOrderId ^Integer	ID of the withdrawal order generated by Nuvei.
merchantWDRequestId ^String	A unique ID that you generate for the withdrawal request.
userAccountId ^String	The customer’s Account ID on your site. Only you know this value and no validations are performed by Nuvei.
pmRedirectUrl ^String	If this parameter exists, you should redirect to the provided URL to complete the process with the third-party payment provider. This parameter is only relevant for payment methods that support withdrawals in redirect mode (such as Trustly).

cancelRequest

Definition

1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "230811147",
    "wdRequestId": 100,
    "merchantWDRequestId": "12345",
    "userAccountId": "8675309",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": 0,
    "reason": "",
    "wdRequestStatus": "Approved",
    "wdRequestId": 8675309,
    "merchantWDRequestId": "741852",
    "userAccountId": "5675306"
}

When your customer chooses to cancel a Pending request from within the Withdraw page, you send the input parameters to Nuvei through the cancelRequest method. The status of the withdrawal is changed from Pending to Canceled and no funds are transferred.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/cancelRequest.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/cancelRequest.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
userTokenId ^String ~Required	This ID uniquely identifies your consumer/user in your system.
wdRequestId ^Integer(20) ~Required	A unique ID generated by Nuvei returned in the DMN for the request.
merchantWDRequestId ^String ~Required	A unique ID that you generate for the withdrawal order. This value must be unique. This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
timeStamp ^String ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.
userAccountId ^String ^Optional	The customer’s Account ID on your site. The value of this parameter indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
version ^String	The version of the API call.
status ^String	Indicates if the API call was successful or not: Success: Successful result. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when an error occurs.
reason ^String	Reason an error occurred.
wdRequestStatus ^String	The current status of the withdrawal request: Pending: The initial status of all requests. This indicates the transaction has not yet been processed. Approved: The request was approved. Declined: You or the APM declined the transaction. Canceled: The customer canceled the request from the Withdraw page. Partially Approved: The request is partially approved. This is relevant for split requests only. Error: Indicates an error occurred.
wdRequestId ^Integer(20)	A unique ID generated by Nuvei for the withdrawal request.
merchantWDRequestId ^String	A unique ID that you generate for the withdrawal request.
userAccountId ^String	The customer’s Account ID on your site. The value of this parameter indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.

declineRequest

Definition

1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "230811147",
    "wdRequestId": 100,
    "merchantWDRequestId": "12345",
    "userAccountId": "8675309",
    "operatorName": "Admin",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": 0,
    "reason": "",
    "wdRequestStatus": "Approved",
    "wdRequestId": 8675309,
    "merchantWDRequestId": "741852",
    "userAccountId": "5675306"
}

When your administrator declines a request, the customer’s funds are not returned to their payment method.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/declineRequest.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/declineRequest.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
wdRequestId ^Integer(20) ~Required	A unique ID generated by Nuvei returned in the DMN for the request.
merchantWDRequestId ^String ~Required	A unique ID that you generate for the withdrawal order. This value must be unique. This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
timeStamp ^String ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.
userAccountId ^String ^Optional	The customer’s Account ID on your site. The value of this parameter indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.
operatorName ^String ^Optional	The name of the administrator of the request.
comment ^String ^Optional	The administrator’s comments regarding the transaction.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
version ^String	The version of the API call.
status ^String	Indicates if the API call was successful or not: Success: Successful result. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when an error occurs.
reason ^String	Reason an error occurred.
wdRequestStatus ^String	The current status of the withdrawal request: Pending: The initial status of all requests. This indicates the transaction has not yet been processed. Approved: The request was approved. Declined: You or the APM declined the transaction. Canceled: The customer canceled the request from the Withdraw page. Partially Approved: The request is partially approved. This is relevant for split requests only. Error: Indicates an error occurred.
wdRequestId ^Integer(20)	ID of the withdrawal request.
merchantWDRequestId ^Long	A unique ID that you generate for the withdrawal request.
userAccountId ^String	The customer’s Account ID on your site. The value of this parameter indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.

placeWithdrawalOrder (Split Withdrawal)

Definition

1
2
3
4
5
6
7
8
9
10
11
12
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdRequestId": 100,
    "merchantWDRequestId": "12345",
    "merchantOrderId": "12345",
    "userUniqueId": "8675309",
    "userPMId": "3846",
    "operatorName": "Admin",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": 0,
    "reason": "",
    "wdRequestStatus": "Approved",
    "wdOrderStatus": "Approved",
    "wdRequestId": 8675309,
    "wdOrderId": 12345,
    "merchantWDRequestId": "741852",
    "merchantWDOrderId": "3846",
    "userAccountId": "5675306",
    "pmRedirectUrl": ""
}

When you want to split a withdrawal across several customer accounts, you must use the placeWithdrawalOrder method. This method creates an order for each account to which funds are to be withdrawn. Each order is processed individually and Nuvei returns a status response for each order. You can continue to place withdrawal orders until the entire deposit has been withdrawn by the customer.
When your back office user decides to return only part of the original deposit, the transaction appears as “in progress” on the Withdrawal API. If you want to allow customers to withdraw only a part of their deposit and close the remaining amount in the Withdrawal API, you can seal the transaction. For more information, see the sealRequest method.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/placeWithdrawalOrder.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/placeWithdrawalOrder.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
wdRequestId ^Integer(20) ~Required	Request ID that the withdrawal order is related to.
merchantWDRequestId ^String ~Required	A unique ID that you generate for the withdrawal request. This value must be unique. This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
merchantUniqueId ^String ~Required	This parameter is sent by the merchant and is used to associate a request with the merchant system. This value must be unique. This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
userPMId ^Long ~Required	ID of the payment methods the customer wants the funds withdrawn to.
amount ^Double ~Required	Amount that the customer wants to withdraw.
currency ^String ~Required	The 3-letter ISO currency code of the currency of the request.
settlementType ^Enum ~Required	Describes the type of settlement 0 – Indicates that the transaction is a withdrawal 1 – Indicates that the transaction is a refund.
timeStamp ^String ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.
gwRelatedTransactionId ^Long %%Conditional	Transaction ID of the request that the refund is related to when the request is a refund request. REQUIRED for refund requests.
merchantWDOrderId ^String ^Optional	A unique ID that you generate for the withdrawal order.
userAccountId ^String ^Optional	The customer’s Account ID on your site. The value of this parameter indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.
operatorName ^String ^Optional	The name of the administrator of the request.
comment ^String ^Optional	The administrator’s comments regarding the transaction.
successUrl ^String ^Optional	URLs used when processing with a redirect payment option. Currently, only Trustly is supported as a redirect payment option. The URLs should be used when you wish to receive the result, upon which you have the option to close the popup (if such is opened in the first place) once the end user completes the process in the third-party payment provider’s page.
failUrl ^String ^Optional	URLs used when processing with a redirect payment option. Currently, only Trustly is supported as a redirect payment option. The URLs should be used when you wish to receive the result, upon which you have the option to close the popup (if such is opened in the first place) once the end user completes the process in the third-party payment provider’s page.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
version ^String	The version of the API call.
status ^String	Indicates if the API call was successful or not. Success: Successful result. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when an error occurs.
reason ^String	Reason an error occurred.
wdRequestStatus ^String	The current status of the withdrawal request: Pending: The initial status of all requests. This indicates the transaction has not yet been processed. Approved: The request was approved. Declined: You or the APM declined the transaction. Canceled: The customer canceled the request from the Withdraw page. Partially Approved: The request is partially approved. This is relevant for split requests only. Error: Indicates an error occurred.
wdOrderStatus ^String	The current status of the withdrawal order: Pending: The initial status of all orders. This indicates the transaction has not yet been processed. Approved: The order was approved. Settling: The status when settleOrder is called. SettlingPending: The status when the withdrawal order is being processed by the APM Gateway and the APM Gateway returns a ‘Pending’ status. This occurs when Nuvei contacts the APM provider and is waiting for a final response. Settled: The initial status of all requests. This indicates the transaction has not yet been processed. Deleted: The status of a withdrawal order that has been deleted. Error: Indicates an error occurred.
wdRequestId ^Integer(20)	ID of the withdrawal request generated by Nuvei.
wdOrderId ^Integer	ID of the withdrawal order generated by Nuvei.
merchantWDRequestId ^String	A unique ID that you generate for the withdrawal request.
merchantWDOrderId ^String	A unique ID that you generate for the withdrawal order.
userAccountId ^String	The customer’s Account ID on your site. The value of this parameter indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.
pmRedirectUrl ^String	If this parameter exists, you should redirect to the provided URL to complete the process with the third-party payment provider. This parameter is only relevant for payment methods that support withdrawals in redirect mode (such as Trustly).

sealRequest

Definition

1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdRequestId": 100,
    "merchantWDRequestId": "12345",
    "userAccountId": "12345",
    "operatorName": "Admin",
    "comment": "Some comment.",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": 0,
    "reason": "",
    "wdRequestStatus": "Approved",
    "wdRequestId": 8675309,
    "merchantWDRequestId": "741852",
    "userAccountId": "5675306"
}

When the amount of a withdrawal request to be returned to the customer is less than their original deposit, you can use this method to seal the deposit. Sealing a deposit means that in the Withdrawal API, the status of the deposit changes from “in progress” to “partial” and no further withdrawals can be made from the request.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/sealRequest.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/sealRequest.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
wdRequestId ^Integer(20) ~Required	A unique ID generated by Nuvei returned in the DMN for the request.
merchantWDRequestId ^String ~Required	A unique ID that you generate for the withdrawal order. This value must be unique. This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
timeStamp ^String ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.
userAccountId ^String ^Optional	The customer’s Account ID on your site. The value of this parameter indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.
operatorName ^String ^Optional	The name of the administrator of the request.
comment ^String ^Optional	The administrator’s comments regarding the transaction.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
version ^String	The version of the API call.
status ^String	Indicates if the API call was successful or not: Success: Successful result. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when an error occurs.
reason ^String	Reason an error occurred.
wdRequestStatus ^String	The current status of the withdrawal request: Pending: The initial status of all requests. This indicates the transaction has not yet been processed. Approved: The request was approved. Declined: You or the APM declined the transaction. Canceled: The customer canceled the request from the Withdraw page. Partially Approved: The request is partially approved. This is relevant for split requests only. Error: Indicates an error occurred.
wdRequestId ^Integer(20)	ID of the withdrawal request.
merchantWDRequestId ^String	A unique ID that you generate for the withdrawal request.
userAccountId ^String	The customer’s Account ID on your site. The value of this parameter indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.

Request Methods

submitRequest

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "230811147",
    "userId": "259",
    "userPMId": "3846",
    "deviceDetails":{ 
        "deviceType": "DESKTOP",
        "deviceName": "deviceName",
        "deviceOS": "deviceOS",
        "browser": "browser",
        "ipAddress": "192.168.2.38"
    },
    "userDetails":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "XXXX",
        "phone": "XXXX",
        "zip": "XXXX",
        "city": "XXXX",
        "countryCode": "XXXX",
        "state": "XXXX",
        "email": "[email protected]"
    },
    "amount": "10.55",
    "currency": "GBP",
    "merchantWDRequestId": "12345",
    "merchantUniqueId": "12345",
    "userAccountId": "12345",
    "customSiteName": "Merchant Site Name",
    "customField1": "1",
    "successUrl": "",
    "failUrl": "",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": 0,
    "reason": "",
    "wdRequestStatus": "Approved",
    "wdRequestId": 8675309,
    "merchantWDRequestId": "12345",
    "userId": "259",
    "userAccountId": "5675306",
    "pmRedirectUrl": ""
}

If you want to submit a request without redirecting your customer to the Withdrawal API, for example, through your own application directly to Nuvei, you can place the request through the submitRequest method.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/submitRequest.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/submitRequest.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
userTokenId ^String ~Required	This ID uniquely identifies your consumer/user in your system.
userPMId ^Long ~Required	ID of the payment methods the customer wants the funds withdrawn to.
amount ^Double ~Required	Amount of the withdrawal order.
currency ^String ~Required	The 3-letter ISO currency code of the request.
merchantWDRequestId ^String ~Required	A unique ID that you generate for the withdrawal order. This value must be unique. This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
merchantUniqueId ^String ~Required	This parameter is sent by the merchant and is used to associate a request with the merchant system. This value must be unique. This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
timeStamp ^String ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.
deviceDetails ^Class ~Only ipAddress	deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255) ipAddress (String, 15) – It can be defined as mandatory or non-mandatory as needed by Nuvei’s Integration Team.
userId ^String ^Optional	User ID you generate for the customer.
userDetails ^Class ^Optional	email (REQUIRED) firstName lastName address phone zip city countryCode state
userAccountId ^String ^Optional	The customer’s Account ID on your site. The value of this parameter indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.
customSiteName ^String ^Optional	The merchant site name that should replace the default MerchantSite name. This parameter is useful for merchants operating many websites that are distinguished only by name.
customFieldX ^String ^Optional	Fifteen custom parameters that you may use by replacing X with 1 to 15. The customFieldX that you have passed as the customFieldX parameter initially when making the first request to the Withdrawal API.
successUrl ^String ^Optional	URLs used when processing with a redirect payment option. Currently, only Trustly is supported as a redirect payment option. The URLs should be used when you wish to receive the result, upon which you have the option to close the popup (if such is opened in the first place) once the end user completes the process in the third-party payment provider’s page.
failUrl ^String ^Optional	URLs used when processing with a redirect payment option. Currently, only Trustly is supported as a redirect payment option. The URLs should be used when you wish to receive the result, upon which you have the option to close the popup (if such is opened in the first place) once the end user completes the process in the third-party payment provider’s page.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
version ^String	The version of the API call.
status ^String	Indicates if the API call was successful or not. Success: Successful result. Error: Unsuccessful result due to some technical failure, for example, the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when an error occurs.
reason ^String	Reason an error occurred.
wdRequestStatus ^String	The current status of the withdrawal request: Pending: The initial status of all requests. This indicates the transaction has not yet been processed. Approved: The request was approved. Declined: You or the APM declined the transaction. Canceled: The customer canceled the request from the Withdraw page. Partially Approved: The request is partially approved. This is relevant for split requests only. Error: Indicates an error occurred.
wdRequestId ^Integer(20)	ID of the withdrawal request generated by Nuvei.
merchantWDRequestId ^String	A unique ID that you generate for the withdrawal request.
userId ^String	An external user ID you generate for the customer. This ID is for your records and tracking purposes only.
userAccountId ^String	The customer’s Account ID on your site. Only you know this value and no validations are performed by Nuvei.
pmRedirectUrl ^String	If this parameter exists, you should redirect to the provided URL to complete the process with the third-party payment provider. This parameter is only relevant for payment methods that support withdrawals in redirect mode (such as Trustly).

getCandidatesForRefund

Definition

1
2
3
4
5
6
7
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdRequestId": 12345,
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "transactionDetailList":{
        "gwRelatedTransactionId": "8675309",
        "pmIssuer": "Visa",
        "pmName": "Credit Card",
        "pmDisplayName": "1111",
        "amount": "10.55",
        "remainingAmount": "1.55",
        "userPMId": "3846",
        "currency": "GBP",
        "transactionDate": "20180518040831",
        "email": "",
        "acquirereBankName": "",
        "convertedAmount": "",
        "convertedCurrency": "",
        "merchantSiteId": ""
    },
    "version": "1",
    "status": "Success",
    "errCode": 0,
    "reason": ""
}

This method returns a list of a customer’s approved deposits that had not been refunded or were only partially refunded up to the last six months according to their userId. The list of refund requests returned by the getCandidatesForRefund method includes the transactionId for the withdrawal request, the paymentMethodID, the payment method’s name, and the customer’s account information.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/getCandidatesForRefund.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/getCandidatesForRefund.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
wdRequestId ^Integer(20) ~Required	A unique ID generated by Nuvei returned in the DMN for the request.
timeStamp ^String ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
transactionsDetailList ^Class	gwRelatedTransactionId – Transaction ID of Gateway deposit transaction that can be refunded. pmIssuer – The credit card company that processed the original transaction. pmName – Type of the payment method (such as PayPal and credit card). pmDisplayName – For credit card, last four digits of the card number; for APMs, this value represents the user’s account name, such as PayPal email address or Neteller Secure ID. amount – Amount of original deposit transaction. remainingAmount – Remaining amount of money from the original transaction that can be returned. userPMId – A unique ID automatically generated by Nuvei that represents the payment method selected by the customer. currency – The currency used in the withdrawal. transactionDate – The original transaction date. email – The consumer email. acquirerBankName – The acquiring bank name. convertedAmount – The amount after currency conversion, if accrued. convertedCurrency – The currency after currency conversion, if accrued. merchantSiteId
version ^String	The version of the API call.
status ^String	Indicates if the API call was successful or not. Success: Successful result. Error: Unsuccessful result due to some technical failure, for example, the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when an error occurs.
reason ^String	Reason an error occurred.

getRequests

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdRequestOrderCount": "",
    "userTokenId": "230811147",
    "userId": "259",
    "wdRequestId": 8675309,
    "merchantWDRequestId": "12345",
    "merchantUniqueId": "852",
    "dateRange": {
        "fromDate": "201407100000",
        "toDate": "201407152359"
    },
    "statusList": "Approved",
    "stateList": "OPEN",
    "paymentMethodsList": "cc_card",
    "countryIsoList": "GB",
    "amountRange": {
        "fromAmount": "0",
        "toAmount": 1000,
        "Currency": "GBP"
    },
    "userRegistrationDateRange": {
        "fromDate": "2014071000000",
        "toDate": "201407152359"
    },
    "sortField": "requestedAmount",
    "sortOrder": "ASC: Ascending",
    "firstResult": "0",
    "maxResults": "10",
    "operatorName": "",
    "wdRequestOrderCountRange": {
        "from" : "2",
        "to": "5"
    },
    "merchantSiteIds": ["1212", "1225", "1287"],
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "merchantSiteName": "Any Site Name",
    "version": "1",
    "status": "Success",
    "errCode": 0,
    "reason": "",
    "withdrawalRequest": {
        "userTokenId": "",
        "userId": "",
        "userDetails": {
            "firstName": "John",
            "lastName": "Smith",
            "address": "XXXX",
            "phone": "XXXX",
            "zip": "XXXX",
            "city": "XXXX",
            "countryCode": "XXXX",
            "state": "XXXX",
            "email": "[email protected]"
        },
        "wdRequestId": "",
        "merchantWDRequestId": "",
        "userPMId": "",
        "approvedAmount": "",
        "merchantUniqueId": "",
        "requestedAmount": "",
        "requestedCurrency": "",
        "state": "",
        "wdRequestStatus": "",
        "wdRequestOrderCount": "",
        "pmName": "",
        "pmIssuer": "",
        "pmDisplayName": "",
        "creationDate": "",
        "lastModifiedDate": "",
        "dueDate": "",
        "withdrawalOrders":{
            "wdOrderId": "12345",
            "merchantWDOrderId": "",
            "pmName": "",
            "pmIssuer": "",
            "pmDisplayName": "",
            "amount": "",
            "currency": "",
            "settlementType": "",
            "gwRelatedTransactionId": "",
            "wdOrderStatus": "",
            "gwTrxId": "",
            "errorCode": "",
            "extendedErrorCode": "",
            "reasonCode": "",
            "apmTrxId": "",
            "apmErrorDetails": "",
            "apmErrorCode": "",
            "operatorName": "",
            "comment": "",
            "creationDate": "",
            "lastModifiedDate": "",
            "userPMId": "",
            "numOfPMs": "",
            "netDepositAmount": "",
            "gwReason": "",
            "gwStatus": "",
            "merchantUniqueId": "",
            "executionTime": "",
            "userPMData": ""
        }
    },
    "totalCount": "1"
}

The getRequests method returns a list of a customer’s withdrawal requests.
In the request, you define the criteria that determine which requests are returned. For example, through the statusList parameter, you can request that Nuvei only return Pending withdrawal requests.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/getRequests.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/getRequests.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
timeStamp ^String ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.
wdRequestId ^Integer(20) ^Optional	A unique ID generated by Nuvei returned in the DMN for the request.
merchantWDRequestId ^String ^Optional	A unique ID that you generate for the withdrawal order. This value must be unique.
merchantUniqueId ^String ^Optional	This parameter is sent by the merchant and is used to associate a request with the merchant system. This value must be unique.
wdRequestOrderCount ^String ^Optional	Retrieves only requests that have exactly <wdRequestOrderCount> number of orders. This parameter is overridden by the wdRequestOrderCountRange parameter (if it is present).
userTokenId ^String ^Optional	This ID uniquely identifies your consumer/user in your system.
userId ^String ^Optional	Your ID for the customer.
dateRange ^String ^Optional	Defines the date range of the requests you want to return.
statusList ^String ^Optional	Defines the statuses of the requests you want to return. Possible values: Approved Declined Pending In Progress Partially Approved Error
stateList ^String ^Optional	Defines the state of the requests you want to return. Possible values: OPEN IN_PROGRESS CLOSED
paymentMethodsList ^Array ^Optional	Contains an array of payment option IDs wrapped as a string.
countryIsoList ^Array ^Optional	Contains an array of 2-letter ISO country codes.
amountRange ^String ^Optional	Returns a list of requests within the defined amount range.
userRegistrationDateRange ^String ^Optional	Returns requests according to the date the customer registered.
sortField ^String ^Optional	Defines how the response is to be sorted. The permitted values include: requestedAmount requestedCurrency approvedAmount requestStatus state creationDate lastModifiedDate displayStatus
sortOrder ^String ^Optional	Defines how the sorted response is to be returned in descending or ascending order. The permitted values include: ASC: Ascending DESC: Descending
firstResult ^String ^Optional	Defines how many results are returned, for example, if you want to display only the first 10 records of the search result, then firstResult should be 10. If there is no firstResult, the default value is 0.
maxResults ^String ^Optional	Based on the search result set of records, you can define how many results to return. The value of the maxResults parameter determines maximum number of requests to be returned, for example, if you want to display only the first 10 records of the search result, then maxResult should be 10). If there is no maxResults, all the results defined for your request are returned.
operatorName ^String ^Optional	The name of the administrator of the requests.
wdRequestOrderCountRange ^JSON object ^Optional	Defines criteria for the number of orders – requests that have between “from” to “to” orders are included in the response. This returns only requests that have two or more orders, but not more than five orders.
merchantSiteIds ^Array ^Optional	An array of filter results by Merchant Site IDs. Only sites that belong to the merchant are allowed.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
merchantSiteName ^String	The name of the site in your account where the request originated.
version ^String	The version of the API call.
status ^String	Indicates if the API call was successful or not: Approved: Successful result. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when an error occurs.
reason ^String	Reason an error occurred.
withdrawalRequest ^Class	The order details of each withdrawal request.
totalCount ^String	Total number of requests returned.

Order Methods

getOrders

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "230811147",
    "userId": "6789",
    "wdOrderId": 12345,
    "wdRequestId": 8675309,
    "gwTrxId": "",
    "apmTrxId": "",
    "merchantWDOrderId": "",
    "merchantUniqueId": "",
    "dateRange": {
        "fromDate": "201407100000",
        "toDate": "201407152359"
    },
    "statusList": [
        "Approved"
    ],
    "requestDateRange": {
        "fromDate": "2014071000000",
        "toDate": "201407152359"
    },
    "requestAmountRange": {
        "fromAmount": "0",
        "toAmount": 1000,
        "Currency": "GBP"
    },
    "orderAmountRange": {
        "fromAmount": "0",
        "toAmount": 1000,
        "Currency": "GBP"
    },
    "userRegistrationDateRange": {
        "fromDate": "2014071000000",
        "toDate": "201407152359"
    },
    "requestStatusList": [
        "Approved"
    ],
    "requestPaymentMethod": "",
    "NumOfPMsRange": [
        "fromNumOfPMs",
        "toNumOfPMs"
    ],
    "NetDepositRange": [
        "fromNetDeposit",
        "toNetDeposit"
    ],
    "countryIsoList" :[
        "DE"
    ],
    "sortField": "approvedAmount",
    "sortOrder": "ASC",
    "paymentMethodList": "cc_card",
    "firstResult": "0",
    "maxResults": "0",
    "operatorName": "Any Name",
    "wdRequestOrderCountRange ": {
        "from": "0",
        "to": "5"
    },
    "merchantSiteIds": ["1212", "1225", "1287"],
    "executionTimeRange": {
        "fromDate": "201407100000",
        "toDate": "201407152359"
    },
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "merchantSiteName": "Any Site Name",
    "version": "1",
    "status": "Success",
    "errCode": 0,
    "reason": "",
    "orders": {
        "withdrawalOrder": {
            "wdOrderId": "",
            "merchantWDOrderId": "",
            "userPMId": "",
            "pmName": "",
            "pmIssuer": "",
            "pmDisplayName": "",
            "amount": "",
            "currency": "",
            "settlementType": "",
            "gwRelatedTransactionId": "",
            "wdOrderStatus": "",
            "gwTrxId": "",
            "errorCode": "",
            "extendedErrorCode": "",
            "reasonCode": "",
            "apmTrxId": "",
            "apmErrorDetails": "",
            "apmErrorCode": "",
            "operatorName": "",
            "numOfPM": "",
            "netDepositAmount": "",
            "comment": "",
            "creationDate": "",
            "lastModifiedDate": "",
            "gwReason": "",
            "gwStatus": "",
            "merchantUniqueId": "",
            "feeAmount": "",
            "executionTime": "",
            "userPMData": "",
            "withdrawalRequest": {
                "userTokenId": "",
                "userId": "",
                "userDetails": {
                     "firstName": "John",
                     "lastName": "Smith",
                     "address": "XXXX",
                     "phone": "XXXX",
                     "zip": "XXXX",
                     "city": "XXXX",
                     "countryCode": "XXXX",
                     "state": "XXXX",
                     "email": "[email protected]"
                },
                "wdRequestId": "",
                "merchantWDRequestId": "",
                "userPMId": "",
                "requestedAmount": "",
                "requestedCurrency": "",
                "state": "",
                "wdRequestStatus": "",
                "creationDate": "",
                "lastModifiedDate": "",
                "dueDate": "",
                "wdRequestOrderCount": "",
                "pmName": "",
                "pmIssuer": "",
                "pmDisplayName": "",
                "approvedAmount": "",
                "merchantUniqueId": "",
                "feeAmount": ""
            }
        }
    },
    "totalCount": "10"
}

The getOrders method returns a list of a customer’s withdrawal orders. In the request, you define the criteria that determine which orders are returned.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/getOrders.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/getOrders.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
merchantUniqueId ^String ~Required	This parameter is sent by the merchant and is used to associate a request with the merchant system. This value must be unique. This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
timeStamp ^String ~Required	The local time when the method call is performed in YYYYMMDDHHmmss format.
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.
userTokenId ^String ^Optional	This ID uniquely identifies your consumer/user in your system.
userId ^String ^Optional	The user ID given by the merchant to the customer.
wdOrderId ^Integer ^Optional	A unique ID generated by Nuvei returned in the DMN for the order.
wdRequestId ^Integer(20) ^Optional	A unique ID generated by Nuvei returned in the DMN for the request.
gwTrxId ^String ^Optional	The ID of the order provided by Nuvei’s Gateway.
apmTrxId ^String ^Optional	The ID of the order provided by an APM.
merchantWDOrderId ^String ^Optional	The order ID given by the merchant to the customer.
dateRange ^String ^Optional	Defines the date range of the requests you want to return. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmmss format.
statusList ^String ^Optional	Defines the statuses of the orders you want to return. Possible values: Approved Declined Pending In Progress Partially Approved Error
requestDateRange ^String ^Optional	Defines the date range of the requests you want to return. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmmss format.
requestAmountRange ^String ^Optional	Returns a list of requests within the defined amount range. This parameter consists of three values: “fromAmount”, “toAmount”, and “Currency”.
orderAmountRange ^String ^Optional	Returns a list of orders within the defined amount range. This parameter consists of three values: “fromAmount”, “toAmount”, and “Currency”.
userRegistrationDateRange ^String ^Optional	Returns orders according to the date range the customer registered. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmmss format.
requestStatusList ^Array ^Optional	An array that defines the statuses of the orders you want to return. Possible values: Approved Declined Pending In Progress Partially Approved Error
requestPaymentMethod ^String ^Optional	Contains payment option IDs wrapped as a string.
numOfPMsRange ^Array ^Optional	An array of the amount of the payment methods in a range. This value consists of a “fromNumOfPMs” value and a “toNumOfPMs” value.
netDepositRange ^Array ^Optional	An array of the net deposit range. This value consists of a “fromNetDeposit” value and a “toNetDeposit” value.
countryIsoList ^Array ^Optional	Contains an array of 2-letter ISO country codes.
sortField ^String ^Optional	Defines how the response is to be sorted. Possible values: requestedAmount requestedCurrency approvedAmount requestStatus state orderCreationDate orderLastModifiedDate displayStatus orderAmount orderCurrency orderStatus requestCreationDate requestLastModifiedDate UserId firstName + lastName email numOfPM NetDepositAmount
sortOrder ^String ^Optional	Defines how the sorted response is to be returned in descending or ascending order. ASC: Ascending DESC: Descending
paymentMethodsList ^String ^Optional	Defines the type of payment method used in the order.
firstResult ^String ^Optional	You can define a start position in the list of results that are returned. The value of this parameter defines how many results to omit from the start of the result list, for example, if you want to omit the first 10 records of the search result, then the firstResult should be 10. If there is no firstResult, the default value is 0.
maxResults ^String ^Optional	Based on the search result set of records, you can define how many results to return. The value of the maxResults parameter determines maximum number of requests to be returned, for example, if you want to display only the first 10 records of the search result, then maxResult should be 10). If there is no maxResults, all the results for your request are returned.
operatorName ^String ^Optional	The name of the administrator of the orders.
wdRequestOrderCountRange ^JSON object ^Optional	Include only orders for withdrawal requests that contain “from” and “to” values representing the number of orders.
merchantSiteIds ^Array ^Optional	An array of filter results by Merchant Site IDs. Only sites that belong to the merchant are allowed.
executionTimeRange ^String ^Optional	This defines the time range for execution. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmmss format.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
merchantSiteName ^String	The name of the site in your account where the request originated.
version ^String	The version of the API call.
status ^String	Indicates if the API call was successful or not. Success: Successful result. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when an error occurs.
reason ^String	Reason an error occurred.
orders ^Class	Details of the withdrawal orders and for each order its request details.
totalCount ^String	Total number of requests returned.

settleWithdrawalOrder

Definition

1
2
3
4
5
6
7
8
9
10
11
12
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdOrderId": 12345,
    "merchantWDOrderId": "12345",
    "userAccountId": "8675309",
    "triggerAutoSeal": "",
    "operatorName": "",
    "comments": "",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": 0,
    "reason": "",
    "wdRequestStatus": "Approved",
    "wdOrderStatus": "Settled",
    "wdRequestId": 8675309,
    "wdOrderId": 12345,
    "merchantWDRequestId": "12345",
    "merchantWDOrderId": "12345",
    "userAccountId": "96385271"
}

When a customer submits a withdrawal request that includes several withdrawal orders and you want to settle specific withdrawal orders in the request, you can specify which orders to settle through the settleWithdrawalOrder method. The settleWithdrawalOrder method settles a single order according the wdOrderID you send in the request. Nuvei then processes the request and returns a response.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/settleWithdrawalOrder.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/settleWithdrawalOrder.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
wdOrderId ^Integer ~Required	Request ID that the withdrawal order is related to.
timeStamp ^String ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.
merchantWDOrderId ^String ^Optional	A unique ID that you generate for the withdrawal order.
userAccountId ^String ^Optional	The customer’s Account ID on your site. The value of this parameter indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.
triggerAutoSeal ^String ^Optional	A flag, which, if false, overrides the auto seal functionality.
operatorName ^String ^Optional	The name of the administrator of the order.
comments ^String ^Optional	The administrator’s comments regarding the transaction.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
version ^String	The version of the API call.
status ^String	Indicates if the API call was successful or not. Success: Successful result. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when an error occurs.
reason ^String	Reason an error occurred.
wdRequestStatus ^String	The current status of the withdrawal request: Pending: The initial status of all requests. This indicates the transaction has not yet been processed. Approved: The request was approved. Declined: You or the APM declined the transaction. Canceled: The customer canceled the request from the Withdraw page. Partially Approved: The request is partially approved. This is relevant for split requests only. Error: Indicates an error occurred.
wdOrderStatus ^String	The current status of the withdrawal order: Pending: The initial status of all orders. This indicates the transaction has not yet been processed. Approved: The order was approved. Settling: The status when settleOrder is called. SettlingPending: The status when the withdrawal order is being processed by the APM Gateway and the APM Gateway returns a ‘Pending’ status. This occurs when Nuvei contacts the APM provider and is waiting for a final response. Settled: The initial status of all requests. This indicates the transaction has not yet been processed. Deleted: The status of a withdrawal order that has been deleted. Error: Indicates an error occurred.
wdRequestId ^Integer(20)	ID of the withdrawal request.
wdOrderId ^Integer	ID of the withdrawal order.
merchantWDRequestId ^String	A unique ID that you generate for the withdrawal request.
merchantWDOrderId ^String	A unique ID that you generate for the withdrawal order.
userAccountId ^String	The customer’s Account ID on your site. The value of this parameter indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.

getOrderIds

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "230811147",
    "userId": "6789",
    "wdOrderId": 12345,
    "wdRequestId": 8675309,
    "gwTrxId": "",
    "apmTrxId": "",
    "merchantWDOrderId": "",
    "merchantUniqueId": "",
    "dateRange": {
        "fromDate": "201407100000",
        "toDate": "201407152359"
    },
    "merchantSiteIds": ["1212", "1225", "1287"],
    "executionTimeRange" : {
        "fromDate": "201407100000",
        "toDate": "201407152359"
    },
    "statusList": [
        "Approved"
    ],
    "requestDateRange": {
        "fromDate": "201407100000",
        "toDate": "201407152359"
    },
    "requestAmountRange": {
        "fromAmount": "0",
        "toAmount": 1000,
        "Currency": "GBP"
    },
    "orderAmountRange": {
        "fromAmount": "0",
        "toAmount": 1000,
        "Currency": "GBP"
    },
    "userRegistrationDateRange": {
        "fromDate": "201407100000",
        "toDate": "201407152359"
    },
    "requestStatusList": [
        "Approved"
    ],
    "requestPaymentMethod": "Some method",
    "NumOfPMsRange": {
        "fromNumOfPMs": "0",
        "toNumOfPMs": "2"
    },
    "NetDepositRange": {
        "fromNetDeposit": "200",
        "toNetDeposit": "500"
    },
    "countryIsoList": [
        "DE"
    ],
    "sortField": "requestedAmount",
    "sortOrder": "ASC",
    "paymentMethodsList": "cc_card",
    "firstResult": "0",
    "maxResults": "0",
    "operatorName": "Any Name",
    "wdRequestOrderCountRange": {
        "from" : "0",
        "to" : "5"
    },
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "reason": "",
    "wdOrdersId": "",
    "totalCount": "10"
}

The getOrderIds method returns a list of your Order IDs per customer.

Through this method, you can retrieve the Order IDs and then settle those Orders through the settleOrderInBatch method.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/getOrderIds.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/getOrderIds.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
merchantUniqueId ^String ~Required	This parameter is sent by the merchant and is used to associate a request with the merchant system. This value must be unique. This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
timeStamp ^String ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.
userTokenId ^String ^Optional	This ID uniquely identifies your consumer/user in your system.
userId ^String ^Optional	The user ID given by the merchant to the customer.
wdOrderId ^Integer ^Optional	A unique ID generated by Nuvei returned in the DMN for the order.
wdRequestId ^Integer(20) ^Optional	A unique ID generated by Nuvei returned in the DMN for the request.
gwTrxId ^String ^Optional	The ID of the order provided by Nuvei’s Gateway.
apmTrxId ^String ^Optional	The ID of the order provided by an APM.
merchantWDOrderId ^String ^Optional	The order ID given by the merchant to the customer.
dateRange ^String ^Optional	Defines the date range of the requests you want to return. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmmss format.
merchantSiteIds ^Array ^Optional	An array of filter results by Merchant Site IDs. Only sites that belong to the merchant are allowed.
executionTimeRange ^String ^Optional	This defines the time range for execution of the transactions. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmmss format.
statusList ^String ^Optional	Defines the statuses of the orders you want to return. Possible values: Approved Settling Pending Settled Error Deleted Settling Externally Settled Externally
requestDateRange ^String ^Optional	Defines the date range of the requests you want to return. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmmss format.
requestAmountRange ^String ^Optional	Returns a list of requests within the defined amount range. This parameter consists of three values: “fromAmount”, “toAmount”, and “Currency”.
orderAmountRange ^String ^Optional	Returns a list of orders within the defined amount range. This parameter consists of three values: “fromAmount”, “toAmount”, and “Currency”.
userRegistrationDateRange ^String ^Optional	Returns orders according to the date range the customer registered. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmmss format.
requestStatusList ^Array ^Optional	An array that defines the statuses of the orders you want to return. Possible values: Approved Declined Pending In Progress Partially Approved Error
requestPaymentMethod ^String ^Optional	Contains payment option IDs wrapped as a string.
numOfPMsRange ^Array ^Optional	An array of the amount of the payment methods in range. This value consists of a “fromNumOfPMs” value and a “toNumOfPMs” value.
netDepositRange ^Array ^Optional	An array of the net deposit range. This value consists of a “fromNetDeposit” value and a “toNetDeposit” value.
countryIsoList ^Array ^Optional	Contains an array of 2-letter ISO country codes.
sortField ^String ^Optional	Defines how the response is to be sorted. Possible values: requestedAmount requestedCurrency approvedAmount requestStatus state orderCreationDate orderLastModifiedDate displayStatus orderAmount orderCurrency orderStatus requestCreationDate requestLastModifiedDate UserId firstName + lastName email numOfPM NetDepositAmount
sortOrder ^String ^Optional	Defines how the sorted response is to be returned in descending or ascending order. ASC: Ascending DESC: Descending
paymentMethodsList ^String ^Optional	Defines the type of payment method used in the order.
firstResult ^String ^Optional	You can define a start position in the list of results that are returned. The value of this parameter defines how many results to omit from the start of the result list, for example, if you want to omit the first 10 records of the search result, then the firstResult should be 10. If there is no firstResult, the default value is 0.
maxResults ^String ^Optional	Based on the search result set of records, you can define how many results to return. The value of the maxResults parameter determines maximum number of requests to be returned, for example, if you want to display only the first 10 records of the search result, then maxResult should be 10). If there is no maxResults, all the results for your request are returned.
operatorName ^String ^Optional	The name of the administrator of the order.
wdRequestOrderCountRange ^JSON Object ^Optional	Include only orders for withdrawal requests that contain “from” and “to” values representing the number of orders.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
version ^String	The version of the protocol.
status ^String	Indicates if the API call was successful or not. Possible values: Success: Successful result. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer	The error code in the event of an error.
reason ^String	Reason an error occurred.
wdOrderIds ^String	List of Order IDs returned.
totalCount ^String	Total number of orders returned according to the criteria you defined in the request.

settleOrdersInBatch

Definition

1
2
3
4
5
6
7
8
9
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdOrderIds": ["12345", "12346"],
    "operatorName": "",
    "comment": "",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": 0,
    "reason": "",
    "orders": "wdOrderId"
}

The settleOrdersInBatch method enables the merchant to settle a group of orders, as defined by the merchant, in one action. If you send any orders that have already been settled, Nuvei ignores those orders and settles only those that are eligible to be settled.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/settleOrdersInBatch.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/settleOrdersInBatch.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
wdOrderIds ^String ~Required	List of Order IDs returned.
timeStamp ^String ~Required	The local time when the method call is performed in the YYYYMMDDHHmmss format.
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.
operatorName ^String ^Optional	The name of the administrator of the order.
comment ^String ^Optional	The administrator’s comments regarding the transaction.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
version ^String	The version of the protocol.
status ^String	Indicates if the API call was successful or not. Success: Successful result. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when an error occurs.
reason ^String	Reason an error occurred.
orders ^String	Details of the settleOrdersInBatch orders and requests. Possible values: wdOrderId operationStatus operationReason errorCode

deleteWithdrawalOrder

Definition

1
2
3
4
5
6
7
8
9
10
11
12
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdOrderId": 12345,
    "merchantWDOrderId": "12345",
    "userAccountId": "8675309",
    "triggerAutoSeal": "",
    "operatorName": "",
    "comment": "",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": 0,
    "reason": "",
    "wdOrderId": 1234567890,
    "merchantWDOrderId": "12345",
    "userAccountId": "8675309"
}

The deleteWithdrawalOrder method deletes an order for withdrawal made by the customer.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/deleteWithdrawalOrder.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/deleteWithdrawalOrder.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
wdOrderId ^Integer ~Required	ID of the withdrawal order to be deleted.
timeStamp ^String ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.
merchantWDOrderId ^String ^Optional	ID of the merchant withdrawal order.
userAccountId ^String ^Optional	This is the end user’s account ID on the side of the merchant. No validations are performed from the Nuvei’s side.
triggerAutoSeal ^String ^Optional	A flag, which, if false, overrides the auto seal functionality.
operatorName ^String ^Optional	The name of the administrator of the order.
comment ^String ^Optional	Operator’s comment for the operation.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
version ^String	The version of the protocol.
status ^String	Indicates if the API call was successful or not. Success: Successful result. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when an error occurs.
reason ^String	Reason an error occurred.
wdOrderId ^Integer	ID of the withdrawal order that is being deleted.
merchantWDOrderId ^String	ID of the merchant withdrawal order.
userAccountId ^String	This is an End User’s account ID on the side of the merchant. No validations are performed from Nuvei’s side.

updateOrdersDetails

Definition

1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "5078248497400694938",
    "merchantSiteId": "142163",
    "wdOrderIds": [ "8625458" ],
    "operatorName": "John Smith",
    "details":{
        "executionTime": "202312141714"
    },
    "timeStamp": "20241214171227",
    "checksum": "9046df34de44cb4409079816e0d420d23fa06e2fc230367721c63edc9c99889d"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{

    "merchantId": "5078248497400694938",
    "merchantSiteId": "142163",
    "version": "1.0.0",
    "status": "SUCCESS",
    "orders": [
        {
            "wdOrderId": 8625468,
            "operationStatus": "SUCCESS",
            "operationReason": null,
            "errorCode": null
        }
    ]

}

The updateOrdersDetails enables the update of the order’s details.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/updateOrdersDetails.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/updateOrdersDetails.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
wdOrderIds ^Array ~Required	ID of the withdrawal in Nuvei’s system.
timeStamp ^String ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.
details ^Array ~Required	An array with the following attribute: executionTime (String, 50) in either yyyyMMdd or yyyyMMddHHmm format.
operatorName ^String ^Optional	The name of the administrator of the order.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
version ^String	The version of the API.
status ^String	Indicates if the API call was successful or not: Success: Successful result. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when an error occurs.
reason ^String	Reason an error occurred.
orders ^String	Details of the settleOrdersInBatch orders and requests. Possible values: wdOrderId operationStatus operationReason errorCode

Net Deposit Methods

The Net Deposit service allows customers to deposit funds across multiple payment methods through Cashier while at the same time protecting you from potential money laundering schemes. Each time a customer deposits funds through Cashier, the net deposit value for that UPO is increased. Each time a customer withdraws funds through Cashier, the new deposit value for that UPO is decreased. A UPO’s net deposit value is the sum of all deposits made with that UPO minus the sum of all withdrawals for that UPO.

For example, if a customer deposits to their account through UPO1 $50 and UPO2 $100, and withdraws $25 in UPO2, their total net deposit for UPO1 is $50 and for UPO2 $75.

	Deposits	Withdrawals	Net Deposit
UPO1	$50		$50
UPO2	$100	$25	$75

When your customer requests to withdraw funds from their account to a specific UPO, the funds are split first to all UPOs with positive net deposit values, and only the remainder is sent to the requested UPO.

Example 1:
In this example, the customer deposits funds via two UPOs, $50 through UPO1 and $100 through UPO2. The customer then withdraws $25 through UPO2 leaving a remaining net deposit of $75 for UPO2.
Later, the same customer wins $200 through your site and requests to withdraw those funds to UPO1. Nuvei first returns the net deposit of UPO1 and UPO2 before sending any additional funds beyond the original deposit to UPO1. The net deposits of UPO1 and UPO2 are returned leaving a remaining amount of $75 to be returned. This remaining amount is returned to UPO1.

	Deposits	Withdraws	Net Deposit
UPO1	$50		$50
UPO2	$100	$25	$75
Winnings	$200
Withdrawal Request to UPO1	$200
UPO1		$50	$0
UPO2		$75	$0
Remainder – to UPO1		$75

The net deposit functionality is designed to prevent money laundering where customers attempt to transfer funds between various UPOs. For example, if a customer deposits $10 through UPO1 and then $10,000 in UPO2, and subsequently tries to withdraw $10,000 through UPO1, Nuvei’s netDeposit functionality returns $10 to UPO1 and then the remaining $10,000 to UPO2.
Net deposits are calculated automatically by Nuvei per UPO. There are no integrations requirements involved on your side; however, Nuvei does expose several API methods in the event that you want to manage your customers’ net deposits. The deposit flow in Cashier in which the net deposit functionality is explained below:

1. Redirect your customer to Cashier with that customer’s user_token_id. For new customers, you generate the user_token_id, and for existing customers, you provide the ID you generated the first time you registered the customer.
2. When the customer submits their deposit, Nuvei generates a UPO ID for that payment method.

If the deposit is successful, the net deposit value for that UPO is increased. Nuvei returns a response that indicates if the transaction was successful.

getNetDeposits

Definition

1
2
3
4
5
6
7
8
9
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "230811147",
    "currency": "GBP",
    "userPMId": "12345",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "netDeposits":{
        "amount": "10.55",
        "currency": "GBP",
        "userPMId": "3846",
        "pmDisplayName": "1111",
        "pmName": "Credit Card",
        "pmIssuer": "Visa"
    },
    "version": "1",
    "status": "Success",
    "errCode": 0,
    "reason": ""
}

The getNetDeposits method returns a list of a customer’s net deposits. After invoking the getNetDeposits method, you can manually update your customers’ net deposits to allow them to withdraw funds to payment methods in which the withdraw amount exceeds the deposit amount made for a particular payment method.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/getNetDeposits.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/getNetDeposits.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
userTokenId ^String ~Required	This ID uniquely identifies your consumer/user in your system.
currency ^String ~Required	The currency of the net deposit.
userPMId ^Long ~Required	ID of the payment methods the customer wants the funds withdrawn to.
timeStamp ^String ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
netDeposits ^Class	amount – The net deposit amount for the transaction currency – The currency of the net deposit userPMId – ID of the user’s payment method. This value is used when updating a net deposit amount through the UpdateNetDepositValue method. pmDisplayName – For credit card, last four digits of the card number. Any other case an empty string is returned. pmName – Type of the payment method (such as PayPal and credit card). pmIssuer – The credit card company that processed the original transaction. If a credit card is not used, an empty string is returned.
version ^String	The version of the protocol.
status ^String	Indicates if the API call was successful or not. Possible values: Success: Successful result. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when an error occurs.
reason ^String	Reason an error occurred.

updateNetDepositValue

Definition

1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "230811147",
    "userPMId": "12345",
    "amount": "10.55",
    "movementType": "4",
    "currency": "GBP",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": 0,
    "reason": ""
}

The updateNetDepositValue enables you to update a customer’s net deposit.
Through this method, you can manually update your customers’ net deposits to allow them to withdraw funds to payment methods in which the withdraw amount exceeds the deposit amount made for a particular payment method.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/updateNetDepositValue.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/updateNetDepositValue.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
userTokenId ^String ~Required	This ID uniquely identifies your consumer/user in your system.
userPMId ^Long ~Required	ID of the payment methods the customer wants the funds withdrawn to.
amount ^Double ~Required	The amount to be added to the net deposit amount. For example, $50.00 means $50 is added to the net deposit in addition to the existing net deposit amount.
movementType ^String ~Required	The type of movement. Possible values: 1 – Deposit 2 – Manual Deposit 3 – Manual Withdrawal 4 – Withdrawal Order
currency ^String ~Required	The currency of the amount being applied to the net deposit.
timeStamp ^String ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
version ^String	The version of the protocol.
status ^String	Indicates if the API call was successful or not. Possible values: Success: Successful result. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when an error occurs.
reason ^String	Reason an error occurred.

getUserPaymentMethodNetDeposits

Definition

1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "230811147",
    "currency": "GBP",
    "country": "GB",
    "userPMId": "8675309",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userPaymentMethods":{
        "pmName": "Credit Card",
        "pmIssuer": "Visa",
        "userId": "259",
        "pmDisplayName": "1111",
        "upoStatus": "0"
    },
    "version": "1",
    "status": "Success",
    "errCode": 0,
    "reason": ""
}

The getUserPaymentMethodNetDeposits enables the receipt of the net deposits per user payment method.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/withdrawal/getUserPaymentMethodNetDeposits.do

@Test https://ppp-test.nuvei.com/ppp/api/withdrawal/getUserPaymentMethodNetDeposits.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^Long ~Required	Your unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required	Your website’s unique identification number provided by Nuvei.
userTokenId ^String ~Required	This ID uniquely identifies your consumer/user in your system.
currency ^Double ~Required	The 3-letter ISO currency code of the currency of the request.
userPMId ^String ~Required	The unique ID automatically generated by Nuvei, which represents the payment the method selected by the customer.
timeStamp ^String ~Required	The local time when the method call is performed in YYYYMMDDHHmmss format.
checksum ^Hexadecimal String ~Required	The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. Press here for more information.
country ^String ^Optional	2-letter ISO country code of the customer.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
userPaymentMethods ^Class	userPaymentMethod contains: pmName: Type of the payment method (such as PayPal and credit card). pmIssuer: The credit card company that processed the original transaction. If a credit card is not used, an empty string is returned. userId: Customer’s ID for the payment method. pmDisplayName: For credit card, last four digits of the card number; for APMs, this value represents the user’s account name, such as PayPal email address or Neteller Secure ID. upoStatus: Indicates if the payment method is suspended for the user. 0 is returned for active payment methods, 1 for suspended payment methods. When a payment method is suspended the customer cannot process transactions through that payment method.
version ^String	The version of the protocol.
status ^String	Indicates if the API call was successful or not: Success: Successful result. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer	Error code when an error occurs.
reason ^String	Reason an error occurred.

Pre-chargeback

Pre-chargeback Overview

To prevent and manage disputes and to fight fraud, merchants can enroll in pre-chargeback programs via Nuvei. These programs offer ways to handle potential chargebacks before they become actual chargebacks. One of these programs is Ethoca Alerts (by Mastercard). For transactions processed by Nuvei, merchants can respond to alerts in Nuvei’s Control Panel, or can set a rule to automatically refund transactions up to a threshold amount. For transactions not processed by Nuvei, merchants can use the /preDisputeDecision method to handle Ethoca alerts.

/preDisputeDecision

Endpoint URL

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "alertDetails":{
        "correlationId":"35b82abb-0c13-4d1d-bc2c-8f3e7d056835",
        "alertReceivedDate":"2018-02-27T04:33:04.000Z"
    },
    "decisionDetails":{
        "decisionDescription":"previously_refunded",
        "refundIndicator":"refunded"
    },
    "timeStamp":"20240915143321",
    "checksum":"1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "internalRequestId": 2543543,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "version": "1.0",
    "alertDetails": {
        "correlationId": "35b82abb-0c13-4d1d-bc2c-8f3e7d056835",
        "alertReceivedDate": "2018-02-27T04:33:04.000Z"
    },
    "decisionDetails": {
        "decisionDescription": "previously_refunded",
        "refundIndicator": "refunded"
    },
    "result": {
        "status": "success"
    }
}

This method allows merchants to update their decision based on Ethoca alerts for transactions not processed by Nuvei. Upon receiving an alert, merchants have a 48-hour window before a chargeback occurs, during which they can send their decision regarding the case to Ethoca and halt the chargeback process.

Press here for more information.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/preDisputeDecision.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/preDisputeDecision.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
alertDetails ^Class ~Required	correlationId (String, REQUIRED) – The identifier of the related Ethoca alert, as received in the alert from Ethoca, to which the merchant responds. alertReceivedDate (String, REQUIRED) – The date of the related Ethoca alert, as received in the alert from Ethoca, to which the merchant responds.
decisionDetails ^Class ~Required	decisionDescription (String, REQUIRED) – The merchant decision on the alert. Press here to see the list of possible decisions. refundIndicator (String, REQUIRED) – An indicator stating the refund-related status of the related transaction, as provided by the merchant. Press here to see the list of possible values.
timeStamp ^String(14) ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, timeStamp, decisionDescription, merchantSecretKey Press here to see an example.

Output Parameters

Parameter	Description
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter. Press here to see the list of error codes.
reason ^String(400)	If an error occurred on the request side, an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter. Press here to see the list of error reasons.
version ^String(10)	The current version of the request. The current version is 1.
alertDetails ^Class	correlationId (String) – The identifier of the related Ethoca alert, as received in the alert from Ethoca, to which the merchant responds. alertReceivedDate (String) – The date of the related Ethoca alert, as received in the alert from Ethoca, to which the merchant responds.
decisionDetails ^Class	decisionDescription (String) – The merchants decision on the alert. Press here to see the list of possible decisions. refundIndicator (String) – An indicator stating the refund-related status of the related transaction, as provided by the merchant. Press here to see the list of possible values.
result ^Class	status (String) – Response status from Ethoca. Possible values: success, failure errors (Class)  code (Integer) – Error code when the response status from Ethoca is failure.  reason (String) – Error reason when the response status from Ethoca is failure.

KYC API

KYC Overview

Know your customer (KYC) is the process of a business identifying and verifying the identity of its clients as part of due diligence requirements. The objective of KYC guidelines is to prevent financial institutions from being used, intentionally or unintentionally, by criminal elements for money laundering activities.

Nuvei’s anti-money laundering (AML) and electronic KYC (eKYC) solutions enable businesses to quickly and easily identify high-risk applicants and manage them appropriately. Our electronic identity checks help organizations meet their KYC and AML obligations when new accounts are created and when existing consumers need to be checked.
This method can be used for initiating a real time electronic identity check/Pep and Sanctions (politically exposed persons and financial sanctions) checks via multiple leading providers.

Preliminary KYC Verification Requirements

Prior to initializing KYC verification, be sure to invoke the /createUser method for generating a userTokenID since this is a required parameter for any KYC check.

Interpreting KYC Results

The KYC transaction results can be interpreted by a combination of the transaction result (technical) and the KYC result (business).

• eKYC verification results are derived from the provider’s response regarding the number of matches among the name, address and date of birth and other data sources.
• Document verification results are derived from the list of issues detected in the uploaded proof-of-identity images.

Please note that a proof of residence is always returned with “Review” as the KYC result since this type of documentation cannot be verified by nature. For a list of possible issues, see Issue Types under getDocumentUploadUrl.

Transaction Results

• Approved – The transaction was finalized as successful following a provider asynchronous notification.
• Pending – The transaction was initialized successfully but is still pending on an asynchronous notification by the provider. Once a notification is sent a correction is updated in the system.
• Declined – The transaction was finalized as unsuccessful following a provider asynchronous notification.
• Error – The transaction could not be completed due to technical errors.

KYC Result

• Approve – It is recommended to allow the customer to progress and update the end user’s KYC status accordingly.
• Error – The verification could not be accomplished due to technical errors.
• Review – It is recommended to manually review the details and decide regarding the end user’s KYC status.
• Reject – It is recommended to update the end user’s KYC status accordingly.
• None – Verification could not be performed at the provider side. It is recommended to revise the request parameters.

eKYC

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "230811147",
    "userId": "259",
    "clientUniqueId": "12345",
    "clientRequestId": "100",
    "deviceDetails": {
        "deviceType": "DESKTOP",
        "deviceName": "deviceName",
        "deviceOS": "deviceOS",
        "browser": "browser",
        "ipAddress": "ipAddress"
    },
    "userDetails": {
        "firstName": "John",
        "lastName": "Smith",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "[email protected]",
        "county": ""
    },
    "ekycUserDetails": {
        "userName": "someUserName",
        "languageCode": "eng",
        "dateOfBirth": "1985-01-01",
        "title": "Mr.",
        "gender": "male",
        "building": "123",
        "mobileCountryCode": "01",
        "mobileNumber": "8675309",
        "identification": "12345",
        "identificationType": "sometype"
    },
    "bankingDetails": {
        "accountHolderName": "John Smith",
        "payId": "[email protected]",
        "payIdType": "Email"
  },
    "merchantDetails": {
        "customField1": "",
        "customField2": ""
    },
    "urlDetails": {
        "notificationUrl": ""
    },
    "customData": "",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/eKYC.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
    "clientRequestId": "100",
    "internalRequestId": 12345,
    "status": "SUCCESS",
    "orderId": "39272",
    "transactionId": "1000030724",
    "transactionStatus": "APPROVED",
    "merchantDetails": {
        "customField1": "",
        "customField2": ""
    },
    "customData": "",
    "kycResult": "APPORVED",
    "kycServiceDetails": [{
        "serviceDescription": "",
        "subPoviderDescription": "",
        "resultDescription": "",
        "referenceId": "",
        "rawProviderData":
        {
        }
    }],
    "ownerName": "Moneytech ABN",
    "kycErrorCode": "",
    "kycErrorReason": "",
    "errCode": "",
    "reason": "",
    "legalName": "{\"sandbox\":true,\"type\":\"KY5\",\"userId\":\"7AF5FEC5B6DDCDF4A085A943BE436555\",\"email\":\"[email protected]\",\"user\":\"bf0da85bf82932eef21acfa734b6f605\",\"campaign\":\"6ac0ff3c6957b6f8e5d0813f52689ce3\",\"entityId\":1,\"iat\":1720159230,\"exp\":1720245630,\"KYC\":{\"registered_for_autodeposit\":true,\"legal_name\":{\"first_name\":\"John\",\"last_name\":\"Smith\"}}}"
}

eKYC stands for “electronic KYC”, which enables performing the entire KYC process online.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/eKYC.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/eKYC.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system.
userId ^String(20) ~Required	Name of the user in the merchant system.
clientUniqueId ^String(45) ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
userDetails ^Class ~Required	firstName (REQUIRED)(String, 30) lastName (REQUIRED)(String, 50) address (REQUIRED)(String, 50) phone (String, 18) zip (REQUIRED)(String, 10) city (String, 30) country (REQUIRED, String, 2) – 2-letter ISO country code state (String, 2) – (2-letter ISO state code) email (REQUIRED)(String, 100) county
ekycUserDetails ^Class ~Required	userName (String) languageCode (String) dateOfBirth (REQUIRED, in YYYY-MM-DD format)(String, 10) title (String) gender (String) building (REQUIRED)(String) mobileCountryCode (String) mobileNumber (String) identification identificationType (String) The possible values for identificationType are: PassportNumber, NationalId, DrivingLicense. building should be populated with house number or building name.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, timeStamp, merchantSecretKey.
deviceDetails ^Class ^Optional	deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255) ipAddress (String, 15)
ekycType ^String(255) ^Optional	This parameter controls the sub-checks category of the eKYC required in the API call. Bureau – Performs eKYC check that validates a name against an address and date of birth PEP_Sanctions – Performs Pep & sanctions checks (politically exposed persons and sanctions lists lookup) All – Performs both Bureau and Pep & sanctions checks
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response. It is not passed to the payments gateway and is not used for processing.
urlDetails ^Class ^Optional	notificationUrl (String, 1000) This parameter determines where to return the DMN. Each parameter is limited for up to 1000 characters.
customData ^String(255) ^Optional	This parameter can be used to pass any type of information. If sent in request, then is passed on to the payments gateway, is visible in Nuvei’s back office tool transaction reporting and is returned in response.
bankingDetails ^Class ^Optional	AccountHolderName (String) – Name associated with the bank account. PayId – Mobile phone number, email address, ABN/ACN, or Organisation Identifier. PayIdType – Possible values: ABN, Email, PhoneNumber, OrganisationId, ACN Press here for more information.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
clientUniqueId ^String(45)	The unique transaction ID in the merchant system.
clientRequestId ^String(255)	The unique ID of the API request in the merchant system.
internalRequestId ^Integer(20)	The Nuvei Internal unique request ID, used for reconciliation purposes, etc.).
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
orderId ^String(20)	The order ID provided by Nuvei.
transactionId ^String(20)	The gateway transaction ID.
transactionStatus ^String(20)	The gateway transaction status. This parameter indicates the successful processing of the transaction, and has no implication on the consumer’s KYC analysis.
merchantDetails ^Class	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response. It is not passed to the payments gateway and is not used for processing.
customData ^String(255)	This parameter can be used to pass any type of information. If sent in request, then is passed on to the payments gateway, is visible in Nuvei’s back office tool transaction reporting and is returned in response.
KYCResult ^String	The result of the consumer’s KYC analysis. Possible values: APPROVED DECLINED REVIEW NONE
kycServiceDetails ^Class	serviceDescription subPoviderDescription resultDescription referenceId rawProviderData – The structure of this parameter is different for each eKYC provider.
kycErrorCode ^String	The KYC related error code.
kycErrorReason ^String	The KYC related error description.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^String(10)	The current version of the request. The current version is 1.
ownerName ^String	The financial institution that owns the PayID account.
legalName ^String	Contains all of the information from the account.

getDocumentUploadUrl

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "230811147",
    "userId": "259",
    "clientUniqueId": "12345",
    "clientRequestId": "100",
    "userDetails": {
        "firstName": "John",
        "lastName": "Smith",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "[email protected]",
        "county": ""
    },
    "kycUserDetails": {
        "userName": "someUserName",
        "dateOfBirth": "1985-01-01",
        "title": "Mr.",
        "gender": "male",
        "building": "123",
        "postcode": "71937",
        "mobileCountryCode": "01",
        "mobileNumber": "8675309"
    },
    "merchantDetails": {
        "customField1": "",
        "customField2": ""
    },
    "urlDetails": {
        "successUrl": "",
        "failureUrl": ""
    },
    "merchantLocale": "",
    "themeId": "",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/getDocumentUploadUrl.do', // the methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "url": "",
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
    "clientRequestId": "100",
    "internalRequestId": 12345,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "version": "1.0"
}

As part of the KYC process, customers are required to send personal documents to verify their identity.
This method return a URL that enables the uploading of these documents easily to help complete the KYC process quickly and securely.
The URL can be opened either via redirect or via IFrame, which directs the user to an upload wizard where a prompt appears to upload the required documents according to the merchant policy. Once the request is sent, Nuvei sends the merchant a DMN as its response.
The feature supports both Desktop and Mobile browsers.
Nuvei detects and displays the relevant Proof of ID documents based on the provider’s coverage for the end user’s country.

Document Retrieval

Transaction related documents can be retrieved and reviewed on demand via the Control Panel using the KYC Checks Report.

@Links URLs

@Live https://secure.safecharge.com/ppp/api/v1/getDocumentUploadUrl.do

@Test https://ppp-test.nuvei.com/ppp/api/v1/getDocumentUploadUrl.do

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system.
userId ^String(20) ~Required	Name of the user in the merchant system.
clientUniqueId ^String(45) ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
userDetails ^Class ~Required	firstName (String, 30) lastName (String, 50) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 2) – 2-letter ISO state code) email (REQUIRED)(String, 100) county (String, 255)
kycUserDetails ^Class ~Required	userName (String) dateOfBirth (in YYYY-MM-DD format)(String, 10) title (String) gender (String) building (String) postcode (String) mobileCountryCode (String) mobileNumber (String) building should be populated with house number or building name.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, timeStamp, merchantSecretKey.
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level which is not passed to the payments gateway and is not used for processing.
urlDetails ^Class ^Optional	successUrl (String, 1000) failureUrl (String, 1000) Each parameter is limited for up to 1000 characters.
merchantLocale ^String(5)	The default language. The current default value is English (for example: en_US).
themeId ^String ^Optional	This parameter is configured per merchant site but if sent as input it overrides the configuration and the themeId chosen is presented.

Output Parameters

PARAMETER	DESCRIPTION
url ^String	The document upload page url including parameters. For example: https://secure.SafeCharge.com/ppp/documentupload.do?merchant_id=427583496191624621&merchant_site_id=142033&…
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
internalRequestId ^Integer(20)	The Nuvei Internal unique request ID, used for reconciliation purposes, etc.

Issue Types (for document upload only)

The following table lists the possible issues that may arise from the document upload process. Where applicable, the appropriate issue code(s) is returned in the DMN.

ISSUE TYPE ID	DESCRIPTION
1	The ID document is expired.
2	The image quality is not sufficient. Please submit a new image.
3	The ID has two sides. Please submit images of both front and back.
4	Unable to determine ID type.
5	Comparison of printed data with MRZ (machine-readable zone) – unexpected result.
6	The ID type is not accepted for this transaction.
7	The age requirement is not met.
8	The image file type is not supported.
9	The image file size is not supported.
10	Document integrity issue – unexpected result.
11	ePassport photo – unexpected result.
12	Liveness checks – undetermined.
13	Unable to determine the ID’s expiration date.
14	UK DL No. – unexpected result.
15	Unable to validate DL No.
16	ePassport data – unexpected result.
17	DL (US) data – unexpected result.
18	Unable to confirm consistency of ID data across Face Data, MRZ (machine-readable zone) and/or Barcode.
19	ID data – unexpected result.
20	Composite check-digit – unexpected result.
21	Geolocation data not available.
22	MRZ (machine-readable zone) data – unexpected result
23	eChip authentication – unexpected authentication result.
24	eChip data – unexpected data result.
25	The document’s face data is unavailable for comparison.

KYC in Payment Page

KYC services, such as eKYC and document verification, can be utilized not only using server to server calls as mentioned above, but also as part of Nuvei’s Payment Page flow, which can be called with the kyc request parameter.

Nuvei’s Payment Page offers a few flows in which KYC can be embedded:

- Pre-deposit – The configured KYC service(s) is executed before a consumer attempts to deposit. If all KYC services executed fail, the consumer is notified in the UI and the deposit does not take place.
- Post deposit – The configured KYC service(s) is executed after a consumer attempts to deposit.
- Pre-withdrawal – The configured KYC service(s) is executed before a consumer attempts to withdraw. If all KYC services executed failed, the consumer is notified in the UI and the withdrawal does not take place. For more information, please refer to the Withdrawal Integration section.

The KYC result is sent to merchants using the KYC Direct Merchant Notification (DMN). If it is configured to receive such notifications, it is able to use this information for their consumers’ management.

The KYC hosted flows and the KYC services that are activated need to be configured for merchants per their choice during integration phase.

For more information, please contact Nuvei’s Integration Team.

Input Parameters

PARAMETER	DESCRIPTION
kyc ^String(255) ^Optional	This parameter determines the point in time in the customer’s life cycle at which the merchant would like to initiate automated KYC checks. Possible values: preDeposit – KYC is checked before a user places a deposit. After successful verification, the user is automatically re-directed to the Nuvei cashier deposit page postDeposit – KYC is checked after a user places a successful deposit preWithdrawal – KYC is checked upon a user placing a Withdrawal request NOTE: When a merchant wishes to perform a check in the customer’s registration process without a redirection to the deposit page afterwards, the eKYC.do API method should be used.
ekycFlow ^String(255) ^Optional	This parameter describes the business logic layer of the KYC checks, allowing a merchant to perform one of the following: EKYC_ONLY – Perform only this type DOC_VER_ONLY – Perform only this type FULL – Always do both CASCADING or empty value – Do both only in a case of a fallback (cascading direction is always from eKYC to document verification)
ekycType ^String(255) ^Optional	This parameter controls the sub-checks category of the eKYC required in the API call. Bureau – Performs eKYC check that validates a name against an address and date of birth PEP_Sanctions – Performs Pep & sanctions checks (politically exposed persons and sanctions lists lookup) All – Performs both Bureau and Pep & sanctions checks

KYC DMN Response Parameters

The following table contains a list of KYC DMN parameters that Nuvei sends to the merchant server.

PARAMETER	DESCRIPTION
merchantId ^String ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String ~Required	This ID uniquely identifies your consumer/user in your system.
type ^String ~Required	The type of KYC verification. Possible values: Document verification eKYC
clientUniqueId ^String ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
clientRequestId ^String ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
internalRequestId ^Integer ~Required	The Nuvei Internal unique request ID, used for reconciliation purposes, etc.
status ^String ~Required	The cashier status of merchant request. Possible statuses: SUCCESS ERROR
transactionId ^String ~Required	The gateway transaction ID.
providerReferenceId ^String ~Required	The transaction ID as received from the KYC provider.
transactionStatus ^String ~Required	The gateway transaction status. Possible values: APPROVED DECLINED ERROR
merchantDetails ^Class ~Required	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response.
KYCResult ^String ~Required	The description of the KYC result. Possible values: APPROVED DECLINED REVIEW NONE
orderId ^String ^Optional	The order ID provided by Nuvei.
ageCheck ^String ^Optional	The result of the age verification.
redirectUrl ^String ^Optional	The URL used by the merchant to redirect consumers to the payment method for authentication and authorization of the payment. This is required for document upload.
KYCServiceDetails ^Class ^Optional	These details are relevant only for eKYC. service subProvider result referenceId rawProviderData rawProviderData is an object with string data elements (e.g. raw data), which vary among providers.
kycErrorCode ^String ^Optional	The KYC related error code.
kycErrorReason ^String ^Optional	The KYC related error description.
errCode ^Integer ^Optional	Error code if error occurred at the cashier side.
reason ^String ^Optional	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the request side.
version ^Sting ^Optional	The version of your request. The current version is 1.
userInfo ^Class ^Optional	The users personal information. userName languageCode countryCode firstName lastName address city state zip email phone dateOfBirth title userId userTokenId gender buildingName postcode mobileCountryCode mobileNumber identification identificationType
transactionIssues ^Class ^Optional	The issues that arose from the transaction. description decision
documents ^Class ^Optional	The document details. id documentId type category KYCResult (REQUIRED) status documentData (Class) – Consists of forenames, surname, fullName, dateOfBirth, gender, nationality, placeOfBirth, documentDescription, documentNumber, dateOfIssue, dateOfExpiry, issuingCountry, addressLine1, addressLine2, addressLine3, addressLine4, addressCity, addressState, addressPostcode, addressCountry, issuer.
documentIssues ^Class ^Optional	Issues that have arisen in the document upload. description decision