We changed, SafeCharge becomes Nuvei.
Navbar
JSON Node.JS java php C#

Additional Services Home

Introduction

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

Payment Options API

Payment Option Methods

Using our User Payment Option (UPO) feature, 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.

/getMerchantPaymentMethods

Definition

https://ppp-test.safecharge.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
2
3
4
5
6
var response = safecharge.GetMerchantPaymentMethods(
    "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
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
{
    "sessionToken": "",
    "merchantId": "",
    "merchantSiteId": "",
    "clientRequestId": "",
    "internalRequestId": "",
    "paymentMethods": [
      {
        "paymentMethod": "cc_card",
        "paymentMethodDisplayName": [
          {
            "language": "en",
            "message": "Credit Card"
          }
        ],
        "isDirect": "true",
        "countries": [
          "US",
          "DE"
        ],
        "currencies": [
          "USD"
        ],
        "logoURL": "",
        "fields": [
          {
            "name": "ccCardNumber",
            "regex": "",
            "type": "text",
            "validationmessage": [
              {
                "language": "en",
                "message": "Invalid Card Number"
              }
            ],
            "caption": [
              {
                "language": "en",
                "message": "Card Number"
              }
            ]
          },
          {
            "name": "ccExpMonth",
            "regex": "",
            "type": "text",
            "validationmessage": [
              {
                "language": "en",
                "message": "Invalid Expiration Month"
              }
            ],
            "caption": [
              {
                "language": "en",
                "message": "Card Expiration Month"
              }
            ]
          },
          {
            "name": "ccExpYear",
            "regex": "",
            "type": "text",
            "validationmessage": [
              {
                "language": "en",
                "message": "Invalid Expiration Year"
              }
            ],
            "caption": [
              {
                "language": "en",
                "message": "Card Expiration Year"
              }
            ]
          },
          {
            "name": "ccNameOnCard",
            "regex": "",
            "type": "text",
            "validationmessage": [
              {
                "language": "en",
                "message": "Invalid Name on Card"
              }
            ],
            "caption": [
              {
                "language": "en",
                "message": "Cardholder name as it appears on your credit card"
              }
            ]
          }
        ]
      }
    ],
    "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.safecharge.com/ppp/api/v1/getMerchantPaymentMethods.do

Input Parameters

PARAMETER DESCRIPTION
sessionToken ^String(36) ~Required Session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required Merchant ID provided by Nuvei.
merchantSiteId ^Integer(20) ~Required Merchant Site ID provided by Nuvei.
clientRequestId ^String(255) ~Required ID of the API request in merchant system. This value must be unique.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
currencyCode ^String(20) ^Optional The three-letter ISO currency code that the transaction is to be completed in.
countryCode ^String(2) ^Optional The two-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.
timeStamp ^String(14) ~Required The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^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.

Output Parameters

PARAMETER DESCRIPTION
sessionToken ^String(36) Session identifier returned by /getSessionToken.
merchantId ^String(20) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
clientRequestId ^String(20) ID of the API request in merchant system.
internalRequestID ^String(20) Nuvei Internal unique request ID (used for reconciliation purposes, etc.).
paymentMethods ^Class paymentMethod(String, 50)
paymentMethodDisplayName {language(String, 2), message(String, 400)},
isDirect(String, 5)
countries(String, 2)
currencies(String, 3)
logoURL(String, 255)

fields:
name(String, 45)
regex(String, 128)
type(String, 45)
validationMessage {language(String, 2), message(String, 400)},
caption {language(String, 2), message(String, 400)}
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) If an error occurred on the request side then 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 your request. Current version is 1.

/createUser

Definition

https://ppp-test.safecharge.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 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 the userTokenId as defined by the merchant for the user. Future calls relevant to this user require the userTokenId sent in this request.

@Links URLs

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

@Test https://ppp-test.safecharge.com/ppp/api/v1/createUser.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 the merchant’s system.
clientRequestId ^String(255) ~Required ID of the API request in 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.
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(60) ^Optional The street address of the user being registered.
state ^String(2) ^Optional The two-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) ~Required The two-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.
timeStamp ^String(14) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^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.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^String(20) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
internalRequestId ^String(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId ^String(255) 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 ^Integer(11) If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter (e.g. failure in checksum validation, timeout from processing engine, etc.).
version ^String(10) The current version of the request. The current version is 1.
userId ^String(20) Unique identifier of the user in Nuvei.

/updateUser

Definition

https://ppp-test.safecharge.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 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.safecharge.com/ppp/api/v1/updateUser.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 the merchant’s system.
clientRequestId ^String(255) ~Required ID of the API request in 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.
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(60) ^Optional The street address of the user being registered.
state ^String(2) ^Optional The two-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 two-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.
timeStamp ^String(14) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^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.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^String(20) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
internalRequestId ^Long(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId ^String(255) 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 ^Integer(11) If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter (e.g. failure in checksum validation, timeout from processing engine, etc.).
version ^String(10) The current version of the request. The current version is 1.
userId ^String(20) Unique identifier of the user in Nuvei.

/getUserDetails

Definition

https://ppp-test.safecharge.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 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 User Token ID sent in the createUser call.

@Links URLs

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

@Test https://ppp-test.safecharge.com/ppp/api/v1/getUserDetails.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 the merchant’s system.
clientRequestId ^String(255) ~Required ID of the API request in 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(15) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^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) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
internalRequestId ^String(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId ^String(255) ID of the API request in the merchant’s system.
userDetails ^Class firstName(String, 30)
lastName(String, 40)
address(String, 60)
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 ^Integer(11) If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
version ^String(10) The current version of the request. The current version is 1.

/addUPOCreditCard

Definition

https://ppp-test.safecharge.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 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 User Token ID. 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.safecharge.com/ppp/api/v1/addUPOCreditCard.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 the merchant’s system.
clientRequestId ^String(255) ~Required ID of the API request in 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.
ccCardNumber ^String(20) ~Required A valid credit card number.

Please avoid sending a card that was expired as it may cause a transaction to be declined.
ccExpMonth ^String(2) ~Required Two-digit value representing the expiration month.
ccExpYear ^String(2) ~Required Two-digit or four-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(2) ~Required The name of the credit card owner as it appears on the card.
billingAddress ^Class ^Optional firstName(String, 30)
lastName(String, 40)
address(String, 60)
phone(String, 18)
zip(String, 10)
city(String, 30)
countryCode(two-letter ISO country code)(String, 2)
state(two-letter ISO state code)(String, 2)
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 at integration@safecharge.com.
timeStamp ^String(14) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^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.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^String(20) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
internalRequestId ^String(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId ^String(255) 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 ^Integer(11) If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
version ^String(10) The current version of the request. The current version is 1.
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.safecharge.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 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 the User Token ID. 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.safecharge.com/ppp/api/v1/addUPOCreditCardByToken.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 the merchant’s system.
clientRequestId ^String(255) ~Required ID of the API request in 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.
ccExpMonth ^String(2) ~Required Two-digit value representing the expiration month.
ccExpYear ^String(4) ~Required Two-digit or four-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.
billingAddress ^Class ^Optional firstName(String, 30)
lastName(String, 40)
address(String, 60)
phone(String, 18)
zip(String, 10)
city(String, 30)
countryCode(two-letter ISO country code)(String, 2)
state(two-letter ISO state code)(String, 2)
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.
timeStamp ^String(14) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^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.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^String(20) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
internalRequestId ^String(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId ^String(255) 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 ^Integer(11) If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
version ^String(10) The current version of the request. The current version is 1.

/addUPOCreditCardByTempToken

Definition

https://ppp-test.safecharge.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 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 credit card temporary token for a specific user according to the User Token ID. 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.safecharge.com/ppp/api/v1/addUPOCreditCardByTempToken.do

Input Parameters

PARAMETER DESCRIPTION
sessionToken ^String(36) ~Required Session identifier returned by /getSessionToken.
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 the merchant’s system.
clientRequestId ^String(255) ~Required ID of the API request in 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.
ccTempToken ^String(45) ~Required A temporary card token.

Please avoid sending a card that was expired as it may cause a transaction to be declined.
billingAddress ^Class ^Optional firstName(String, 30)
lastName(String, 40)
address(String, 60)
cell(String, 18)
phone(String, 18)
zip(String, 10)
city(String, 30)
country(two-letter ISO country code)(String, 2)
state(two-letter ISO state code)(String, 2)
email(String, 100)
county(String, 255)
timeStamp ^String(15) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^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.

Output Parameters

PARAMETER DESCRIPTION
sessionToken ^String(36) Session identifier returned by /getSessionToken.
merchantId ^String(20) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
internalRequestId ^String(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId ^String(255) 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 ^Integer(11) If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
version ^String(10) The current version of the request. The current version is 1.

/addUPOAPM

Definition

https://ppp-test.safecharge.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": "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": "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 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 User Token ID. 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.safecharge.com/ppp/api/v1/addUPOAPM.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 the merchant’s system.
clientRequestId ^String(255) ~Required ID of the API request in 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.
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 Input Fields.
apmData ^Map ~Required List of name-value pairs that contain the parameters of the user payment option. For more information, refer to APM Input Fields.
billingAddress ^Class ^Optional firstName(String, 30)
lastName(String, 40)
address(String, 60)
cell(String, 18)
phone(String, 18)
zip(String, 10)
city(String, 30)
country(two-letter ISO country code)(String, 2)
state(two-letter ISO state code)(String, 2)
email(String, 100)
county(String, 255)
timeStamp ^String(14) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^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.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^String(20) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
internalRequestId ^String(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId ^String(255) 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 ^Integer(11) If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
version ^String(10) The current version of the request. The current version is 1.

/editUPOCC

Definition

https://ppp-test.safecharge.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 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.safecharge.com/ppp/api/v1/editUPOCC.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 the merchant’s system.
clientRequestId ^String(255) ~Required ID of the API request in 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.
userPaymentOptionId ^String(45) ~Required The unique user payment option ID as assigned by Nuvei.
ccExpMonth ^String(2) ~Required Two-digit value representing the expiration month.
ccExpYear ^String(4) ~Required Two-digit or four-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.
billingAddress ^Class ^Optional firstName(String, 30)
lastName(String, 40)
address(String, 60)
cell(String, 18)
phone(String, 18)
zip(String, 10)
city(String, 30)
country(two-letter ISO country code)(String, 2)
state(two-letter ISO state code)(String, 2)
email(String, 100)
county(String, 255)
timeStamp ^String(14) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^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.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^String(20) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
internalRequestId ^String() Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId ^String(255) 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 ^Integer(11) If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
version ^String(10) The current version of the request. The current version is 1.

/editUPOAPM

Definition

https://ppp-test.safecharge.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 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 User Token ID.

@Links URLs

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

@Test https://ppp-test.safecharge.com/ppp/api/v1/editUPOAPM.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 the merchant’s system.
clientRequestId ^String(255) ~Required ID of the API request in 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.
userPaymentOptionId ^String(45) ~Required The unique user payment option ID as assigned by Nuvei.
apmData ^Map ~Required List of name-value pairs that contain the parameters of the user payment option. For more information, refer to APM Input Fields.
billingAddress ^Class ^Optional firstName(String, 30)
lastName(String, 40)
address(String, 60)
cell(String, 18)
phone(String, 18)
zip(String, 10)
city(String, 30)
country(two-letter ISO country code)(String, 2)
state(two-letter ISO state code)(String, 2)
email(String, 100)
county(String, 255)
timeStamp ^String(14) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^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.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^String(20) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
internalRequestId ^String(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId ^String(255) 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 ^Integer(11) If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
version ^String(10) The current version of the request. The current version is 1.

/deleteUPO

Definition

https://ppp-test.safecharge.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 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.safecharge.com/ppp/api/v1/deleteUPO.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 the merchant’s system.
clientRequestId ^String(255) ~Required ID of the API request in 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.
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 ^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) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
internalRequestId ^String(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId ^String(255) 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 ^Integer(11) If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
version ^String(10) The current version of the request. The current version is 1.

/getUserUPOs

Definition

https://ppp-test.safecharge.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 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
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": "58",
    "clientRequestId": "107",
    "status":"SUCCESS",
    "errCode": "0",
    "reason" : "",
    "version": "1",
    "paymentMethods": [ {
        "userPaymentOptionId": "741",
        "paymentMethodName":"cc_card",
        "upoName":"(1111)",
        "upoRegistrationDate":"",
        "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":"",
        "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 User Token ID.

@Links URLs

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

@Test https://ppp-test.safecharge.com/ppp/api/v1/getUserUPOs.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 the merchant’s system.
clientRequestId ^String(255) ~Required ID of the API request in 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(14) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^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) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
internalRequestId ^String(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId ^String(255) 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 ^Integer(11) If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
version ^String(10) The current version of the request. The current version is 1.
paymentMethods ^Class List of Payment Options.
issuerCountry ^String(2) ISO code of the card issuer’s country.

List of Payment Options

PARAMETER DESCRIPTION
userPaymentOptionId ^String(45) The unique user payment option ID as assigned by Nuvei.
paymentMethodName ^String(50) The 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 Input Fields.
upoName ^String (255) User-friendly name that helps identify the account.
For cards, it usually includes the card number and for APMs it is usually one of the APM account identifier fields, for example account_id field. In both cases the chosen field to be used as upoName can be set per configuration.
Note: During UPO creation, the 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: YYYYMMDDHHmmss
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, 60)
cell(String, 18)
phone(String, 18)
zip(String, 10)
city(String, 30)
country(two-letter ISO country code)(String, 2)
state(two-letter ISO state code)(String, 2)
email(String, 100)
county(String, 255)
upoData ^Class This block contains the UPO details of the user.

Please refer to APM Input Fields for more information.

Please note: Only the relevant parameters for a specific UPO are returned when they are stored in Nuvei’s system.

/suspendUPO

Definition

https://ppp-test.safecharge.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 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.safecharge.com/ppp/api/v1/suspendUPO.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 the merchant’s system.
clientRequestId ^String(255) ~Required ID of the API request in 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.
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 ^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) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
internalRequestId ^String(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId ^String(255) 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 ^Integer(11) If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
version ^String(10) The current version of the request. The current version is 1.

/enableUPO

Definition

https://ppp-test.safecharge.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 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.safecharge.com/ppp/api/v1/enableUPO.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 the merchant’s system.
clientRequestId ^String(255) ~Required ID of the API request in 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.
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 ^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) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
internalRequestId ^String(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId ^String(255) 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 ^Integer(11) If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
version ^String(10) The current version of the request. The current version is 1.
Rebilling

Rebilling Introduction

Rebilling Overview

Nuvei’s new rebilling service enables merchants to create and manage recurring charges for products and services offered to their customers.
The service gives the merchant the flexibility to set payment plans or subscriptions. Moreover, it gives the merchant the ability to modify, extend, or cancel such charging plans.
The service also takes advantage of the card schemes’ card updaters (on supported cards) to ensure 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.
All the above platforms communicate directly with the service’s API methods.

Service Structure

The rebilling service consists of three key components:

How Does It Work?

Creating a subscription requires a merchant to provide an active payment option to be used in the subscription’s lifecycle. The user payment option (UPO) can be created by using a unique method on our end, which requires the card’s full payment details, including CVV2. When implementing Rebilling with Cashier, the Cashier can create the UPO as part of creating the subscription.
Once the initial payment’s date has arrived, an initial payment is sent for processing on the gateway using this payment-method indicator.
Any recurring payment according to the subscription’s conditions is processed with the card’s token/UPOID, flagged to the acquirers as a rebill payment and with no CVV2.

What if a Recurring Payment Has Failed?

To ensure a smooth subscription experience to both its merchants and their customers, Nuvei has implemented a retry engine into its rebilling service. If a recurring payment is declined, the merchant is notified with a DMN (Direct Merchant Notification) callback, and our retry mechanism is initiated:

API Implementation

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

Creating a Plan

Definition

https://ppp-test.safecharge.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": "Darin's Masterplan",
    "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 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.safecharge.com/ppp/api/createPlan.do

Request Parameters

Parameter Description
merchantId ^Long ~Required Merchant unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required Merchant website’s unique identification number provided by Nuvei
name ^String(50) ~Required Name of the plan is being created.
initialAmount ^Double(20) ^Optional 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) ~Required Amount that users subscribed to this plan are charged on recurring base.
description ^String(200) ^Optional Short description of the product.
currency ^String ~Required Currency with which all the users subscribed to this plan are charged.
startАfter ^Integer ^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 ^Integer ^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 ^Integer ~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.
planStatus ^String ^Optional ACTIVE – Users are able to subscribe to this plan
INACTIVE – Users are not be 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.
timeStamp ^String ~Required The time when the method call is performed according to the GMT+2 time zone in YYYYMMDDHHmmss format.
checksum ^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”, “merchant key”
The resulting string is hashed using SHA-256.

Editing a Plan

Definition

https://ppp-test.safecharge.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": "Darin's Masterplan - Updated",
    "currency": "GBP",
    "initialAmount": "13.67",
    "recurringAmount": "3.24",
    "planStatus": "INACTIVE",
    "timeStamp": "20191209121225",
    "checksum": "0661ef048083f96bd31cbd70f4e2d6a2"
}

Example Response

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

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

@Links URLs

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

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

Request Parameters:

Parameter Description
merchantId ^Long ~Required Merchant unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required Merchant website’s unique identification number provided by Nuvei
planId ^Long ~Required Name of the product is being created.
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 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 ^Integer ^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 ^Integer ^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 ^Integer ^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 be able to subscribe to the plan.
The plan is still active for current existing subscriptions.
timeStamp ^String ~Required The time when the method call is performed according to the GMT+2 time zone in YYYYMMDDHHmmss format.
checksum ^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”, “merchant key”
The resulting string is hashed using SHA-256.

Obtaining Plan Information

Definition

https://ppp-test.safecharge.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 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": "Darin's Masterplan",
            "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.safecharge.com/ppp/api/getPlansList.do

Request Parameters:

Parameter Description
merchantId ^Long ~Required Merchant unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required Merchant website’s unique identification number provided by Nuvei.
firstResult ^Integer ^Optional First result value.
maxResult ^Integer ^Optional Max result value.
planIds ^Array ^Optional ID of the plan.
currency ^String ^Optional Currency of the Plan
recurringPeriod ^Integer ^Optional Expected values per one of the parameters:
Day (Integer) = 1 (daily), 7 (weekly)
Month (Integer) = 1 (monthly)
Year (Integer) = 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.
timeStamp ^String ~Required The time when the method call is performed according to the GMT+2 time zone in YYYYMMDDHHmmss format.
planStatus ^String ^Optional Active – Users are able to subscribe to this plan. Inactive – Users are not be able to subscribe to the plan. The plan is still active for current existing subscriptions.
checksum ^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”, “planIds”, “currency”, “planStatus”, “timeStamp”, “merchant key”
The resulting string is hashed using SHA-256.

Creating a Subscription

Definition

https://ppp-test.safecharge.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 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 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.safecharge.com/ppp/api/createSubscription.do

Request Parameters:

Parameter Description
merchantId ^Long ~Required Merchant unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required Merchant web site’s unique identification number provided by Nuvei.
planId ^Long ~Required 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.
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 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 ^Integer ^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 ^Integer ^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.
endAfter ^Integer ~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 ^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”, “merchant key”
The resulting string is hashed using SHA-256.

Editing a Subscription

Definition

https://ppp-test.safecharge.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 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.safecharge.com/ppp/api/editSubscription.do

Request Parameters:

Parameter Description
merchantId ^Long ~Required Merchant unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required Merchant website’s unique identification number provided by Nuvei.
subscriptionId ^Long ~Required ID of the user’s active subscription in Nuvei system.
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 ^Integer ^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 ^Integer ^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 ^Integer ^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.
timeStamp ^String ~Required The time when the method call is performed according to the GMT+2 time zone in YYYYMMDDHHmmss format.
checksum ^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”, “merchantkey”
The resulting string is hashed using SHA-256.

Obtaining Subscription Information

Definition

https://ppp-test.safecharge.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 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.safecharge.com/ppp/api/getSubscriptionsList.do

Request Parameters:

Parameter Description
merchantId ^Long ~Required Merchant unique identification number provided by Nuvei.
merchantSiteId ^Long ~Required Merchant website’s unique identification number provided by Nuvei.
firstResults ^Integer ^Optional First result value.
maxResults ^Integer ^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 Subscription ID or list of IDs.
subscriptionStatuses ^Array ^Optional There are 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:
• Nuvei REST API call
• Nuvei cPanel
planIds ^Array ^Optional Plan ID 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 end 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 ^Integer ^Optional Expected values per one of the parameters:
Day (Integer) = 1 (daily), 7 (weekly)
Month (Integer) = 1 (monthly)
Year (Integer) = 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.
timeStamp ^String ~Required The time when the method call is performed according to the GMT+2 time zone in YYYYMMDDHHmmss format.
checksum ^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”, “planIds”, “subscriptionIds”, “subscriptionStatuses”, “timeStamp”, “merchant key”
The resulting string is hashed using SHA-256.

Cancelling a Plan

editPlan.do is also used to cancel an existing plan.
A plan is not deleted, but its status can be changed to ‘INACTIVE’.
For further guidance, please refer to the Editing a Plan section.

Cancelling a Subscription

Definition

https://ppp-test.safecharge.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 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.safecharge.com/ppp/api/cancelSubscription.do

Request Parameters:

Parameter Description
merchantId ^String ~Required Merchant unique identification number provided by Nuvei.
merchantSiteId ^String ~Required 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”, “merchant key”
The resulting string is hashed using SHA-256.

Cashier Implementation

This section introduces merchants to the Nuvei Cashier Rebilling page. To implement the Cashier Rebilling page, a new Cashier site must be created. The Rebilling module is supported by the NOVO theme for desktop and mobile.

Creating a Plan (Cashier)

A plan is created by:

Creating a Subscription (Cashier)

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.

Request Parameters:

*Note: Nuvei validates the accuracy of each string’s value.

Parameter Description
checksum ^String ~Mandatory Checksum.
country ^String ~Mandatory Country.
merchantLocale ^String ^Optional Merchant Locale.
city ^String ^Optional City.
theme_id ^String ^Optional ID of the merchant theme. Provided by Nuvei.
initial_amount ^String ^Optional Initial amount of the subscription. This parameter overrides initialAmount of the plan, if sent.
merchant_id ^String ~Mandatory ID of the merchant in Nuvei system.
userid ^String ^Optional User ID in Nuvei system.
phone1 ^String ^Optional Phone.
currency ^String ~Mandatory Currency of the subscription is being created. It will override the currency of the plan the user is subscribing to.
planId ^String ~Mandatory PlanId the subscription is being created to.
'PlanId’ can be retrieved by calling API method 'getPlans’ or in cPanel/Recurring section. It will be renamed as planId in near future.
user_token ^String ^Optional Auto – If there is no User created in Nuvei system to the user_token_id, it shall automatically create one upon successful subscription in our DB. In case there is already existing User in Nuvei to the same user_token_id, the system shall update user details with the new ones sent in the request. Register - Nuvei system shall create a new user in its DB 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 ~Mandatory 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 ~Mandatory Nuvei API version.
user_token_id ^String ~Mandatory ID of the user in merchant system.
rebilling_amount ^String Rebilling amount.
If sent, it overrides recurringAmount of the plan the user is subscribing to.

How to build the request to Nuvei Rebilling page:

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

Request Example:

1
https://ppp-test.safecharge.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:
“merchant key” followed by all the values of each of the parameters in the request in the order they are sent.

Request Checksum Example:

Request Example:

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



Checksum calculation:

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



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

Cashier Rebilling Page Example

NovoDesktopRebilling

Withdrawals API

Withdrawals Introduction

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 the 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.safecharge.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 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.safecharge.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.
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.
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. For more information, see Calculating Request Checksums.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^Long Your unique identification number provided by Nuvei.
merchantSiteId ^Long Your website’s unique identification number provided by Nuvei.
version ^String The version of the API call.
status ^String Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer Error code when a withdrawal request is declined.
reason ^String Reason an error occurred.
wdRequestStatus ^String The current status of the withdrawal request:
Pending: The initial Status of all requests. This indicates the transaction has not yet been processed.
Approved: The request was approved.
Declined: You or the APM declined the transaction.
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 ^Integer 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.safecharge.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 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.safecharge.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.
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.
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. For more information, see Calculating Request Checksums.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^Long Your unique identification number provided by Nuvei.
merchantSiteId ^Long Your website’s unique identification number provided by Nuvei.
version ^String The version of the API call.
status ^String Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer Error code when an error occurs.
reason ^String Reason an error occurred.
wdRequestStatus ^String The current status of the withdrawal request:
Pending: The initial Status of all requests. This indicates the transaction has not yet been processed.
Approved: The request was approved.
Declined: You or the APM declined the transaction.
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.safecharge.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 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.safecharge.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.
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.
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. For more information, see Calculating Request Checksums.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^Long Your unique identification number provided by Nuvei.
merchantSiteId ^Long Your website’s unique identification number provided by Nuvei.
version ^String The version of the API call.
status ^String Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer Error code when an error occurs.
reason ^String Reason an error occurred.
wdRequestStatus ^String The current status of the withdrawal request:
Pending: The initial Status of all requests. This indicates the transaction has not yet been processed.
Approved: The request was approved.
Declined: You or the APM declined the transaction.
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.safecharge.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 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.safecharge.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.
merchantWDOrderId ^String ^Optional A unique ID that you generate for the withdrawal order.
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 ISO 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.
gwRelatedTransactionId ^Long ~Conditional Transaction ID of the request that the refund is related to when the request is a refund request. Mandatory for refund requests.
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.
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. For more information, see Calculating Request Checksums.

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 ^Integer Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer Error code when an error occurs.
reason ^String Reason an error occurred.
wdRequestStatus ^String The current status of the withdrawal request:
Pending: The initial Status of all requests. This indicates the transaction has not yet been processed.
Approved: The request was approved.
Declined: You or the APM declined the transaction.
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.safecharge.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 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.safecharge.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.
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.
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. For more information, see Calculating Request Checksums.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^Long Your unique identification number provided by Nuvei.
merchantSiteId ^Long Your website’s unique identification number provided by Nuvei.
version ^String The version of the API call.
status ^String Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer Error code when an error occurs.
reason ^String Reason an error occurred.
wdRequestStatus ^String The current status of the withdrawal request:
Pending: The initial Status of all requests. This indicates the transaction has not yet been processed.
Approved: The request was approved.
Declined: You or the APM declined the transaction.
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.safecharge.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":"127.0.0.1"
    },
    "userDetails":{
        "firstName": "John",
        "lastName": "Adams",
        "address": "XXXX",
        "phone": "XXXX",
        "zip": "XXXX",
        "city": "XXXX",
        "countryCode": "XXXX",
        "state": "XXXX",
        "email": "safecharge@safecharge.com"
    },
    "amount": "10.55",
    "currency": "GBP",
    "merchantWDRequestId": "12345",
    "merchantUniqueId": "12345",
    "userAccountId": "12345",
    "customSiteName": "Merchant's Site Name",
    "customFieldX": "1",
    "successUrl": "",
    "failUrl": "",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

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.safecharge.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.
userId ^String ^Optional User ID you generate for the customer.
userPMId ^Long ~Required ID of the payment methods the customer wants the funds withdrawn to.
userDetails ^Class ^Optional firstName
lastName
address
phone
zip
city
countryCode
state
email (mandatory)
amount ^Double ~Required Amount of the withdrawal order.
currency ^String ~Required ISO code of the currency 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.
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.
deviceDetails ^Class ~Only ipAddress deviceType (String, 10)
deviceName (String, 255)
deviceOS (String, 255)
browser (String, 255)
ipAddress (String, 15)

Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (if device type cannot be recognized). The ipAddress parameter can be defined as mandatory or non-mandatory as needed by Nuvei’s Integration Team.
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. For more information, see Calculating Request Checksums.

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 ^Integer Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example, the request was sent with a parameter out of the allowed range.
errCode ^Integer Error code when an error occurs.
reason ^String Reason an error occurred.
wdRequestStatus ^String The current status of the withdrawal request:
Pending: The initial Status of all requests. This indicates the transaction has not yet been processed.
Approved: The request was approved.
Declined: You or the APM declined the transaction.
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 ^Integer 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.safecharge.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 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.safecharge.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. For more information, see Calculating Request Checksums.

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 ^Integer Error code when an error occurs.
reason ^String Reason an error occurred.

getRequests

Definition

https://ppp-test.safecharge.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": "Credit 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 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": "jamesd@safecharge.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.safecharge.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.
wdRequestOrderCount ^Integer ^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.
wdRequestId ^Long ~Required A unique ID generated by Nuvei returned in the DMN for the request.
merchantWDRequestId ^String ~Deep State 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 ~Deep State 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.
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 payment option IDs wrapped as a string.
countryIsoList ^Array ^Optional Contains an array of country ISO 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 ^Integer ^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 ^Integer ^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 count of orders – requests that have between “from” and “to” orders are included in the response. This returns only requests that have 2 or more orders, but not more than 5 orders.
merchantSiteIds ^Array ^Optional Filter results by merchant site IDs. Only sites that belong to the merchant are allowed. For example:
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. For more information, see Calculating Request Checksums.

Output Parameters

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

Orders Methods

getOrders

Definition

https://ppp-test.safecharge.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 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": "lilyanaz@safecharge.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.safecharge.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.
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.
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.
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 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 The amount of the payment methods in range. This value consists of a “fromNumOfPMs” value and a “toNumOfPMs” value.
netDepositRange ^Array ^Optional The net deposit range. This value consists of a “fromNetDeposit” value and a “toNetDeposit” value.
countryIsoList ^Array ^Optional Contains an array of country ISO 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:
cc_card: credit card
dc_card: debit card
firstResult ^Integer ^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 ^Integer ^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 Filtered 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.
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. For more information, see Calculating Request Checksums.

Output Parameters

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

settleWithdrawalOrder

Definition

https://ppp-test.safecharge.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 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.safecharge.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.
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 ^Boolean ^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.
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. For more information, see Calculating Request Checksums.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^Long Your unique identification number provided by Nuvei.
merchantSiteId ^Long Your website’s unique identification number provided by Nuvei.
version ^String The version of the API call.
status ^String Indicates if the API call was successful or not.
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer Error code when an error occurs.
reason ^String Reason an error occurred.
wdRequestStatus ^String The current status of the withdrawal request:
Pending: The initial Status of all requests. This indicates the transaction has not yet been processed.
Approved: The request was approved.
Declined: You or the APM declined the transaction.
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.safecharge.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 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 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.safecharge.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.
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.
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.
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 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 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 The amount of the payment methods in range. This value consists of a “fromNumOfPMs” value and a “toNumOfPMs” value.
netDepositRange ^Array ^Optional The net deposit range. This value consists of a “fromNetDeposit” value and a “toNetDeposit” value.
countryIsoList ^Array ^Optional Contains an array of country ISO 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.
Possible values include:
cc_card: credit card
dc_card: debit card
firstResult ^Integer ^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 ^Integer ^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.
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. For more information, see Calculating Request Checksums.

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 ^Integer The error code in the event of an error.
reason ^String Reason an error occurred.
wdOrderIds ^String List of Order IDs returned.
totalCount ^Integer Total number of orders returned according to the criteria you defined in the request.

settleOrdersInBatch

Definition

https://ppp-test.safecharge.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 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.safecharge.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.
operatorName ^String ^Optional The name of the administrator who approved the request.
comment ^String ^Optional The administrator’s comments regarding the transaction.
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. For more information, see Calculating Request Checksums.

Output Parameters

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

deleteWithdrawalOrder

Definition

https://ppp-test.safecharge.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 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.safecharge.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
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 ^Boolean ^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.
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. For more information, see Calculating Request Checksums.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^Long Your unique identification number provided by Nuvei.
merchantSiteId ^Long Your website’s unique identification number provided by Nuvei.
version ^String The version of the protocol.
status ^String Indicates if the API call was successful or not.
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer Error code when an error occurs.
reason ^String Reason an error occurred.
wdOrderId ^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.safecharge.com/ppp/api/withdrawal/updateOrdersDetails.do
Example Request
1
2
3
4
5
6
7
8
9
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdOrderIds": "12345",
    "operatorName": "",
    "details": "",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

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 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.safecharge.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 ^String ~Required ID of the withdrawal in Nuvei’s system.
operatorName ^String ^Optional Name of the operator settling the order.
details ^String ^Optional Details of the execution time in YYYYMMDDHHmmss format.
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. For more information, see Calculating Request Checksums.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^Long Your unique identification number provided by Nuvei.
merchantSiteId ^Long Your website’s unique identification number provided by Nuvei.
version ^String The version of the API.
status ^String Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer Error code when an error occurs.
reason ^String Reason an error occurred.
orders ^String Details of the settleOrdersInBatch orders and requests.
Possible values 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 User Payment Option (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.safecharge.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 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.safecharge.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. For more information, see Calculating Request Checksums.

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: e.g. PayPal, Credit Card)
pmIssuer – Credit card name (if cc_card or dc_card). If a credit card or debit card are not used, an empty string is returned.
version ^String The version of the protocol.
status ^String Indicates if the API call was successful or not.
Possible values:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode ^Integer Error code when an error occurs.
reason ^String Reason an error occurred.

updateNetDepositValue

Definition

https://ppp-test.safecharge.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 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.safecharge.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 ^Integer ~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. For more information, see Calculating Request Checksums.

Output Parameters

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

getUserPaymentMethodNetDeposits

Definition

https://ppp-test.safecharge.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 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.safecharge.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 ISO 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. For more information, see Calculating Request Checksums.

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 cc_card or dc_card) – NULL if empty.
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 ^Integer 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 mandatory 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.safecharge.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 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.safecharge.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 system.
userId ^String(20) ~Required Name of the user in merchant system.
clientUniqueId ^String(45) ~Required ID of the transaction in merchant system. This value must be unique.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
clientRequestId ^String(255) ~Required ID of the API request in merchant system. This value must be unique.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
deviceDetails ^Class ^Optional deviceType(String, 10)
deviceName(String, 255)
deviceOS(String, 255)
browser(String, 255)
ipAddress(String, 15)

The supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (If a device type cannot be recognized).
userDetails ^Class ~Required firstName (mandatory)(String, 30)
lastName (mandatory)(String, 50)
address (mandatory)(String, 60)
phone (optional)(String, 18)
zip (mandatory)(String, 10)
city (optional)(String, 30)
country (mandatory, two-letter ISO country code)(String, 2)
state (optional, two-letter ISO state code)(String, 2)
email (mandatory)(String, 100)
county (optional)
ekycUserDetails ^Class ~Required userName(String)
languageCode(String)
dateOfBirth (mandatory, in YYYY-MM-DD format)(String1 10)
title(String)
gender(String)
building (mandatory)(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.
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, not mandatory)
customField2 (String, 255, not mandatory)
customField3 (String, 255, not mandatory)
customField4 (String, 255, not mandatory)
customField5 (String, 255, not mandatory)
customField6 (String, 255, not mandatory)
customField7 (String, 255, not mandatory)
customField8 (String, 255, not mandatory)
customField9 (String, 255, not mandatory)
customField10 (String, 255, not mandatory)
customField11 (String, 255, not mandatory)
customField12 (String, 255, not mandatory)
customField13 (String, 255, not mandatory)
customField14 (String, 255, not mandatory)
customField15 (String, 255, not mandatory)

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.
timeStamp ^String(14) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^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.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^String(20) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ID of the user in merchant system.
clientUniqueId ^String(45) ID of the transaction in merchant system.
clientRequestId ^String(255) ID of the API request in merchant system.
internalRequestId ^String(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, not mandatory)
customField2 (String, 255, not mandatory)
customField3 (String, 255, not mandatory)
customField4 (String, 255, not mandatory)
customField5 (String, 255, not mandatory)
customField6 (String, 255, not mandatory)
customField7 (String, 255, not mandatory)
customField8 (String, 255, not mandatory)
customField9 (String, 255, not mandatory)
customField10 (String, 255, not mandatory)
customField11 (String, 255, not mandatory)
customField12 (String, 255, not mandatory)
customField13 (String, 255, not mandatory)
customField14 (String, 255, not mandatory)
customField15 (String, 255, not mandatory)

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) If an error occurred on the request side then an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
version ^String(10) The current version of the request. The current version is 1.

getDocumentUploadUrl

Definition

https://ppp-test.safecharge.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": {
        "sucessUrl": "",
        "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 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 on the 'KYC Transactions Report Details’ screen. Further information on this can be found in the Control Panel user guide.

@Links URLs

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

@Test https://ppp-test.safecharge.com/ppp/api/v1/getDocumentUploadUrl.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 system.
userId ^String(20) ~Required Name of the user in merchant system.
clientUniqueId ^String(45) ~Required ID of the transaction in merchant system. This value must be unique.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
clientRequestId ^String(255) ~Required ID of the API request in merchant system. This value must be unique.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
userDetails ^Class ~Required firstName (optional)(String, 30)
lastName (optional)(String, 50)
address (optional)(String, 60)
phone (optional)(String, 18)
zip (optional)(String, 10)
city (optional)(String, 30)
country (optional, two-letter ISO country code)(String, 2)
state (optional, two-letter ISO state code)(String, 2)
email (mandatory)(String, 100)
county (optional)(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.
merchantDetails ^Class ^Optional customField1 (String, 255, not mandatory)
customField2 (String, 255, not mandatory)
customField3 (String, 255, not mandatory)
customField4 (String, 255, not mandatory)
customField5 (String, 255, not mandatory)
customField6 (String, 255, not mandatory)
customField7 (String, 255, not mandatory)
customField8 (String, 255, not mandatory)
customField9 (String, 255, not mandatory)
customField10 (String, 255, not mandatory)
customField11 (String, 255, not mandatory)
customField12 (String, 255, not mandatory)
customField13 (String, 255, not mandatory)
customField14 (String, 255, not mandatory)
customField15 (String, 255, not mandatory)

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) No
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.
timeStamp ^String(14) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^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.

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) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ID of the user in merchant system.
clientUniqueId ^String(255) ID of the transaction in merchant system.
clientRequestId ^String(20) ID of the API request in merchant system.
internalRequestId ^String(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 Checkout 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, by calling getPaymentPageUrl with the kyc request parameter.

Nuvei’s Checkout 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 at integration@safecharge.com.

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 Merchant ID provided by Nuvei.
merchantSiteId ^String ~Required Merchant Site ID provided by Nuvei.
userTokenId ^String ~Required 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 ID of the transaction in the merchant’s system.
clientRequestId ^String ~Required ID of the API request in the merchant’s system.
orderId ^String ^Optional The order ID provided by Nuvei.
internalRequestId ^String ~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
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 to 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 Error reason if error occurred at the cashier side (e.g.: failure in checksum validation, timeout from processing engine, etc.).
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 (mandatory)
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