Navbar
JSON Node.JS java php C#

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:

/cardTokenization

Definition

https://ppp-test.nuvei.com/ppp/api/v1/cardTokenization.do
Example Request
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":"john.smith@email.com",
        "country":"US"
    }
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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) Session identifier returned by /getSessionToken.
internalRequestId ^String(20) SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
status ^String(20) The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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 ^Integer(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

https://ppp-test.nuvei.com/ppp/api/v1/getMerchantPaymentMethods.do
Example Request
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":"20151105021120",
    "checksum":"6133d0fd12e90ff8de5d8ab5e52a8c23"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 field is used to prevent 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 ID of the API request in merchant’s 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 merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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.

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

https://ppp-test.nuvei.com/ppp/api/v1/createUser.do
Example Request
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": "testUserToken",
    "clientRequestId": "100",
    "firstName": "John",
    "lastName": "Smith",
    "address": "some street",
    "state": "",
    "city":"",
    "zip":"",
    "countryCode": "GB",
    "phone":"",
    "locale": "en_UK",
    "email": "john.smith@test.com",
    "dateOfBirth": "",
    "county":"",
    "timeStamp": "20150915143321",
    "checksum": "21bc2501b7857059862124a5d04c9ade"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 The ID of the user in the merchant’s system.
clientRequestId ^String(255) ~Required Based on the merchant configuration, this field is used to prevent 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(2) ^Optional The 2-letter 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’s system.
status ^String(20) The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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

https://ppp-test.nuvei.com/ppp/api/v1/updateUser.do
Example Request
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": "testUserToken",
     "firstName": "John",
     "lastName": "Smith",
     "address": "some street",
     "state": "",
     "city": "London",
     "zip":"",
     "countryCode": "GB",
     "phone":"",
     "locale": "en_UK",
     "email": "john.smith@test.com",
     "dateOfBirth": "",
     "county":"",
     "timeStamp": "20150915143421",
     "checksum": "b47f85bf3a06f5971b38b16e74b230a0"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 The ID of the user in the merchant’s system.
clientRequestId ^String(255) ~Required Based on the merchant configuration, this field is used to prevent 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(2) ^Optional The 2-letter 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’s system.
status ^String(20) The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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

https://ppp-test.nuvei.com/ppp/api/v1/getUserDetails.do
Example Request
1
2
3
4
5
6
7
8
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "testUserToken",
    "clientRequestId": "101",
    "timeStamp": "20150915143921",
    "checksum": "03aab7ddc2d551ee672632c4a3c56902"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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": "john.smith@test.com",
        "locale": "",
        "birthdate": "",
        "userTokenId": "testUserToken",
        "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 The ID of the user in the merchant’s system.
clientRequestId ^String(255) ~Required Based on the merchant configuration, this field is used to prevent 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’s 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, 2)
email (String, 100)
locale
birthdate (String, 10)
userTokenId (String, 255)
userId(String, 20)
county (String, 255)
status ^String(20) The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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

https://ppp-test.nuvei.com/ppp/api/v1/addUPOCreditCard.do
Example Request
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":"testUserToken",
    "clientRequestId": "235",
    "ccCardNumber": "5101080963349948",
    "ccExpMonth": "01",
    "ccExpYear": "2020",
    "ccNameOnCard": "test name",
    "billingAddress":{
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "countryCode": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "externalTokenProvider": {
        "externalTokenProvider":"",
        "externalTokenData":"",
        "cardType":"",
        "isDecryptService":""
    },
    "timeStamp": "20150915151435",
    "checksum": "2e9084f71d45487a417c0efbb9bdd58a"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 The ID of the user in the merchant’s system.
clientRequestId ^String(255) ~Required Based on the merchant configuration, this field is used to prevent 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, 2) – 2-letter ISO state code.
email (String, 100)
county (String, 255)
externalTokenProvider ^Class ^Optional externalTokenProvider (String, 45)
externalTokenData (String, 255)
cardType (String, 45)
isDecryptService (String, 1)

External token provider is a type of entity in the payment industry with its own flow. For example: Visa Checkout.
For Visa Checkout it is required to pass on the values:
externalTokenProvider – “VisaCheckout”,
externalTokenData – The callId received from Visa,
cardType – “CardToken” or “PAN” depend on the card type relevant for current request,
isDecryptService – 1.
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’s system.
status ^String(20) The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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 – visa, visa electron
Amex – amex
MasterCard – master_card
bankcard – bankcard
UnionPay – china_union
Diners – diners, diners_club_carte_blanche, diners_club_enroute, diners_club_international, diners_club_us_and_canada
Discover – discover_card
JCB – jcb
LaserCard – laser
Maestro – maestro
SOLO – solo
SWITCH – switch
Entropay – entropay, entropay_visa, entropay_master_card
IsraeliCard – israeli_card
Mir – mir
Dankort – dankort
DankortVisa – dankort_visa
UATP – uatp
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

https://ppp-test.nuvei.com/ppp/api/v1/addUPOCreditCardByToken.do
Example Request
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": "487106",
    "clientRequestId": "110",
    "ccExpMonth": "12",
    "ccExpYear": "24",
    "ccNameOnCard": "John Smith",
    "ccToken":"ZQBxAEgAawBpAHEAcwBkACQAcAB2AGcAcQAlAFkAYQBcACwAdQBHAD0ATwB4AE8AKwA4AE8ALQA9ACMAZABsADgAeAArAEcAdwAvAGkAQAAzAA==",
    "brand": "Visa",
    "uniqueCC": "aL+zlvNa84dvxQlmWz3COgkwqrE=",
    "bin": "411111",
    "last4Digits": "1111",
    "billingAddress":{
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "countryCode": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "lastDepositUse":"",
    "lastDepositSuccess":"",
    "lastWithdrawalUse":"",
    "lastWithdrawalSuccess":"",
    "registrationDate":"",
    "expiryDate":"",
    "timeStamp": "20150915161438",
    "checksum": "f84c4e7e7d5aa1e83cd785100746bafc"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 The ID of the user in the merchant’s system.
clientRequestId ^String(255) ~Required Based on the merchant configuration, this field is used to prevent 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) ~Required The brand of the credit card. Possible values:
Visa – visa, visa electron
Amex – amex
MasterCard – master_card
bankcard – bankcard
UnionPay – china_union
Diners – diners, diners_club_carte_blanche, diners_club_enroute, diners_club_international, diners_club_us_and_canada
Discover – discover_card
JCB – jcb
LaserCard – laser
Maestro – maestro
SOLO – solo
SWITCH – switch
Entropay – entropay, entropay_visa, entropay_master_card
IsraeliCard – israeli_card
Mir – mir
Dankort – dankort
DankortVisa – dankort_visa
UATP – uatp
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, 2) – 2-letter 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’s 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 merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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

https://ppp-test.nuvei.com/ppp/api/v1/addUPOCreditCardByTempToken.do
Example Request
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": "487106",
    "clientRequestId": "110",
    "ccTempToken":"ZQBxAEgAawBpAHEAcwBkACQAcAB2AGcAcQAlAFkAYQBcACwAdQBHAD0ATwB4AE8AKwA4AE8ALQA9ACMAZABsADgAeAArAEcAdwAvAGkAQAAzAA==",
    "billingAddress":{
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "timeStamp": "20150915161438",
    "checksum": "f84c4e7e7d5aa1e83cd785100746bafc"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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",
    "useTokenId":"",
    "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 The ID of the user in the merchant’s system.
clientRequestId ^String(255) ~Required Based on the merchant configuration, this field is used to prevent 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, 2) – 2-letter 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’s 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 merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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

https://ppp-test.nuvei.com/ppp/api/v1/addUPOAPM.do
Example Request
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": "testUserToken",
    "clientRequestId": "43",
    "paymentMethodName": "apmgw_expresscheckout",
    "apmData": {
        "email": "user@mail.com"
    },
    "billingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "22 Main Street",
        "phone": "6175551414",
        "zip": "02460",
        "city": "Boston",
        "country": "US",
        "state": "MA",
        "email": "john.smith@email.com",
        "county":"Suffolk"
    },
    "timeStamp": "20150915153043",
    "checksum": "fb4641d3abe02bc309bd746f77bbf0d3ab9fa24c405f1027e4cbce888405e053"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 The ID of the user in the merchant’s system.
clientRequestId ^String(255) ~Required Based on the merchant configuration, this field is used to prevent 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 block.
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, 2) – 2-letter 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’s 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 merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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

https://ppp-test.nuvei.com/ppp/api/v1/editUPOCC.do
Example Request
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": "testUserToken",
    "clientRequestId": "4556",
    "userPaymentOptionId": "741",
    "ccExpMonth": "12",
    "ccExpYear": "24",
    "ccNameOnCard": "John Smith",
    "billingAddress":{
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "countryCode": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "timeStamp": "20150915155818",
    "checksum": "5d99ee468cd33c0b87d0dc2fc7585376"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 The ID of the user in the merchant’s system.
clientRequestId ^String(255) ~Required Based on the merchant configuration, this field is used to prevent 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, 2) – 2-letter 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’s system.
status ^String(20) The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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

https://ppp-test.nuvei.com/ppp/api/v1/editUPOAPM.do
Example Request
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": "testUserToken",
    "clientRequestId": "43",
    "userPaymentOptionId": "743",
    "apmData": {
        "account_id": "userA@mail.com"
    },
    "billingAddress":{
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "countryCode": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "timeStamp": "20150915160424",
    "checksum": "71b589416aba502be1521e1ce6b94726"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 The ID of the user in the merchant’s system.
clientRequestId ^String(255) ~Required Based on the merchant configuration, this field is used to prevent 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 block.

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, 2) – 2-letter 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’s system.
status ^String(20) The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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

https://ppp-test.nuvei.com/ppp/api/v1/deleteUPO.do
Example Request
1
2
3
4
5
6
7
8
9
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "testUserToken",
    "clientRequestId": "108",
    "userPaymentOptionId": "742",
    "timeStamp": "20150915151243",
    "checksum": "c2f1ccf85719ba0a69022c7753e9ba9b"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 The ID of the user in the merchant’s system.
clientRequestId ^String(255) ~Required Based on the merchant configuration, this field is used to prevent 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’s system.
status ^String(20) The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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

https://ppp-test.nuvei.com/ppp/api/v1/getUserUPOs.do
Example Request
1
2
3
4
5
6
7
8
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "testUserToken",
    "clientRequestId": "107",
    "timeStamp": "20150915151231",
    "checksum": "aa7566ab686602fe38a62d40d796bb01"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": "58",
    "clientRequestId": "107",
    "status":"SUCCESS",
    "errCode": "0",
    "reason" : "",
    "version": "1",
    "paymentMethods": [ {
        "userPaymentOptionId": "741",
        "paymentMethodName":"cc_card",
        "upoName":"(1111)",
        "upoRegistrationDate":"",
        "upoRegistrationTime": "",
        "upoStatus": "enabled",
        "expiryDate": "",
        "billingAddress":{
            "firstName": "some first name",
            "lastName": "some last name",
            "phone": "972502457558",
            "address": "some street",
            "zip": "",
            "city": "some city",
            "countryCode": "GB",
            "state": "",
            "email": "someemail@somedomain.com",
            "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": "user@mail.com",
        "upoRegistrationDate":"",
        "upoRegistrationTime": "",
        "upoStatus ": "suspended",
        "expiryDate": "",
        "billingAddress":{
            "firstName": "some first name",
            "lastName": "some last name",
            "address": "some street",
            "phone": "972502457558",
            "zip": "",
            "city": "some city",
            "country": "GB",
            "state": "",
            "email": "someemail@somedomain.com",
            "county":""
        },
        "upoData": {
            "account_id": "user@mail.com"
            }
        }]
}

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 The ID of the user in the merchant’s system.
clientRequestId ^String(255) ~Required Based on the merchant configuration, this field is used to prevent 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.

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’s system.
status ^String(20) The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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.
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 fields, 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, 2) – 2-letter ISO state code.
    email (String, 100)
    county (String, 255)
upoData (Class) – This block 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.
Please refer to APM Input Fields and APIs for more information.
issuerCountry ^String(2) The 3-letter ISO currency code of the card issuer’s country.

/suspendUPO

Definition

https://ppp-test.nuvei.com/ppp/api/v1/suspendUPO.do
Example Request
1
2
3
4
5
6
7
8
9
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "testUserToken",
    "clientRequestId": "109",
    "userPaymentOptionId": "743",
    "timeStamp": "20150915160842",
    "checksum": "a7b8817a0b761c11c756512366305595"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 The ID of the user in the merchant’s system.
clientRequestId ^String(255) ~Required Based on the merchant configuration, this field is used to prevent 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’s system.
status ^String(20) The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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

https://ppp-test.nuvei.com/ppp/api/v1/enableUPO.do
Example Request
1
2
3
4
5
6
7
8
9
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "testUserToken",
    "clientRequestId": "135",
    "userPaymentOptionId": "743",
    "timeStamp": "20150915205412",
    "checksum": " 1c5343ba85154d4416855737d4e6888a"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 The ID of the user in the merchant’s system.
clientRequestId ^String(255) ~Required Based on the merchant configuration, this field is used to prevent 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’s system.
status ^String(20) The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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

https://ppp-test.nuvei.com/ppp/api/v1/addBankAccount.do
Example Request
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":"john.smith@email.com",
        "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"
    }
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 ID of the transaction in the merchant’s 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 field is used to prevent 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’s 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, 2) – 2-letter 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 ID of the transaction in the merchant’s system.
clientRequestId ^String(255) The ID of the API request in merchant’s 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’s system.
status ^String(20) The cashier status of merchant request.
Possible values: SUCCESS, ERROR
errCode ^String(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 ^String(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

https://ppp-test.nuvei.com/ppp/api/v1/enrollAccount.do
Example Request
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":"john.smith@email.com",
        "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":"mhsbg.xxnbx@udapl.rg",
        "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":"sgkuy.tzizt@eabeq.bq",
        "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":"mhsbg.xxnbx@udapl.rg",
        "phone":"359888526527",
        "address":"222333 Peachtree Place",
        "city":"Atlanta",
        "country":"US",
        "state":"GA",
        "zip":"30318",
        "cell":"359881526527",
        "county":null,
        "addressMatch":"N",
        "addressLine2":"Billing Addres Line 2",
        "addressLine3":"Billing Addres 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":"sgkuy.tzizt@eabeq.bq",
        "county":"UCounty",
        "language":"en",
        "dateOfBirth":"1975-02-22",
        "identification":"112223333"
    }
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 ID of the transaction in the merchant’s 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 field is used to prevent 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’s 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, 2) – 2-letter 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, 2) – 2-letter 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, 2) – 2-letter 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 ID of the transaction in the merchant’s system. For a direct API request, use the same value in /getDocumentUrl and /enrollAccount calls.
clientRequestId ^String(20) The ID of the API request in merchant’s 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’s 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 merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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 ^String(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 3-letter 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

https://ppp-test.nuvei.com/ppp/api/v1/fundAccount.do
Example Request
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":"john.smith@email.com",
        "county":"Suffolk",
        "language":"en",
        "dateOfBirth":"1972-06-02",
        "identification":"987456982"
    },
    "urlDetails":{
        "notificationUrl":"https:///merchant.url/interactionsCompleted"
    }
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 ID of the transaction in the merchant’s 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 field is used to prevent 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’s 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, 2) – 2-letter 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 ID of the transaction in the merchant’s system.
clientRequestId ^String(20) The ID of the API request in merchant’s 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’s 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 merchant’s API request/call.
Possible statuses: SUCCESS or ERROR.
errCode ^String(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 ^String(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

https://ppp-test.nuvei.com/ppp/api/v1/getAccountDetails.do
Example Request
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":"john.smith@email.com",
        "county":"Suffolk",
        "language":"en",
        "dateOfBirth":"1972-06-02",
        "identification":"987456982"
    }
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 ID of the transaction in the merchant’s 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 field is used to prevent 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’s 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, 2) – 2-letter 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 ID of the transaction in the merchant’s system.
clientRequestId ^String(20) The ID of the API request in merchant’s 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’s 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 merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^String(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 ^String(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

https://ppp-test.nuvei.com/ppp/api/v1/getDocumentUrl.do
Example Request
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"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 ID of the transaction in the merchant’s 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 field is used to prevent 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 The ID of the user in the merchant’s 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 ID of the transaction in the merchant’s system.
clientRequestId ^String(20) The ID of the API request in merchant’s 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’s 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 ^String(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.
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

Definition

https://ppp-test.nuvei.com/ppp/api/v1/createPlan.do
Example Request
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": "20191209121236",
    "checksum": "038c3c0009081e848c4812e573fe679f" 
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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

Request 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

https://ppp-test.nuvei.com/ppp/api/v1/editPlan.do
Example Request
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": "20191209121225",
    "checksum": "0661ef048083f96bd31cbd70f4e2d6a2"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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

Request 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

https://ppp-test.nuvei.com/ppp/api/v1/getPlansList.do
Example Request
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": "20191209121218",
    "checksum": "f7a0aec563dc52b41397f153f27449a3"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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

Request 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 fields + “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

https://ppp-test.nuvei.com/ppp/api/v1/createSubscription.do
Example Request
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": "20191209121255",
    "checksum": "2ca0a41a55128b1b5babb74cd0ff6fc0"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 block 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

Request 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 parameter is a unique identifier for each customer generated by the Merchant.
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

https://ppp-test.nuvei.com/ppp/api/v1/editSubscription.do
Example Request
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": "20191209121246",
    "checksum": "4289d93d4202bf414e07df85a09d5181"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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

Request 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

https://ppp-test.nuvei.com/ppp/api/v1/getSubscriptionsList.do
Example Request
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": "EUR"
    },
    "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": "20191209121200",
    "checksum": "336ae3123a017254b70840ff0fe62b46"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON

Example Response

1
2
3
4
{
    "total": 0,
    "status": "SUCCESS"
}

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

Request 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’s 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 parameter is a unique identifier for each customer generated by the Merchant.
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 fields + “null” to rest of them returns all the records in DB where the valid value is available.

/cancelSubscription

Definition

https://ppp-test.nuvei.com/ppp/api/v1/cancelSubscription.do
Example Request
1
2
3
4
5
6
7
{
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "subscriptionId": "935031",
    "timeStamp": "20191209121259",
    "checksum": "516722e70a68e587edea4b30a6a438a2"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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

Request 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)

Request Parameters

Parameter Description
checksum ^Hexadecimal String ~Required Checksum.
country ^String ~Required Country.
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.
merchant_id ^String ~Required The ID of the merchant in Nuvei system.
userid ^String ^Optional User ID in Nuvei system.
phone1 ^String ^Optional Phone.
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.
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.
merchant_site_id ^String ~Required The ID of the merchant site provided by Nuvei.
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.
version ^String ~Required Nuvei API version.
user_token_id ^String ~Required The ID of the user in merchant’s system.
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



c

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:

Cashier Rebilling Page Example

NovoDesktopRebilling

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 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

https://ppp-test.nuvei.com/ppp/api/withdrawal/approveRequest.do
Example Request
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": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 ^Long ~Required A unique ID generated by Nuvei and returned in the initial DMN of the withdrawal 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 who approved 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 ^String 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.
Cancelled: The customer cancelled 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 ^Long ID of the withdrawal request generated by Nuvei.
wdOrderId ^Long 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

https://ppp-test.nuvei.com/ppp/api/withdrawal/cancelRequest.do
Example Request
1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "12345",
    "wdRequestId": "100",
    "merchantWDRequestId": "12345",
    "userAccountId": "8675309",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 parameter is a unique identifier for each customer generated by the merchant.
wdRequestId ^Long ~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 ^String 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.
Cancelled: The customer cancelled 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 ^Long 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

https://ppp-test.nuvei.com/ppp/api/withdrawal/declineRequest.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "12345",
    "wdRequestId": "100",
    "merchantWDRequestId": "12345",
    "userAccountId": "8675309",
    "operatorName": "Admin",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 ^Long ~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 who approved 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 ^String 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.
Cancelled: The customer cancelled 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 ^Long 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

https://ppp-test.nuvei.com/ppp/api/withdrawal/placeWithdrawalOrder.do
Example Request
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": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 ^Long ~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’s 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 who approved 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 ^String 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.
Cancelled: The customer cancelled 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 ^Long ID of the withdrawal request generated by Nuvei.
wdOrderId ^Long 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

https://ppp-test.nuvei.com/ppp/api/withdrawal/sealRequest.do
Example Request
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": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 ^Long ~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 who approved 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 ^String 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.
Cancelled: The customer cancelled 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 ^Long 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.

Requests Methods

submitRequest

Definition

https://ppp-test.nuvei.com/ppp/api/withdrawal/submitRequest.do
Example Request
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": "12345",
    "userId": "259",
    "userPMId": "3846",
    "deviceDetails":{ 
        "deviceType":"DESKTOP",
        "deviceName":"deviceName",
        "deviceOS":"deviceOS",
        "browser":"browser",
        "ipAddress":"192.168.2.38"
    },
    "userDetails":{
        "firstName": "John",
        "lastName": "Adams",
        "address": "XXXX",
        "phone": "XXXX",
        "zip": "XXXX",
        "city": "XXXX",
        "countryCode": "XXXX",
        "state": "XXXX",
        "email": "john.adams@email.com"
    },
    "amount": "10.55",
    "currency": "GBP",
    "merchantWDRequestId": "12345",
    "merchantUniqueId": "12345",
    "userAccountId": "12345",
    "customSiteName": "Merchant's Site Name",
    "customField1": "1",
    "successUrl": "",
    "failUrl": "",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 parameter is a unique identifier for each customer generated by you.
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’s 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 firstName
lastName
address
phone
zip
city
countryCode
state
email (REQUIRED)
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’s 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 fields 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 ^String 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.
Cancelled: The customer cancelled 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 ^Long 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

https://ppp-test.nuvei.com/ppp/api/withdrawal/getCandidatesForRefund.do
Example Request
1
2
3
4
5
6
7
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdRequestId": "12345",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 ^String ~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 (TransactionMainId – ID of Gateway deposit transaction that can be refunded),
pmIssuer (the credit card company that processed the original transaction),
pmName (the name of the payment method, credit card, PayPal etc.),
pmDisplayName (for credit cards: last 4 digits; for Alternative Payment Methods: AccountID),
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 ^String Error code when an error occurs.
reason ^String Reason an error occurred.

getRequests

Definition

https://ppp-test.nuvei.com/ppp/api/withdrawal/getRequests.do
Example Request
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": "8675309",
    "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": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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": "Adams",
            "address": "XXXX",
            "phone": "XXXX",
            "zip": "XXXX",
            "city": "XXXX",
            "countryCode": "XXXX",
            "state": "XXXX",
            "email": "john.adams@email.com"
        },
        "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 ^Long ^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. This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
merchantUniqueId ^String ^Optional This parameter is sent by the merchant and is used to associate a request with the merchant’s 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.
wdRequestOrderCount ^String ^Optional Retrieve only requests that have exactly / number of orders. This parameter is overridden by the wdRequestOrderCountRange parameter (if it is present)
userTokenId ^String ^Optional This parameter is a unique identifier for each customer generated by you.
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 maxResult 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 maxResult, all the results for defined by your request are returned.
operatorName ^String ^Optional The operatorName of the withdrawal 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 ^String Error code when an error occurs.
reason ^String Reason an error occurred.
withdrawalRequest ^Class Details of the withdrawal requests and for each requests its order details.
totalCount ^String Total number of requests returned.

Orders Methods

getOrders

Definition

https://ppp-test.nuvei.com/ppp/api/withdrawal/getOrders.do
Example Request
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": "555",
    "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": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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": "Adams",
                     "address": "XXXX",
                     "phone": "XXXX",
                     "zip": "XXXX",
                     "city": "XXXX",
                     "countryCode": "XXXX",
                     "state": "XXXX",
                     "email": "john.adams@email.com"
                },
                "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’s 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 parameter is a unique identifier for each customer generated by you.
userId ^String ^Optional The user ID given by the merchant to the customer.
wdOrderId ^Long ^Optional A unique ID generated by Nuvei returned in the DMN for the order.
wdRequestId ^Long ^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 include:
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 include:
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 include:
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 maxResult 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 maxResult, all the results for your request are returned.
operatorName ^String ^Optional The operatorName 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 ^String 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

https://ppp-test.nuvei.com/ppp/api/withdrawal/settleWithdrawalOrder.do
Example Request
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": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 ^Long ~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 who approved the request.
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 ^String 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.
Cancelled: The customer cancelled 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 ^Long ID of the withdrawal request.
wdOrderId ^Long 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

https://ppp-test.nuvei.com/ppp/api/withdrawal/getOrderIds.do
Example Request
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": "555",
    "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": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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’s 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 parameter is a unique identifier for each customer generated by you.
userId ^String ^Optional The user ID given by the merchant to the customer.
wdOrderId ^Long ^Optional A unique ID generated by Nuvei returned in the DMN for the order.
wdRequestId ^Long ^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 include:
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 include:
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 include:
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 maxResult 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 maxResult, all the results for your request are returned.
operatorName ^String ^Optional The name of the administrator who approved the request.
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 include:
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 ^String 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

https://ppp-test.nuvei.com/ppp/api/withdrawal/settleOrdersInBatch.do
Example Request
1
2
3
4
5
6
7
8
9
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdOrderIds": ["12345", "12346"],
    "operatorName": "",
    "comment": "",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 who approved 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 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 ^String Error code when an error occurs.
reason ^String Reason an error occurred.
orders ^String Details of the settleOrdersInBatch orders and requests.
Possible values include:
wdOrderId
operationStatus
operationReason
errorCode

deleteWithdrawalOrder

Definition

https://ppp-test.nuvei.com/ppp/api/withdrawal/deleteWithdrawalOrder.do
Example Request
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": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 ^Long ~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’s 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 Name of the operator deleting 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 ^String Error code when an error occurs.
reason ^String Reason an error occurred.
wdOrderId ^Long ID of the withdrawal order that is being deleted.
merchantWDOrderId ^String ID of the merchant’s 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

https://ppp-test.nuvei.com/ppp/api/withdrawal/updateOrdersDetails.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "5078248497400694938",
    "merchantSiteId": "142163",
    "wdOrderIds": [ "8625458" ],
    "operatorName": "John Smith",
    "details":{
        "executionTime": "202312141714"
    },
    "timeStamp": "20231214171227",
    "checksum": "9046df34de44cb4409079816e0d420d23fa06e2fc230367721c63edc9c99889d"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 Name of the operator settling 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 ^String Error code when an error occurs.
reason ^String Reason an error occurred.
orders ^String Details of the settleOrdersInBatch orders and requests.
Possible values include:
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

https://ppp-test.nuvei.com/ppp/api/withdrawal/getNetDeposits.do
Example Request
1
2
3
4
5
6
7
8
9
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "12345",
    "currency": "GBP",
    "userPMId": "12345",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 parameter is a unique identifier for each customer generated by you.
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 cards, the value is the last four digits of the card number (**********1111). Any other case an empty string is returned.
pmName – Type of the payment method (such as PayPal and Credit Card)
pmIssuer – Credit card name. 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 ^String Error code when an error occurs.
reason ^String Reason an error occurred.

updateNetDepositValue

Definition

https://ppp-test.nuvei.com/ppp/api/withdrawal/updateNetDepositValue.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "12345",
    "userPMId": "12345",
    "amount": "10.55",
    "movementType": "4",
    "currency": "GBP",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 parameter is a unique identifier for each customer generated by the merchant.
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 ^String Error code when an error occurs.
reason ^String Reason an error occurred.

getUserPaymentMethodNetDeposits

Definition

https://ppp-test.nuvei.com/ppp/api/withdrawal/getUserPaymentMethodNetDeposits.do
Example Request
1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "12345",
    "currency": "GBP",
    "country": "GB",
    "userPMId": "8675309",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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 parameter is a unique identifier for each customer generated by you.
currency ^Double ~Required The 3-letter ISO currency code of the currency of the request.
country ^String ~Required ISO country code of the customer.
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.

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: Name of the payment method, for example, PayPal or Credit Card.
pmIssuer: Credit card name. 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 (…..1111). 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 ^String Error code when an error occurs.
reason ^String Reason an error occurred.
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 parameter since this is a required field 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).


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

KYC Result

eKYC

Definition

https://ppp-test.nuvei.com/ppp/api/v1/eKYC.do
Example Request
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
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "testUserToken",
    "userId": "259",
    "clientUniqueId": "12345",
    "clientRequestId": "100",
    "deviceDetails": {
        "deviceType": "DESKTOP",
        "deviceName": "deviceName",
        "deviceOS": "deviceOS",
        "browser": "browser",
        "ipAddress": "ipAddress"
    },
    "userDetails": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "ekycUserDetails": {
        "userName": "someUserName",
        "languageCode": "eng",
        "dateOfBirth": "1985-01-01",
        "title": "Mr.",
        "gender": "male",
        "building": "123",
        "mobileCountryCode": "01",
        "mobileNumber": "8675309",
        "identification": "12345",
        "identificationType": "sometype"
    },
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "urlDetails": {
        "notificationUrl": ""
    },
    "customData":"",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
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
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "testUserToken",
    "clientUniqueId": "12345",
    "clientRequestId": "100",
    "internalRequestId": "12345",
    "status": "SUCCESS",
    "orderId":"39272",
    "transactionId": "1000030724",
    "transactionStatus": "APPROVED",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "customData":"",
    "kycResult": "APPORVED",
    "kycServiceDetails": [{
        "serviceDescription": "",
        "subPoviderDescription": "",
        "resultDescription": "",
        "referenceId": "",
        "rawProviderData":
        {
        }
    }],
    "kycErrorCode": "",
    "kycErrorReason": "",
    "errCode": "",
    "reason": ""
}

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 ID of the user in merchant’s system.
userId ^String(20) ~Required Name of the user in merchant’s system.
clientUniqueId ^String(45) ~Required The ID of the transaction in the merchant’s 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 field is used to prevent 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)
customField2 (String, 255)
customField3 (String, 255)
customField4 (String, 255)
customField5 (String, 255)
customField6 (String, 255)
customField7 (String, 255)
customField8 (String, 255)
customField9 (String, 255)
customField10 (String, 255)
customField11 (String, 255)
customField12 (String, 255)
customField13 (String, 255)
customField14 (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.

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) The ID of the user in merchant’s system.
clientUniqueId ^String(45) The ID of the transaction in merchant’s system.
clientRequestId ^String(255) The ID of the API request in merchant’s system.
internalRequestId ^Integer(20) The Nuvei Internal unique request ID, used for reconciliation purposes, etc.).
status ^String(20) The status of merchant’s 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)
customField2 (String, 255)
customField3 (String, 255)
customField4 (String, 255)
customField5 (String, 255)
customField6 (String, 255)
customField7 (String, 255)
customField8 (String, 255)
customField9 (String, 255)
customField10 (String, 255)
customField11 (String, 255)
customField12 (String, 255)
customField13 (String, 255)
customField14 (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

rawProviderData fields structure is different for each eKYC provider.
kycErrorCode ^String The KYC related error code.
kycErrorReason ^String The KYC related error description.
errCode ^String(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.

getDocumentUploadUrl

Definition

https://ppp-test.nuvei.com/ppp/api/v1/getDocumentUploadUrl.do
Example Request
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
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "testUserToken",
    "userId": "259",
    "clientUniqueId": "12345",
    "clientRequestId": "100",
    "userDetails": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "kycUserDetails": {
        "userName": "someUserName",
        "dateOfBirth": "1985-01-01",
        "title": "Mr.",
        "gender": "male",
        "building": "123",
        "postcode": "71937",
        "mobileCountryCode": "01",
        "mobileNumber": "8675309"
    },
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "urlDetails": {
        "successUrl": "",
        "failureUrl": ""
    },
    "merchantLocale": "",
    "themeId": "",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
Example Request
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);
    });
});
Example Request
1
COMING SOON
Example Request
1
COMING SOON
Example Request
1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "url":"",
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "testUserToken",
    "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’s 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 ID of the user in merchant’s system.
userId ^String(20) ~Required Name of the user in merchant’s system.
clientUniqueId ^String(45) ~Required The ID of the transaction in the merchant’s 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 field is used to prevent 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)
customField2 (String, 255)
customField3 (String, 255)
customField4 (String, 255)
customField5 (String, 255)
customField6 (String, 255)
customField7 (String, 255)
customField8 (String, 255)
customField9 (String, 255)
customField10 (String, 255)
customField11 (String, 255)
customField12 (String, 255)
customField13 (String, 255)
customField14 (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) The ID of the user in merchant’s system.
clientUniqueId ^String(255) The ID of the transaction in merchant’s system.
clientRequestId ^String(20) The ID of the API request in merchant’s 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 The ID of the user in the merchant’s system.
type ^String ~Required The type of KYC verification.
Possible values:
Document verification
eKYC
clientUniqueId ^String ~Required The ID of the transaction in the merchant’s 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 field is used to prevent 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
customField2
customField3
customField4
customField5
customField6
customField7
customField8
customField9
customField10
customField11
customField12
customField13
customField14
customField15
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 ^String ^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 (this is a class and 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