API Reference Home

Introduction

No data has been generated

Welcome to the Nuvei API Reference Guide.

If this is your first time visiting, we recommend you also visit our documentation portal.

Nuvei’s API is simple, easy-to-use, secure, and stateless, which enables online merchants and service providers to process consumer payments through Nuvei’s digital payment Gateway.

This API Reference Guide describes the API’s services and functionality, and is intended for developers by providing all necessary integration information, including the necessary requests and responses.

Prerequisites

Before you begin to connect to our services, make sure you meet the following requirements:

• IP whitelisting – Outbound traffic must be open to ANY destination on port TCP 443.
• TLS1.2 – The merchant must support TLS1.2 and above.
• TLS SNI – The merchant must support TLS SNI.

 

Session Initiation

/openOrder

Endpoint URL

1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "clientUniqueId": "12345",
    "currency": "USD",
    "amount": "200",
    "userTokenId": "230811147",
    "timeStamp": "20240118191751",
    "checksum": "6b53666fc048a825be63cbb820da467b"
}

1
2
3
4
5
6
7
8
9
10
11
12
//Initialize the SDK (see https://docs.nuvei.com/?p=53443#initializing-the-sdk)

// openOrder
safecharge.paymentService.openOrder({
    userTokenId: "230811147",
    clientUniqueId: "12345",
    clientRequestId: "1C6CT7V1L",
    currency: "USD",
    amount: "200",
}, function(err, result) {
    console.log(err, result);
});

1
2
3
4
5
6
7
8
9
10
11
12
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    String userTokenId = "230811147";
    String clientUniqueId = "12345";
    String clientRequestId = "1C6CT7V1L";
    String currency = "USD";
    String amount = "200";

    Safecharge safecharge = new Safecharge();
    SafechargeResponse response = safecharge.openOrder(userTokenId, clientRequestId, clientUniqueId, null, null, null, null, currency, amount, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null);
}

1
2
3
4
5
6
7
8
9
10
11
12
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
//openOrder
$openOrderRequest = $SafeCharge->getPaymentService()->openOrder([
    "userTokenId"       => "230811147",
    "clientUniqueId"    => "12345",
    "clientRequestId"   => "1C6CT7V1L",
    "currency"          => "USD",
    "amount"            => "200",
]);
?>

1
2
3
4
5
6
7
8
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.OpenOrder(
    "USD",
    "200",
    clientUniqueId: "12345",
    clientRequestId: "1C6CT7V1L",
    userTokenId: "230811147");

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "orderId": "271397458",
    "sessionToken": "7df876e6-9a2b-4fae-8ac0-85d70d2d48ce",
    "clientUniqueId": "12345",
    "internalRequestId": 222584528,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0",
    "clientRequestId": "1C6CT7V1L"
}

Calling the server-side /openOrder API request is the first step in a Web SDK or Simply Connect flow. /openOrder authenticates your Nuvei merchant credentials, sets up an order in the Nuvei system, and returns a sessionToken.

sessionToken must be included in all subsequent Web SDK and Simply Connect method calls in that session, such as for createPayment() or checkout().

/openOrder also allows you to set user-related parameters such as shipping details and billing details. Using the preventOverride parameter either allows or prevents subsequent Web SDK and Simply Connect method calls from overriding these user-related parameters.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(45) ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in a DMN as the merchant_unique_id parameter.
timeStamp ^String(14) ~Required	The local time (in 24-hour format) when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the input parameters, which must be concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey. Press here to see an example. NOTE: clientRequestId is optional and does not need to be included in the concatenation.
currency ^String(3) %%Conditional	The 3-letter ISO currency code. REQUIRED when using the Web SDK createPayment() method.
amount ^String(12) %%Conditional	The transaction amount. REQUIRED when using the Web SDK createPayment() method.
openAmount ^Class %%Conditional	Allows the merchant to set amount limits, which are validated. REQUIRED if min and max values are provided in checkout(). min (String) – Minimum payment amount. max (String) – Maximum payment amount. Press here for more information.
externalSchemeDetails ^Class %%Conditional	Use this if you want to process an MIT/recurring transaction that was initiated with another processor. Press here for more information. transactionId (String, 50) – Original transactionId for the initial payment as originated in the external system. Press here to view the structure of the parameter. brand (String, 20) – The card brand. Currently supported with the following values:  VISA  MASTERCARD  AMEX  DINERS  DISCOVER
authenticationOnlyType ^String(30) %%Conditional	If you are not using User Payment Management (tokenization) and would like to send Zero Amount Authorization, you need to set authenticationOnlyType to one of the following values: RECURRING – For when multiple transactions are submitted by the merchant separately based on an agreement between the merchant and the cardholder. INSTALLMENTS – For when a single transaction is divided into multiple charges. ADDCARD – For when a cardholder adds their card to be used for future transactions. MAINTAINCARD – For when a merchant wants to verify that an existing card is still valid. ACCOUNTVERIFICATION – For a verification different than those listed above.
userTokenId ^String(255) %%Conditional	This ID uniquely identifies your consumer/user in your system. It is REQUIRED only if you wish to use the userPaymentOptionId parameter for future charging of this user without re-collecting the payment details. Press here for more information.
isRebilling ^String(2) %%Conditional	When sending an /openOrder before performing recurring/rebilling createpayment(), include these parameters: • isRebilling=0. • For a 3DS transaction, you must specify rebillExpiry and rebillFrequency under the v2AdditionalParams class, under the threeD class.
companyDetails ^Class %%Conditional	Mastercard requires Acquirers to send this class to provide additional data for authorizing and clearing domestic transactions in France. taxId (String, 55) – The Tax ID of the merchant’s company.
recipientDetails ^Class %%Conditional	For Account Funding Transactions (AFTs), details of the person receiving the funds. Must be in Latin characters. firstName (String, 30) lastName (String, 40) NOTE: Press here for non-domestic AFT requirements.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
transactionType ^String(45) ^Optional	The type of transaction: Sale, Auth, or PreAuth. Sale – Performs a regular payment request. Auth – Performs an authorization-only request. Press here for more information. PreAuth – Performs an authorization-only request (with a longer settlement period). Press here for more information.
deviceDetails ^Class ^Optional	ipAddress (String, 15) deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255)
amountDetails ^Class ^Optional	NOTE: The items and amountDetails prices should be summed up according to each APMs requirement. NOTE: All prices must be in the same currency. totalShipping (String) totalHandling (String) totalDiscount (String) totalTax (String)
items ^Array ^Optional	An array describing the items in the purchase. NOTE: The items and amountDetails prices should be summed up according to each APMs requirement. NOTE: All prices must be in the same currency. name (String, 255, REQUIRED if items is used) – The name of the item. type (String, 50, REQUIRED if items is used) – The item type.  Possible values:  Discount, Physical, Shipping_fee, Digital, Gift_card, Store_credit, Surcharge, Sales_tax (only for US) price (String, 10, REQUIRED if items is used) – The net unit price of the item. quantity (String, 10, REQUIRED if items is used) – The quantity of an item. groupId (String, 50, REQUIRED only for certain APMs) – Category of the item (clothing, electronics, etc.). discount (String, 10, REQUIRED only for certain APMs) – The discount value of an item. discountRate (String, 10, REQUIRED only for certain APMs) – The discount percentage. shipping (String, 10, REQUIRED only for certain APMs) – The net price of shipping. shippingTax (String, 10, REQUIRED only for certain APMs) – The VAT amount of shipping. shippingTaxRate (String, 10, REQUIRED only for certain APMs) – The VAT percentage for shipping. tax (String, 10, REQUIRED only for certain APMs) – The VAT amount for an item. taxRate (String, 10, REQUIRED only for certain APMs) – The VAT percentage for an item. imageUrl (String, 610, REQUIRED only for certain APMs) – The URL of the image representing the item. productUrl (String, 610, REQUIRED only for certain APMs) – The URL of the item on the merchant site.
subMerchant ^Class ^Optional	countryCode (String, 2) – The 2-letter ISO country code of the PayFac’s submerchant. city (String, 20) – The city name of the PayFac’s submerchant. id (String, 15) – Represents the internal merchant’s ID, which is sent to the relevant card scheme. address (String, 48, CONDITIONAL) – The physical location where the transaction occurred, or the business location for virtual transactions. REQUIRED for PayFac-enabled transactions. state (String, 6, CONDITIONAL) – The ISO country subdivision code of the PayFac’s submerchant. REQUIRED for PayFac-enabled transactions. phone (String, 18) – The phone number of the PayFac’s submerchant that can be used for transaction inquiries. Recommended for PayFac-enabled transactions. Press here for more information.
dynamicDescriptor ^Class ^Optional	Special configuration is required for this class. For more information, please contact Nuvei’s Integration Support Team. merchantName (String, 25) – The merchant name, as is displayed for the transaction on the consumer’s card statement. For PayFac only, the maximum length of the parameter is 22, consisting of the following structure: XXX*<merchant name> where:  • XXX – The PayFac prefix, approved by Nuvei Underwriting Team.  Can be a length of 3, 7, 9, or 12.  • * – A fixed character.  • <merchant name> – Submerchant name.  Can be a length of 18, 14, 12, or 9, respectively. merchantPhone (String, 13) – The merchant contact information, as is displayed for the transaction on the consumer’s card statement. It can also be an email address.
isMoto ^String(1) ^Optional	Set this to “1” to mark the transaction as MOTO (mail order/telephone order). Leave null or “0” for regular transaction.
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response.
urlDetails ^Class ^Optional	With this class, a merchant can dynamically provide possible URLs to which the end user is redirected after a payment is made, as well as a dynamic URL for DMNs. successUrl (String, 1000) – The URL the customer is directed to after a successful transaction. failureUrl (String, 1000) – The URL the customer is directed to after an unsuccessful transaction. pendingUrl (String, 1000) – The URL the customer is directed to when the transaction response is pending. notificationUrl (String, 1000) – The URL to which DMNs are sent. Although DMN responses can be configured per merchant site, this parameter allows dynamically returning the DMN to the provided address per request. appReturnLink (String, 255) – The deep link used to return to the merchant native application (press here for an example). NOTE: This parameter is not supported for all cases. appUrl (String, 255) – Link to which the provider redirects the user at the end of the payment process (press here for an example). NOTE: This parameter is not supported for all cases.
addendums ^Class ^Optional	Contains industry specific addendums. The addendum fields that appear are based on the specific addendum type. See addendums Class for more information.
preventOverride ^String ^Optional	Allows or prevents future requests (createPayment(), authenticate3d(), or checkout()) from overriding parameters belonging to the following classes, which were provided in the original /openOrder request: shippingAddress, userDetails, billingAddress If equal to “0” or not sent (default) – Allows override by future requests. If a future request includes parameters belonging to one of the classes (above), then those parameters are overridden by the new values, and all the other parameter values in that class are set to null. If equal to “1” – Prevents override by future requests. Nuvei ignores future input values for parameters belonging to the classes above, and uses the original values provided by the /openOrder request, even if these are blank.
currencyConversion ^Class ^Optional	type (String, 10) – Indicates the currency conversion type.  Possible values: MCP, DCC originalAmount (String, 12) – The original amount of the transaction in the currency that the merchant requested. originalCurrency (String, 3) – The 3-letter ISO currency code of the currency that the merchant requested in the transaction.
paymentOption.card.threeD ^Class Path ^Optional	Using Web SDK, you can use the threeD Input Class to pass certain 3DS parameters. These parameters cannot be passed directly using the Web SDK to prevent user manipulation. Refer to threeD Input Class for class specific parameter details.
paymentOption.card.storedCredentials ^Class Path ^Optional	For storing card credentials, refer to storedCredentials Class.
isPartialApproval ^Boolean ^Optional	Describes a situation where the deposit was completed and processed with an amount lower than the requested amount due to a consumer’s lack of funds within the desired payment method. Partial approval is only supported by Nuvei acquiring. For partial approval to be available for the merchant, it should be configured by Nuvei’s Integration Support Team. Possible values: 1 – Allow partial approval 0 – Not allow partial approval
productId ^String(50) ^Optional	A free text parameter used to identify the product/service sold. If this parameter is not sent or is sent with an empty value, then it contains the concatenation of all item names up until the parameter maximum length. Risk rules and traffic management rules are usually built based on this parameter value.
customData ^String(255) ^Optional	Can be used to pass any type of information. If sent in request, then it is visible in Nuvei’s back office tool transaction reporting and is returned in response.
webMasterId ^String(255) ^Optional	An affiliate parameter that the merchant can send. This is used by Nuvei’s eCommerce plugins (Magento, Demandware) and by Nuvei REST API SDKs to send the plugin/SDK name and version so that Support is able to identify from where the transaction arrived at the REST API Gateway.
sessionCardDeclineLimit ^String ^Optional	Enables limiting the number of transaction declines that can be received during a single session. If this limit of declines is reached, the session expires immediately. Default value is null.
customSiteName ^String(50) ^Optional	The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name. Risk rules and traffic management rules are usually built based on this parameter value.

Additional Input Parameters

In addition, you can set the following parameters (billingAddress, userDetails, and shippingAddress) in /openOrder.

PARAMETER	DESCRIPTION
billingAddress ^Class ^Optional	country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30, REQUIRED) lastName (String, 40, REQUIRED) phone (String, 18, REQUIRED for 3DS card authentication if email not provided) city (String, 30) address (String, 50) streetNumber (String, 20) zip (String, 10) state (String, 3) – ISO country subdivision code cell (String, 18) county (String, 255) addressMatch (String, 1) – Set to “Y” when address matches shipping address addressLine2 (String, 50) addressLine3 (String, 50) homePhone (String) workPhone (String)
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) streetNumber (String, 20) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This represents the customer’s identification number in their respective country. If you have only one set of this user information (not including identification) to send in the request, it must be sent using the billingAddress class.
shippingAddress ^Class %%Conditional	For certain APMs, some parameters are REQUIRED, as detailed in the APM Payments table. salutation (String, 20) – Examples: Mr and Mrs firstName (String, 30) lastName (String, 40) address (String, 50) streetNumber (String, 20) cell (String, 18) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (100) county (String, 255) addressLine2 (String, 50) addressLine3 (String, 50) companyName (String, 255) careOf (String, 50)

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier to be used by the request that processed the newly opened order.
merchantId ^String(20)	Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
merchantDetails ^Class	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response.
status ^String(20)	The status of merchant’s API request/call. Possible values: SUCCESS, 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, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
version ^String(10)	The current version of the API method. The current version is 1.
orderId ^String(20)	The order ID provided by Nuvei.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
partialApproval ^Class	Partial approval is when the deposit completes with a processed amount lower than the requested amount due to a lack of sufficient funds in the consumer payment method. requestedAmount (String, 12) – The original requested amount. requestedCurrency (String, 3) – The currency of the original request. processedAmount (String, 12) – The amount that was actually deposited in the transaction. processedCurrency (String, 3) – The currency used in the processed transaction request.

/updateOrder

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId": "39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": " 487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "currency": "USD",
    "amount": "10",
    "amountDetails":{
        "totalShipping": "0",
        "totalHandling": "0",
        "totalDiscount": "0",
        "totalTax": "0"
    },
    "items":[
        {
            "name": "name",
            "price": "10",
            "quantity": "1"
        }
    ],
    "deviceDetails":{
        "deviceType": "DESKTOP",
        "deviceName": "iPhone 5s",
        "deviceOS": "iOS 10.2",
        "browser": "safari",
        "ipAddress": "192.168.2.38"
    },
    "userDetails":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "22 Main Street",
        "phone": "6175551414",
        "zip": "02460",
        "city": "Boston",
        "country": "US",
        "state": "MA",
        "email": "[email protected]",
        "county": "Suffolk"
    },
    "shippingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "cell": "6175553333",
        "phone": "6175551414",
        "address": "22 Main Street",
        "zip": "02460",
        "city": "Boston",
        "country": "US",
        "state": "MA",
        "email": "[email protected]",
        "county": "Suffolk"
    },
    "billingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "address": "22 Main Street",
        "cell": "6175553333",
        "phone": "6175551414",
        "zip": "02460",
        "city": "Boston",
        "country": "US",
        "state": "MA",
        "email": "[email protected]",
        "county": "Suffolk"
    },
    "dynamicDescriptor":{
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "merchantDetails":{
        "customField1": "",
        "customField2": ""
    },
    "addendums":{
        "localPayment":{
        "numberOfInstallments": "121",
        "nationalId": "123456789",
        "installmentType": "3",
        "debitType": "2"
        }
    },
    "timeStamp": "20240118191751",
    "checksum": "6b53666fc048a825be63cbb820da467b"
}

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/updateOrder.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

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

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

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId": "39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033", 
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "internalRequestId": 866,
    "merchantDetails": {
        "customField1": "",
        "customField2": ""
    },
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "version": "1.0"
}

Using the /updateOrder method, Simply Connect allows you to modify the amount of a previously opened/created order during the checkout process without having to reload the checkout page.

Press here for more information.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
orderId ^String(45) ~Required	The ID to be used as an input parameter in the update method and payment methods. The parameter is sent to define which merchant order to update.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant site ID provided by Nuvei.
clientUniqueId ^String(45) ~Required	The unique transaction ID in the merchant system. This value must be unique. This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
timeStamp ^String(14) ~Required	The local time (in 24-hour format) when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the input parameters, which must be concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey. Press here to see an example. NOTE: clientRequestId, amount, and currency are optional and do not need to be included in the concatenation.
userTokenId ^String(255) %%Conditional	This ID uniquely identifies your consumer/user in your system. It is REQUIRED only if you wish to use the userPaymentOptionId parameter for future charging of this user without re-collecting the payment details. Press here for more information.
clientRequestId ^String(255) ^Optional	ID of the API request in the merchant system. This value must be unique. This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
currency ^String(3) ^Optional	The 3-letter ISO currency code.
amount ^Double(12) ^Optional	The transaction amount.
amountDetails ^Class ^Optional	NOTE: The items and amountDetails prices should be summed up according to each APMs requirement. NOTE: All prices must be in the same currency. totalShipping (String) totalHandling (String) totalDiscount (String) totalTax (String)
items ^Array ^Optional	An array describing the items in the purchase. NOTE: The items and amountDetails prices should be summed up according to each APMs requirement. NOTE: All prices must be in the same currency. name (String, 255, REQUIRED if items is used) – The name of the item. type (String, 50, REQUIRED if items is used) – The item type.  Possible values:  Discount, Physical, Shipping_fee, Digital, Gift_card, Store_credit, Surcharge, Sales_tax (only for US) price (String, 10, REQUIRED if items is used) – The net unit price of the item. quantity (String, 10, REQUIRED if items is used) – The quantity of an item. groupId (String, 50, REQUIRED only for certain APMs) – Category of the item (clothing, electronics, etc.). discount (String, 10, REQUIRED only for certain APMs) – The discount value of an item. discountRate (String, 10, REQUIRED only for certain APMs) – The discount percentage. shipping (String, 10, REQUIRED only for certain APMs) – The net price of shipping. shippingTax (String, 10, REQUIRED only for certain APMs) – The VAT amount of shipping. shippingTaxRate (String, 10, REQUIRED only for certain APMs) – The VAT percentage for shipping. tax (String, 10, REQUIRED only for certain APMs) – The VAT amount for an item. taxRate (String, 10, REQUIRED only for certain APMs) – The VAT percentage for an item. imageUrl (String, 610, REQUIRED only for certain APMs) – The URL of the image representing the item. productUrl (String, 610, REQUIRED only for certain APMs) – The URL of the item on the merchant site.
deviceDetails ^Class ^Optional	ipAddress (String, 15) deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255)
dynamicDescriptor ^Class ^Optional	Special configuration is required for this class. For more information, please contact Nuvei’s Integration Support Team. merchantName (String, 25) – The merchant name, as is displayed for the transaction on the consumer’s card statement. For PayFac only, the maximum length of the parameter is 22, consisting of the following structure: XXX*<merchant name> where:  • XXX – The PayFac prefix, approved by Nuvei Underwriting Team.  Can be a length of 3, 7, 9, or 12.  • * – A fixed character.  • <merchant name> – Submerchant name.  Can be a length of 18, 14, 12, or 9, respectively. merchantPhone (String, 13) – The merchant contact information, as is displayed for the transaction on the consumer’s card statement. It can also be an email address.
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response.
addendums ^Class ^Optional	Contains industry specific addendums. The addendum fields that appear are based on the specific addendum type. See addendums Class for more information.

Additional Input Parameters

In addition, you can set the following parameters (billingAddress, userDetails, and shippingAddress) in /openOrder.

PARAMETER	DESCRIPTION
billingAddress ^Class ^Optional	country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30, REQUIRED) lastName (String, 40, REQUIRED) phone (String, 18) city (String, 30) address (String, 50) zip (String, 10) state (String, 3) – ISO country subdivision code cell (String, 18) county (String, 255) addressMatch (String, 1) – Set to “Y” when address matches shipping address addressLine2 (String, 50) addressLine3 (String, 50) homePhone (String) workPhone (String)
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This represents the customer’s identification number in their respective country. If you have only one set of this user information (not including identification) to send in the request, it must be sent using the billingAddress class.
shippingAddress ^Class ^Optional	salutation (String, 20) – Examples: Mr and Mrs firstName (String, 30) lastName (String, 40) address (String, 50) streetNumber (String, 20) cell (String, 18) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (100) county (String, 255) addressLine2 (String, 50) addressLine3 (String, 50) companyName (String, 255) careOf (String, 50)

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
orderId ^String(20)	The order ID provided by Nuvei.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255)	The ID of the user in the merchant system.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
merchantDetails ^Class	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response. It is not passed to the payment gateway and is not used for processing.
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 (such as failure in checksum validation, timeout from processing engine)
version ^String(10)	The current version of the API method. The current version is 1.

Web SDK

Web SDK Overview

The Nuvei Web SDK integration platform is a JavaScript library of API methods that you can use to accept payments on your own payment page, as part of your own custom payment flow.

Web SDK is easy to integrate, yet does not require any PCI whatsoever, giving you complete control over the UI and UX.

For a complete guide to Web SDK, including its advantages, please refer to the Web SDK topic in our main documentation portal.

 

Web SDK Methods

SafeCharge()

This method initializes the Web SDK.

Input

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
sfc = SafeCharge({
    sessionToken: result.sessionToken, // received from openOrder API
    env: "int", // "prod"
    merchantId: "1475082432483184221", // as assigned by Nuvei
    merchantSiteId: "184941", // as assigned by Nuvei
    blockCards: [["visa","credit","corporate"], ["amex", "GB", "prepaid"]], // Visa corporate credit cards and British prepaid Amex cards are blocked
    blockPasteCard: true,
    disableNuveiAnalytics: true,
    showAccountCapture: true,
    onPaymentEvent: function(result) {
        console.log('onPaymentEvent =>', result);
    },
    logLevel: "4", // "0" (default)
    support19Digits: true, // false (default)
});

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(20) ~Required	The sessionToken retrieved from a call to /openOrder that references the order created in the Nuvei system.
merchantId ^String(20) ~Required	Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	Merchant Site ID provided by Nuvei.
env ^String(4) ~Required	The Nuvei environment you’re running on. If not provided, prod is assumed. Possible values: prod – production int – integration
logLevel ^String(1) ^Optional	Determines the level of detail at which data must be shown on the console. Possible values: 0 (default) – No logging 1 – Plain text 2 – Info 3 – Warn 4 – Error 5 – Debug 6 – Trace
blockCards ^Array ^Optional	Specifies which sets of cards can be blocked from appearing to the customer in a list of payment methods. Press here for more information.
blockPasteCard ^Boolean ^Optional	When set to true, no card details can be pasted into any of the card input fields. Possible values: false (default), true
support19Digits ^Boolean ^Optional	When set to true, Web SDK supports unique credit card lengths, such as 15 and 19 digits. Possible values: true, false
disableNuveiAnalytics ^Boolean ^Optional	When set to true, analytics are disabled to prevent the analytics tool from conflicting with the merchant code. Possible values: false (default), true
onPaymentEvent ^Array ^Optional	Defines an event callback that provides maximum transparency for the payment flow, by reporting back to you at each stage of the payment flow. You can use this information for analytics or to perform some custom action. Press here for more information.
showAccountCapture ^Boolean ^Optional	When set to true, the bank capture redirectUrl is opened in a pop-up window. Possible values: false (default), true
strictCardBlocking ^Boolean ^Optional	Indicates if not receiving a proper response from the cardRecognition service should block and fail the transaction. Possible values: false (default), true
cvvIcon ^String ^Optional	Determines if an icon appears in the CVV textbox, which also shows a tooltip on mouseover. Possible values: false (default) – No icon is displayed. true – A default icon is displayed. Additionally, you can provide an object that allows setting a different icon and position.  backgroundImage – Custom URL  tooltipPosition: top or bottom

createPayment()

Use this method together with invoking Nuvei Fields to perform end-to-end card payment processing, while meeting all PCI requirements.

Before calling createPayment(), you must first open an order on the server side using the /openOrder API call as described in Initiate a Session.

Please refer to Quick Start for Web SDK for the best use of this method.

Input

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
sfc.createPayment({
    sessionToken: "<as received from /openOrder>",
    clientUniqueId: "<unique transaction ID in merchant system>", // optional
    cardHolderName: "john smith",
    paymentOption : nuveiFieldsObj
    billingAddress: {
        "email": "[email protected]",
        "country": "US"
    }
  }, function(res) {
        console.log(res);
  })

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(20) ~Required	The sessionToken retrieved from a call to /openOrder that references the order created in Nuvei system.
paymentOption ^Class ~Required	The option used to send the payment details. Set the payment option by setting the Nuvei Fields object, for example to nuveiFieldsObj. Press here for more information on how to use Nuvei Fields. Alternatively, you can use one of the following options: If you are handling a returning user and want to use a previously saved user payment option: userPaymentOptionId (String) – Identifies a payment option previously used by the customer, and is now requested for re-use (Nuvei keeps payment option details from a previous use). Upon re-use, any of the following additional parameters from the card class may be needed as well:  • expirationMonth (String, 2) – For a newer card expiration.  • expirationYear (String, 4) – For a newer card expiration.  • CVV (String, 4) – Recommended for high-risk merchants. If you wish to process an APM: alternativePaymentMethod (Class) – Represents the alternative payment method (APM) used to process the transaction. Please refer to APM Input Parameters for more information. If you need advanced APM features: subMethod – This class allows using an APM but with a different payment flow.  • subMethod (String, 50) – The APM name.  • referenceId (String) – Allows the merchant to provide an ID of a previous transaction, billing agreement,   or pre-approval of an APM.   NOTE: Use this parameter only if you are not using Nuvei’s User Payment Management feature.  • email (String, 255) – If no email is provided, it is automatically populated from billingAddress. Press here for more information. If you wish to collect the card details yourself: card (Class) – Represents a credit/debit card.  • cardNumber (String, 20, REQUIRED) – The card number.  • cardHolderName (String, 70, REQUIRED) – The cardholder name.  • expirationMonth (String, 2, REQUIRED) – The card expiration month.  • expirationYear (String, 4, REQUIRED) – The card expiration year.  • CVV (String, 4, REQUIRED) – The CVV/CVC security code.
billingAddress ^Class ~Some Parameters Required	The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters. country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30, REQUIRED) lastName (String, 40, REQUIRED) address (String, 50) addressLine2 (String, 50) addressLine3 (String, 50) phone (String, 18) zip (String, 10) city (String, 30) state (String, 3) – ISO country subdivision code county (String, 255) These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.
apmWindowType ^String ^Optional	Allows merchants to choose how an APM window is opened. Possible values: popup (default) – A pop-up window opens. newTab – A pop-up windows opens in a new browser tab. redirect – The customer is redirected to their APM provider’s page, which opens on top of the current payment page. customRedirect – The customer is redirected to their APM provider’s page, and then the merchant implements the redirection.
alwaysCollectCvv ^String ^Optional	Used to set the CVV parameter to optional. By default, the CVV is always collected. Set this parameter to “optional” to make the CVV parameter optional. NOTE: If the merchant does not want to collect the CVV at all, then they should use Nuvei’s Three-Part Card Fields Integration and not include the CVV/CVC value.
selectedBrand ^String(128) ^Optional	The brand selected by the consumer for the transaction processing.

Additional Input Parameters

In addition, you can send the following parameters either with the preceding authentication server side, using the /openOrder API call, or directly to createPayment().

PARAMETER	DESCRIPTION
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This represents the customer’s identification number in their respective country. NOTE: When processing a createPayment(), authenticate3d(), or checkout() request, if you provided any billingAddress values (such as country and email), then the system uses those values instead of the values provided in the userDetails class.
shippingAddress ^Class ^Optional	For certain APMs, some parameters are REQUIRED, as detailed in the APM Payments table. salutation (String, 20) – Examples: Mr and Mrs firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (String, 100) county (String, 255) careOf (String, 50)
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response.

Output

The createPayment response comes in two steps:

• The createPayment returned values (as detailed in the following example and Output Parameters).

  These contain the fiscal result parameter, which provides instant feedback to the end user.

• Verifying the response.

  Since the returned values are liable to a user’s manipulation, you have to verify the response directly from your server with the /getPaymentStatus method (or alternatively with the DMNs). For details regarding the payment verification, please refer to our Quick Start Guide.
  

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "result": "DECLINED",
    "errCode": -1,
    "errorDescription": "Decline",
    "ccCardNumber": "5****5761",
    "bin": "511142",
    "last4Digits": "5761",
    "ccExpMonth": "09",
    "ccExpYear": "21",
    "transactionId": "1110000000004146935",
    "threeDReason": "",
    "threeDReasonId": "",
    "challengeCancelReasonId": "",
    "challengeCancelReason": "",
    "isLiabilityOnIssuer": "1",
    "isExemptionRequestInAuthentication": "0"
    "challengePreferenceReason": "12",
    "cancelled": false
}

Output Parameters

PARAMETER	DESCRIPTION
result ^String(20)	The fiscal status of a merchant request. Possible values: APPROVED, DECLINED, ERROR, PENDING
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter. In case of success (declined or approved), returns 0. Values as detailed in Response Handling. In addition, it can have the value of “-5”, which means the 3DS process was aborted.
errorDescription ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter. Values as detailed in Response Handling. In addition, it can have the value of “General 3D error”, which means the 3DS process was aborted.
cancelled ^String	If the process was canceled by the end user
transactionId ^String(20)	The Gateway transaction ID.
ccCardNumber ^String(20)	The credit card number in a mask (for example: 4****1111).
bin ^String(6)	The BIN number representing the issuer.
last4Digits ^String(4)	The last four digits of the card number.
ccExpMonth ^String(2)	The expiration month
ccExpYear ^String(4)	The expiration year.
threeDReasonId ^String	Reason ID for a failed 3DS authorization as received from the issuer. Press here for more information.
threeDReason ^String	Reason description for a failed 3DS authorization as received from the issuer. Press here for more information.
challengeCancelReasonId ^String	Reason ID for a canceled 3DS authorization as received from the issuer.
challengeCancelReason ^String	Reason description for a canceled 3DS authorization as received from the issuer.
isLiabilityOnIssuer ^String	Indicates if there is 3DS liability shift. If equal to “1” – Liability shift is present. If equal to “0”, empty or null – No liability shift has occurred.
isExemptionRequestInAuthentication ^String	Indicates if an exemption was requested during 3DS authorization.
challengePreferenceReason ^String	This value is returned following a 3DS challenge and describes the reason for challenge. Press here for more information.

getApms()

This method returns the APMs supported with all their metadata needed for displaying them to the user and preparing them for processing, such as their display name, logo, required input to collect from the end user, and so on. One important parameter it returns for each APM is the APM identifier with Nuvei that you need to submit when requesting the payment (with the createPayment() method).

The method can retrieve either the entire APM set supported by your account with Nuvei, or alternatively, a customized set of APMs. For example, you can request to retrieve APMs that correspond to certain criteria such as by transaction currency or by the user country.

Input

Example Request

1
2
3
4
5
6
7
8
sfc.getApms({
    type: "withdrawal",
    currencyCode: "USD",
    countryCode: "US", //detect
    languageCode: "en"
},
    function(res){console.log(res);
    });

Input Parameters

PARAMETER	DESCRIPTION
currencyCode ^String(3) ^Optional	The 3-letter ISO currency code. If currencyCode is provided, the returned APM set consists only of APMs that support this currency. If not provided, the APM set includes all APMs regardless of their supported currencies.
countryCode ^String ^Optional	The 2-letter ISO country code. If countryCode is provided, the returned APM set consists only of APMs supported in this country. Alternatively, you can enter a value of “detect” so the current country is automatically detected by geolocation. If no value is provided, the APM set includes all APMs regardless of where they are supported.
languageCode ^String(2) ^Optional	The language in which the transaction is to be completed.
type ^String ^Optional	Relevant for gaming, forex or other industries that pay out to their customers, but not relevant for other industries. The type of the payment methods to be returned. Possible values: DEPOSIT (default if no value is sent), WITHDRAWAL

Output

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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
{
    "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"
                        }
                    ]
                }
            ]
        },
        {
            "paymentMethod": "apmgw_Instant_Open_Banking",
            "paymentMethodDisplayName":[

            ],
            "isDirect": "false",
            "countries":[
                "BE"
            ],
            "currencies":[
                "USD"
            ],
            "fields":[
                {
                    "name": "ob_account_number",
                    "type": "text",
                    "caption":[
                        {
                            "language": "eng",
                            "message": "Account Number"
                        }
                    ]
                },
                {
                    "name": "ob_sort_code",
                    "type": "text",
                    "caption":[
                        {
                            "language": "eng",
                            "message": "Sort Code"
                        }
                    ]
                },
                {
                    "name": "ob_iban",
                    "type": "text",
                    "caption":[
                        {
                            "language": "en",
                            "message": "IBAN"
                        }
                    ]
                },
                {
                    "name": "instantOb_bankId",
                    "type": "text",
                    "caption":[
                        {
                            "language": "eng",
                            "message": "Bank ID"
                        }
                    ],
                    "listValues":[
                        {
                            "code": "ngp-bbru",
                            "caption": "NextGenPSD2",
                            "mandatoryFields":[
                                "ob_iban"
                            ]
                        },
                        {
                            "code": "ngp-ingba",
                            "caption": "ING Austria",
                            "mandatoryFields":[

                            ]
                        }
                    ]
                }
            ]
        }
    ],
    "type": "DEPOSIT",
    "status": "",
    "errCode": "",
    "reason": "",
    "version": ""
}

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
paymentMethods ^Array	An array of payment methods and their attributes: paymentMethod (String, 50) paymentMethodDisplayName (Array) [language (String, 2), message (String, 400)] isDirect (String, 5) countries [(String, 2)] currencies [(String, 3)] logoURL (String, 255) fields[  name (String, 45)  regex (String, 128)  type (String, 45)  validationMessage (Array) [language (String, 2), message (String, 400)],  caption (Array) [language (String, 2), message (String, 400)]  listValues (Array) [  code (String, 255)  caption (String)  mandatoryFields (Array) [(String, 45)]  ] ]
type ^String	The type of the payment methods to be returned. Possible values: DEPOSIT (default if no value is sent), WITHDRAWAL
result ^String(20)	The status of merchant’s API request/call. Possible values: APPROVED, ERROR.
errCode ^Integer(11)	If an error occurred on the request side, then an error code is returned in this parameter.
errorDescription ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
version ^String(10)	The current version of the API method. The current version is 1.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.

authenticate3d()

Use this method to perform a 3DS-only authentication request. The output of this request (mainly the cavv and eci values) can be used to process a card payment with any PSP or acquirer and thus benefit from the 3DS liability shift.

This is also the quickest way for a merchant to migrate to 3DS; just call this method on the client side and use cavv and eci with your existing integration – either with Nuvei or any other PSP.

Before calling authenticate3d(), you must first call the /openOrder API call on the server side.

Please read the following topics for best use of this method:

• 3DS Authentication Only
• Nuvei Fields guide (for full PCI descoping)

Input

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
sfc.authenticate3d({
    sessionToken: result.sessionToken, // received from openOrder API
    paymentOption : nuveiFieldsObj
    billingAddress: {
        firstName: "John",
        lastName: "Smith",
        email: "[email protected]",
        country: "US"
    }
}, function(res) {
    console.log(res.paymentOption.threeD); // the structure containing the cvv and eci
    if (res.cancelled === true) {
        example.querySelector('.token').innerText = 'cancelled';
    } else {
        example.querySelector('.token').innerText = res.transactionStatus + ' - Reference: ' + res.transactionId;
    }
    example.classList.add('submitted');
});

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(20) ~Required	The sessionToken retrieved from a call to /openOrder that references the order created in the Nuvei system.
paymentOption ^Class ~Required	The option used to send the payment details. Set the payment option by setting the Nuvei Fields object, for example to nuveiFieldsObj. Press here for more information on how to use Nuvei Fields. Alternatively, you can use one of the following options: If you are handling a returning user and want to use a previously saved user payment option: userPaymentOptionId (String) – Identifies a payment option previously used by the customer, and is now requested for re-use (Nuvei keeps payment option details from a previous use). Upon re-use, any of the following additional parameters from the card class may be needed as well:  • expirationMonth (String, 2) – For a newer card expiration.  • expirationYear (String, 4) – For a newer card expiration.  • CVV (String, 4) – Recommended for high-risk merchants. If you wish to collect the card details yourself: card (Class) – Represents a credit/debit card.  • cardNumber (String, 20, REQUIRED) – The card number.  • cardHolderName (String, 70, REQUIRED) – The cardholder name.  • expirationMonth (String, 2, REQUIRED) – The card expiration month.  • expirationYear (String, 4, REQUIRED) – The card expiration year.  • CVV (String, 4, REQUIRED) – The CVV/CVC security code.
billingAddress ^Class ~Some Parameters Required	The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters. country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30, REQUIRED) lastName (String, 40, REQUIRED) address (String, 50) addressLine2 (String, 50) addressLine3 (String, 50) phone (String, 18) zip (String, 10) city (String, 30) state (String, 3) – ISO country subdivision code county (String, 255) These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.

Additional Input Parameters

In addition, you can send the following parameters either with the preceding authentication server side, using the /openOrder API call, or directly to authenticate3d().

PARAMETER	DESCRIPTION
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This represents the customer’s identification number in their respective country. NOTE: When processing a createPayment(), authenticate3d(), or checkout() request, if you provided any billingAddress values (such as country and email), then the system uses those values instead of the values provided in the userDetails class.
shippingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (String, 100) county (String, 255)
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response.

Output

You get the response directly from the authenticate3d() return value (as detailed below).

The following are the most important output parameters you should examine:

(For the complete response specification, please refer to /payment Output Parameters.)

• 3DS Authorization Fields: The values you need to use in your follow-up call to the payment request. These parameters are stored under the threeD class, under the card class, under the paymentOption class in the response:
  • eci
  • cavv

• status: Can be either SUCCESS or ERROR.
• errCode and reason: Shows the error description in case one was received.
  

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "result": "APPROVED",
    "errCode": 0,
    "errorDescription": "",
    "cavv": "Vk83Y2t0cHRzRFZzRlZlR0JIQXo=",
    "eci": "2",
    "dsTransID": "737eace8-353c-481e-9504-d496aa40485a",
    "ccCardNumber": "5****5761",
    "ccTempToken": "fb13b742-88f6-465d-ba87-3e676beac4d3",
    "bin": "511142",
    "last4Digits": "5761",
    "ccExpMonth": "09",
    "ccExpYear": "21",
    "transactionId": "1110000000004146935",
    "threeDReason": "",
    "threeDReasonId": "",
    "challengeCancelReasonId": "",
    "challengeCancelReason": "",
    "challengePreferenceReason": "12",
    "isExemptionRequestInAuthentication": "0"
    "cancelled": "false"
}

Output Parameters

PARAMETER	DESCRIPTION
eci ^String(2)	The Electronic Commerce Indicator (ECI) that indicates the level of security used in a 3DS program when the cardholder provides payment information to the merchant. Possible eci data values: Visa  5 – The cardholder was successfully authenticated.  6 – The issuer or cardholder does not participate in a 3DS program.  7 – Payment authentication was not performed. Mastercard  2 – The cardholder was successfully authenticated.  1 – The issuer or cardholder does not participate in a 3DS program.  6 – Payment authentication was not performed.  7 – The cardholder was successfully authenticated for the initial MIT.
cavv ^String(50)	The card authentication verification value as received from the MPI.
dsTransID ^String(36)	The transaction ID received from the MPI for 3DS.
result ^String(20)	The cashier status of a merchant request. Possible values: APPROVED, DECLINED, ERROR
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter. In case of success (declined or approved), returns 0. Values as detailed in Response Handling. In addition, it can have the value of “-5”, which means the 3DS process was aborted.
errorDescription ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter. Values as detailed in Response Handling. In addition, it can have the value of “General 3D error”, which means the 3DS process was aborted.
cancelled ^String	If the process was canceled by the end user
transactionId ^String(20)	The Gateway transaction ID.
ccCardNumber ^String(20)	The credit card number in a mask (for example: 4****1111).
ccTempToken ^String	A temporary card token that can be used instead of your card number in your call to the /payment method.
bin ^String(6)	The BIN number representing the issuer.
last4Digits ^String(4)	The last four digits of the card number.
ccExpMonth ^String(2)	The expiration month
ccExpYear ^String(4)	The expiration year.
threeDReasonId ^String	Reason ID for a failed 3DS authorization as received from the issuer. Press here for more information.
threeDReason ^String	Reason description for a failed 3DS authorization as received from the issuer. Press here for more information.
challengeCancelReasonId ^String	Reason ID for a canceled 3DS authorization as received from the issuer.
challengeCancelReason ^String	Reason description for a canceled 3DS authorization as received from the issuer.
isExemptionRequestInAuthentication ^String	Indicates if an exemption was requested during authorization.
challengePreferenceReason ^String	This value is returned following a 3DS challenge and describes the reason for challenge. Press here for more information.

getCardDetails()

This method can be used by the merchant to retrieve details about a card, such as card type and brand. In addition, the method also returns the account’s currency, which is needed for Dynamic Currency Conversion (DCC).

For a Postman script that simulates this method, please press here, or refer to our guide for testing with Postman.

Input

Example Request

1
2
3
4
5
6
7
8
9
10
11
sfc.getCardDetails({
    sessionToken: result.sessionToken, // received from openOrder API
    merchantId: "1475082432483184221", // as assigned by Nuvei
    merchantSiteId: "184941", // as assigned by Nuvei
    cardNumber: "5111426646345761", // either cardNumber OR useFields: "true"
    useFields: "true", // either cardNumber OR useFields: "true"
    clientRequestId: "1C6CT7V1L",
    clientUniqueId: "12345"
}, function(cardDetails) {
    console.log(cardDetails);
  });

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
cardNumber ^String(20) %%Conditional	The full credit card number (for PCI-compliant merchants). REQUIRED if useFields is not provided.
useFields ^Boolean %%Conditional	Set this parameter to true to retrieve the card number from the Nuvei Fields object instead of the from cardNumber. REQUIRED if cardNumber is not provided.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
clientUniqueId ^String(45) ^Optional	The unique transaction ID in the merchant system. It appears in a DMN as the merchant_unique_id parameter.

Output

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
{
    "brand": "VISA",
    "secondaryBrand": "BancontactAcquirer",
    "cardType": "Credit",
    "bin": "511142",
    "last4digits": "5761",
    "ccExpMonth": "09",
    "ccExpYear": "21",
    "program": "Visa Platinum",
    "visaDirectSupport": "0",
    "issuerCountry": "pe",
    "currency": "pen",
    "dccAllowed": "false",
    "sessionToken": "eaeed493-6ed1-4e44-9cc9-7e698efe51e2",
    "internalRequestId": 212986558,
    "status": "SUCCESS",
    "reason": "",
    "errCode": 0,
    "merchantId": "479748173730597238",
    "merchantSiteId": "204388",
    "version": "1.0",
    "clientRequestId": "20201025110518",
    "isPrepaid": "false",
    "issuerBankName": "River Valley Credit Union"
}

Output Parameters

Parameter	Description
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
brand ^String	The name of the card scheme (for example: Visa).
secondaryBrand ^String(50)	The secondary brand supported by a co-badged card.
cardType ^String	The type of card used in the transaction. Possible values: credit, debit
bin ^String(6)	The BIN number representing the issuer.
last4Digits ^String(4)	The last four digits of the card number.
ccExpMonth ^String(2)	The expiration month
ccExpYear ^String(4)	The expiration year.
program ^String	The card program used in the transaction (for example: Visa Platinum).
cardProduct ^String	The code of the card program used in the transaction (for example: Commercial & Business).
visaDirectSupport ^String	Indicates whether Visa Direct is supported or not.
dccAllowed ^String	Indicates whether DCC is allowed for this card.
issuerCountry ^String(2)	2-letter ISO code of the card issuer’s country.
currency ^String(3)	The 3-letter ISO currency code.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
version ^String(10)	The current version of the API method. The current version is 1.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
status ^String	The cashier status of a merchant request. Possible values: SUCCESS, ERROR
isPrepaid ^String	Indicates if the card is prepaid or not.
issuerBankName ^String	Indicates the issuer bank name.

clientGetDccDetails()

This method calculates the DCC transaction amount and rateValueWithMarkup based on the selected payment method and target currency, as well as the original amount and currency provided in the /openOrder call.

Input

Example Request

1
2
3
4
5
6
7
8
9
10
11
sfc.clientGetDccDetails({
    sessionToken: result.sessionToken, // received from openOrder API
    merchantId: "1475082432483184221", //as assigned by Nuvei
    merchantSiteId: "184941", // as assigned by Nuvei
    cardNumber: "5111426646345761", // either cardNumber OR useFields: "true" OR apm: "<APM_API_name>"
    useFields: "true", // either cardNumber OR useFields: "true" OR apm: "<APM_API_name>"
    apm: "<APM_API_name>", // either cardNumber OR useFields: "true" OR apm: "<APM_API_name>"
    currency: "USD"
}, function(dccRes) {
    console.log(dccRes);
});

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(45) ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in a DMN as the merchant_unique_id parameter.
cardNumber ^String(20) %%Conditional	The full credit card number (for PCI-compliant merchants). REQUIRED if apm and useFields are not provided.
apm ^String(50) %%Conditional	The payment method. REQUIRED if cardNumber and useFields are not provided. For the values of specific APMs, press here.
useFields ^Boolean %%Conditional	Set this parameter to true to retrieve the card number from the Nuvei Fields object instead of the from cardNumber. REQUIRED if cardNumber and apm are not provided.
currency ^String(3) %%Conditional	The 3-letter ISO currency code of the conversion currency. REQUIRED if country is not provided. If both currency and country are provided in the input, the currency takes precedence.
country ^String(2) %%Conditional	The 2-letter ISO country code of the conversion country. REQUIRED if currency is not provided. If both currency and country are provided in the input, the currency takes precedence.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.

Output

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "amount": "178.29",
    "clientRequestId": "560673023851979",
    "currency": "USD",
    "dccFullSupport": "false",
    "errCode": 0,
    "internalRequestId": 289971718,
    "merchantId": "479748173730597238",
    "merchantSiteId": "204388",
    "originalAmount": "200",
    "originalCurrency": "EUR",
    "rateValueWithMarkUp": "0.8914572821049559",
    "reason": "",
    "sessionToken": "24a73293-d7e5-4aa5-a2d3-3d6fe2702c80",
    "status": "SUCCESS",
    "version": "1.0"
}

Output Parameters

Parameter	Description
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
rateValueWithMarkup ^String(12)	The rate value with markup.
markUpValue ^String(12)	The markup percentage value.
dccFullSupport ^Boolean	Determines if DCC is fully supported by the issuer or not. Possible values: true – DCC is supported by issuer. false – DCC not supported by issuer.
amount ^String(12)	The converted amount.
currency ^String(3)	The 3-letter ISO currency code of the conversion currency.
originalAmount ^String(12)	The original amount of the transaction in the currency that the merchant requested.
originalCurrency ^String(12)	The 3-letter ISO currency code of the currency that the merchant requested in the transaction.
status ^String(20)	The cashier status of a merchant request. Possible values: SUCCESS, 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, then an error reason is returned in this parameter.
version ^String(10)	The current version of the API method. The current version is 1.

accountCapture()

A few APMs require you to collect third-party information from the customer to process a withdrawal (payout) request. Once the merchant has successfully obtained a session token by calling /getSessionToken, the merchant can call the accountCapture() method to request a URL from one of these APMs and redirect the customer to capture their bank account details. It stores the captured data in a UPO record, which you can then include in a /payout request.

Press here for additional information including a list of supported APMs.

Input

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
sfc.accountCapture({
    sessionToken: result.sessionToken, // received from openOrder API
    merchantId: "1475082432483184221", // as assigned by Nuvei
    merchantSiteId: "184941", // as assigned by Nuvei
    paymentMethod: "apmgw_PayRetailers_Payouts",
    userTokenId: "230811147",
    currencyCode: "MXN",
    countryCode: "MX",
    languageCode: "es"
    urlDetails:{
        successUrl: "[URL the customer is directed to after a successful transaction]",
        failureUrl: "[URL the customer is directed to after an unsuccessful transaction]",
        pendingUrl: "[URL the customer is directed to when the transaction response is pending]",
        notificationUrl: "[URL to which DMNs are sent]"
    },
}, function(accountRes) {
    console.log(accountRes);
});

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system. This must be sent when using the User Payment Management feature.
paymentMethod ^String(50) ~Required	Specifies the payment method name of the payment option to be charged. See: APM Input Parameters.
currencyCode ^String(3) ~Required	The 3-letter ISO currency code.
countryCode ^String(2) ~Required	The 2-letter ISO country code.
languageCode ^String(2) ^Optional	The language in which the transaction is to be completed.
urlDetails ^Class ^Optional	With this class, a merchant can dynamically provide possible URLs to which the end user is redirected after a payment is made, as well as a dynamic URL for DMNs. successUrl (String, 1000) – The URL the customer is directed to after a successful transaction. failureUrl (String, 1000) – The URL the customer is directed to after an unsuccessful transaction. pendingUrl (String, 1000) – The URL the customer is directed to when the transaction response is pending. notificationUrl (String, 1000) – The URL to which DMNs are sent. Although DMN responses can be configured per merchant site, this parameter allows dynamically returning the DMN to the provided address per request. NOTE: If showAccountCapture is set to true, but the urlDetails class is empty (no URLs received), then the redirect pop-up is closed automatically. appReturnLink (String, 255) – The deep link used to return to the merchant native application (press here for an example). NOTE: This parameter is not supported for all cases. appUrl (String, 255) – Link to which the provider redirects the user at the end of the payment process (press here for an example). NOTE: This parameter is not supported for all cases.

Output

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
{
    "redirectUrl": "https://apmtest.gate2shop.com/ppp/resources/cdn/v1/bank-details-7613.html?submitUrl\u003dhttps%3A%2F%2Fjumpbox.safecharge.com%2Fdmz%2FApmConnector%2FbankCapture%2F9F4FADA84DCD3BF0968819EA8DF3B67E\u0026country\u003dUS\u0026locale\u003den_US",
    "userTokenId": "bankCaptureUser4",
    "sessionToken": "e44a932a-e9fc-4482-a570-cf07175408e0",
    "internalRequestId": 23238261,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "8256777005602846935",
    "merchantSiteId": "112106",
    "version": "1.0"
}

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by getSessionToken.
merchantId ^String(20)	Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	Merchant Site ID provided by Nuvei.
redirectUrl ^String(1000)	The URL the client is redirected to in order to enter bank account details.

setOpenAmount()

The setOpenAmount() method is used to set or override the payment amount (in the same currency) from the client side.

Use the setOpenAmount() method:

• When an amount was not sent in the /openOrder request.
• To change a payment amount (same currency) if you have not called the createPayment() request yet. For example, whenever the customer changes any amount on your payment page.

Call the setOpenAmount() method from the client-side, as shown below: (If you included the openAmount{min,max} object in the /openOrder request earlier, then the system also validates that the amount falls within the (min,max) limits.)

Example Request

1
2
3
4
5
6
7
sfc.setOpenAmount({
     clientRequestId: "1C6CT7V1L",
     clientUniqueId: "12345",
     amount: "156"
}, function(crRes) {
     console.log(crRes);
});

getUserUPOs()

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

Example Request

1
2
3
sfc.getUserUPOs(function(response) {
    console.log(response);
});

getToken()

Use this method to get a temporary one-time token (ccTempToken).

A temporary token is valid only for an API session, and is used only if you are processing with our server-to-server API and wish to be PCI descoped.

The return value from the function is ccTempToken, which can then be used in the server-to-server API /payment API call.

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
sfc.getToken(scard, {
    sessionToken: "cca3885e-aeeb-4844-b405-d084445d89ff",
    cardHolderName: "CL-BRW1",
    billingAddress: {
        email: "[email protected]",
        country: "US"
    }
}).then(function(result) {
    if (result.status === 'SUCCESS') {
        console.log(result);
        //pass the result.ccTempToken to the server side
    } else {
        console.log(result);
    }
});

destroy()

This method is used to remove the payment element from the payment page.

Example Request

1
destroy()

addApmUpo()

This method is used to register a new APM UPO with the provided APM details.

Input

Example Request

1
2
3
4
5
6
7
8
9
10
sfc.addApmUpo({
    paymentMethodName: "apmgw_expresscheckout",
    apmData: {email: "[email protected]"},
    billingAddress: { // optional
        email: "[email protected]",
        country: "US"
    }},
    function(result) {
    console.log(result);
});

Input Parameters

PARAMETER	DESCRIPTION
paymentMethodName ^String(50) ~Required	Nuvei’s unique name of the payment method (for example apmgw_Neteller). For a list of possible values, see the “paymentMethod” column in the table in APM Payments.
apmData ^Class ~Required	List of name-value pairs that contain the parameters of the user payment option. The same parameters used in the “Payment Input Fields” column should be used in this class. For more information, refer to APM Payments.
billingAddress ^Class ^Optional	country (String, 2) – 2-letter ISO country code NOTE: For certain APMs, countryCode is used instead. email (String, 100) firstName (String, 30) lastName (String, 40) address (String, 50) cell (String, 18) phone (String, 18) zip (String, 10) city (String, 30) state (String, 3) – ISO country subdivision code county (String, 255)

Output

Example Response

1
2
3
4
5
6
7
{
    "result": "ADDED",
    "errCode": 0,
    "errorDescription": "",
    "userPaymentOptionId": "14958143",
    "cancelled": false
}

Output Parameters

PARAMETER	DESCRIPTION
result ^String(20)	The cashier status of a merchant request. Possible values: ADDED, ERROR
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter. In case of success (declined or approved), returns 0. Values as detailed in Response Handling. In addition, it can have the value of “-5”, which means the 3DS process was aborted.
errorDescription ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter. Values as detailed in Response Handling. In addition, it can have the value of “General 3D error”, which means the 3DS process was aborted.
userPaymentOptionId ^String	Represents the ID for the newly created payment option, which can be referenced in future requests. Refer to Card-on-File for further details.
cancelled ^Boolean	If the process was canceled by the end user.

addCardUpo()

This method is used to register a new credit card UPO with the provided credit card details.

Input

Example Request

1
2
3
4
5
6
7
8
9
10
sfc.addCardUpo({
    useFields: true, // or websdk cardNumber object
    cardHolderName: document.getElementById('cardHolderName').value, // optional
    billingAddress: { // optional
        email: "[email protected]",
        country: "US"
    }},
    function(result) {
        console.log(result);
});

Input Parameters

PARAMETER	DESCRIPTION
useFields ^Boolean %%Conditional	Set this parameter to true to retrieve the card number from the Nuvei Fields object instead of the from cardNumber. REQUIRED if cardNumber is not provided.
cardNumber ^String(20) %%Conditional	A valid credit card number. REQUIRED if useFields is not provided.
expMonth ^String(2) %%Conditional	2-digit value representing the expiration month. REQUIRED if useFields is not provided.
expYear ^String(2) %%Conditional	2-digit or 4-digit value representing the expiration year. When the value is two digits, the year is assumed to be 2000 + ccExpYear. The expMonth and expYear must be a future date. The year may not exceed 10 years in to the future. REQUIRED if useFields is not provided.
cardHolderName ^String(70) ^Optional	The cardholder name. Can only be used if useFields is not provided.
billingAddress ^Class ^Optional	country (String, 2) – 2-letter ISO country code NOTE: For certain APMs, countryCode is used instead. email (String, 100) firstName (String, 30) lastName (String, 40) address (String, 50) cell (String, 18) phone (String, 18) zip (String, 10) city (String, 30) state (String, 3) – ISO country subdivision code county (String, 255)

Output

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
{
    "result": "ADDED",
    "errCode": 0,
    "errorDescription": "",
    "userPaymentOptionId": "14958143",
    "ccCardNumber": "5****5761",
    "bin": "511142",
    "last4Digits": "5761",
    "ccExpMonth": "09",
    "ccExpYear": "21",
    "cancelled": false
}

Output Parameters

PARAMETER	DESCRIPTION
result ^String(20)	The cashier status of a merchant request. Possible values: ADDED, ERROR
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter. In case of success (declined or approved), returns 0. Values as detailed in Response Handling. In addition, it can have the value of “-5”, which means the 3DS process was aborted.
errorDescription ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter. Values as detailed in Response Handling. In addition, it can have the value of “General 3D error”, which means the 3DS process was aborted.
userPaymentOptionId ^String	Represents the ID for the newly created payment option, which can be referenced in future requests. Refer to Card-on-File for further details.
ccCardNumber ^String(20)	The credit card number in a mask (for example: 4****1111).
bin ^String(6)	The BIN number representing the issuer.
last4Digits ^String(4)	The last four digits of the card number.
ccExpMonth ^String(2)	The expiration month
ccExpYear ^String(4)	The expiration year.
cancelled ^Boolean	If the process was canceled by the end user.

createApplePayPayment()

This method is used to validate the merchant domain. After the payment token from the Apple device is generated, the method calls createPayment() and continues with the payment.

Input

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
sfc.createApplePayPayment({
    sessionToken: "sessionToken", // received from openOrder API
    merchantId: "1475082432483184221", // as assigned by Nuvei
    merchantSiteId: "142033", // as assigned by Nuvei
    clientUniqueId: "12345", // optional
    countryCode: 'GB',
    currencyCode: 'GBP',
    applePay3Dflow: "disable", // disable (default), enable
    collectUserDetails: false,
    billingAddress: {
        firstName: 'John',
        lastName: 'Smith',
        country: 'US',
        email: '[email protected]'
    },
    userDetails: {
        firstName: 'John',
        lastName: 'Smith',
        country: 'US',
        email: '[email protected]'
    }
    shippingAddress: {
        firstName: 'John',
        lastName: 'Smith',
        address: '22 Main Street',
        city: 'Boston',
        zip: '02460',
        state: 'MA',
        country: 'US'
    },
    total: {
        label: 'Your Company',
        amount: '19.99'
  }
    function(res) {
        console.log(res)
    }
});

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
currencyCode ^String(3) ~Required	The 3-letter ISO currency code.
countryCode ^String(2) ~Required	The 2-letter ISO country code.
total ^Class ~Required	Used for UI purposes for Apple Pay. label – The label of the company that is presented in the payment pop-up. amount – The payment amount that is presented in the payment pop-up.
applePay3Dflow ^String(7) ^Optional	Allows the merchant to decide which flow the Web SDK uses to process the transaction. Possible values: enable – The transaction is processed with 3DS verification. disable (default) – The card transaction is processed as a non-3D Apple Pay transaction.
collectUserDetails ^String(5) ^Optional	Determines if customer details are collected from the Apple Pay supported device. Possible values: true, false (default)
clientUniqueId ^String(45) ^Optional	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in a DMN as the merchant_unique_id parameter.
billingAddress ^Class ^Optional	The billing address related to a user payment option. country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30, REQUIRED) lastName (String, 40, REQUIRED) These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This represents the customer’s identification number in their respective country. NOTE: When processing a createPayment(), authenticate3d(), or checkout() request, if you provided any billingAddress values (such as country and email), then the system uses those values instead of the values provided in the userDetails class.
shippingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (String, 100) county (String, 255)

Output

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "bin": "520424",
    "cancelled": false,
    "cavv": "",
    "ccCardNumber": "****0049",
    "ccExpMonth": "09",
    "ccExpYear": "26",
    "dsTransID": "",
    "eci": "",
    "errCode": "0",
    "errorDescription": "",
    "last4Digits": "0049",
    "mcc": "",
    "result": "APPROVED",
    "transactionId": "8110000000000691752",
    "transactionStatus": "APPROVED",
    "transactionType": "Auth",
    "xid": ""
}

Output Parameters

PARAMETER	DESCRIPTION
result ^String(20)	The cashier status of a merchant request. Possible values: ADDED, ERROR
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter. In case of success (declined or approved), returns 0. Values as detailed in Response Handling. In addition, it can have the value of “-5”, which means the 3DS process was aborted.
errorDescription ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter. Values as detailed in Response Handling. In addition, it can have the value of “General 3D error”, which means the 3DS process was aborted.
ccCardNumber ^String(20)	The credit card number in a mask (for example: 4****1111).
bin ^String(6)	The BIN number representing the issuer.
last4Digits ^String(4)	The last four digits of the card number.
ccExpMonth ^String(2)	The expiration month
ccExpYear ^String(4)	The expiration year.
cancelled ^Boolean	If the process was canceled by the end user.
cavv ^String(28)	The cardholder authentication verification value that is passed from the issuer to the merchant after the card authentication has taken place during the payment flow.
dsTransID ^String(36)	The transaction ID received from the MPI for 3DS.
eci ^String	Indicates the level of security used in a 3DS program when the cardholder provides payment information to the merchant. Press here for possible eci data values.
mcc ^String(4)	A 4-digit number that classifies the type of goods or services a business offers.
transactionId ^String(20)	The Gateway transaction ID.
transactionStatus ^String(20)	The Gateway transaction status.
transactionType ^String(45)	The type of transaction.

submitWdRequest()

This method allows a user to submit a withdrawal request.

Input

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
let withdrawal = window.websdk({
    sessionToken: "sessionToken", // => received from openOrder
    env: "int", // "prod"
    merchantSiteId: "merchantSiteId", // => assigned by Nuvei
    merchantId: "merchantId" // => assigned by Nuvei
});

withdrawal.submitWdRequest({
     merchantId: "8256777005602846935",
     merchantSiteId: "112106", 
     upoId: 91963498, 
     amount: 115.20, currency: "USD", 
     merchantUniqueId: "12345", 
     merchantWDRequestId: "123456789", 
     userId: "850512345", 
     userDetails: {email: "[email protected]"}, 
     userAccountId: "test", 
     userTokenId: "230811147",
     customField1: "test"
}, function(result) {
    console.log(result);
});

Input Parameters

PARAMETER	DESCRIPTION
upoId ^String ~Required	ID of the payment methods to which the customer wants the funds withdrawn.
amount ^String ~Required	Amount that the customer wants to withdraw.
userId ^String ~Required	User ID the merchant generates for the customer.
sessionToken ^String(20) ^Optional	The sessionToken retrieved from a call to /openOrder that references the order created in the Nuvei system. If not provided, its value is taken from the websdk() initialization.
merchantId ^String ^Optional	Merchant ID provided by Nuvei. If not provided, its value is taken from the websdk() initialization.
merchantSiteId ^String ^Optional	Merchant Site ID provided by Nuvei. If not provided, its value is taken from the websdk() initialization.
merchantWDRequestId ^String ^Optional	A unique ID generated by the merchant for the withdrawal order.
merchantUniqueId ^String ^Optional	This parameter is sent by the merchant and is used to associate a request with the merchant system.
userAccountId ^String ^Optional	The customer’s Account ID on the merchant’s site. The value of this parameter indicates which account balance the withdrawn funds should be applied to when the customer has multiple accounts on the merchant site.
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) countryCode (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (String, 100)
customFieldX ^String(255) ^Optional	Fifteen custom fields that can be used by replacing X with 1 to 15. The customFieldX that the merchant passed as the customFieldX parameter initially when making the first request to the Withdrawal API.
userTokenId ^String(255) ^Optional	This parameter is a unique identifier for each customer generated by the merchant.

Output

Example Response

1
2
3
4
5
6
7
8
9
{
    "errCode": 0,
    "reason": "",
    "wdRequestStatus": "Approved",
    "wdRequestId": 8675309,
    "merchantWDRequestId": "123456789",
    "userAccountId": "test",
    "userId": "850512345"
}

Output Parameters

PARAMETER	DESCRIPTION
errCode ^Integer(11)	Error code when a withdrawal request is declined.
reason ^String	Reason an error occurred.
wdRequestStatus ^String	The current status of the withdrawal request: Pending: The initial Status of all requests. This indicates the transaction has not yet been processed. Approved: The request was approved. Declined: You or the APM declined the transaction. Canceled: The customer canceled the request from the Withdraw page. Partially Approved: The request is partially approved. This is relevant for split requests only. Error: Indicates an error occurred.
wdRequestId ^Integer(20)	ID of the withdrawal request generated by Nuvei.
merchantWDRequestId ^String	A unique ID generated by the merchant for the withdrawal request.
userAccountId ^String	The customer’s Account ID on the merchant site. Only the merchant knows this value and no validations are performed by Nuvei.
userId ^String	An external user ID the merchant generates for the customer. This ID is for the merchant records and tracking purposes only.

getWdRequests()

This method returns a list of the user’s pending withdrawal requests for the merchant to show to the user.

Input

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
var websdkInst = websdk({
    sessionToken: "sessionToken", // => received from openOrder
    env: "int", // "prod"
    merchantSiteId: "merchantSiteId", // => assigned by Nuvei
    merchantId: "merchantId" // => assigned by Nuvei
});

websdkInst.getWdRequests({
    userTokenId: 230811147
},
    function(result) {
        console.log(result);
})

Input Parameters

PARAMETER	DESCRIPTION
userTokenId ^String(255) ~Required	This parameter is a unique identifier for each customer generated by the merchant.

Output

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
{
    "internalRequestId": 1163370518,
    "status": "SUCCESS",
    "errCode": 0,
    "merchantId": "8536594779582844752",
    "merchantSiteId": "231188",
    "version": "1.0",
    "sessionToken": "19070b07-ae43-4e2e-9e51-b5d1ac4c44b6",
    "totalCount": 1,
    "merchantSiteName": "Any Site Name",
    "withdrawalRequests": [
        {
            "appId": null,
            "userTokenId": "23081114722",
            "userId": "850512345",
            "userDetails": {
                "firstName": "John",
                "lastName": "Smith",
                "address": "22 Main Street",
                "phone": "6175551414",
                "zip": "02460",
                "city": "Boston",
                "countryCode": "US",
                "state": "MA",
                "email": "[email protected]"
            },
            "userAccountId": null,
            "wdRequestId": "8675309",
            "merchantWDRequestId": null,
            "userPMId": "120610868",
            "requestedAmount": "115.2",
            "requestedCurrency": "USD",
            "state": "Open",
            "wdRequestStatus": "Pending",
            "creationDate": "20240712160557",
            "lastModifiedDate": "20240712160557",
            "dueDate": "20240712160557",
            "operatorName": null,
            "pendingKyc": null,
            "wdRequestOrderCount": 0,
            "pmName": "Card",
            "pmIssuer": "MasterCard",
            "pmDisplayName": "5****1111",
            "approvedAmount": "0.0",
            "merchantUniqueId": null,
            "feeAmount": null,
            "merchantSiteInfo": {
                "merchantSiteName": "Any Site Name",
                "merchantSiteId": "231188"
            }
        }
    ]
}

Output Parameters

PARAMETER	DESCRIPTION
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
status ^String(20)	The status of the merchant API request/call. Possible statuses: SUCCESS or ERROR.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
merchantId ^Long	Your unique identification number provided by Nuvei.
merchantSiteId ^Long	Your website’s unique identification number provided by Nuvei.
version ^String(10)	The current version of the request. The current version is 1.
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
totalCount ^String	Total number of requests returned.
merchantSiteName ^String	The name of the site in your account where the request originated.
withdrawalRequests ^Array	Details of the withdrawal requests and for each request its order details. appId (String) userTokenId (String) – This ID uniquely identifies your consumer/user in your system userId (String) – The user ID given by the merchant to the customer. userDetails (Class)  firstName (String, 30)  lastName (String, 50)  address (String, 50)  phone (String, 18)  zip(String, 10)  city (String, 30)  country (String, 2) – 2-letter ISO country code  state (String, 2) – 2-letter ISO state code)  email (REQUIRED)(String, 100) 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. wdRequestId (String) – ID of the withdrawal request generated by Nuvei. merchantWDRequestId (String) – A unique ID that you generate for the withdrawal request. userPMId (String) – A unique ID automatically generated by Nuvei that represents the payment method selected by the customer. requestedAmount (String) – The requested withdrawal amount. requestedCurrency (String) – The requested withdrawal currency. state (String) wdRequestStatus – The current status of the withdrawal request. Press here for possible values. creationDate (String) – The date on which the request was created. lastModifiedDate (String) – The last date on which the request was modified. dueDate (String) operatorName – The name of the administrator of the request. pendingKyc (String) wdRequestOrderCount – Retrieves only requests that have exactly <wdRequestOrderCount> number of orders. This parameter is overridden by the wdRequestOrderCountRange parameter (if it is present). pmName (String) – The type of the payment method (such as PayPal and credit card). pmIssuer (String) – The credit card company that processed the original transaction. pmDisplayName (String) – For credit card, last four digits of the card number; for APMs, this value represents the user’s account name, such as PayPal email address or Neteller Secure ID. approvedAmount (String) – The approved withdrawal amount. merchantUniqueId – This parameter is sent by the merchant and is used to associate a request with the merchant system. This value must be unique. feeAmount (String) – The fee amount for this request (if relevant). merchantSiteInfo (Class)  merchantSiteName (String) – The name of the site in your account where the request originated.  merchantSiteId – Your website’s unique identification number provided by Nuvei.

cancelWdRequest()

This method cancels an existing withdrawal request.

Input

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
var websdkInst = websdk({
    sessionToken: "sessionToken", // => received from openOrder
    env: "int", // "prod"
    merchantSiteId: "merchantSiteId", // => assigned by Nuvei
    merchantId: "merchantId" // => assigned by Nuvei
});

websdkInst.cancelWdRequest({
    userTokenId: 230811147,
    wdRequestId: 8675309
},
    function(result) {
        console.log(result);
})

Input Parameters

PARAMETER	DESCRIPTION
userTokenId ^String(255) ~Required	This parameter is a unique identifier for each customer generated by the merchant.
wdRequestId ^Integer(20) ~Required	A unique ID generated by Nuvei returned in the DMN for the request.

Output

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": "Canceled",
    "wdRequestId": 8675309,
    "merchantWDRequestId": "741852",
    "userAccountId": "5675306"
}

Output Parameters

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

Simply Connect

Simply Connect Overview

The Nuvei Simply Connect integration platform is a feature-rich and flexible end-to-end payment solution based on a JavaScript library of API methods. It is hosted directly on your web page, so there is no need to redirect your customer to a different page or IFrame. You can use Simply Connect as an “out-of-the-box” solution, or it can be customized according to your preferences.

For a complete guide to Simply Connect, including its advantages, please refer to the Simply Connect topic in our main documentation portal.

 

Simply Connect Methods

checkout()

Use this method as a single end-to-end solution for accepting payments. It integrates easily into your payment flow and has its own customizable UI, which embeds seamlessly into your payment page.

Input

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
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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
function main() {
    document.getElementById('checkout').innerHTML = "";
    checkout({
        sessionToken: document.getElementById('session').value,
        merchantSiteId: "142033",
        merchantId: "427583496191624621",
        country: "US", // detect
        currency: "USD",
        userId: "259",
        renderTo: ".container_for_checkout",
        amount: "135",
        openAmount: {
            min: "1",
            max: "500"
        },
        amountSuggestions: ["110", "120", "130"],
        onResult: function(result) {
            console.log("Result", result)
        },
        billingAddress: {
            firstName: "John",
            lastName: "Smith",
            email: "[email protected]",
            country: "US"
        },
        onReady: function(result) {
            console.log(result);
        },
        onSelectPaymentMethod: function(paymentDetails) {
            console.log("onSelectPaymentMethod", paymentDetails);
        },
        onPaymentEvent: function(result) {
            console.log('onPaymentEvent =>', result);
        },
        upoDeleted: function(paymentDetails) {
            console.log("upoDeleted", paymentDetails);
        },
        prePayment: function(paymentDetails) {
            return new Promise((resolve, reject) => {
                console.log(paymentDetails);
                resolve(); // reject(), reject('Message')
            });
        },
        onPaymentFormChange: function(pm, label, action, oldValue, newValue, validation, pasted) {
            console.log('onPaymentFormChange =>', pm, label, action, oldValue, newValue, validation, pasted);
        },
        onSuggestedAmount: function(result) {
            console.log('onSuggestedAmount', result);
        },
        disableDeclineRecovery: false,
            onDeclineRecovery: function(declineRecoveryHistory) {
                console.log('Decline Recovery History =>', declineRecoveryHistory); 
                var declineRecoveryOverride; 
                if (!isOverriden) { 
                    declineRecoveryOverride = {nextPm: true, differentCard: true, retry: true, supportMessage: "[email protected]"}; 
                    isOverriden = true; 
                } 
                return new Promise((resolve, reject) => { 
                    resolve(declineRecoveryOverride); 
                }); 
            }, 
        });
        useDCC: "disable", // enable, force 
        strictDcc: "false", // false means customers can use a card even if it isn't "DCC Allowed"
        savePM: "true", // option to save payment method for future use and needed for apm recurring billing
        selectUpo: 83648899, // "83648899", "first"
        selectPM : "apmgw_<APM provider name>", // first, none
        promoCode: true, // The default value is false.
        support19Digits: true, // false (default)
        upoRestriction: {
            maxApmUpos: 4,
            onePerApm: true,
            maxCards: 7
        },
        disableDeleteUpoButton: false, // true
        prepopulateApmFields: {
            iban: "12345678909",
            email: "[email protected]"
        },
        cardInstallments: {
            installmentType: {
                singlePayment: true,
                type1: [2,3,4,5,6],
                type2: [6,12,18]
            },
        nationalID: true
        },
        readonlyPrepopulateApmFields: "false", // true
        subMethod: ["PayNPlay", "QuickRegistration"], // for APMs that support Customer Registration via APM
        pmWhitelist: ["apmgw_QIWI", "apmgw_MoneyBookers"],
        showCardLogos: true, // default is false 
        blockCards: [
            ["visa", "credit", "corporate"],
            ["amex", "GB", "prepaid"]
        ], // Visa corporate credit cards and British prepaid Amex cards are blocked
        // or cardWhitelist: [["visa", "credit", "corporate"],["amex", "GB", "prepaid"]],
        blockPasteCard: true,
        alwaysCollectCvv: "true",
        maskCvv: true,
        fullName: document.getElementById('cardHolderName').value,
        email: "[email protected]",
        locale: "en", // de, es, fr, it, pl, pt, ru
        textDirection: "ltr", // rtl
        env: "int", // "prod"
        cardLogo: {
            cardLogoPosition: "right",
            backgroundSize: "30px 40px"
        },  //or cardLogo: false -> to hide the card logo
        disableDeclineRecovery: "true",
        apmWindowType: "newTab", // popup (default), redirect
        theme: "tiles", // accordion, horizontal, cashier
        paymentTiles: "splash", // showMore
        apmConfig: {
            apmgw_PIX: {
                savePM: "true",
                fields: {
                    pix_key: "hidden", // optional or hidden
        },
        showResponseMessage: true, //false, {pending:false, decline:false, success:true, expired:false}
        autoOpenPM: true
            // logLevel: 0,
            // i18n: {
            //     my_methods: "Meine Zahlungsmethoden"
            //     card_number: "KARTA",
            //     mm_yy: "MMM / YYY",
            //     cvv: "CVVV"
            // }
    });
}

Mandatory Basic Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(20) ~Required	The sessionToken retrieved from a call to /openOrder that references the order created in the Nuvei system.
merchantId ^String(20) ~Required	Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	Merchant Site ID provided by Nuvei.
amount ^String(20) ~Required	Mandatory for visualization purposes similar to currency.
currency ^String(20) ~Required	It is used for visualization in the payment method (button, Apple Pay overlay), as well as for filtering supported payment methods.
renderTo ^String ~Required	The name of the HTML container that you previously created for checkout().
country ^String(2) ~Required	The 2-letter ISO country code. Used as a filter in retrieving payment methods. Must be entered in uppercase. Alternatively, you can enter a value of “detect” so the current country is automatically detected by geolocation.
userId ^String(20) ~Required	The ID of the customer in the merchant system. NOTE: This is not to be confused with userTokenId.
onResult ^Function ~Required	Defines a callback function called to provide the full response information each time a payment request is returned – declines, errors, and approvals. Press here for more information.
billingAddress ^Class ~Some Parameters Required	The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters. country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30, REQUIRED) lastName (String, 40, REQUIRED) address (String, 50) addressLine2 (String, 50) addressLine3 (String, 50) phone (String, 18) zip (String, 10) city (String, 30) state (String, 3) – ISO country subdivision code county (String, 255) These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.

UI Customization Input Parameters

PARAMETER	DESCRIPTION
locale ^String(2) ^Optional	Language in which the text is displayed. Supported languages: de, en (default), es, fr, it, pl, pt, ru
i18n ^String ^Optional	Used to define custom messages to replace existing ones (also known as “internationalization”). Press here for more information.
textDirection ^String(3) ^Optional	Sets the text direction. Possible values: ltr (left-to-right) (default), rtl (right-to-left)
fieldStyle ^Object ^Optional	Used to customize the look and feel of the Simply Connect form to match your payment page by customizing the styles of the payment HTML forms. Press here for more information.
theme ^String ^Optional	Determines the theme used for the checkout page. Possible values: accordion (default), horizontal, tiles, cashier
paymentTiles ^String ^Optional	Determines how the payment gallery is opened by default. Possible values: splash (default), showMore NOTE: If there are no UPOs, the gallery opens with “Show more”.
showCardLogos ^Boolean ^Optional	When set to true, all supported card logos are displayed, except logos of cards that are blocked by blockCards. Possible values: false (default), true
cvvIcon ^String ^Optional	Determines if an icon appears in the CVV textbox, which also shows a tooltip on mouseover. Possible values: false (default) – No icon is displayed. true – A default icon is displayed. Additionally, you can provide an object that allows setting a different icon and position.  backgroundImage – Custom URL  tooltipPosition: top or bottom

Payment Customization Input Parameters

PARAMETER	DESCRIPTION
openAmount ^Class ^Optional	Allows the merchant to set amount limits, which are validated. min (String) – Minimum payment amount. max (String) – Maximum payment amount. Press here for more information.
amountSuggestions ^Array ^Optional	Allows the merchant to suggest up to three amounts.
payButton ^String(13) ^Optional	Determines how the amount is displayed. Possible values: amountButton (default) – Displays the amount on the pay button. textButton – Displays text on the button. noButton – The button can be displayed outside the Simply Connect form. NOTE: When the user presses the button, it calls the checkout.submitPayment() method, which invokes a payment process outside the checkout() method flow.
pmWhitelist ^Array ^Optional	An array of only the specified APMs that are displayed to the customer in the Payment Methods list. NOTE: pmWhiteList and pmBlacklist cannot be used together in the same initialization.
pmBlacklist ^Array ^Optional	An array of the specified APMs that are not displayed to the customer in the Payment Methods list even if they are returned by an API. NOTE: pmWhiteList and pmBlacklist cannot be used together in the same initialization.
blockCards ^Array ^Optional	Specifies cards and sets of cards you do not accept. You can include blockCards or cardWhiteList in a checkout() request. Do not include both. Press here for more information.
cardWhiteList ^Array ^Optional	Specifies cards and sets of cards you accept. You can include cardWhiteList or blockCards in a checkout() request. Do not include both. Press here for more information.
blockPasteCard ^Boolean ^Optional	When set to true, no card details can be pasted into any of the card input fields. Possible values: false (default), true
useDCC ^String ^Optional	Determines how the DCC is set for the user and/or the user session. Possible values: enable – Enables the checkbox. disable (default) – Disables the checkbox. force – Enables and selects the checkbox. The customer is still able to clear the checkbox.
strictDcc ^String ^Optional	Allows a merchant to perform a DCC conversion even if the card is not returned by the APM as DCC enabled. Possible values: false (default) – Customers are allowed to use DCC even for cards that do not have the status of “DCC Allowed” (set by the issuing bank). true – Customers are only allowed to use DCC for cards that have the status of “DCC Allowed” (set by the issuing bank).
alwaysCollectCvv ^String ^Optional	Determines how and when to display the CVV parameter. Possible values: true (default) – Always displays the CVV parameter. false – Displays the CVV parameter for UPOs only. never – Never displays the CVV parameter. optional – Always displays the CVV parameter, but as an optional parameter. upoOptional – Displays the CVV parameter for UPOs only, and as an optional parameter.
maskCvv ^String ^Boolean	Determines if the CVV digits in the CVV text box are masked (true) or visible (false)(default).
disableDeclineRecovery ^Boolean ^Optional	When set to false, the end user is offered alternative ways to complete the transaction, such as suggesting a different APM, suggesting another card, and contacting Tech Support. Possible values: true (default), false
showResponseMessage ^String ^Optional	Controls the message dialogs for the Simply Connect form. Possible values: True (default) – All transaction pop-ups (pending, success, and decline) and the session pop-up (expired) are displayed. False – Only the expired pop-up is displayed (transaction pop-ups are not). Additionally, you can provide an object that contains the four possible pop-up types and set the value for each as desired.
autoOpenPM ^String ^Optional	Controls whether payment methods are always open in the presence of a UPO. Possible values: true (default) – The APM section is never collapsible. false – The APM section is collapsible only if UPOs exist; otherwise, it is not collapsible. hide – The APM section is not displayed at all (including the header).
apmWindowType ^String ^Optional	Allows merchants to choose how an APM window is opened. Possible values: popup (default) – A pop-up window opens, redirecting the customer to their APM provider’s page. newTab – A pop-up window opens in a new browser tab, redirecting the customer to their APM provider’s page. redirect – A modal window opens automatically on top of the current payment page, redirecting the customer to their APM provider’s page. NOTE: To use the redirect window type, you must have already provided the urlDetails class in the /openOrder request for the system to navigate the customer back after leaving the APM provider’s page.
subMethod ^Array ^Optional	An array of alternative payment flows. For APMs that support customer registration via APM: [QuickRegistration,PayNPlay] For APMs that support Fast Flow: [ReferenceTransaction,AliasRegistration,Skrill1Tap]
savePM ^String ^Optional	Determines whether to present the user with a checkbox to save payment details and whether Nuvei saves them as a UPO. Possible values: true (default) – Checkbox to save payment details appears. If the user selects it, Nuvei saves the payment details as a UPO. Required in the initial request of an APM Recurring Billing transaction. force – Checkbox to save payment details appears. Selected by default, the user can clear the checkbox. false – Checkbox to save payment details does not appear. Therefore, users cannot save them and Nuvei cannot save them as a UPO. always – Instead of the checkbox to save payment details, an agreement message appears, and Nuvei saves the payment details as a UPO.
savePmUrl ^String ^Optional	URL for the terms and conditions regarding secure storing of payment details. - For a link to savePmUrl to appear in addition to the agreement message, savePM must be always.
apmConfig ^Class %%Conditional	You can use the apmConfig class to provide payment method-specific parameters.  apmgw_<paymentMethod> (Class) – Identifies the payment method. For example: PayPal is apmgw_expresscheckout; cc_card is for all credit cards; and so on.   savePM (String) – For the specified payment method, determines whether to present the user with a checkbox to save payment details and whether Nuvei saves them as a UPO. Overrides the general savePM value.    Possible values:    true (default) – Checkbox to save payment details appears. If the user selects it, Nuvei saves the payment details as a UPO. Required for the initial request of an APM Recurring Billing transaction.    false – Checkbox to save payment details does not appear. Therefore, users cannot save them and Nuvei cannot save them as a UPO.    always – Instead of the checkbox to save payment details, an agreement message appears, and Nuvei saves the payment details as a UPO.   apmConfig.apmgw_ classes support other APM-specific parameters. For example, Apple Pay supports apmConfig.applePay.buttonType, which allows a merchant to customize the Apple Pay button text. When relevant, information about APM-specific apmConfig.apmgw_ parameters appears in the APM guide and on the APM Input Parameters page.
selectUpo ^String ^Optional	A merchant can now preselect a UPO based on its UPO ID (either as a number 11111 or as a string “11111”), or the merchant can set it to “first”, in which case the first UPO is selected.
selectPM ^String ^Optional	Determines the behavior of preselection of payment methods (PMs) per available themes. Possible values: apmgw_<APM provider name> – The entered payment method is preselected in the payment page. first – In the accordion theme, the first PM is preselected and opened by default. In the tiles/horizontal themes, the first PM is preselected. none – In the accordion theme, all PMs are collapsed and none are preselected. In the tiles/horizontal/cashier themes, no PMs are preselected and no payment details are shown. NOTE: selectUpo has priority over selectPM.
fullName ^String ^Optional	Used to prefill the cardHolderName parameter.
email ^String ^Optional	Used to prefill the email parameter for relevant APMs.
support19Digits ^Boolean ^Optional	When set to true, Web SDK supports unique credit card lengths, such as 15 and 19 digits. Possible values: true, false
upoRestriction ^Class ^Optional	Allows limiting the number of saved UPOs by the user. maxApmUpos (Integer) – Defines the maximum number of UPOs that can be saved per APM. Default value is not provided or null, which means there is no limit. onePerApm (Boolean) – Sets a limit of only one account being allowed per APM. Default is false. maxCards (Integer) – Defines the maximum number of cards that can be saved per APM. NOTE: This class overrides the force and always values in savePm.
cardInstallments ^Class ^Optional	Allows a merchant to set the relevant installments parameters. Supported countries: Brazil, Mexico, Colombia, Chile, Peru, Israel. installmentType (Class, Optional) – The type of installment.  Single Payment (String, Optional) – Determines if a single payment is displayed as an option.   Possible values:   true – Single Payment appears.   false – Single Payment does not appear.  type1 (Array, Optional) – Deferred with interest.   Positive integers separated by a comma (“,”) represent the number of monthly installments.  type2 (Array, Optional) – Deferred without interest.   Positive integers separated by a comma (“,”) represent the number of monthly installments.  type3 (Array, Optional) – Deferred without interest and months of grace.   Positive integers separated by a comma (“,”) represent the number of monthly installments. nationalId (String, CONDITIONAL) – Determines if an input field for the user’s Personal ID is displayed.  Possible values:  true – Personal ID user input field appears.  false – Personal ID user input field does not appear.
promoCode ^Boolean	Enables or disables a promotional code checkbox and field on the payment page. Possible values: true – The checkbox and field appear on the payment page. false (default) – The checkbox and field do not appear. Press here for more information.
useDualBrand ^Boolean	Enables presenting both brands of a co-badged card on the payment page. Possible values: true – When Nuvei detects a supported co-badged card, both brands appear on the payment page. false (default) – When Nuvei detects a supported co-badged card, only the primary brand appears on the payment page.

Event Callbacks Input

The following is a list of Simply Connect event callback inputs a merchant can set to get notified when an event is triggered for checkout().

• onResult
• onReady
• onFormValidated
• prePayment
• upoDeleted
• onPaymentFormChange
• onSelectPaymentMethod
• onPaymentEvent
• onDeclineRecovery
• userData
• onSuggestedAmount
• wdRequestCanceled

Miscellaneous Input Parameters

PARAMETER	DESCRIPTION
logLevel ^String(1) ^Optional	Determines the level of detail at which data must be shown on the console. Possible values: 0 (default) – No logging 1 – Plain text 2 – Info 3 – Warn 4 – Error 5 – Debug 6 – Trace
env ^String(4) ^Optional	The Nuvei environment you’re running on. If not provided, prod is assumed. Possible values: prod – production int – integration
cardLogo ^Class ^Optional	Use this to set a different style for the card logo (size and location). cardLogoPosition (String, 5) – Possible values: right, left. backgroundSize (String) – The size of the log in pixels. Alternatively, use cardLogo: false to hide the card logo.
disableDeleteUpoButton ^Boolean ^Optional	A merchant can remove the UPO delete button, making it impossible for the user to delete any UPOs. Possible values: false (default), true
pre-populateApmFields ^Object ^Optional	Allows customers to use information previously collected by the merchant, instead of having to re-enter the information. NOTE: The pre-population applies to any APM that supports collecting the defined parameter(s).
readonlyPrepopulateApmFields ^Boolean ^Optional	Prevents the user from changing any values prepoluated by prepopulateApmFields. Possible values: false (default), true NOTE: The read-only status applies to all APM pre-populated values.
strictCardBlocking ^Boolean ^Optional	Indicates if not receiving a proper response from the cardRecognition service should block and fail the transaction. Possible values: false (default), true
asciiValidation ^Boolean ^Optional	When called, the validation for invalid characters is triggered that checks that the cardholder name consists of only valid characters according to this ASCII table. This validation is required by Mastercard to avoid a case where a deposit is performed with invalid characters, but then a subsequent withdrawal cannot be performed. Possible values: false (default), true
preventScrollOnInt ^Boolean ^Optional	If set to false (default), the focus is on the first checkout field. If set to true, the focus is not changed.

Additional Input Parameters

In addition, you can send the following parameters either with the preceding authentication server side, using the /openOrder API call, or directly to checkout().

PARAMETER	DESCRIPTION
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This represents the customer’s identification number in their respective country. NOTE: When processing a createPayment(), authenticate3d(), or checkout() request, if you provided any billingAddress values (such as country and email), then the system uses those values instead of the values provided in the userDetails class.
shippingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (String, 100) county (String, 255)
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response.

Output

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "result": "APPROVED",
    "errCode": 0,
    "errorDescription": "",
    "ccCardNumber": "5****5761",
    "bin": "511142",
    "last4Digits": "5761",
    "ccExpMonth": "09",
    "ccExpYear": "21",
    "transactionId": "1110000000004146935",
    "threeDReason": "",
    "threeDReasonId": "",
    "challengeCancelReasonId": "",
    "challengeCancelReason": "",
    "isLiabilityOnIssuer": "1",
    "challengePreferenceReason": "12",
    "cancelled": false
}

Output Parameters

PARAMETER	DESCRIPTION
result ^String(20)	The cashier status of a merchant request. Possible values: APPROVED, DECLINED, ERROR
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter. In case of success (declined or approved), returns 0. Values as detailed in Response Handling. In addition, it can have the value of “-5”, which means the 3DS process was aborted.
errorDescription ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter. Values as detailed in Response Handling. In addition, it can have the value of “General 3D error”, which means the 3DS process was aborted.
ccCardNumber ^String(20)	The credit card number in a mask (for example: 4****1111).
bin ^String(6)	The BIN number representing the issuer.
last4Digits ^String(4)	The last four digits of the card number.
ccExpMonth ^String(2)	The expiration month
ccExpYear ^String(4)	The expiration year.
transactionId ^String(20)	The Gateway transaction ID.
threeDReason ^String	Reason description for a failed 3DS authorization as received from the issuer. Press here for more information.
threeDReasonId ^String	Reason ID for a failed 3DS authorization as received from the issuer. Press here for more information.
challengeCancelReasonId ^String	Reason ID for a canceled 3DS authorization as received from the issuer.
challengeCancelReason ^String	Reason description for a canceled 3DS authorization as received from the issuer.
isLiabilityOnIssuer ^String	Indicates if there is 3DS liability shift. If equal to “1” – Liability shift is present. If equal to “0”, empty or null, no liability shift has occurred.
challengePreferenceReason ^String	This value is returned following a 3DS challenge and describes the reason for challenge. Press here for more information.
cancelled ^String	If the process was canceled by the end user.

checkout.getApms()

This method returns the APMs supported with all their metadata needed for displaying them to the user and preparing them for processing, such as their display name, logo, required input to collect from the end user, and so on. One important parameter it returns for each APM is the APM identifier with Nuvei that you need to submit when requesting the payment (with the checkout() method).

The method can retrieve either the entire APM set supported by your account with Nuvei, or alternatively, a customized set of APMs. For example, you can request to retrieve APMs that correspond to certain criteria such as by transaction currency or by the user country.

Input

Example Request

1
2
3
4
5
6
7
8
checkout.getApms({
    type: "withdrawal",
    currencyCode: "USD",
    countryCode: "US", //detect
    languageCode: "en"},
    function(result) {
        console.log(result)
});

Input Parameters

PARAMETER	DESCRIPTION
currencyCode ^String(3) ^Optional	The 3-letter ISO currency code. If currencyCode is provided, the returned APM set consists only of APMs that support this currency. If not provided, the APM set includes all APMs regardless of their supported currencies.
countryCode ^String ^Optional	The 2-letter ISO country code. If countryCode is provided, the returned APM set consists only of APMs supported in this country. Alternatively, you can enter a value of “detect” so the current country is automatically detected by geolocation. If no value is provided, the APM set includes all APMs regardless of where they are supported.
languageCode ^String(2) ^Optional	The language in which the transaction is to be completed.
type ^String ^Optional	Relevant for gaming, forex or other industries that pay out to their customers, but not relevant for other industries. The type of the payment methods to be returned. Possible values: DEPOSIT (default if no value is sent), WITHDRAWAL

Output

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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
{
    "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"
                        }
                    ]
                }
            ]
        },
        {
            "paymentMethod": "apmgw_Instant_Open_Banking",
            "paymentMethodDisplayName":[

            ],
            "isDirect": "false",
            "countries":[
                "BE"
            ],
            "currencies":[
                "USD"
            ],
            "fields":[
                {
                    "name": "ob_account_number",
                    "type": "text",
                    "caption":[
                        {
                            "language": "eng",
                            "message": "Account Number"
                        }
                    ]
                },
                {
                    "name": "ob_sort_code",
                    "type": "text",
                    "caption":[
                        {
                            "language": "eng",
                            "message": "Sort Code"
                        }
                    ]
                },
                {
                    "name": "ob_iban",
                    "type": "text",
                    "caption":[
                        {
                            "language": "en",
                            "message": "IBAN"
                        }
                    ]
                },
                {
                    "name": "instantOb_bankId",
                    "type": "text",
                    "caption":[
                        {
                            "language": "eng",
                            "message": "Bank ID"
                        }
                    ],
                    "listValues":[
                        {
                            "code": "ngp-bbru",
                            "caption": "NextGenPSD2",
                            "mandatoryFields":[
                                "ob_iban"
                            ]
                        },
                        {
                            "code": "ngp-ingba",
                            "caption": "ING Austria",
                            "mandatoryFields":[

                            ]
                        }
                    ]
                }
            ]
        }
    ],
    "type": "DEPOSIT",
    "status": "",
    "errCode": "",
    "reason": "",
    "version": ""
}

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
paymentMethods ^Array	An array of payment methods and their attributes: paymentMethod (String, 50) paymentMethodDisplayName (Array) [language (String, 2), message (String, 400)] isDirect (String, 5) countries [(String, 2)] currencies [(String, 3)] logoURL (String, 255) fields[  name (String, 45)  regex (String, 128)  type (String, 45)  validationMessage (Array) [language (String, 2), message (String, 400)],  caption (Array) [language (String, 2), message (String, 400)]  listValues (Array) [  code (String, 255)  caption (String)  mandatoryFields (Array) [(String, 45)]  ] ]
type ^String	The type of the payment methods to be returned. Possible values: DEPOSIT (default if no value is sent), WITHDRAWAL
status ^String(20)	The status of merchant’s API request/call. Possible values: APPROVED, ERROR.
errCode ^Integer(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 (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
version ^String(10)	The current version of the API method. The current version is 1.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.

checkout.getCardDetails()

This method can be used by the merchant to retrieve details about a card, such as card type and brand. In addition, the method also returns the account’s currency, which is needed for DCC.

For a Postman script that simulates this method, please press here, or refer to our guide for testing with Postman.

Input

Example Request

1
2
3
4
5
6
7
checkout.getCardDetails({
    clientRequestId: "1C6CT7V1L",
    clientUniqueId: "12345"
},
    function(cardDetails) {
        console.log(cardDetails)
});

Input Parameters

PARAMETER	DESCRIPTION
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
clientUniqueId ^String(45) ^Optional	The unique transaction ID in the merchant system. It appears in a DMN as the merchant_unique_id parameter.

Output

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
{
    "brand": "VISA",
    "secondaryBrand": "BancontactAcquirer",
    "cardType": "Credit",
    "bin": "511142",
    "last4digits": "5761",
    "ccExpMonth": "09",
    "ccExpYear": "21",
    "program": "Visa Platinum",
    "visaDirectSupport": "0",
    "isPrepaid": "true",
    "issuerCountry": "pe",
    "currency": "pen",
    "dccAllowed": "false",
    "sessionToken": "eaeed493-6ed1-4e44-9cc9-7e698efe51e2",
    "internalRequestId": 212986558,
    "status": "SUCCESS",
    "reason": "",
    "errCode": 0,
    "merchantId": "479748173730597238",
    "merchantSiteId": "204388",
    "version": "1.0",
    "clientRequestId": "20201025110518",
    "issuerBankName": "River Valley Credit Union"
}

Output Parameters

Parameter	Description
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
brand ^String	The name of the card scheme (for example: Visa).
secondaryBrand ^String(50)	The secondary brand supported by a co-badged card.
cardType ^String	The type of card used in the transaction. Possible values: credit, debit
bin ^String(6)	The BIN number representing the issuer.
last4Digits ^String(4)	The last four digits of the card number.
ccExpMonth ^String(2)	The expiration month
ccExpYear ^String(4)	The expiration year.
program ^String	The card program used in the transaction (for example: Visa Platinum).
cardProduct ^String	The code of the card program used in the transaction (for example: Commercial & Business).
visaDirectSupport ^String	Indicates whether Visa Direct is supported or not
dccAllowed ^String	Indicates whether DCC is allowed for this card.
issuerCountry ^String(2)	2-letter ISO code of the card issuer’s country.
currency ^String(3)	The 3-letter ISO currency code.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
version ^String(10)	The current version of the API method. The current version is 1.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
status ^String	The cashier status of a merchant request. Possible values: SUCCESS, ERROR
isPrepaid ^String	Indicates if the card is prepaid or not.
issuerBankName ^String	Indicates the issuer bank name.

checkout.clientGetDccDetails()

This method calculates the DCC transaction amount and rateValueWithMarkup based on the selected payment method and target currency, as well as the original amount and currency provided in the /openOrder call.

Input

Example Request

1
2
3
4
5
6
7
8
9
checkout.clientGetDccDetails({
    clientRequestId: "1C6CT7V1L",
    clientUniqueId: "12345",
    currency: "USD",
    country: "US"
},
    function(result) {
        console.log(result)
});

Input Parameters

PARAMETER	DESCRIPTION
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
clientUniqueId ^String(45) ^Optional	The unique transaction ID in the merchant system. It appears in a DMN as the merchant_unique_id parameter.
currency ^String(3) ^Optional	The 3-letter ISO currency code of the conversion currency. You can optionally use this parameter to override the currency selected by the user in Simply Connect checkout(). If not provided, currency from checkout() is used. NOTE: If both currency and country are provided in the input, the currency takes precedence.
country ^String(2) ^Optional	The 2-letter ISO country code of the conversion country. You can optionally use this parameter to override the country selected by the user in Simply Connect checkout(). If not provided, country from checkout() is used. NOTE: If both currency and country are provided in the input, the currency takes precedence.

Output

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "amount": "178.29",
    "clientRequestId": "560673023851979",
    "currency": "USD",
    "dccFullSupport": "false",
    "errCode": 0,
    "internalRequestId": 289971718,
    "merchantId": "479748173730597238",
    "merchantSiteId": "204388",
    "originalAmount": "200",
    "originalCurrency": "EUR",
    "rateValueWithMarkUp": "0.8914572821049559",
    "reason": "",
    "sessionToken": "24a73293-d7e5-4aa5-a2d3-3d6fe2702c80",
    "status": "SUCCESS",
    "version": "1.0"
}

Output Parameters

Parameter	Description
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
rateValueWithMarkup ^String(12)	The rate value with markup.
markUpValue ^String(12)	The markup percentage value.
dccFullSupport ^Boolean	Determines if DCC is fully supported by the issuer or not. Possible values: true – DCC is supported by issuer. false – DCC not supported by issuer.
amount ^String(12)	The converted amount.
currency ^String(3)	The 3-letter ISO currency code of the conversion currency.
originalAmount ^String(12)	The original amount of the transaction in the currency that the merchant requested.
originalCurrency ^String(12)	The 3-letter ISO currency code of the currency that the merchant requested in the transaction.
status ^String(20)	The cashier status of a merchant request. Possible values: SUCCESS, 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, then an error reason is returned in this parameter.
version ^String(10)	The current version of the API method. The current version is 1.

checkout.getUserUPOs()

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

Example Request

1
2
3
4
checkout.getUserUPOs(
    function(result) {
        console.log(result)
});

checkout.applyOverlay()

When a customer is waiting for a response while their request is being processed, you can use this method to apply a semi-transparent overlay over the Simply Connect form, making it read-only to prevent further customer input. This is useful when you are “hooking” into the process and performing your own logic, such as when you are performing a custom risk check.

Example Request

1
2
3
4
onResult: function(result) {
    console.log("Result", result),
        setTimeout(function(){ checkout.applyOverlay(); }, 1000);
}

checkout.removeOverlay()

Use this method to remove the “overlay” that disables the Simply Connect form, which you set with applyOverlay().

Example Request

1
2
3
4
onResult: function(result) {
    console.log("Result", result),
        setTimeout(function(){ checkout.removeOverlay(); }, 1000);
}

checkout.getToken()

This method is used for advanced cases when the merchant would like to get a temporary token to process a card request on our server side (using our API). This method returns a ccTempToken (a card/CVV pair token that expires when the session token does).

Example Request

1
2
3
4
5
new Promise(async (resolve, reject) => {
    var getTokenResponse = await checkout.getToken();
    // some merchant code here
    resolve(); // or reject payment
});

checkout.destroy()

This method is used to remove the Simply Connect element from your payment page.

Example Request

1
checkout.destroy()

checkout.submitPayment()

Call this method if you want to initiate a payment request using Simply Connect. This method is usually used in conjunction with having your own custom PAY button outside the Simply Connect form (using the payButton = noButton option).

Example Request

1
checkout.submitPayment()

checkout.setOpenAmount()

The setOpenAmount() method is used to set or override the payment amount (in the same currency) from the client side.

Press here for more information.

Example Request

1
2
3
4
checkout.setOpenAmount('150', function(setOpenOrderResponse) {
    //merchant code here
    console.log(setOpenOrderResponse);
});

checkout.deleteUpo()

Call this method if you want to delete a UPO by its UPO ID.

Example Request

1
2
3
checkout.deleteUpo(upoId).then(result => { 
    console.log(result); // result = response of UPO deleting service (SUCCESS or ERROR) 
});

checkout.showDeclined()

Call this method to display either a default or customized message for when a transaction is declined.

Example Request

1
2
checkout.showDeclined(); // shows the default decline message
checkout.showDeclined(declineMsg); // shows a custom decline message

checkout.showApproved()

Call this method to display the message for when a transaction is approved.

Example Request

1
checkout.showApproved();

checkout.showRefresh()

Call this method to display a message with a button to refresh the page.

Example Request

1
checkout.showRefresh();

checkout.addUpo()

Call this method to add the selected APM as a new UPO during the registration (not payment) process.

Example Request

1
2
3
checkout.addUpo().then((response ) => {
    console.log(response);
});

withdrawal()

Use this method as a single end-to-end solution for accepting withdrawals. It integrates easily into your withdrawal flow and has its own customizable UI, which embeds seamlessly into your withdrawal page.

Input

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
withdrawal({
    renderTo: ".sconnect-container",
    sessionToken: "0251fca5-212d-40f2-80ba-fed5058f14f5",
    merchantSiteId: "112106",
    merchantId: "8256777005602846935",
    userTokenId: "230811147",
    userId: "850512345",
    clientUniqueId: "695701003A",
    env: "int", // "prod"
    country: "DE",
    locale: "en", // de, es, fr, it, pl, pt, ru
    currency: "EUR",
    amount: "115",
    openAmount: {
        min: "1",
        max: "500"
    },
    selectUpo: 83648899, // "83648899", "first"
    selectPM : "apmgw_<APM provider name>", // first, none
    showResponseMessage: true, //false, {pending:false, decline:false, success:true, expired:false}
    amountSuggestions: [
        "10",
        "50",
        "100"
    ],
    logLevel: "6",
    onResult: "function(result) {
                    console.log('onResult', result);
                }",
    onReady: "function(result) {
                    console.log('onReady', result);
                }"
});

Mandatory Basic Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(20) ~Required	The sessionToken retrieved from a call to /openOrder that references the order created in the Nuvei system.
merchantId ^String ~Required	Merchant ID provided by Nuvei.
merchantSiteId ^String ~Required	Merchant Site ID provided by Nuvei.
amount ^String ~Required	Mandatory for visualization purposes similar to currency.
currency ^String(3) ~Required	The 3-letter ISO currency code.
renderTo ^String ~Required	The name of the HTML container that you previously created for withdrawal().
country ^String(2) ~Required	The 2-letter ISO country code. Used as a filter in retrieving payment methods. Must be entered in uppercase. Alternatively, you can enter a value of “detect” so the current country is automatically detected by geolocation.
userId ^String ~Required	The ID of the customer in the merchant system. NOTE: This is not to be confused with userTokenId.
onResult ^Function ^Optional	Defines a callback function called to provide the full response information each time a payment request is returned – declines, errors, and approvals.
clientUniqueId ^String ^Optional	The unique transaction ID in the merchant system.

UI Customization Input Parameters

PARAMETER	DESCRIPTION
locale ^String(2) ^Optional	Language in which the text is displayed. Supported languages: de, en (default), es, fr, it, pl, pt, ru, he
i18n ^String ^Optional	Used to define custom messages to replace existing ones (also known as “internationalization”). Press here for more information.
theme ^String ^Optional	Determines the theme used for the checkout page. Possible values: horizontal (default), tiles
paymentTiles ^String ^Optional	Determines how the payment gallery is opened by default. Possible values: splash (default), showMore NOTE: If there are no UPOs, the gallery opens with “Show more”.

Payment Customization Input Parameters

PARAMETER	DESCRIPTION
openAmount ^Class ^Optional	Allows the merchant to set amount limits, which are validated. min (String) – Minimum payment amount. max (String) – Maximum payment amount. Press here for more information.
amountSuggestions ^Array ^Optional	Allows the merchant to suggest up to three amounts.
payButton ^String(13) ^Optional	Determines how the amount is displayed. Possible values: amountButton (default) – Displays the amount on the pay button. textButton – Displays text on the button.
pmWhitelist ^Array ^Optional	An array of only the specified APMs that are displayed to the customer in the Payment Methods list. NOTE: pmWhiteList and pmBlacklist cannot be used together in the same initialization.
pmBlacklist ^Array ^Optional	An array of the specified APMs that are not displayed to the customer in the Payment Methods list even if they are returned by an API. NOTE: pmWhiteList and pmBlacklist cannot be used together in the same initialization.
blockCards ^Array ^Optional	Specifies cards and sets of cards you do not accept. You can include blockCards or cardWhiteList in a checkout() request. Do not include both. Press here for more information.
cardWhiteList ^Array ^Optional	Specifies cards and sets of cards you accept. You can include cardWhiteList or blockCards in a checkout() request. Do not include both. Press here for more information.
showResponseMessage ^String ^Optional	Controls the message dialogs for the Simply Connect form. Possible values: True (default) – All transaction pop-ups (pending, success, and decline) and the session pop-up (expired) are displayed. False – Only the expired pop-up is displayed (transaction pop-ups are not). Additionally, you can provide an object that contains the four possible pop-up types and set the value for each as desired
savePmUrl ^String ^Optional	URL for the terms and conditions regarding secure storing of payment details.
selectUpo ^String ^Optional	A merchant can now preselect a UPO based on its UPO ID (either as a number 11111 or as a string “11111”), or the merchant can set it to “first”, in which case the first UPO is selected.
selectPM ^String ^Optional	Determines the behavior of preselection of payment methods (PMs) per available themes. Possible values: apmgw_<APM provider name> – The entered payment method is preselected in the payment page. first – In the accordion theme, the first PM is preselected and opened by default. In the tiles/horizontal themes, the first PM is preselected. none – In the accordion theme, all PMs are collapsed and none are preselected. In the tiles/horizontal/cashier themes, no PMs are preselected and no payment details are shown. NOTE: selectUpo has priority over selectPM.

Event Callbacks Input

The following is a list of Simply Connect event callback inputs a merchant can set to get notified when an event is triggered for withdrawal().

PARAMETER	DESCRIPTION
onReady ^Function ^Optional	Defines a callback function for when the Simply Connect form is fully loaded. Press here for more information.
onResult ^Function ~Required	Defines a callback function called to provide the full response information each time a payment request is returned – declines, errors, and approvals. Press here for more information. Press here for more information.
onSuggestedAmount ^Function ^Optional	This is called when a customer selects a suggested amount button on the payment (checkout) page or on the withdrawal page. Press here for more information.

Miscellaneous Input Parameters

PARAMETER	DESCRIPTION
logLevel ^String(1) ^Optional	Determines the level of detail at which data must be shown on the console. Possible values: 0 (default) – No logging 1 – Plain text 2 – Info 3 – Warn 4 – Error 5 – Debug 6 – Trace
env ^String(4) ^Optional	The Nuvei environment you’re running on. If not provided, prod is assumed. Possible values: prod – production int – integration
strictCardBlocking ^Boolean ^Optional	Indicates if not receiving a proper response from the cardRecognition service should block and fail the transaction. Possible values: false (default), true
wdRequestsLimit ^String ^Optional	Specifies the number of withdrawal requests allowed. Default value is 1.

Additional Input Parameters

In addition, you can send the following parameters either with the preceding authentication server side, using the /openOrder API call, or directly to withdrawal().

PARAMETER	DESCRIPTION
merchantWDRequestId ^String ^Optional	A unique ID generated by the merchant for the withdrawal order.
merchantUniqueId ^String ^Optional	This parameter is sent by the merchant and is used to associate a request with the merchant system.
userTokenId ^String(255) ^Optional	This parameter is a unique identifier for each customer generated by the merchant.
userAccountId ^String ^Optional	The customer’s Account ID on the merchant’s site. The value of this parameter indicates which account balance the withdrawn funds should be applied to when the customer has multiple accounts on the merchant site.
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This represents the customer’s identification number in their respective country. NOTE: When processing a createPayment(), authenticate3d(), or checkout() request, if you provided any billingAddress values (such as country and email), then the system uses those values instead of the values provided in the userDetails class.

Output

Example Response

1
2
3
4
5
6
7
8
9
10
11
{
    "result": "SUCCESS",
    "wdRequestStatus": "Pending",
    "errCode": 0,
    "reason": "",
    "wdRequestId": 6653201,
    "merchantWDRequestId": "",
    "userAccountId": "",
    "userId": "850512345",
    "wdRequestsLimitReached": true
}

Output Parameters

PARAMETER	DESCRIPTION
result ^String	The status of merchant’s API request/call.
errCode ^Integer(11)	Error code when a withdrawal request is declined.
reason ^String	The reason an error occurred.
wdRequestId ^Integer(20)	ID of the withdrawal request generated by Nuvei.
merchantWDRequestId ^String	Unique ID that the merchant generates 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.
userId ^String	The ID of the customer in the merchant system.
wdRequestsLimitReached ^Boolean	Indicates (true/false) if the limit of withdrawal requests set in wdRequestsLimit was reached.

withdrawal.getApms()

This method returns the APMs supported with all their metadata needed for displaying them to the user and preparing them for processing, such as their display name, logo, required input to collect from the end user, and so on. One important parameter it returns for each APM is the APM identifier with Nuvei that you need to submit when requesting the withdrawal (with the withdrawal() method).

The method can retrieve either the entire APM set supported by your account with Nuvei, or alternatively, a customized set of APMs. For example, you can request to retrieve APMs that correspond to certain criteria such as by transaction currency or by the user country.

Input

Example Request

1
2
3
4
5
6
withdrawal.getApms({
    countryCode: 'US', // optional
    languageCode: 'en'}, // optional
    function(result) {
        console.log(result)
});

Input Parameters

PARAMETER	DESCRIPTION
countryCode ^String ^Optional	The 2-letter ISO country code. If countryCode is provided, the returned APM set consists only of APMs supported in this country. Alternatively, you can enter a value of “detect” so the current country is automatically detected by geolocation. If no value is provided, the APM set includes all APMs regardless of where they are supported.
languageCode ^String(2) ^Optional	The language in which the transaction is to be completed.

Output

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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
{
    "sessionToken": "0d2901f4-58e9-438d-83b8-3f5f828722da",
    "clientRequestId": "4872356814759773",
    "errCode": 0,
    "internalRequestId": 40031741,
    "merchantId": "1483395720714828521",
    "merchantSiteId": "198771",
    "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"
                        }
                    ]
                }
            ]
        },
        {
            "paymentMethod": "apmgw_Instant_Open_Banking",
            "paymentMethodDisplayName":[

            ],
            "isDirect": "false",
            "countries":[
                "BE"
            ],
            "currencies":[
                "USD"
            ],
            "fields":[
                {
                    "name": "ob_account_number",
                    "type": "text",
                    "caption":[
                        {
                            "language": "eng",
                            "message": "Account Number"
                        }
                    ]
                },
                {
                    "name": "ob_sort_code",
                    "type": "text",
                    "caption":[
                        {
                            "language": "eng",
                            "message": "Sort Code"
                        }
                    ]
                },
                {
                    "name": "ob_iban",
                    "type": "text",
                    "caption":[
                        {
                            "language": "en",
                            "message": "IBAN"
                        }
                    ]
                },
                {
                    "name": "instantOb_bankId",
                    "type": "text",
                    "caption":[
                        {
                            "language": "eng",
                            "message": "Bank ID"
                        }
                    ],
                    "listValues":[
                        {
                            "code": "ngp-bbru",
                            "caption": "NextGenPSD2",
                            "mandatoryFields":[
                                "ob_iban"
                            ]
                        },
                        {
                            "code": "ngp-ingba",
                            "caption": "ING Austria",
                            "mandatoryFields":[

                            ]
                        }
                    ]
                }
            ]
        }
    ],
    "reason": "",
    "status": "SUCCESS",
    "type": "WITHDRAWAL",
    "version": "1.0"
}

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The 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)	The unique ID of the API request in the merchant system.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
paymentMethods ^Array	An array of payment methods and their attributes: paymentMethod (String, 50) paymentMethodDisplayName (Array) [language (String, 2), message (String, 400)] isDirect (String, 5) countries [(String, 2)] currencies [(String, 3)] logoURL (String, 255) fields[  name (String, 45)  regex (String, 128)  type (String, 45)  validationMessage (Array) [language (String, 2), message (String, 400)],  caption (Array) [language (String, 2), message (String, 400)]  listValues (Array) [  code (String, 255)  caption (String)  mandatoryFields (Array) [(String, 45)]  ] ]
type ^String	The type of the payment methods to be returned. Possible values: DEPOSIT (default if no value is sent), WITHDRAWAL
status ^String(20)	The status of merchant’s API request/call. Possible values: APPROVED, ERROR.
errCode ^Integer(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 (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
version ^String(10)	The current version of the API method. The current version is 1.

withdrawal.getUserUPOs()

This method returns a list of available saved payment methods for a specific user according to userTokenId. Before rendering the withdrawal form, call this method and then present the payment methods to the user.

Example Request

1
2
3
withdrawal.getUserUPOs(function(response) {
    console.log(response);
});

withdrawal.applyOverlay()

When a customer is waiting for a response while their withdrawal is being processed, you can use this method to apply a semi-transparent overlay over the Simply Connect form, making it read-only to prevent further customer input. This is useful when you are “hooking” into the process and performing your own logic, such as when you are performing a custom risk check.

Example Request

1
2
3
4
onResult: function(result) {
    console.log("Result", result),
        setTimeout(function(){ withdrawal.applyOverlay(); }, 1000);
}

withdrawal.removeOverlay()

Use this method to remove the “overlay” that disables the Simply Connect form, which you set with applyOverlay().

Example Request

1
2
3
4
onResult: function(result) {
    console.log("Result", result),
        setTimeout(function(){ withdrawal.removeOverlay(); }, 1000);
}

withdrawal.addUpo()

Call this method to add the selected APM as a new UPO during the registration (not withdrawal) process.

Example Request

1
2
3
withdrawal.addUpo().then((response ) => {
    console.log(response);
});

 

Simply Connect Events

This section presents the Simply Connect event callback input fields a merchant can set to get notified when an event is triggered.

onResult

Defines a callback function called to provide the full response information each time a payment request is returned – declines, errors, and approvals.

Press here for more information.

Input

Example Request

1
2
3
    onResult: function(result) {
        console.log("Result", result)
    },

Input Parameters

PARAMETER	DESCRIPTION
result ^String(20)	The cashier status of a merchant request. Possible values: APPROVED, DECLINED, ERROR, PENDING
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter. In case of success (declined or approved), returns 0. Values as detailed in Response Handling. In addition, it can have the value of “-5”, which means the 3DS process was aborted.
errorDescription ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter. Values as detailed in Response Handling. In addition, it can have the value of “General 3D error”, which means the 3DS process was aborted.
userPaymentOptionId ^String	Represents the ID for the newly created payment option, which can be referenced in future requests. Refer to Card-on-File for further details.
cavv ^String	A cryptogram created by the issuer that serves as a proof that the merchant is entitled to this authentication.
eci ^String	Indicates the level of security used in a 3DS program when the cardholder provides payment information to the merchant. Press here for possible eci data values.
dsTransID ^String	The transaction ID received from the MPI for 3DS.
ccCardNumber ^String(20)	The credit card number in a mask (for example: 4****1111).
bin ^String(6)	The BIN number representing the issuer.
last4Digits ^String(4)	The last four digits of the card number.
ccExpMonth ^String(2)	The expiration month
ccExpYear ^String(4)	The expiration year.
transactionId ^String	The Gateway transaction ID.
cancelled ^Boolean	If the process was canceled by the end user.
transactionStatus ^String	The Gateway transaction status. Possible values: APPROVED, DECLINED, ERROR
transactionType ^String(45)	The type of transaction.

onReady

Defines a callback function for when the Simply Connect form is fully loaded.

Input

Example Request

1
2
3
    onReady: function(readyData) {
        console.log("Ready", readyData);
    },

Input Parameters

PARAMETER	DESCRIPTION
loaded ^String	Returns {loaded:true} when the checkout is loaded.

onFormValidated

If the state of any field on the Simply Connect form is changed, this callback function is triggered to notify the merchant if the Simply Connect form is ready to be submitted to payment.

Input

Example Request

1
2
3
    onFormValidated: function(result) {
        console.log('onFormValidated result =>', result);
    }

Input Parameters

PARAMETER	DESCRIPTION
isFormValid ^Boolean	Possible values: false, true
invalidFields ^Array	Possible values: “invalidFields:[]” if isFormValid is true “invalidFields:[list of invalid fields name]” if isFormValid is false

prePayment

Defines a callback function that allows the merchant to be notified just before a payment is finalized, receive all the payment details, and decide whether to proceed to the payment or to stop the payment (optionally with a rejection message).

Press here for more information.

Input

Example Request

1
2
3
4
5
    prePayment: function(paymentDetails) {
        return new Promise((resolve, reject) => {
            console.log(paymentDetails);
            resolve(); // or reject() or reject('Message')
    });

Input Parameters

PARAMETER	DESCRIPTION
paymentOption ^Class	The option used to send the payment details. Press here to see the contents of the class.
amount ^String(12)	The transaction amount.
currency ^String(3)	The 3-letter ISO currency code.
useDCC ^String	Determines how the DCC is set for the user and/or the user session. Possible values: enable – Enables the checkbox. disable (default) – Disables the checkbox. force – Enables and selects the checkbox. The customer is still able to clear the checkbox.
dccDetails ^Class	Presents information on the currency conversion of the transaction. amount – The original amount. currency – The original currency. chargedAmount – The converted amount. chargedCurrency – The converted currency. rate – The fixed rate. markup – The total markup that was charged in addition to the original conversion.
savePM ^String	Determines whether to present the user with a checkbox to save payment details and whether Nuvei saves them as a UPO.
installmentType ^String	The type of installment. Possible values:  Single Payment – The Single Payment option was selected (no installments).  type1 – Deferred with interest.  type2 – Deferred without interest.  type3 – Deferred without interest and months of grace.
numberOfInstallments ^String	The number of payment installments. Possible values:  none – Single Payment option was selected.  A positive integer.
promoCode ^Boolean	Provides the merchant with the promotional code the user entered on the Simply Connect form. Press here to see an example.

Possible Responses

The possible responses – to proceed to the payment or to stop the payment.

Example Response

1
    resolve(); // or reject() or reject('Message')

Response Parameters

PARAMETER	DESCRIPTION
resolve() ^String	Continues with the payment.
reject() ^String	Stops the payment. Optionally, you can add a message to the rejection.

upoDeleted

This callback is called when a user selects and removes a UPO from the gallery.

Press here for more information.

Input

Example Request

1
2
3
    upoDeleted: function(paymentDetails) {
        console.log("upoDeleted", paymentDetails);
    },

Input Parameters

See paymentOption class below.

onPaymentFormChange

This event callback is called when focus moves to/away from any field or object on the Simply Connect form. This is useful for tracking customer behavior on the Simply Connect form (such as selecting a field and changing a field value), for performing user activity analytics, and for error validation.

Input

Example Request

1
2
3
    onPaymentFormChange: function(pm, label, action, oldValue, newValue, validation, pasted) {
        console.log('onPaymentFormChange =>', pm, label, action, oldValue, newValue, validation, pasted);
    },

Input Parameters

PARAMETER	DESCRIPTION
pm ^String	The payment method.
label ^String	The label of the field.
action ^String	focus or blur
oldValue ^String	The value before the event.
newValue ^String	The value after the event.
validation ^String	The validation error (i18n label). Only relevant for a validation error.
pasted ^String	Indicates if the new value is pasted

onSelectPaymentMethod

This callback function is called when a user selects a payment method from the gallery, either an existing UPO or a new one.

For an existing UPO, the merchant receives all the information about the UPO. For a new payment option, only the method name is received.

Press here for more information.

Input

Example Request

1
2
3
    onSelectPaymentMethod: function(paymentDetails) {
        console.log("onSelectPaymentMethod", paymentDetails);
    },

Input Parameters

See paymentOption class below.

onPaymentEvent

This event callback provides maximum transparency into the payment flow, by reporting back to you at each stage of the payment flow. You can use this information for analytics or perform some custom action.

Input

Example Request

1
2
3
    onPaymentEvent: function(result) {
        console.log('onPaymentEvent =>', result);
    },

Input Parameters

PARAMETER	DESCRIPTION
pm ^String	The Payment method.
eventType ^String	The type of event. Possible values: initiated (once payment initiated) tokenized (after initAuth3D) paymentStarted (after clientPayment() or clientAuthorize3D()) challengeStarted (before redirection) challengeEnded (after finalizePayment()) redirectionStarted (for APM) redirectionEnded (for APM)
threeD ^String	version – The 3D version. flow – The type of 3D flow.  Possible values: frictionless, challenge

onDeclineRecovery

This allows merchants to override the decline recovery recommendations with their own preferences each time the decline recovery dialog is to be displayed.

When the function is called, the history (declineRecoveryHistory) of all the previous decline recovery actions taken by the user is sent to the merchant. The merchant can then pass declineRecoveryOverride back to Simply Connect by calling resolve(declineRecoveryOverride).

Input

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
var isOverriden = false;
checkout({..., 
  disableDeclineRecovery: false, 
    onDeclineRecovery: function(declineRecoveryHistory) { 
      console.log('Decline Recovery History =>', declineRecoveryHistory); 
      var declineRecoveryOverride; 
      if (!isOverriden) { 
        declineRecoveryOverride = {nextPm: true, differentCard: true, retry: true, supportMessage: '[email protected]'}; 
        isOverriden = true; 
      } 
      return new Promise((resolve, reject) => { 
        resolve(declineRecoveryOverride ); 
      }); 
    }, 
  })
});

Input Parameters

PARAMETER	DESCRIPTION
nextPm ^Boolean	Displays another payment method. Possible values: True, False (default)
differentCard ^Boolean	Allows the user to enter a different credit card. Possible values: True, False (default)
retry ^Boolean	Tries the same payment method again. Possible values: True, False (default)
supportMessage ^String	Displays either an email, a phone number, or just text.

userData

This event callback is called before the payment is performed. The purpose is to set the user information (userDetails, billingAddress, shippingAddress), so it is updated on the payment record and in processing.

Press here for more information.

onSuggestedAmount

This is called when a customer selects a suggested amount button on the payment (checkout) page or on the withdrawal page.

Press here for more information.

Input

Example Request

1
2
3
    onSuggestedAmount: function(result) {
        console.log('onSuggestedAmount', result);
    },

Input Parameters

PARAMETER	DESCRIPTION
action ^String	Specifies if the suggested amount button is being used for a checkout (payment) or withdrawal. Possible values: checkout, withdrawal
pm ^String	The name of the paymentMethod.
selected_amount ^String	The value of the selected suggested amount button.

wdRequestCanceled

When a customer cancels a pending withdrawal request, this callback is triggered to notify the merchant of the canceled request.

Press here for more information.

Input

Example Request

1
2
3
    wdRequestCanceled: function(canceledWdRequest) {
        console.log('wdRequestCanceled', canceledWdRequest);
    }

Input Parameters

PARAMETER

DESCRIPTION

withdrawalRequest ^Class

Details of the withdrawal requests and for each request its order details. appId (String) userTokenId (String) – This ID uniquely identifies your consumer/user in your system userId (String) – The user ID given by the merchant to the customer. userDetails (Class)  firstName (String, 30)  lastName (String, 50)  address (String, 50)  phone (String, 18)  zip(String, 10)  city (String, 30)  country (String, 2) – 2-letter ISO country code  state (String, 3) – ISO country subdivision code  email (REQUIRED)(String, 100) 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. wdRequestId (String) – ID of the withdrawal request generated by Nuvei. merchantWDRequestId (String) – A unique ID that you generate for the withdrawal request. userPMId (String) – A unique ID automatically generated by Nuvei that represents the payment method selected by the customer. requestedAmount (String) – The requested withdrawal amount. requestedCurrency (String) – The requested withdrawal currency. state (String) wdRequestStatus – The current status of the withdrawal request. Press here for possible values. creationDate (String) – The date on which the request was created. lastModifiedDate (String) – The last date on which the request was modified. dueDate (String) operatorName – The name of the administrator of the request. pendingKyc (String) wdRequestOrderCount – Retrieves only requests that have exactly <wdRequestOrderCount> number of orders. This parameter is overridden by the wdRequestOrderCountRange parameter (if it is present). pmName (String) – The type of the payment method (such as PayPal and credit card). pmIssuer (String) – The credit card company that processed the original transaction. pmDisplayName (String) – For credit card, last four digits of the card number; for APMs, this value represents the user’s account name, such as PayPal email address or Neteller Secure ID. approvedAmount (String) – The approved withdrawal amount. merchantUniqueId – This parameter is sent by the merchant and is used to associate a request with the merchant system. This value must be unique. feeAmount (String) – The fee amount for this request (if relevant). merchantSiteInfo (Class)  merchantSiteName (String) – The name of the site in your account where the request originated.  merchantSiteId – Your website’s unique identification number provided by Nuvei.

paymentOption Class

With UPO

PARAMETER

DESCRIPTION

upo ^Array

An array of payment methods and their attributes: paymentMethodName (String, 50) – The unique name of the payment method.  For a list of possible values, see the “paymentMethod” column in the tables in APM Payments. upoName (String, 255) – A name that helps identify the account.  For cards, it usually includes the card number.  For APMs, it is usually one of the APM account identifier fields, such as account_id.  In both cases, the field chosen to be used as upoName can be set per configuration.  NOTE: During UPO creation, upoName is set and it cannot be updated or changed later on. upoRegistrationDate (String, 8) – The date that the UPO was registered in the following format: YYYYMMDD. upoStatus (String, 20) – The status of the UPO for the user.  Possible values: suspended, enabled. userPaymentOptionId (String, 45) – The unique user payment option ID as assigned by Nuvei. upoData (Class) – Contains the UPO details of the user.  issuerCountry  uniqueCC  ccCardNumber  cardProduct  bin  cardType  ccExpMonth  ccExpYear  allowDcc  optionalWdType  brand  ccNameOnCard  secondaryBrand – Relevant for a co-badged card only.  lastUsedBrand – Relevant for a co-badged card only.  isDualBranded – Relevant for a co-badged card only.

Without UPO

PARAMETER

DESCRIPTION

card ^Class

An array of payment methods and their attributes: paymentMethodName (String, 50) – The unique name of the payment method.  For a list of possible values, see the “paymentMethod” column in the tables in APM Payments. ccNameOnCard – The cardholder name. ccCardNumber (String, 20) – The masked credit card number, for example: 4****1111 bin (String, 6) – The BIN number of the credit card. ccExpMonth (String, 2) – The 2-digit value representing the expiration month. ccExpYear (String, 4) – The 4-digit value representing the expiration year. brand – The name of the card scheme; for example: Visa cardProduct (String) – The code of the card program used in the transaction; for example: “N” for Visa Platinum. cardType (String) – The type of card used in the transaction.  Possible values: credit, debit dccAllowed (String) – Indicates whether DCC is allowed for this card. issuerCountry (String, 2) – 2-letter ISO code of the card issuer’s country. program (String) – The card program used in the transaction (for example: Visa Platinum). visaDirectSupport (String) – Indicates whether Visa Direct is supported or not.

REST API

REST API Overview

Nuvei offers a server-to-server REST API integration to accept payments. Server-to-server integrations are relatively complex. In most cases, these integrations are less recommended than our Web SDK and Payment Page, which are easier to implement. However, there are clear cases where server-to-server is the correct integration to use:

• PCI level-1 merchants – Merchants having the highest PCI level and processing, transmitting, and storing themselves their cardholder information.
• Multiple PSP processing merchants – Sometimes merchants that are processing with other PSPs or Acquirers in addition to us prefer using the server-to-server integration rather than the other more straightforward integration methods.

/getSessionToken

Endpoint URL

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

1
2
This method is not relevant when using Server SDKs. Please refer to the following guide for initialization instructions:
https://docs.nuvei.com/?p=53443

1
2
This method is not relevant when using Server SDKs. Please refer to the following guide for initialization instructions:
https://docs.nuvei.com/?p=29433

1
2
This method is not relevant when using Server SDKs. Please refer to the following guide for initialization instructions:
https://docs.nuvei.com/?p=53233

1
2
This method is not relevant when using Server SDKs. Please refer to the following guide for initialization instructions:
https://docs.nuvei.com/?p=48413

Example Response

1
2
3
4
5
6
7
8
9
10
11
{
    "sessionToken": "2da9b9cd-573e-4055-a209-3ac2b855f9af",
    "internalRequestId": 222310158,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0",
    "clientRequestId": "1C6CT7V1L"
}

This method receives a merchant’s authentication details and returns a unique session token (sessionToken). sessionToken is used throughout the payment session as an authentication token.

For subsequent calls to the session, the token must be provided for validation to ensure that it is still active and valid.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	Merchant Site ID provided by Nuvei.
timeStamp ^String(14) ~Required	The local time (in 24-hour format) when the method call is performed in the following format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the input parameters, which must be concatenated in the following order: merchantId, merchantSiteId, clientRequestId, timeStamp, merchantSecretKey. Press here to see an example. NOTE: clientRequestId is optional and does not need to be included in the concatenation.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned, which is then used as an input.
merchantId ^String(20) ~Required	Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
status ^String(20)	The status of merchant’s API request/call. Possible values: SUCCESS, ERROR.
errCode ^Integer(11)	The error code in the event of an error.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”).
version ^String(10)	The current version of the API method. The current version is 1.
clientRequestId ^String(20)	The ID of the API request in merchant system.

/initPayment

Endpoint URL

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "sessionToken": "e524e7c5-9855-4ce9-b0f9-1045f34fd526",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
    "clientRequestId": "1C6CT7V1L",
    "amount": "200",
    "currency": "USD",
    "paymentOption": {
        "card": {
            "cardNumber": "4000027891380961",
            "cardHolderName": "John Smith",
            "expirationMonth": "12",
            "expirationYear": "2030",
            "CVV": "217",
            "threeD": { "methodNotificationUrl": "<methodNotificationURL>"
            }
        }
    },
    "deviceDetails": {
        "ipAddress": "192.168.2.38"
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
//Initialize the SDK (see https://docs.nuvei.com/?p=53443#initializing-the-sdk)

safecharge.paymentService.initPayment({
    userTokenId: "230811147",
    amount: "200",
    currency: "USD",
    paymentOption: {
        "card": {
            cardNumber: "4000027891380961",
            cardHolderName: "John Smith",
            expirationMonth: "12",
            expirationYear: "2030",
            CVV: "217",
            threeD: {
                "methodNotificationUrl": "<methodNotificationURL>" }
        }
    },
    deviceDetails: {
        ipAddress: "192.168.2.38"
    },
}, function (initPErr, initPRes, reqData) {
    console.log(initPErr, initPRes);
});

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
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    String userTokenId = "230811147";
    String clientUniqueId = "12345";
    String clientRequestId = "1C6CT7V1L";
    String currency = "USD";
    String amount = "200";

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("192.168.2.38");

    InitPaymentThreeD threeD = new InitPaymentThreeD();
    threeD.setMethodNotificationUrl("<methodNotificationURL>");

    InitPaymentCard card = new InitPaymentCard();
    card.setCardNumber("4000027891380961");
    card.setCardHolderName("John Smith");
    card.setCVV("217");
    card.setExpirationMonth("12");
    card.setExpirationYear("2030");
    card.setThreeD(threeD);

    InitPaymentOption initPaymentOption = new InitPaymentOption();
    initPaymentOption.setCard(card);

    Safecharge safecharge = new Safecharge();
    SafechargeResponse response = safecharge.initPayment(userTokenId, clientUniqueId, clientRequestId, currency, amount, deviceDetails, initPaymentOption, null, null, null, null);
}

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
//initPayment
$initPaymentResponse = $safeCharge->getPaymentService()->initPayment([
    "currency"       => "USD",
    "amount"         => "200",
    "userTokenId"    => "230811147",
    "clientUniqueId" => "12345",
    "clientRequestId"  => "1C6CT7V1L",
    "paymentOption"  => [
        "card" => [
            "cardNumber"      => "4000027891380961",
            "cardHolderName"  => "John Smith",
            "expirationMonth" => "12",
            "expirationYear"  => "2030",
            "CVV"             => "217",
            "threeD" =>[
                "methodNotificationUrl" =>"<methodNotificationURL>",
                ]
        ]
    ],
    "deviceDetails"     => [
        "ipAddress"  => "192.168.2.38"
    ],
]);
?>

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
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.InitPayment(
    "USD",
    "200",
    new InitPaymentOption
    {
        Card = new InitPaymentCard
        {
            CardNumber = "4000027891380961",
            CardHolderName = "John Smith",
            ExpirationMonth = "12",
            ExpirationYear = "26",
            CVV = "217",
            ThreeD = new InitPaymentThreeD
            {
                MethodNotificationUrl = "<MethodNotificationUrl>",
            }
        }
    },
    userTokenId: "230811147",
    orderId: "33704071",
    clientUniqueId: "12345",
    clientRequestId: "1C6CT7V1L",
    deviceDetails: new DeviceDetails { IpAddress = "192.168.2.38" };
    );

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
{
    "reason": "",
    "orderId": "33704071",
    "transactionStatus": "APPROVED",
    "customData": "merchant custom data",
    "internalRequestId": 10036001,
    "version": "1.0",
    "transactionId": "2110000000000587378",
    "merchantSiteId": "142033",
    "transactionType": "InitAuth3D",
    "gwExtendedErrorCode": 0,
    "gwErrorCode": 0,
    "merchantId": "427583496191624621",
    "clientUniqueId": "12345",
    "errCode": 0,
    "paymentOption": {
        "card": {
            "ccCardNumber": "5****5761",
            "bin": "511142",
            "threeD": {
                "methodPayload": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImVkNGZlNTkzLWUzMWUtNDEyMC05M2EwLTBkNDBhNzUxNzEzMSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ3d3cuVGhpc0lzQU1ldGhvZE5vdGlmaWNhdGlvblVSTC5jb20ifQ==",
                "methodUrl": "https://srv-azr-acq2:4435/api/ThreeDSMethod/threeDSMethodURL",
                "v2supported": "true",
                "serverTransId": "ed4fe593-e31e-4120-93a0-0d40a7517131",
                "version": "2.1.0",
                "directoryServerId": "A000000003",
                "directoryServerPublicKey": "MIIFrjCCBJagAwIBAgIQB2rJm.."
            },
            "ccExpMonth": "12",
            "ccExpYear": "25",
            "last4Digits": "5761"
        }
    },
    "sessionToken": "e524e7c5-9855-4ce9-b0f9-1045f34fd526",
    "userTokenId": "230811147",
    "status": "SUCCESS"
}

This method initiates the payment process for transactions. It is recommended to use our Web SDK instead of calling this method directly.

The /initPayment request determines if the card supports 3DS and initializes the payment in the Nuvei system.

@Links URLs

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

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

Input Parameters

Parameter	Description
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The merchant site ID provided by Nuvei.
clientUniqueId ^String(45) ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in a DMN as the merchant_unique_id parameter.
currency ^String(3) ~Required	The 3-letter ISO currency code. If the merchant did not call /openOrder prior, then a value must be sent by the merchant in this parameter.
amount ^String(12) ~Required	The transaction amount. If the merchant did not call /openOrder prior, then a value must be sent by the merchant in this parameter.
paymentOption ^Class ~Required	The option used to send the payment details. Choose from the following options: If you wish to collect the card details: card (Class) – Represents a credit/debit card.  • cardNumber (String, 20, REQUIRED) – The card number.  • cardHolderName (String, 70, REQUIRED) – The cardholder name.  • expirationMonth (String, 2, REQUIRED) – The card expiration month.  • expirationYear (String, 4, REQUIRED) – The card expiration year.  • CVV (String, 4, REQUIRED) – The CVV/CVC security code.  • brand (String, 20, CONDITIONAL) – The card brand.   REQUIRED when the merchant performs the encryption of the token.   Relevant for Apple Pay or Google Pay only.  • last4Digits (String, 20, CONDITIONAL) – The last four digits of the card number.   REQUIRED when the merchant performs the encryption of the token.   Relevant for Apple Pay or Google Pay only.  • acquirerId (String, 2) – The ID of the acquirer that processed the transaction.  • selectedBrand (String, 128) – The brand selected by the consumer for the transaction processing.  OR  For payment with a temporary token generated by getToken() instead of card details:   ccTempToken (String, 45)   cardHolderName (String, 70)  Advanced card scenarios:   • For a 3DS payment, use the threeD class with the following parameter:    threeD.methodNotificationUrl (String, 255) – The URL the ACS redirects to after performing    the 3DS fingerprinting. Refer to 3DS Fingerprinting for details.   • When using an external token provider such as Apple Pay or Google Pay, refer to externalToken Class. If you are handling a returning user and want to use a previously saved user payment option: userPaymentOptionId (String) – Identifies a payment option previously used by the customer, and is now requested for re-use (Nuvei keeps payment option details from a previous use). Upon re-use, any of the following additional parameters from the card class may be needed as well:  • expirationMonth (String, 2) – For a newer card expiration.  • expirationYear (String, 4) – For a newer card expiration.  • CVV (String, 4) – Recommended for high-risk merchants.
deviceDetails ^Class ~ipAddress Required	ipAddress (String, 15, REQUIRED) deviceManufacturerIdentifier (String, CONDITIONAL) – REQUIRED when the merchant performs the encryption of the token. Relevant for Apple Pay only. deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255)
userTokenId ^String(255) %%Conditional	This ID uniquely identifies your consumer/user in your system. It is REQUIRED only if you wish to use the userPaymentOptionId parameter for future charging of this user without re-collecting the payment details. Press here for more information.
relatedTransactionId ^String(19) ^Optional	If the merchant receives a soft decline error in the /payment response, they can send /initPayment again, this time including relatedTransactionId with the same value received in transactionId from the /payment call response. Press here for more information.
urlDetails ^Class ^Optional	With this class, a merchant can dynamically provide possible URLs to which the end user is redirected after a payment is made, as well as a dynamic URL for DMNs. successUrl (String, 1000) – The URL the customer is directed to after a successful transaction. failureUrl (String, 1000) – The URL the customer is directed to after an unsuccessful transaction. pendingUrl (String, 1000) – The URL the customer is directed to when the transaction response is pending. notificationUrl (String, 1000) – The URL to which DMNs are sent. Although DMN responses can be configured per merchant site, this parameter allows dynamically returning the DMN to the provided address per request. appReturnLink (String, 255) – The deep link used to return to the merchant native application (press here for an example). NOTE: This parameter is not supported for all cases. appUrl (String, 255) – Link to which the provider redirects the user at the end of the payment process (press here for an example). NOTE: This parameter is not supported for all cases.
billingAddress ^Class ^Optional	addressMatch (String, 1) – Set to “Y” when address matches shipping address city (String, 30) country (String, 2) – 2-letter ISO country code. Must be entered in uppercase. address (String, 50) addressLine2 (String, 50) addressLine3 (String, 50) zip (String, 10) state (String, 3) – ISO country subdivision code email (String, 100) phone (String, 18) cell (String, 18) firstName (String, 30) lastName (String, 40)
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
customData ^String(255) ^Optional	Can be used to pass any type of information. If sent in request, then it is visible in Nuvei’s back office tool transaction reporting and is returned in response.
webMasterId ^String(255) ^Optional	An affiliate parameter that the merchant can send. This is used by Nuvei’s eCommerce plugins (Magento, Demandware) and by Nuvei REST API SDKs to send the plugin/SDK name and version so that Support is able to identify from where the transaction arrived at the REST API Gateway.
orderId ^String(45) ^Optional	The ID to be used as an input parameter in the update method and payment methods. The parameter is sent to define which merchant order to update.

Output Parameters

Parameter	Description
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
transactionId ^String(20)	The Gateway transaction ID.
transactionType ^String(45)	The type of transaction: InitAuth3D
status ^String(20)	The cashier status of a merchant request. Possible values: SUCCESS, ERROR
transactionStatus ^String(20)	The Gateway transaction status.
errCode ^Integer(11)	The error code if an error occurred at the cashier side.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the cashier side.
gwErrorCode ^Integer(11)	The error reason code if an error occurred. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the specific error.
gwErrorReason ^String(400)	The error reason if an error occurred.
gwExtendedErrorCode ^Integer(11)	The error reason code if an error occurred on the bank side. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
version ^String(10)	The current version of the API method. The current version is 1.
paymentOption ^Class	Represents the data retrieved from the processed payment method. • card (Class) – Information about the card that was processed:  ▫ bin (String, 6) – The BIN number of the credit card.  ▫ last4Digits (String, 4) – The last four digits of the credit card number.  ▫ ccCardNumber (String, 20) – The masked credit card number (for example: 4****1111).  ▫ ccExpMonth (String, 2) – The 2-digit value representing the expiration month.  ▫ ccExpYear (String, 4) – The 4-digit value representing the expiration year.  ▫ ccTempToken (String, 36) – A temporary card token to be used during the same session.  ▫ acquirerId (String, 2) – The ID of the acquirer that processed the transaction.  ▫ threeD (Class) – The class containing the 3DS information.   ▪ methodUrl (String, 256) – The 3D “Method URL” required for 3DS fingerprinting,    as described in 3DS Fingerprinting.   ▪ version (String, 8) – The 3DS version.    Possible values: 2.1.0, 2.2.0 or null (3DS not used).   ▪ v2supported (String) – Indicates if 3DS flow is supported.    Possible values: true (supported) or null, false (not supported).   ▪ serverTransId (String) – 3DS Server Transaction ID to be used in the threeDSMethod     in the merchant website.   ▪ methodPayload (String) – To be used with the “Method URL” in the threeDSMethod,    as described in 3DS Fingerprinting.   ▪ directoryServerId (String) – The 3DS directory server ID. Relevant only for the 3D Mobile SDK.   ▪ directoryServerPublicKey (String) – The 3DS directory public encryption key.    Relevant only for the 3D Mobile SDK. OR userPaymentOptionId (String) – If initPayment was processed with userPaymentOptionId rather than having provided the card class, this parameter echoes back the same userPaymentOptionId that was provided in the input.
cardType ^String	The type of card used in the transaction. Possible values: credit, debit
issuerCountry ^String(2)	2-letter ISO code of the card issuer’s country.
orderId ^String(20)	The ID returned from the MerchantOrderID input parameter in update and payment methods. This parameter is returned to define which merchant order to update.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
cardAuthMethod ^String	Indicates the card authentication method (DPAN/PAN_ONLY) returned in the response. NOTE: This is only relevant for Google Pay.
processedBrand ^String(50)	The brand with which the transaction was processed.

/payment

Endpoint URL

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
{
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "amount": "100",
    "currency": "USD",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
    "paymentOption": {
        "card": {
            "cardNumber": "4000027891380961",
            "cardHolderName": "John Smith",
            "expirationMonth": "12",
            "expirationYear": "2030",
            "CVV": "217"
        }
    },
    "deviceDetails": {
        "ipAddress": "192.168.2.38"
    },
    "billingAddress": {
        "firstName": "John",
        "lastName": "Smith",
        "email": "[email protected]",
        "country": "US"
    },
    "timeStamp": "20241105081132",
    "checksum": "5582d0189dd440f4bbf960569ec22e77"
}

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
{
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "timeStamp": "20241105081132",
    "checksum": "5582d0189dd440f4bbf960569ec22e77",
    "currency": "USD",
    "amount": "100",
    "paymentOption": {
        "card": {
            "cardNumber": "4000027891380961",
            "cardHolderName": "John Smith",
            "expirationMonth": "12",
            "expirationYear": "2030",
            "CVV": "217",
           "threeD": {
                "methodCompletionInd": "U",
                "version": "2",
                "notificationURL": "http://www.notify_URL.com",
                "merchantURL": "http://www.merchant_URL.com",
                "platformType": "02",
                "v2AdditionalParams": {
                    "challengeWindowSize": "05"
                },
                "browserDetails": {
                    "acceptHeader": "text/html,application/xhtml+xml",
                    "ip": "192.168.1.11",
                    "javaEnabled": "TRUE",
                    "javaScriptEnabled": "TRUE",
                    "language": "EN",
                    "colorDepth": "48",
                    "screenHeight": "400",
                    "screenWidth": "600",
                    "timeZone": "0",
                    "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47"
                }
            },
            "billingAddress": {
                "firstName": "John",
                "lastName": "Smith",
                "country": "GB",
                "email": "[email protected]"
            },
            "deviceDetails": {
                "ipAddress": "93.146.254.172"
            }
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "amount": "100",
    "currency": "USD",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
    "paymentOption": {
        "card": { 
            "ccTempToken": "c0275892-fce1-488f-9268-1c826b2574e8"
        }
    },
    "deviceDetails": { 
        "ipAddress": "192.168.2.38"
    },
    "timeStamp": "20241105081132",
    "checksum": "5582d0189dd440f4bbf960569ec22e77"
}

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
{
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "amount": "200",
    "currency": "USD",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
    "paymentOption": {
        "alternativePaymentMethod": {
            "paymentMethod": "apmgw_MoneyBookers",
            "account_id": "SkrillTestUser3"
        }
    },
    "billingAddress": {
        "firstName": "John",
        "lastName": "Smith",
        "country": "US",
        "email": "[email protected]"
    },
    "deviceDetails": {
        "ipAddress": "192.168.2.38"
    },
    "userDetails": {
        "firstName": "John",
        "lastName": "Smith",
        "country": "US",
        "email": "[email protected]"
  },
    "timeStamp": "20241105081140",
    "checksum": "edfb11a5c5ea8b2a7f53a6bc623226c0"
}

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
{
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "amount": "200",
    "currency": "USD",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
    "paymentOption": {
        "card": {
            "cardNumber": "4000027891380961",
            "cardHolderName": "John Smith",
            "expirationMonth": "12",
            "expirationYear": "2030",
            "CVV": "217",
            "threeD": {
                "methodCompletionInd": "Y",
                "version": "2.1.0",
                "notificationURL": "<notificationURL>",
                "merchantURL": "<merchantURL>",
                "platformType": "02",
                "v2AdditionalParams": {
                    "challengeWindowSize": "05"
                },
                "browserDetails": {
                    "acceptHeader": "text/html,application/xhtml+xml",
                    "ip": "192.168.1.11",
                    "javaEnabled": "TRUE",
                    "javaScriptEnabled": "TRUE",
                    "language": "EN",
                    "colorDepth": "48",
                    "screenHeight": "400",
                    "screenWidth": "600",
                    "timeZone": "0",
                    "userAgent": "Mozilla"
                }
            }
        }
    },
    "relatedTransactionId": "<transactionId returned from /initPayment>",
    "billingAddress": {
        "firstName": "John",
        "lastName": "Smith",
        "country": "US",
        "email": "[email protected]"
    },
    "deviceDetails": {
        "ipAddress": "192.168.2.38"
    },
    "timeStamp": "20241105091105",
    "checksum": "328bd06ea3f696229d1387c9313dfd1e"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "clientUniqueId": "12345",
    "amount": "200",
    "currency": "USD",
    "userTokenId": "230811147",
    "paymentOption": {
        "card": {
            "cardNumber": "4000027891380961",
            "cardHolderName": "John Smith",
            "expirationMonth": "12",
            "expirationYear": "2030",
            "CVV": "217"
        }
    },
    "relatedTransactionId": "<transactionId returned from 3DS Payment Request>",
    "billingAddress": {
        "firstName": "John",
        "lastName": "Smith",
        "country": "US",
        "email": "[email protected]"
    },
    "deviceDetails": {
        "ipAddress": "192.168.2.38"
    },
    "timeStamp": "20241105091149",
    "checksum": "63bdbdbe3ccb645adacec237ecbe4846"
}

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
{
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "amount": "200",
    "currency": "USD",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
    "paymentOption": {
        "card": {
            "cardNumber": "4000027891380961",
            "cardHolderName": "John Smith",
            "expirationMonth": "12",
            "expirationYear": "2030",
            "CVV": "217",
            "threeD": {
                "externalMpi": {
                    "eci": "2",
                    "cavv": "ejJRWG9SWWRpU2I1M21DelozSXU=",
                    "dsTransID": "9e6c6e9b-b390-4b11-ada9-0a8f595e8600"
                }
            }
        }
    },
    "billingAddress": {
        "firstName": "John",
        "lastName": "Smith",
        "country": "US",
        "email": "[email protected]"
    },
    "deviceDetails": {
        "ipAddress": "192.168.2.38"
    },
    "timeStamp": "20241105091144",
    "checksum": "42b44b5ffe82d625abbd8b2c61b721a3"
}

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
{
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "amount": "200",
    "currency": "USD",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
     "paymentOption": {
        "userPaymentOptionId": "53463338",
        "card": {
            "CVV": "217"
        }
    },
    "deviceDetails": {
        "ipAddress": "192.168.2.38"
    },
    "billingAddress": {
        "firstName": "John",
        "lastName": "Smith",
        "email": "[email protected]",
        "country": "US"
    },
    "timeStamp": "20241105081132",
    "checksum": "5582d0189dd440f4bbf960569ec22e77"
}

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
{
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "amount": "200",
    "currency": "USD",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
    "paymentOption": {
        "card": {
            "externalToken": {
                "externalTokenProvider": "ApplePay",
                "mobileToken": "{\"paymentData\": {\"version\":\"EC_v1\",\"data\":\"2uhvZkdQfbZw8I4X9tZ8FijeTufEdcU61hMiuRKPyk43zqC9e6bnyNANZkbeZPyEvoZY1HtAQcmKm04GyoP+wG9L4OHIPi0SXd1GOR0mB7iVTQqcBElNYQfHESh9xj480o8A1KrkI5YW3rxEOxgjpi6520fXe9Tvs4r9iF9Bmc4lbWKyyZxLH7L12ThxdGoIcR25E4NADv4EidgTPjavEeF1xuBXuej+bD2WnEGOUtJpj8V43qvpZz2NUDxAC0yRxgOBomEMPjcJWVlWGuKFI700rs4Fx+UkIHhl\/diRM71OmPeoaTRyf\/qShuCNBz\/cxdyG\/rZtFLFY\/coUS3MHWzCYgdPNetPImf1jTrh+k4VFsJb9uh54b7h6mNUQEzFV\/EGVJJoNtDaT4cVYn\/xywUAkrCcOmEWyFrM90ukwPg0=\",\"signature\":\"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID5jCCA4ugAwIBAgIIaGD2mdnMpw8wCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE2MDYwMzE4MTY0MFoXDTIxMDYwMjE4MTY0MFowYjEoMCYGA1UEAwwfZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtU0FOREJPWDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgjD9q8Oc914gLFDZm0US5jfiqQHdbLPgsc1LUmeY+M9OvegaJajCHkwz3c6OKpbC9q+hkwNFxOh6RCbOlRsSlaOCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwHQYDVR0OBBYEFAIkMAua7u1GMZekplopnkJxghxFMAwGA1UdEwEB\/wQCMAAwHwYDVR0jBBgwFoAUI\/JJxE+T5O8n5sT2KGw\/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB\/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB\/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0kAMEYCIQDaHGOui+X2T44R6GVpN7m2nEcr6T6sMjOhZ5NuSo1egwIhAL1a+\/hp88DKJ0sv3eT3FxWcs71xmbLKD\/QJ3mWagrJNMIIC7jCCAnWgAwIBAgIISW0vvzqY2pcwCgYIKoZIzj0EAwIwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcNMTQwNTA2MjM0NjMwWhcNMjkwNTA2MjM0NjMwWjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwFxGEGddkhdUaXiWBB3bogKLv3nuuTeCN\/EuT4TNW1WZbNa4i0Jd2DSJOe7oI\/XYXzojLdrtmcL7I6CmE\/1RFo4H3MIH0MEYGCCsGAQUFBwEBBDowODA2BggrBgEFBQcwAYYqaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZXJvb3RjYWczMB0GA1UdDgQWBBQj8knET5Pk7yfmxPYobD+iu\/0uSzAPBgNVHRMBAf8EBTADAQH\/MB8GA1UdIwQYMBaAFLuw3qFYM4iapIqZ3r6966\/ayySrMDcGA1UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB\/wQEAwIBBjAQBgoqhkiG92NkBgIOBAIFADAKBggqhkjOPQQDAgNnADBkAjA6z3KDURaZsYb7NcNWymK\/9Bft2Q91TaKOvvGcgV5Ct4n4mPebWZ+Y1UENj53pwv4CMDIt1UQhsKMFd2xd8zg7kGf9F3wsIW2WT8ZyaYISb1T4en0bmcubCYkhYQaZDwmSHQAAMYIBjDCCAYgCAQEwgYYwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTAghoYPaZ2cynDzANBglghkgBZQMEAgEFAKCBlTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0yMDA1MTQxMTEzMDJaMCoGCSqGSIb3DQEJNDEdMBswDQYJYIZIAWUDBAIBBQChCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIJPkOnv7VCVYvnXUWwIchmkON4dVtXHsTssY1uMJkn0XMAoGCCqGSM49BAMCBEcwRQIhAMzNQ\/Xw8dxOD3V\/tizLXRpV77PpcfTpYUUpN0gJztrqAiBWqco9HpLSoVN5ySEmZdAGRuer2Az06xRkmsToV03rnQAAAAAAAA==\",\"header\": {\"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEAnHMlqALgHhQoT5tf1Df9WApE6gFx6LgZaSUAOkikr4Tn97T2pgi3Iz9guCcHOCcfelv+qfPcHzfBbvs4UWilg==\",\"publicKeyHash\":\"STh9vCW6aUGJLEEtdHr1w0AHd1uDXgrNOGNZqKcKW9g=\",\"transactionId\":\"e5cf25993cbf76cac2467aece05ad07be7aeebcc439efe2e957dd1b6f556ffae\"}},\"paymentMethod\": {\"displayName\":\"Visa 4228\",\"network\":\"Visa\",\"type\":\"debit\"},\"transactionIdentifier\":\"E5CF25993CBF76CAC2467AECE05AD07BE7AEEBCC439EFE2E957DD1B6F556FFAE\"}"
            }
        }
    },
    "billingAddress": {
        "firstName": "John",
        "lastName": "Smith",
        "email": "[email protected]",
        "country": "US"
    },
    "deviceDetails": {
        "ipAddress": "192.168.2.38"
    },
    "timeStamp": "20240517130543",
    "checksum": "de0e48812c269933d9eb37e74db45f1c"
}

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
{
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "amount": "200",
    "currency": "USD",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
    "paymentOption": {
        "card": {
            "externalToken": {
                "externalTokenProvider": "GooglePay",
                "mobileToken": "{\"type\":\"CARD\",\"info\": {\"billingAddress\": {\"name\":\"Cardholder Name\",\"postalCode\":\"94043\",\"countryCode\":\"US\",\"phoneNumber\":\"+1 650-555-5555\"},\"cardNetwork\":\"VISA\",\"cardDetails\":\"1111\",\"assuranceDetails\": {\"accountVerified\":true,\"cardHolderAuthenticated\":false}},\"description\":\"Visa •••• 1111\",\"tokenizationData\": {\"type\":\"PAYMENT_GATEWAY\",\"token\":\"{\\\"signature\\\":\\\"MEQCIBSXDZg3Q0XqXLnrzP8RxBEN3NpNK/I3SJ3+hWSUziJLAiARGCaSHs96UViLtvzZVx1DCDo3fyJ6dhyzvNpHFeogqg\\\\u003d\\\\u003d\\\",\\\"intermediateSigningKey\\\": {\\\"signedKey\\\":\\\"{\\\\\\\"keyValue\\\\\\\":\\\\\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExEpugh2aN/fPWStOyIKruZddUSccE4DdGtYVOc02j7eYFLvyJibFMZp+xR3cWtK5IU5glbJLNUSD/I/pcYS7lw\\\\\\\\u003d\\\\\\\\u003d\\\\\\\",\\\\\\\"keyExpiration\\\\\\\":\\\\\\\"1632225309434\\\\\\\"}\\\",\\\"signatures\\\":[\\\"MEUCIHWii7llskm933S/egpmbQM15BbSTRvSzgX0MFp3ggu+AiEA5jMjfnOlITJ0qvEXE+W3e7ESou0F3OJyE5h3LsSPEkg\\\\u003d\\\"]},\\\"protocolVersion\\\":\\\"ECv2\\\",\\\"signedMessage\\\":\\\"{\\\\\\\"encryptedMessage\\\\\\\":\\\\\\\"ZrgQWBuOzjVki/v9yUae4VrUFnrEc3uMbxR7pgAlp/IL+sypqYEfPLOzM8pgFAeV84iNCXbFJDOWyYFURDqGda4OZH1IMMUvW+Xw+B9g3tnilDCZ/sWzn3UmA0yrXvIdVq9ASLwsp+slKo3STHolCOPfyHOb53XR6w4I97/culMi1FhBPOF5SWmMSkXixvF6tgnzpuMt24gpi9T/kAvgtr+ZpeUDPbfIwMaIZNnBKjlsWICRlIRBBwAY5JctqqrKbf2yNJigVYUbBAZ7mF0/FvFDa13hV8y3NHMTi/x2cChLcgdTWYEmfgZwoQIjhJ+eaitwcChIpRXHEkDvuDdIhVbS4vYAFpD79Rv0e0vGZEPwWfFQpaJv37rvH3Ti1k9WYgJazoP7PbRJi2ZZ2syCgma3ZfAXKiholqr4mfy7+QfQo3/7v91eX//vnnkMScSbHKrs95d+bo0PRCfXbNrwzOJejIRxRsc7Av92oVU3qEdZWaVesp3tDdKGKClkvZnHY0xfWbnX7lhUjRVTd9Tx5/WHaL00HnWLksMj7TOK2qiNS+E12d16ZP5yDtFOJrxNG0WNALPZcaoe\\\\\\\",\\\\\\\"ephemeralPublicKey\\\\\\\":\\\\\\\"BK1xu+RZNIWprQ6M+zbGvYZd0N0rGWSWcgJbSypUknvPxA46zoga2Ai0cOegEM7Ww8gXaXe78w6GvaF8gmmMwIc\\\\\\\\u003d\\\\\\\",\\\\\\\"tag\\\\\\\":\\\\\\\"Jqi6tOiw3CFH0MTzr89Bsm2RkhEvNhcfxwmjtu4GwYA\\\\\\\\u003d\\\\\\\"}\\\"}\"}}"
            }
        }
    },
    "billingAddress": {
        "firstName": "John",
        "lastName": "Smith",
        "email": "[email protected]",
        "country": "US"
    },
    "deviceDetails": {
        "ipAddress": "192.168.2.38"
    },
    "timeStamp": "20240517130543",
    "checksum": "de0e48812c269933d9eb37e74db45f1c"
}

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53443#initializing-the-sdk)

safecharge.paymentService.createPayment({
    amount: "100",
    currency: "USD",
    sessionToken: "9610a8f6-44cf-4c4f-976a-005da69a2a3b", /* taken from /openOrder result */
    paymentOption: {
        card: {
            expirationYear: "2030",
            CVV: "217",
            cardHolderName: "John Smith",
            expirationMonth: "12",
            cardNumber: "4000027891380961"
        }
    },
    billingAddress: {
        firstName: "John",
        lastName: "Smith",
        country: "US",
        email: "[email protected]"
    },
    deviceDetails: {
        ipAddress: "192.168.2.38"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult);
});

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53443#initializing-the-sdk)

safecharge.paymentService.createPayment({
    currency: "USD",
    amount: "100",
    userTokenId: "230811147",
    clientRequestId: "1C6CT7V1L",
    clientUniqueId: "12345",
    paymentOption: {
        card: {
            cardNumber: "4000027891380961",
            cardHolderName: "John Smith",
            expirationMonth: "12",
            expirationYear: "2030",
            CVV: "217",
            threeD: {
                version: "2",
                notificationUrl: "http://www.notify_URL.com",
                merchantUrl: "http://www.merchant_URL.com",
                platformType: "02",
                v2AdditionalParams: {
                    challengeWindowSize: "05"
                browserDetails: {
                    acceptHeader: "text/html,application/xhtml+xml",
                    ip: "192.168.1.11",
                    javaEnabled: "TRUE",
                    javaScriptEnabled: "TRUE",
                    language: "EN",
                    colorDepth: "48",
                    screenHeight: "400",
                    screenWidth: "600",
                    timeZone: "0",
                    userAgent: "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)"
                }
            }
        }
    },
    billingAddress: {
        firstName: "John",
        lastName: "Smith",
        country: "US",
        email: "[email protected]"
    },
    deviceDetails: {
        ipAddress: "192.168.2.38"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult);
});

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53443#initializing-the-sdk)

$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    currency: "USD",
    amount: "200",
    userTokenId: "230811147",
    clientRequestId: "1C6CT7V1L",
    clientUniqueId: "12345",
    paymentOption: {
        alternativePaymentMethod: {
            paymentMethod: "apmgw_MoneyBookers",
            account_id: "SkrillTestUser3"
        }
    },
    billingAddress: {
        firstName: "John",
        lastName: "Smith",
        country: "US",
        email: "[email protected]"
    },
    deviceDetails: {
        ipAddress: "192.168.2.38"
    },
    userDetails: {
        firstName: "John",
        lastName: "Smith",
        country: "US",
        email: "[email protected]"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult);
});

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53443#initializing-the-sdk)

$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    currency: "USD",
    amount: "200",
    userTokenId: "230811147",
    clientUniqueId: "12345",
    clientRequestId: "1C6CT7V1L",
    paymentOption: {
        card: {
            cardNumber: "4000027891380961",
            cardHolderName: "John Smith",
            expirationMonth: "12",
            expirationYear: "2030",
            CVV: "217",
            threeD: {
                methodCompletionInd: "Y",
                version: "2.1.0",
                notificationUrl: "<notificationURL>",
                merchantUrl: "<merchantURL>",
                platformType: "02",
                v2AdditionalParams: {
                    challengeWindowSize: "05"
                browserDetails: { // collected on the 3DS fingerprinting
                    acceptHeader: "text/html,application/xhtml+xml",
                    ip: "192.168.1.11",
                    javaEnabled: "TRUE",
                    javaScriptEnabled: "TRUE",
                    language: "EN",
                    colorDepth: "48",
                    screenHeight: "400",
                    screenWidth: "600",
                    timeZone: "0",
                    userAgent: "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)"
                }
            }
        }
    },
    relatedTransactionId: "2110000000001208909", // as returned from /initPayment
    billingAddress: {
        firstName: "John",
        lastName: "Smith",
        country: "US",
        email: "[email protected]"
    },
    deviceDetails: {
        ipAddress: "192.168.2.38"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult);
});

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53443#initializing-the-sdk)

$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    currency: "USD",
    amount: "200",
    userTokenId: "230811147",
    clientRequestId: "1C6CT7V1L",
    clientUniqueId: "12345",
        card: {
            expirationYear: "2030",
            CVV: "217",
            cardHolderName: "John Smith",
            expirationMonth: "12",
            cardNumber: "4000027891380961"
        }
    },
    relatedTransactionId: "2110000000001208909", // as returned from 1st payment call
    billingAddress: {
        firstName: "John",
        lastName: "Smith",
        country: "US",
        email: "[email protected]"
    },
    deviceDetails: {
        ipAddress: "192.168.2.38"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult);
});

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53443#initializing-the-sdk)

$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    currency: "USD",
    amount: "200",
    userTokenId: "230811147",
    clientRequestId: "1C6CT7V1L",
    clientUniqueId: "12345",
    paymentOption: {
        card: {
            cardNumber: "4000027891380961",
            cardHolderName: "John Smith",
            expirationMonth: "12",
            expirationYear: "2030",
            CVV: "217",
            threeD: {
                externalMpi: {
                    eci: "2",
                    cavv: "ejJRWG9SWWRpU2I1M21DelozSXU",
                    dsTransID: "9e6c6e9b-b390-4b11-ada9-0a8f595e8600"
                }
            }
        }
    },
    billingAddress: {
        firstName: "John",
        lastName: "Smith",
        country: "US",
        email: "[email protected]"
    },
    deviceDetails: {
        ipAddress: "192.168.2.38"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
//Initialize the SDK (see https://docs.nuvei.com/?p=53443#initializing-the-sdk)

safecharge.paymentService.createPayment({
    amount: "100",
    currency: "USD",
    sessionToken: "9610a8f6-44cf-4c4f-976a-005da69a2a3b", /* taken from /openOrder result */
    paymentOption: {
        userPaymentOptionId: "53463338"
        card: {
            CVV: "217"
        }
    },
    billingAddress: {
        firstName: "John",
        lastName: "Smith",
        country: "US",
        email: "[email protected]"
    },
    deviceDetails: {
        ipAddress: "192.168.2.38"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult);
});

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
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    // Parameters needed for payment simple card call
    String userTokenId = "230811147";
    String clientUniqueId = "12345";
    String clientRequestId = "1C6CT7V1L";
    String currency = "USD";
    String amount = "100";

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("192.168.2.38");

    Card card = new Card();
    card.setCardNumber("4000027891380961");
    card.setCardHolderName("John Smith");
    card.setCVV("217");
    card.setExpirationMonth("12");
    card.setExpirationYear("2030");

    PaymentOption paymentOption = new PaymentOption();
    paymentOption.setCard(card);

    UserAddress billingAddress = new UserAddress();
    billingAddress.setFirstName("John");
    billingAddress.setLastName("Smith");
    billingAddress.setEmail("[email protected]");
    billingAddress.setCountry("US");

    Safecharge safecharge = new Safecharge();
    SafechargeResponse response = safecharge.payment(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency, amount, null, null, deviceDetails, null, null, billingAddress, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null);
}

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
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    // Parameters needed for payment full card call
    String userTokenId = "230811147";
    String clientUniqueId = "12345";
    String clientRequestId = "1C6CT7V1L";
    String currency = "USD";
    String amount = "100";

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("192.168.2.38");

    BrowserDetails browserDetails = new BrowserDetails();
    browserDetails.setAcceptHeader("text/html,application/xhtml+xml");
    browserDetails.setIp("192.168.1.11");
    browserDetails.setJavaEnabled("TRUE");
    browserDetails.setJavaScriptEnabled("TRUE");
    browserDetails.setLanguage("EN");
    browserDetails.setColorDepth("48");
    browserDetails.setScreenHeight("400");
    browserDetails.setScreenWidth("600");
    browserDetails.setTimeZone("0");
    browserDetails.setUserAgent("Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)");

    V2AdditionalParams v2AdditionalParams = new V2AdditionalParams();
    v2AdditionalParams.setChallengeWindowSize("2");

    ThreeD threeD = new ThreeD();
    threeD.setBrowserDetails(browserDetails);
    threeD.setV2AdditionalParams(v2AdditionalParams);
    threeD.setVersion("2");
    threeD.setNotificationURL("http://www.notify_URL.com");
    threeD.setMerchantURL("http://www.merchant_URL.com");
    threeD.setPlatformType("02");

    Card card = new Card();
    card.setCardNumber("4000027891380961");
    card.setCardHolderName("John Smith");
    card.setCVV("217");
    card.setExpirationMonth("12");
    card.setExpirationYear("2030");
    card.setThreeD(threeD);

    PaymentOption paymentOption = new PaymentOption();
    paymentOption.setCard(card);

    UserAddress billingAddress = new UserAddress();
    billingAddress.setFirstName("John");
    billingAddress.setLastName("Smith");
    billingAddress.setEmail("[email protected]");
    billingAddress.setCountry("US");

    Safecharge safecharge = new Safecharge();
    SafechargeResponse response = safecharge.payment(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency, amount, null, null, deviceDetails, null, null, billingAddress, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null);
}

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
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    // Parameters needed for payment APM call
    String userTokenId = "230811147";
    String clientUniqueId = "12345";
    String clientRequestId = "1C6CT7V1L";
    String currency = "USD";
    String amount = "200";

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("192.168.2.38");

    RestApiUserDetails userDetails = new RestApiUserDetails();
    userDetails.setFirstName("John");
    userDetails.setLastName("Smith");
    userDetails.setEmail("[email protected]");
    userDetails.setCountry("US");

    Map< String, String > alternativePaymentMethod = new HashMap< >();
    alternativePaymentMethod.put("paymentMethod", "apmgw_MoneyBookers");
    alternativePaymentMethod.put("account_id", "SkrillTestUser3");

    PaymentOption paymentOption = new PaymentOption();
    paymentOption.setAlternativePaymentMethod(alternativePaymentMethod);

    UserAddress billingAddress = new UserAddress();
    billingAddress.setFirstName("John");
    billingAddress.setLastName("Smith");
    billingAddress.setEmail("[email protected]");
    billingAddress.setCountry("US");

    Safecharge safeCharge = new Safecharge();
    SafechargeResponse response = safeCharge.payment(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency, amount, null, null, deviceDetails, userDetails, null, billingAddress, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null);
}

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
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    // Parameters needed for a 3DS payment call
    String userTokenId = "230811147";
    String clientRequestId = "1C6CT7V1L";
    String clientUniqueId = "12345";
    String currency = "USD";
    String amount = "200";

    V2AdditionalParams v2AdditionalParams = new V2AdditionalParams();
    v2AdditionalParams.setChallengeWindowSize("05");

    BrowserDetails browserDetails = new BrowserDetails();
    browserDetails.setAcceptHeader("text/html,application/xhtml+xml");
    browserDetails.setIp("192.168.1.11");
    browserDetails.setJavaEnabled("TRUE");
    browserDetails.setJavaScriptEnabled("TRUE");
    browserDetails.setLanguage("EN");
    browserDetails.setColorDepth("48");
    browserDetails.setScreenHeight("400");
    browserDetails.setScreenWidth("600");
    browserDetails.setTimeZone("0");
    browserDetails.setUserAgent("Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)");

    ThreeD threeD = new ThreeD();
    threeD.setMethodCompletionInd("Y");
    threeD.setVersion("2.1.0");
    threeD.setNotificationURL("<notificationURL>");
    threeD.setMerchantURL("<merchantURL>");
    threeD.setV2AdditionalParams(v2AdditionalParams);
    threeD.setBrowserDetails(browserDetails);

    Card card = new Card();
    card.setCardNumber("4000027891380961");
    card.setCardHolderName("John Smith");
    card.setExpirationMonth("12");
    card.setExpirationYear("2030");
    card.setCVV("217");
    card.setThreeD(threeD);

    PaymentOption paymentOption = new PaymentOption();
    paymentOption.setCard(card);

    UserAddress billingAddress = new UserAddress();
    billingAddress.setFirstName("John");
    billingAddress.setLastName("Smith");
    billingAddress.setCountry("US");
    billingAddress.setEmail("[email protected]");

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("192.168.2.38");

    Safecharge safecharge = new Safecharge();
    PaymentResponse response = safecharge.payment(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency, amount, null, null, deviceDetails, null, billingAddress, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null);
}

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
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    // Parameters needed for liability shift payment call
    String userTokenId = "230811147";
    String clientRequestId = "1C6CT7V1L";
    String clientUniqueId = "12345";
    String currency = "USD";
    String amount = "200";
    String relatedTransactionId = "2110000000001208909";

    Card card = new Card();
    card.setCardNumber("4000027891380961");
    card.setCardHolderName("John Smith");
    card.setExpirationMonth("12");
    card.setExpirationYear("25");
    card.setCVV("217");

    PaymentOption paymentOption = new PaymentOption();
    paymentOption.setCard(card);

    UserAddress billingAddress = new UserAddress();
    billingAddress.setFirstName("John");
    billingAddress.setLastName("Smith");
    billingAddress.setCountry("US");
    billingAddress.setEmail("[email protected]");

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("192.168.2.38");

    Safecharge safecharge = new Safecharge();
    PaymentResponse response = safecharge.payment(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency, amount, null, null, deviceDetails, null, billingAddress, null, null, null, null, null, null, null, null, relatedTransactionId, null, null, null, null, null, null, null, null);
}

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
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    // Parameters needed for external MPI payment call
    String userTokenId = "230811147";
    String clientRequestId = "1C6CT7V1L";
    String clientUniqueId = "12345";
    String currency = "USD";
    String amount = "200";

    ExternalMpi externalMpi = new ExternalMpi();
    externalMpi.setEci("2");
    externalMpi.setCavv("ejJRWG9SWWRpU2I1M21DelozSXU=");
    externalMpi.setDsTransID("9e6c6e9b-b390-4b11-ada9-0a8f595e8600");

    ThreeD threeD = new ThreeD();
    threeD.setExternalMpi(externalMpi);

    Card card = new Card();
    card.setCardNumber("4000027891380961");
    card.setCardHolderName("John Smith");
    card.setExpirationMonth("12");
    card.setExpirationYear("25");
    card.setCVV("217");
    card.setThreeD(threeD);

    PaymentOption paymentOption = new PaymentOption();
    paymentOption.setCard(card);

    UserAddress billingAddress = new UserAddress();
    billingAddress.setFirstName("John");
    billingAddress.setLastName("Smith");
    billingAddress.setCountry("US");
    billingAddress.setEmail("[email protected]");

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("192.168.2.38");

    Safecharge safecharge = new Safecharge();
    PaymentResponse response = safecharge.payment(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency, amount, null, null, deviceDetails, null, billingAddress, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null);
}

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
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    // Parameters needed for payment with UPO call
    String clientRequestId = "1C6CT7V1L";
    String clientUniqueId = "12345";
    String currency = "USD";
    String amount = "200";
    String userTokenId = "230811147";

    Card card = new Card();
    card.setCVV("217");

    PaymentOption paymentOption = new PaymentOption();
    paymentOption.setUserPaymentOptionId("53463338");
    paymentOption.setCard(card);

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("192.168.2.38");

    UserAddress billingAddress = new UserAddress();
    billingAddress.setFirstName("John");
    billingAddress.setLastName("Smith");
    billingAddress.setEmail("[email protected]");
    billingAddress.setCountry("US");

    Safecharge safecharge = new Safecharge();
    Safechargeresponse = safecharge.payment(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency, amount, null, null, deviceDetails, null, null, billingAddress, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, );
}

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    "currency"       => "USD",
    "amount"         => "100",
    "userTokenId"    => "230811147",
    "clientRequestId" => "1C6CT7V1L",
    "clientUniqueId" => "12345",
    "paymentOption"  => [
        "card" => [
            "cardNumber"      => "4000027891380961",
            "cardHolderName"  => "John Smith",
            "expirationMonth" => "12",
            "expirationYear"  => "2030",
            "CVV"             => "217",
        ]
    ],
    "billingAddress" => [
        "firstName"   => "John",
        "lastName"   => "Smith",
        "country"   => "US",
        "email"     => "[email protected]",
    ],
    "deviceDetails"  => [
        "ipAddress"  => "192.168.2.38",
    ],
]);
?>

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    "currency"       => "USD",
    "amount"         => "100",
    "userTokenId"    => "230811147",
    "clientRequestId" => "1C6CT7V1L",
    "clientUniqueId" => "12345",
    "paymentOption"  => [
        "card" => [
            "cardNumber"      => "4000027891380961",
            "cardHolderName"  => "John Smith",
            "expirationMonth" => "12",
            "expirationYear"  => "2030",
            "CVV"             => "217",
            "threeD" =>[
                "version" =>"2",
                "notificationUrl"      => "http://www.notify_URL.com",
                "merchantUrl"          => "http://www.merchant_URL.com",
                "platformType"         => "02",
                "v2AdditionalParams" =>[
                    "challengeWindowSize" =>"05",
                ],
                "browserDetails" =>[
                    "acceptHeader"      =>"text/html,application/xhtml+xml",
                    "ip"                =>"192.168.1.11",
                    "javaEnabled"       =>"TRUE",
                    "javaScriptEnabled" =>"TRUE",
                    "language"          =>"EN",
                    "colorDepth"        =>"48",
                    "screenHeight"      =>"400",
                    "screenWidth"       =>"600",
                    "timeZone"          =>"0",
                    "userAgent"         =>"Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)"
                ]
            ]
        ]
    ],
    "billingAddress" => [
        "firstName"   => "John",
        "lastName"   => "Smith",
        "country"   => "US",
        "email"     => "[email protected]",
    ],
    "deviceDetails"  => [
        "ipAddress"  => "192.168.2.38",
    ],
]);
?>

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    "currency"       => "USD",
    "amount"         => "200",
    "userTokenId"    => "230811147",
    "clientRequestId" => "1C6CT7V1L",
    "clientUniqueId" => "12345",
    "paymentOption"  => [
        "alternativePaymentMethod" => [
            "paymentMethod"      => "apmgw_MoneyBookers",
            "account_id"  => "SkrillTestUser3"
        ]
    ],
    "billingAddress" => [
        "firstName"   => "John",
        "lastName"   => "Smith",
        "country"   => "US",
        "email"     => "[email protected]",
    ],
    "deviceDetails"  => [
        "ipAddress"  => "192.168.2.38",
    ],
    "userDetails" => [
        "firstName"   => "John",
        "lastName"   => "Smith",
        "country"   => "US",
        "email"     => "[email protected]",
    ],
]);
?>

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    "currency"       => "USD",
    "amount"         => "200",
    "userTokenId"    => "230811147",
    "clientRequestId" => "1C6CT7V1L",
    "clientUniqueId" => "12345",
    "paymentOption"  => [
        "card" => [
            "cardNumber"      => "4000027891380961",
            "cardHolderName"  => "John Smith",
            "expirationMonth" => "12",
            "expirationYear"  => "2030",
            "CVV"             => "217",
            "threeD" =>[
                "methodCompletionInd"  => "Y",
                "version"              => "2.1.0",
                "notificationUrl"      => "<notificationURL>",
                "merchantUrl"          => "<merchantURL>",
                "platformType"         => "02",
                "v2AdditionalParams" =>[
                    "challengeWindowSize" =>"05",
                ],
                "browserDetails" =>[        // collected for 3DS fingerprinting
                    "acceptHeader"      => "text/html,application/xhtml+xml",
                    "ip"                => "190.0.23.160",
                    "javaEnabled"       => "TRUE",
                    "javaScriptEnabled" => "TRUE",
                    "language"          => "EN",
                    "colorDepth"        => "48",
                    "screenHeight"      => "400",
                    "screenWidth"       => "600",
                    "timeZone"          => "0",
                    "userAgent"         => "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)"
                ]
            ]
        ]
    ],
    "relatedTransactionId" => "2110000000001208909", // as returned from /initPayment
    "billingAddress" => [
        "firstName"   => "John",
        "lastName"   => "Smith",
        "country"   => "US",
        "email"     => "[email protected]",
    ],
    "deviceDetails"  => [
        "ipAddress"  => "192.168.2.38",
    ],
]);
?>

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    "currency"       => "USD",
    "amount"         => "200",
    "userTokenId"    => "230811147",
    "clientRequestId" => "1C6CT7V1L",
    "clientUniqueId" => "12345",
    "paymentOption"  => [
        "card" => [
            "cardNumber"      => "4000027891380961",
            "cardHolderName"  => "John Smith",
            "expirationMonth" => "12",
            "expirationYear"  => "2030",
            "CVV"             => "217",
        ]
    ],
    "relatedTransactionId" => "2110000000001208909", // as returned from 1st payment call
    "billingAddress" => [
        "firstName"   => "John",
        "lastName"   => "Smith",
        "country"   => "US",
        "email"     => "[email protected]",
    ],
    "deviceDetails"  => [
        "ipAddress"  => "192.168.2.38",
    ],
]);
?>

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    "currency"       => "USD",
    "amount"         => "200",
    "userTokenId"    => "230811147",
    "clientRequestId" => "1C6CT7V1L",
    "clientUniqueId" => "12345",
    "paymentOption"  => [
        "card" => [
            "cardNumber"      => "4000027891380961",
            "cardHolderName"  => "John Smith",
            "expirationMonth" => "12",
            "expirationYear"  => "2030",
            "CVV"             => "217",
            "threeD" =>[
                "externalMpi" =>[
                    "eci"       => "2",
                    "cavv"          => "ejJRWG9SWWRpU2I1M21DelozSXU",
                    "dsTransID"         => "9e6c6e9b-b390-4b11-ada9-0a8f595e8600"
                ]
            ]
        ]
    ],
    "billingAddress" => [
        "firstName"   => "John",
        "lastName"   => "Smith",
        "country"   => "US",
        "email"     => "[email protected]",
    ],
    "deviceDetails"  => [
        "ipAddress"  => "192.168.2.38",
    ],
]);
?>

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    "currency"       => "USD",
    "amount"         => "100",
    "userTokenId"    => "230811147",
    "clientRequestId" => "1C6CT7V1L",
    "clientUniqueId" => "12345",
    "paymentOption"  => [
        "userPaymentOptionId" => "53463338",
        "card" => [
            "CVV"             => "217",
        ]
    ],
    "billingAddress" => [
        "firstName"   => "John",
        "lastName"   => "Smith",
        "country"   => "US",
        "email"     => "[email protected]",
    ],
    "deviceDetails"  => [
        "ipAddress"  => "192.168.2.38",
    ],
]);
?>

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
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.Payment(
    "USD",
    "100",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "John Smith",
            ExpirationMonth = "12",
            ExpirationYear = "26",
            CVV = "217"
        }
    },
    clientRequestId: "1C6CT7V1L",
    userTokenId: "230811147",
    clientUniqueId: "12345",
    deviceDetails: new DeviceDetails { IpAddress = "192.168.2.38" });
    billingAddress: new UserAddress
    {
        FirstName = "John",
        LastName = "Smith",
        Email = "[email protected]",
        Country = "US",
    },

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
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.Payment(
    "USD",
    "100",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "John Smith",
            ExpirationMonth = "12",
            ExpirationYear = "26",
            CVV = "217",
            ThreeD = new ThreeD
            {
                Version = "2",
                NotificationURL = "http://www.notify_URL.com",
                MerchantURL = "http://www.merchant_URL.com",
                PlatformType = "02",
                V2AdditionalParams = new V2AdditionalParams
                {
                    ChallengeWindowSize = "05"
                },
                BrowserDetails = new BrowserDetails
                {
                    AcceptHeader = "text/html,application/xhtml+xml",
                    Ip = "192.168.1.11",
                    JavaEnabled = "TRUE",
                    JavaScriptEnabled = "TRUE",
                    Language = "EN",
                    ColorDepth = "48",
                    ScreenHeight = "400",
                    ScreenWidth = "600",
                    TimeZone = "0",
                    UserAgent = "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)"
                }
            }
        }
    },
    clientUniqueId: "12345",
    clientRequestId: "1C6CT7V1L",
    userTokenId: "230811147",
    deviceDetails: new DeviceDetails { IpAddress = "192.168.2.38" },
    billingAddress: new UserAddress
    {
        FirstName = "John",
        LastName = "Smith",
        Email = "[email protected]",
        Country = "US",
    },
);

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
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.Payment(
    "USD",
    "200",
    new PaymentOption
    {
        AlternativePaymentMethod = new Dictionary<string, string>()
        {
            { "paymentMethod", "apmgw_MoneyBookers" },
            { "account_id", "SkrillTestUser3" }
        }
    },
    clientUniqueId: "12345",
    clientRequestId: "1C6CT7V1L",
    userTokenId: "230811147",
    billingAddress: new UserAddress
    {
        FirstName = "John",
        LastName = "Smith",
        Country = "US",
        Email = "[email protected]"
    },
    userDetails: new UserDetails
    {
        FirstName = "John",
        LastName = "Smith",
        Country = "US",
        Email = "[email protected]"
    },
    deviceDetails: new DeviceDetails { IpAddress = "192.168.2.38" });

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
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.Payment(
    "USD",
    "200",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "John Smith",
            ExpirationMonth = "12",
            ExpirationYear = "26",
            CVV = "217",
            ThreeD = new ThreeD
            {
                MethodCompletionInd = "Y",
                Version = "2.1.0",
                NotificationURL = "<notificationURL>",
                MerchantURL = "<merchantURL>",
                PlatformType = "02",
                V2AdditionalParams = new V2AdditionalParams
                {
                    ChallengeWindowSize = "05"
                },
                BrowserDetails = new BrowserDetails
                {
                    AcceptHeader = "text/html,application/xhtml+xml",
                    Ip = "192.168.1.11",
                    JavaEnabled = "TRUE",
                    JavaScriptEnabled = "TRUE",
                    Language = "EN",
                    ColorDepth = "48",
                    ScreenHeight = "400",
                    ScreenWidth = "600",
                    TimeZone = "0",
                    UserAgent = "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)"
                }
            }
        }
    },
    clientUniqueId: "12345",
    clientRequestId: "1C6CT7V1L",
    userTokenId: "230811147",
    relatedTransactionId: "2110000000001208909", // as returned from /initPayment
    billingAddress: new UserAddress
    {
        FirstName = "John",
        LastName = "Smith",
        Country = "US",
        Email = "[email protected]",
    },
    deviceDetails: new DeviceDetails { IpAddress = "192.168.2.38" });

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
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.Payment(
    "USD",
    "200",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "John Smith",
            ExpirationMonth = "12",
            ExpirationYear = "26",
            CVV = "217"
        }
    },
    clientUniqueId: "12345",
    clientRequestId: "1C6CT7V1L",
    userTokenId: "230811147",
    relatedTransactionId: "2110000000001208909", // as returned from 1st payment call
    billingAddress: new UserAddress
    {
        FirstName = "John",
        LastName = "Smith",
        Country = "US",
        Email = "[email protected]",
    },
    deviceDetails: new DeviceDetails { IpAddress = "192.168.2.38" });

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
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.Payment(
    "USD",
    "200",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "John Smith",
            ExpirationMonth = "12",
            ExpirationYear = "26",
            CVV = "217",
            ThreeD = new ThreeD
            {
                ExternalMpi = new ExternalMpi
                {
                    Eci = "2",
                    Cavv = "ejJRWG9SWWRpU2I1M21DelozSXU",
                    DsTransID = "9e6c6e9b-b390-4b11-ada9-0a8f595e8600",
                }
            }
        }
    },
    clientUniqueId: "12345",
    clientRequestId: "1C6CT7V1L",
    userTokenId: "230811147",
    billingAddress: new UserAddress
    {
        FirstName = "John",
        LastName = "Smith",
        Country = "US",
        Email = "[email protected]",
    },
    deviceDetails: new DeviceDetails { IpAddress = "192.168.2.38" });

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
    "orderId": "271308078",
    "userTokenId": "230811147",
    "isAFT": "True",
    "isAFTOverridden": "True",
    "paymentOption": {
        "userPaymentOptionId": "53959588",
        "card": {
            "ccCardNumber": "4****2535",
            "bin": "400002",
            "last4Digits": "2535",
            "ccExpMonth": "12",
            "ccExpYear": "26",
            "acquirerId": "19",
            "cvv2Reply": "",
            "avsCode": "",
            "cardType": "Credit",
            "cardBrand": "VISA",
            "threeD": {}
        }
    },
    "transactionStatus": "APPROVED",
    "gwErrorCode": 0,
    "gwExtendedErrorCode": 0,
    "transactionType": "Sale",
    "transactionId": "1110000000010304183",
    "externalTransactionId": "",
    "authCode": "111361",
    "customData": "",
    "fraudDetails": {
        "finalDecision": "Accept"
    },
    "sessionToken": "cedbd6c0-52cf-4716-83b1-309e8e8dd2d3",
    "clientUniqueId": "12345",
    "internalRequestId": 222320318,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0",
    "clientRequestId": "1C6CT7V1L",
    "merchantAdviceCode": "02"
}

The /payment method is your endpoint for performing payment of any kind:

• Regular card transactions (credit or debit cards)
• 3DS card transactions
• APM transactions

Required Parameters

• Authentication credentials – sessionToken, merchantId, merchantSiteId, checksum, and timeStamp
• amount and currency
• ipAddress under the deviceDetails class
• firstName, lastName, country and email under the billingAddress class
• A payment option – This details by which option the payment is executed. This is passed using the paymentOption class, which is either created by the Web SDK and passed from the client-side or can be constructed by you directly on the server side.

Selecting a Payment Option (paymentOption Class)

This class determines the option used to send the payment details for the transaction:

• card – Subclass for credit/debit cards. This contains either the card details (number, expiration, etc.) and 3DS information (if required), or the temporary token information.
• userPaymentOptionId – Identifies a payment option that already has been used by the customer and is now requested for re-use. Nuvei keeps the payment option details from a previous use.
• alternativePaymentMethod – Subclass for alternative methods. The specific method is marked by the paymentMethod parameter.
• submethod – Subclass for advanced APM features.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The merchant ID provided by Nuvei (part of the authentication credentials).
merchantSiteId ^String(20) ~Required	The merchant site ID provided by Nuvei (part of the authentication credentials).
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
currency ^String(3) ~Required	The 3-letter ISO currency code.
amount ^String(12) ~Required	The transaction amount.
paymentOption ^Class ~Required	The option used to send the payment details. Choose from the following options: If you wish to collect the card details: card (Class) – Represents a credit/debit card.  • cardNumber (String, 20, REQUIRED) – The card number.  • cardHolderName (String, 70, REQUIRED) – The cardholder name.  • expirationMonth (String, 2, REQUIRED) – The card expiration month.  • expirationYear (String, 4, REQUIRED) – The card expiration year.  • CVV (String, 4, REQUIRED) – The CVV/CVC security code.  • brand (String, 20, CONDITIONAL) – The card brand.   REQUIRED when the merchant performs the encryption of the token.   Relevant for Apple Pay or Google Pay only.  • last4Digits (String, 20, CONDITIONAL) – The last four digits of the card number.   REQUIRED when the merchant performs the encryption of the token.   Relevant for Apple Pay or Google Pay only.  • selectedBrand (String, 128) – The brand selected by the consumer for the transaction processing.  OR  For payment with a temporary token generated by getToken() instead of card details:   ccTempToken (String, 45)   cardHolderName (String, 70)  Advanced card scenarios:   • For 3DS, please refer to threeD Input Class.   • When using an external token provider such as Apple Pay or Google Pay, refer to externalToken Class.   • For storing card credentials, refer to storedCredentials Class. If you are handling a returning user and want to use a previously saved user payment option: userPaymentOptionId (String) – Identifies a payment option previously used by the customer, and is now requested for re-use (Nuvei keeps payment option details from a previous use). Upon re-use, any of the following additional parameters from the card class may be needed as well:  • expirationMonth (String, 2) – For a newer card expiration.  • expirationYear (String, 4) – For a newer card expiration.  • CVV (String, 4) – Recommended for high-risk merchants. If you wish to process an APM: alternativePaymentMethod (Class) – Represents the alternative payment method (APM) used to process the transaction. For details, please refer to APM Input Parameters. If you need advanced APM features: subMethod (Class) – Allows using an APM but with a different payment flow.  • subMethod (String, 50) – The APM name.  • referenceId (String) – Allows the merchant to provide an ID of a previous transaction, billing agreement,   or pre-approval of an APM.   NOTE: Use this parameter only if you are not using Nuvei’s User Payment Management feature.  • email (String, 255) – If no email is provided, it is automatically populated from billingAddress. Press here for more information. __________ savePm (String, 5) – Allows the merchant or the end user to override the default behavior of UPO creation by providing savePm=false so a UPO is not created with this request. Possible values: true (default) – Users can save payment details for UPOs. false – Users cannot save payment details for UPOs.
timeStamp ^String(14) ~Required	The local time (in 24-hour format) when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the input parameters, which must be concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey. Press here to see an example. NOTE: clientRequestId is optional and does not need to be included in the concatenation.
deviceDetails ^Class ~ipAddress Required	ipAddress (String, 15, REQUIRED) deviceManufacturerIdentifier (String, CONDITIONAL) – REQUIRED when the merchant performs the encryption of the token. Relevant for Apple Pay only. deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255)
billingAddress ^Class ~Some Parameters Required	The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters. country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30, REQUIRED) lastName (String, 40, REQUIRED) middleName (String, 40, OPTIONAL when the cardHolderNameVerification class is provided) phone (String, 18, REQUIRED for 3DS card authentication if email not provided) address (String, 50) streetNumber (String, 20) zip (String, 10) city (String, 30) state (String, 3) – ISO country subdivision code addressLine2 (String, 50) addressLine3 (String, 50) county (String, 255) NOTE: For all cross-border Visa Direct OCTs to/from Canada, the following recipient parameters are REQUIRED: address, city, state, country. These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.
cardHolderNameVerification ^Class %%Conditional	Allows the merchant to perform cardholder name verification. REQUIRED when using the cardholder name verification feature. NOTE: The verification is performed on the firstName, lastName, and middleName from the billingAddress class. NOTE: This feature can only be used when amount is 0. performNameVerification (String, 5, REQUIRED)  Possible values:  true – Cardholder name verification is performed.  false (default) – Cardholder name verification is not performed. Press here for an example.
relatedTransactionId ^String(19) %%Conditional	REQUIRED in the following cases: • For 3DS:  ▫ The transactionId from the response to the /initPayment call.   Press here for more information.  ▫ The transactionId from the response to the first /payment call.   Press here for more information. • For non-3D:  ▫ The transactionId from the response to the /initPayment call.   Press here for more information. • For recurring/rebilling and MIT:  ▫ The transactionId from the response to the initial transaction.   Press here for more information. NOTE: If the initial payment was not performed with Nuvei, then only the details in the externalSchemeDetails class need to be provided.
externalSchemeDetails ^Class %%Conditional	Use this class if you want to process an MIT/recurring transaction that was initiated with another processor. Press here for more information. transactionId (String, 50) – Original transactionId for the initial payment as originated in the external system. Press here to view the structure of the parameter. brand (String, 20) – The card brand. Currently supported with the following values:  VISA  MASTERCARD  AMEX  DINERS  DISCOVER
authenticationOnlyType ^String(30) %%Conditional	If you are not using User Payment Management (tokenization) and would like to send Zero Amount Authorization, you need to set authenticationOnlyType to one of the following values: RECURRING – For when multiple transactions are submitted by the merchant separately based on an agreement between the merchant and the cardholder. INSTALLMENTS – For when a single transaction is divided into multiple charges. ADDCARD – For when a cardholder adds their card to be used for future transactions. MAINTAINCARD – For when a merchant wants to verify that an existing card is still valid. ACCOUNTVERIFICATION – For a verification different than those listed above.
userTokenId ^String(255) %%Conditional	This ID uniquely identifies your consumer/user in your system. It is REQUIRED only if you wish to use the userPaymentOptionId parameter for future charging of this user without re-collecting the payment details. Press here for more information.
userDetails ^Class %%Conditional	For certain APMs, some parameters are REQUIRED, as detailed in the APM Payments table. firstName (String, 30) lastName (String, 40) address (String, 50) streetNumber (String, 20) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This represents the customer’s identification number in their respective country.
shippingAddress ^Class %%Conditional	For certain APMs, some parameters are REQUIRED, as detailed in the APM Payments table. salutation (String, 20) – Examples: Mr and Mrs firstName (String, 30) lastName (String, 40) address (String, 50) cell (String, 18) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (100) county (String, 255) addressLine2 (String, 50) addressLine3 (String, 50) streetNumber (String, 20) companyName (String, 255) careOf (String, 50)
isRebilling ^String(2) %%Conditional	When performing recurring/rebilling by sending /payment requests, you must include isRebilling to indicate the stage of the rebilling payment, using the following values: 0 – For the first rebilling payment. 1 – For all subsequent rebilling transactions. NOTES: • For the first rebilling payment:  ▫ Use any payment method under the paymentOption class.  ▫ If this is a 3DS transaction, then you must include rebillExpiry and rebillFrequency under the   v2AdditionalParams class (under the threeD class) in the first /payment request. • For subsequent rebilling payments:  ▫ Use only userPaymentOptionId under the paymentOption class.  ▫ Send relatedTransactionId – the transactionId from the original customer-initiated transaction.
companyDetails ^Class %%Conditional	Mastercard requires Acquirers to send this class to provide additional data for authorizing and clearing domestic transactions in France. taxId (String, 55) – The Tax ID of the merchant’s company.
recipientDetails ^Class %%Conditional	For AFTs, details of the person receiving the funds. Must be in Latin characters. firstName (String, 30) lastName (String, 40) NOTE: Press here for non-domestic AFT requirements.
serviceDueDate ^String(10) %%Conditional	Format is YYYY-MM-DD. REQUIRED for OTA merchants performing subscription transactions or providing a future service.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
clientUniqueId ^String(45) ^Optional	The unique transaction ID in the merchant system. It appears in a DMN as the merchant_unique_id parameter.
amountDetails ^Class ^Optional	NOTE: The items and amountDetails prices should be summed up according to each APMs requirement. NOTE: All prices must be in the same currency. totalShipping (String) totalHandling (String) totalDiscount (String) totalTax (String)
items ^Array ^Optional	An array describing the items in the purchase. NOTE: The items and amountDetails prices should be summed up according to each APMs requirement. NOTE: All prices must be in the same currency. name (String, 255, REQUIRED if items is used) – The name of the item. type (String, 50, REQUIRED if items is used) – The item type.  Possible values:  Discount, Physical, Shipping_fee, Digital, Gift_card, Store_credit, Surcharge, Sales_tax (only for US) price (String, 10, REQUIRED if items is used) – The net unit price of the item. quantity (String, 10, REQUIRED if items is used) – The quantity of an item. groupId (String, 50, REQUIRED only for certain APMs) – Category of the item (clothing, electronics, etc.). discount (String, 10, REQUIRED only for certain APMs) – The discount value of an item. discountRate (String, 10, REQUIRED only for certain APMs) – The discount percentage. shipping (String, 10, REQUIRED only for certain APMs) – The net price of shipping. shippingTax (String, 10, REQUIRED only for certain APMs) – The VAT amount of shipping. shippingTaxRate (String, 10, REQUIRED only for certain APMs) – The VAT percentage for shipping. tax (String, 10, REQUIRED only for certain APMs) – The VAT amount for an item. taxRate (String, 10, REQUIRED only for certain APMs) – The VAT percentage for an item. imageUrl (String, 610, REQUIRED only for certain APMs) – The URL of the image representing the item. productUrl (String, 610, REQUIRED only for certain APMs) – The URL of the item on the merchant site.
subMerchant ^Class ^Optional	countryCode (String, 2) – The 2-letter ISO country code of the PayFac’s submerchant. city (String, 20) – The city name of the PayFac’s submerchant. id (String, 15) – Represents the internal merchant’s ID, which is sent to the relevant card scheme. address (String, 48, CONDITIONAL) – The physical location where the transaction occurred, or the business location for virtual transactions. REQUIRED for PayFac-enabled transactions. state (String, 6, CONDITIONAL) – The ISO country subdivision code of the PayFac’s submerchant. REQUIRED for PayFac-enabled transactions. phone (String, 18) – The phone number of the PayFac’s submerchant that can be used for transaction inquiries. Recommended for PayFac-enabled transactions. Press here for more information.
dynamicDescriptor ^Class ^Optional	Special configuration is required for this class. For more information, please contact Nuvei’s Integration Support Team. merchantName (String, 25) – The merchant name, as is displayed for the transaction on the consumer’s card statement. For PayFac only, the maximum length of the parameter is 22, consisting of the following structure: XXX*<merchant name> where:  • XXX – The PayFac prefix, approved by Nuvei Underwriting Team.  Can be a length of 3, 7, 9, or 12.  • * – A fixed character.  • <merchant name> – Submerchant name.  Can be a length of 18, 14, 12, or 9, respectively. merchantPhone (String, 13) – The merchant contact information, as is displayed for the transaction on the consumer’s card statement. It can also be an email address.
isMoto ^String(1) ^Optional	Set this to “1” to mark the transaction as MOTO (mail order/telephone order). Leave null or “0” for regular transaction.
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response.
urlDetails ^Class ^Optional	With this class, a merchant can dynamically provide possible URLs to which the end user is redirected after a payment is made, as well as a dynamic URL for DMNs. successUrl (String, 1000) – The URL the customer is directed to after a successful transaction. failureUrl (String, 1000) – The URL the customer is directed to after an unsuccessful transaction. pendingUrl (String, 1000) – The URL the customer is directed to when the transaction response is pending. notificationUrl (String, 1000) – The URL to which DMNs are sent. Although DMN responses can be configured per merchant site, this parameter allows dynamically returning the DMN to the provided address per request. appReturnLink (String, 255) – The deep link used to return to the merchant native application (press here for an example). NOTE: This parameter is not supported for all cases. appUrl (String, 255) – Link to which the provider redirects the user at the end of the payment process (press here for an example). NOTE: This parameter is not supported for all cases.
transactionType ^String(45) ^Optional	The type of transaction: Sale, Auth, or PreAuth. Sale – Performs a regular payment request. Auth – Performs an authorization-only request. Press here for more information. PreAuth – Performs an authorization-only request (with a longer settlement period). Press here for more information.
isPartialApproval ^Boolean ^Optional	Describes a situation where the deposit was completed and processed with an amount lower than the requested amount due to a consumer’s lack of funds within the desired payment method. Partial approval is only supported by Nuvei acquiring. For partial approval to be available for the merchant, it should be configured by Nuvei’s Integration Support Team. Possible values: 1 – Allow partial approval 0 – Not allow partial approval
customSiteName ^String(50) ^Optional	The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name. Risk rules and traffic management rules are usually built based on this parameter value.
productId ^String(50) ^Optional	A free text parameter used to identify the product/service sold. If this parameter is not sent or is sent with an empty value, then it contains the concatenation of all item names up until the parameter maximum length. Risk rules and traffic management rules are usually built based on this parameter value.
customData ^String(255) ^Optional	Can be used to pass any type of information. If sent in request, then it is visible in Nuvei’s back office tool transaction reporting and is returned in response.
webMasterId ^String(255) ^Optional	An affiliate parameter that the merchant can send. This is used by Nuvei’s eCommerce plugins (Magento, Demandware) and by Nuvei REST API SDKs to send the plugin/SDK name and version so that Support is able to identify from where the transaction arrived at the REST API Gateway.
orderId ^String(45) ^Optional	The order ID provided by Nuvei. This parameter is passed to define which merchant order to update.
addendums ^Class ^Optional	Contains industry specific addendums. The addendum parameters that appear are based on the specific addendum type. See addendums Class for more information.
currencyConversion ^Class ^Optional	type (String, 10) – Indicates the currency conversion type.  Possible values: MCP, DCC originalAmount (String, 12) – The original amount of the transaction in the currency that the merchant requested. originalCurrency (String, 3) – The 3-letter ISO currency code of the currency that the merchant requested in the transaction.
paymentFlow ^String(10) ^Optional	Indicates the payment flow the merchant would like to follow. direct – The regular 3DS flow. redirect – An alternative 3DS payment flow that is managed by Web SDK.
redirectFlowUITheme ^String(50) ^Optional	The UI theme of the redirect page shown to the end user during the 3DS payment flow managed by Web SDK. Currently, only standard (default) is supported. It is only relevant for the redirect flow and is ignored if provided in the direct flow.
digitalAssetType ^String(1) %%Conditional	Visa code for type of digital asset. REQUIRED for Visa Ramp Providers. Currently supported with the following values: 0 – Default. 1 – Purchase of Central Bank Digital Currency (CBDC) or Tokenized Deposits. 2 – Purchase of Stablecoin (Fiat-backed). 3 – Purchase of Blockchain Native Token/Coin. 4 – Purchase of Non-Fungible Token (NFT).

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
status ^String(20)	The cashier status of a merchant request. Possible values: SUCCESS, ERROR
transactionStatus ^String(20)	The Gateway transaction status. Possible values: APPROVED – The transaction was authorized and approved. DECLINED – The transaction authorization failed. ERROR – An error occurred. Please refer to Response Handling for details. REDIRECT – The transaction was not completed. The end user needs to be redirected to a webpage to complete the transaction.  There are two cases in which this response is returned:  • 3DS – The user needs to be redirected to paymentOption.threeD.acsUrl.  Press here for more information.  • An APM method that requires redirection – The URL is on paymentOption.redirectURL.  Press here for more information.
partialApproval ^Class	Partial approval is when the deposit completes with a processed amount lower than the requested amount due to a lack of sufficient funds in the consumer payment method. requestedAmount (String, 12) – The original requested amount. requestedCurrency (String, 3) – The currency of the original request. processedAmount (String, 12) – The amount that was actually deposited in the transaction. processedCurrency (String, 3) – The currency used in the processed transaction request.
paymentOption ^Class	Represents the data retrieved from the processed payment method. It can be either card, redirectUrl (in the case of an APM), or userPaymentOptionId. • card (Class) – Information about the card that was processed:  ▫ bin (String) – The BIN number representing the issuer.  ▫ last4Digits (String) – The last four digits of the card number.  ▫ ccCardNumber (String) – The credit card number in a mask (for example: ***1111).  ▫ ccExpMonth (String) – The expiration month.  ▫ ccExpYear (String) – The expiration year.  ▫ cvv2Reply (String) – The CVV2 (card verification value) response.   Possible values:   ▪ M – CVV2 Match   ▪ N – CVV2 No Match   ▪ P – Not Processed. For EU card-on-file (COF) and ecommerce (ECOM) network token transactions, Visa removes any CVV and sends P. If you have fraud or security concerns, Visa recommends using 3DS.   ▪ U – Issuer is not certified and/or has not provided Visa the encryption keys   ▪ S – CVV2 processor is unavailable.  ▫ avsCode (String) – The address verification service (AVS) response.   Possible values:   ▪ A – The street address matches, the ZIP code does not.   ▪ W – Postal code matches, the street address does not.   ▪ Y – Postal code and the street address match.   ▪ X – An exact match of both the 9-digit ZIP code and the street address.   ▪ Z – Postal code matches, the street code does not.   ▪ U – Issuer is unavailable.   ▪ S – AVS not supported by issuer.   ▪ R – Retry.   ▪ B – Not authorized (declined).   ▪ N – Both the street address and postal code do not match.  ▫ acquirerId (String) – The ID of the acquirer that processed the transaction.  ▫ cardType (String) – The type of card used in the transaction.   Possible values: Credit, Debit  ▫ cardBrand (String) – The card brand used in the transaction.   Possible values: VISA, MASTERCARD, AMEX  ▫ threeD (class) – Contains the required 3DS information. Refer to threeD Output Class for details. OR • redirectUrl (String) – For an APM, the URL to which the customer is redirected in order to complete the transaction process. OR • userPaymentOptionId (String) – In addition to the above, this parameter represents the ID for the newly created payment option, which can be referenced in future requests. For full details, refer to Card-on-File.
merchantDetails ^Class	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response.
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, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwErrorCode ^Integer(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^Integer(11)	The error code if an error occurred on the bank’s side. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
version ^String(10)	The current version of the API method. The current version is 1.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
transactionId ^String(20)	The Gateway transaction ID.
authCode ^String(128)	The authorization code of the transaction.
transactionType ^String(45)	The type of transaction: Sale or Auth. Sale – Performs a regular payment request. Auth – Performs an authorization only request. Press here for more information.
customData ^String(255)	Can be used to pass any type of information. If sent in the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back office tool for transaction reporting and is returned in the response.
fraudDetails ^Class	finalDecision (String) score (decimal) recommendations (String) system (Array) [systemId (String), systemName (String), decision (String)] rules (Array) [ruleId (String), ruleDescription (String)] score refers to a number between 0 and 1 that indicates the probability of a transaction becoming fraudulent, which is calculated using a risk machine learning model. system refers to which risk management system provided the fraud information. The provider can be Nuvei (systemId=1) or an external provider. rules refers to the risk management system rules triggered by the transaction. decision refers to the risk management system decisions regarding the rules that were triggered by the transaction. There are five possible values for the decision parameter: • Accept – The risk management system accepts the transactions. • Reject – The risk management system rejects the transaction. The transaction is not passed to bank for authorization. The reasons are returned in ruleDescription parameter. • Review – The risk management system flags a transaction for review, but still accepts the transaction. • Error – An error occurred during the risk management system operation. The Gateway continues to process the transaction through the bank. • None – No risk analysis was performed. The Gateway continues to process the transaction through the bank. finalDecision refers to when deciding whether to accept or reject a transaction. The risk management system bases its finalDecision on individual decisions made regarding rules triggered. If none of the rules leads to a Reject decision, the finalDecision accepts the transaction. If at least one of the rules leads to a Reject decision, the finalDecision rejects the transaction. To receive this information in the response, special configurations are required. For more information, please contact Nuvei’s Integration Support Team.
orderId ^String(20)	The ID returned from the merchantOrderID input parameter in update and payment methods. This parameter is returned to define which merchant order to update.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
paymentAccountReference ^String(50)	A unique identifier associated with a specific cardholder PAN, which can be used in place of sensitive consumer identification parameters. If the PaymentAccountReference value is returned in the response (depending on the card scheme decision), then this value is also returned to the merchant.
additionalTransactionBankId ^String(250)	Indicates the APM Reference ID of the transaction. NOTE: This parameter is relevant only for certain APMs.
isAFT ^String	Indicates whether the transaction was processed as a Sale transaction or as an AFT. Possible values: True – Transaction was processed as an AFT. False – Transaction was processed as a Sale transaction.
isAFTOverridden ^String	Possible values: True – Merchant can submit Sales and AFT transactions. False – Merchant can only submit AFT transactions.
merchantAdviceCode ^String	Guides Mastercard merchants on how to proceed after an authorization request is declined. Press here for possible values.
processedBrand ^String(50)	The brand with which the transaction was processed.
cardHolderNameVerification ^Class	Indicates the result of the cardholder name verification request. nameVerificationRequestResult (String)  Possible values:  NameVerificationPerformed  NameVerificationNotPerformed  NameVerificationNotSupported nameVerificationResult (String, 50) firstNameVerificationResult (String, 50) middleNameVerificationResult (String, 50) lastNameVerificationResult (String, 50)  Possible values for each of the four parameters above:  Match  PartialMatch  NoMatch  Unverified Press here for more information.

/settleTransaction

Endpoint URL

1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "clientUniqueId": "12345",
    "amount": "200",
    "currency": "USD",
    "relatedTransactionId": "<transactionId returned from /payment>",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
2
3
4
5
6
7
8
9
10
//Initialize the SDK (see https://docs.nuvei.com/?p=53443#initializing-the-sdk)

safecharge.paymentService.settleTransaction({
    clientUniqueId: "12345",
    amount: "200",
    currency: "USD",
    relatedTransactionId: "<transactionId returned from /payment>",
}, function (stlErr, stlRes) {
    console.log(stlErr, stlRes);
});

1
2
3
4
5
6
7
8
9
10
11
12
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    String clientUniqueId = "12345";
    String clientRequestId = "1C6CT7V1L";
    String currency = "USD";
    String amount = "200";
    String relatedTransactionId = "<transactionId returned from /payment>";

    Safecharge safecharge = new Safecharge();
    SafechargeResponse response = safecharge.settleTransaction(clientUniqueId, null, null, null, null, null, amount, null, null, null, currency, null, null, relatedTransactionId, null);
}

1
2
3
4
5
6
7
8
9
10
11
12
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
//settleTransaction
$settleResponse = $safeCharge->getPaymentService()->settleTransaction([
    "clientUniqueId"          => "12345",
    "clientRequestId"         => "1C6CT7V1L",
    "amount"                  => "200",
    "currency"                => "USD",
    "relatedTransactionId"    => "<transactionId returned from /payment>",
]);
?>

1
2
3
4
5
6
7
8
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.SettleTransaction(
    "USD",
    "200",
    relatedTransactionId: "<transactionId returned from /payment>",
    clientRequestId: "1C6CT7V1L",
    clientUniqueId: "12345");

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "internalRequestId": 45,
    "transactionId": "8498764859",
    "externalTransactionId": "",
    "status": "SUCCESS",
    "isAFT": "True",
    "transactionStatus": "APPROVED",
    "errCode": 0,
    "reason": "",
    "paymentMethodErrorCode": 0,
    "paymentMethodErrorReason": "",
    "gwErrorCode": 0,
    "gwErrorReason": "",
    "gwExtendedErrorCode": 0,
    "customData": "",
    "version": "1"
}

The /settleTransaction method is used for settling an authorization transaction that was previously performed with a two-phase Auth-Settle process, for either full or partial settlements. When partial settlements are issued, multiple settlement requests can be performed for up to the entire amount of the original authorized transaction.

Press here for more information on settling transactions.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(128) ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in a DMN as the merchant_unique_id parameter.
amount ^Decimal(12) ~Required	The transaction amount.
currency ^String(3) ~Required	The 3-letter ISO currency code. It is required to send the same currency as the one sent before for the related transaction.
relatedTransactionId ^String(19) ~Required	The transactionId from the response to the original Auth transaction to be settled.
timeStamp ^String(14) ~Required	The local time (in 24-hour format) when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the input parameters, which must be concatenated in the following order: merchantId, merchantSiteId, clientRequestId, clientUniqueId, amount, currency, relatedTransactionId, authCode, comment, urlDetails, timeStamp, merchantSecretKey. Press here to see an example. NOTE: clientRequestId, authCode, comment, and urlDetails are optional and do not need to be included in the concatenation.
shippingTrackingDetails ^Class %%Conditional	REQUIRED only for certain APMs. shippingCarrierName (String, 200, REQUIRED) – Name of carrier that performs the shipping. trackingId (String, 100, REQUIRED) – Used to track the order with the shipping company/merchant. trackingUrl (String, 2083, REQUIRED) – URL to track the order. addressType (String, 45) – Type of delivery address. shippingType (String, 45) – Type of shipping  Possible values: Shipment, Return
subMerchant ^Class ^Optional	countryCode (String, 2) – The 2-letter ISO country code of the PayFac’s submerchant. city (String, 20) – The city name of the PayFac’s submerchant. id (String, 15) – Represents the internal merchant’s ID, which is sent to the relevant card scheme. address (String, 48, CONDITIONAL) – The physical location where the transaction occurred, or the business location for virtual transactions. REQUIRED for PayFac-enabled transactions. state (String, 6, CONDITIONAL) – The ISO country subdivision code of the PayFac’s submerchant. REQUIRED for PayFac-enabled transactions. phone (String, 18) – The phone number of the PayFac’s submerchant that can be used for transaction inquiries. Recommended for PayFac-enabled transactions. Press here for more information.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
authCode ^String(128) ^Optional	The authorization code of the original Auth transaction to be settled.
comment ^String(255) ^Optional	Enables the addition of a free text comment to the request.
urlDetails ^Class ^Optional	notificationUrl (String, 1000) – The URL to which DMNs are sent.
addendums ^Class ^Optional	Contains industry specific addendums. For /settleTransaction, only airlines and l23processingData are relevant.
customSiteName ^String(50) ^Optional	The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
productId ^String(50) ^Optional	A free text parameter used to identify the product/service sold. If this parameter is not sent or is sent with an empty value, then it contains the concatenation of all item names up until parameter maximum length.
customData ^String(255) ^Optional	Can be used to pass any type of information. If sent in request, then it is visible in Nuvei’s back office tool transaction reporting and is returned in response.
webMasterId ^String(255) ^Optional	An affiliate parameter that the merchant can send. This is used by Nuvei’s eCommerce plugins (Magento, Demandware) and by Nuvei REST API SDKs to send the plugin/SDK name and version so that Support is able to identify from where the transaction arrived at the REST API Gateway.
totalSettleCount ^String(12) ^Optional	The number of settlements the merchant wishes to perform in the /settleTransaction method. Press here for more information. Possible values: 1 or null – Indicates that the transaction is not a split settlement (normal flow). >1 (integer only) – Indicates the number of settlements into which the transaction is split. NOTE: This feature is relevant only for merchants with an American merchantId that works via a TSYS bank as an acquirer.

Deprecated Input Parameters

PARAMETER	DESCRIPTION
descriptorMerchantName ^String(25) ^Optional	Allows the merchant to define a dynamic descriptor, which appears in the payment statement. The name parameter should contain the merchant name. For dynamic descriptor, special configuration is required. For more information, please contact Nuvei’s Integration Support Team.
descriptorMerchantPhone ^String(13) ^Optional	Allows the merchant to define a dynamic descriptor, which appears in the payment statement. The phone parameter should contain either customer support phone number or support email address or merchant URL for Card Not Present requests and the city in which the terminal is located for Card Present/Point of Sale requests. For dynamic descriptor, special configuration is required. For more information, please contact Nuvei’s Integration Support Team.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
transactionId ^String(20)	The transaction ID of the settle transaction for future actions.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
status ^String(20)	The status of merchant’s API request/call. Possible values: SUCCESS, ERROR.
transactionStatus ^String(20)	The Gateway transaction status. Possible values: APPROVED, DECLINED, ERROR
authCode ^String(128)	Authorization code of the transaction.
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, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
paymentMethodErrorCode ^Integer(11)	If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason ^String(400)	If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode ^Integer(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^Integer(11)	Error code if error occurred on the bank’s side. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
customData ^String(255)	Can be used to pass any type of information. If sent in the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back office tool for transaction reporting and is returned in the response.
version ^String(10)	The current version of the API method. The current version is 1.
clientRequestId ^String(255)	The client’s Request ID as defined by the merchant for record-keeping.
isAFT ^String	Indicates whether the transaction was processed as a Sale transaction or as an AFT. Possible values: True – Transaction was processed as an AFT. False – Transaction was processed as a Sale transaction.

/refundTransaction

Endpoint URL

1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "clientUniqueId": "12345",
    "amount": "200",
    "currency": "USD",
    "relatedTransactionId": "2110000000001208909",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
2
3
4
5
6
7
8
9
10
11
//Initialize the SDK (see https://docs.nuvei.com/?p=53443#initializing-the-sdk)

safecharge.paymentService.refundTransaction({
    clientRequestId: "1C6CT7V1L",
    clientUniqueId: "12345",
    amount: "200",
    currency: "USD",
    relatedTransactionId: "2110000000001208909",
}, function (stlErr, stlRes, reqData) {
    console.log(stlErr, stlRes);
});

1
2
3
4
5
6
7
8
9
10
11
12
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
//refundTransaction
$refundResponse = $safeCharge->getPaymentService()->refundTransaction([
    "clientUniqueId"          => "12345",
    "clientRequestId"         => "1C6CT7V1L",
    "amount"                  => "200",
    "currency"                => "USD",
    "relatedTransactionId"    => "2110000000001208909",
]);
?>

1
2
3
4
5
6
7
8
9
10
11
12
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    String clientUniqueId = "12345";
    String clientRequestId = "1C6CT7V1L";
    String currency = "USD";
    String amount = "200";
    String relatedTransactionId = "2110000000001208909";

    Safecharge safecharge = new Safecharge();
    SafechargeResponse response = safecharge.refundTransaction(clientUniqueId, clientRequestId, null, amount, null, null, currency, null, null, null, relatedTransactionId, null);
}

1
2
3
4
5
6
7
8
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.RefundTransaction(
    "US",
    "200",
    relatedTransactionId: "<transactionId returned from /payment>",
    clientRequestId: "1C6CT7V1L",
    clientUniqueId: "12345");

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "internalRequestId": 45,
    "transactionId": "8498764859",
    "externalTransactionId": "",
    "status": "SUCCESS",
    "isAFT": "True",
    "transactionStatus": "APPROVED",
    "authCode": "8378749",
    "errCode": 0,
    "errReason": "",
    "paymentMethodErrorCode": 0,
    "paymentMethodErrorReason": "",
    "gwErrorCode": 0,
    "gwErrorReason": "",
    "gwExtendedErrorCode": 0,
    "customData": "",
    "version": "1",
    "merchantAdviceCode": "02"
}

The /refundTransaction method is used for refunding a previously settled transaction either in full or partially.

When partial refunds are issued, multiple refund requests can be performed for up to the entire amount of the original settled transaction.

Press here for more information on refunding transactions.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	Merchant Site ID provided by Nuvei.
clientUniqueId ^String(64) ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in a DMN as the merchant_unique_id parameter.
amount ^Decimal(12) ~Required	The transaction amount.
currency ^String(3) ~Required	The 3-letter ISO currency code. It is required to send the same currency as the one sent before for the related transaction.
relatedTransactionId ^String(19) ~Required	The transactionId from the response to the original Settle or Sale transaction.
timeStamp ^String(14) ~Required	The local time (in 24-hour format) when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the input parameters, which must be concatenated in the following order: merchantId, merchantSiteId, clientRequestId, clientUniqueId, amount, currency, relatedTransactionId, authCode, comment, urlDetails, timeStamp, merchantSecretKey. Press here to see an example. NOTE: clientRequestId, authCode, comment, and urlDetails are optional and do not need to be included in the concatenation.
subMerchant ^Class ^Optional	countryCode (String, 2) – The 2-letter ISO country code of the PayFac’s submerchant. city (String, 20) – The city name of the PayFac’s submerchant. id (String, 15) – Represents the internal merchant’s ID, which is sent to the relevant card scheme. address (String, 48, CONDITIONAL) – The physical location where the transaction occurred, or the business location for virtual transactions. REQUIRED for PayFac-enabled transactions. state (String, 6, CONDITIONAL) – The ISO country subdivision code of the PayFac’s submerchant. REQUIRED for PayFac-enabled transactions. phone (String, 18) – The phone number of the PayFac’s submerchant that can be used for transaction inquiries. Recommended for PayFac-enabled transactions. Press here for more information.
isMoto ^String(1) ^Optional	Set this to “1” to mark the transaction as MOTO (mail order/telephone order). Leave null or “0” for regular transaction.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
authCode ^String(128) ^Optional	The authorization code of the related Settle or Sale transaction, to be compared to the original one.
comment ^String(255) ^Optional	Enables the addition of a free text comment to the request.
urlDetails ^Class ^Optional	notificationUrl (String, 1000) – The URL to which DMNs are sent.
customSiteName ^String(50) ^Optional	The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
productId ^String(50) ^Optional	A free text parameter used to identify the product/service sold. If this parameter is not sent or is sent with empty value, then it contains the concatenation of all item names up until parameter maximum length.
customData ^String(255) ^Optional	Can be used to pass any type of information. If sent in request, then it is visible in Nuvei’s back office tool transaction reporting and is returned in response.
webMasterId ^String(255) ^Optional	An affiliate parameter that the merchant can send. This is used by Nuvei’s eCommerce plugins (Magento, Demandware) and by Nuvei REST API SDKs to send the plugin/SDK name and version so that Support is able to identify from where the transaction arrived at the REST API Gateway.
digitalAssetType ^String(1) %%Conditional	Visa code for type of digital asset. REQUIRED for Visa Ramp Providers. Currently supported with the following values: 0 – Default. 1 – Purchase of Central Bank Digital Currency (CBDC) or Tokenized Deposits. 2 – Purchase of Stablecoin (Fiat-backed). 3 – Purchase of Blockchain Native Token/Coin. 4 – Purchase of Non-Fungible Token (NFT).

Unreferenced Refund Input Parameters

Press here for more information on unreferenced refunds.

PARAMETER	DESCRIPTION
paymentOption ^Class %%Conditional	The option used to send the payment details. REQUIRED for an unreferenced refund when relatedTransactionId is not provided. Choose from the following options: If you wish to collect the card details: card (Class) – Represents a credit/debit card.  • cardNumber (String, 20, REQUIRED) – The card number.  • cardHolderName (String, 70, REQUIRED) – The cardholder name.  • expirationMonth (String, 2, REQUIRED) – The card expiration month.  • expirationYear (String, 4, REQUIRED) – The card expiration year.  • CVV (String, 4, REQUIRED) – The CVV/CVC security code.  • selectedBrand (String, 128) – The brand selected by the consumer for the transaction processing.  • externalToken (Class) – When the merchant provides a network token, include this class in the request.   networkTokenNumber (String, 20) – Alternative to the Primary Account Number (PAN) and unique to each shopper-merchant pairing.   tokenAssuranceLevel (String, 2) – Value indicating the confidence level of the token-to-Account-PAN binding.   tokenRequestorId (String, 11) – Identifies the token requestor. If you are handling a returning user and want to use a previously saved user payment option: userPaymentOptionId (String) – Identifies a payment option that has already been used by the customer and now it is requested for re-use. Nuvei keeps payment option details from a previous use.
userTokenId ^String(255) %%Conditional	This ID uniquely identifies your consumer/user in your system. It is REQUIRED only if you wish to use the userPaymentOptionId option in the paymentOption class for an unreferenced refund.
companyDetails ^Class %%Conditional	Mastercard requires Acquirers to send this class to provide additional data for authorizing and clearing domestic transactions in France. NOTE: This is relevant only for unreferenced refunds. taxId (String, 55) – The Tax ID of the merchant’s company.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
transactionId ^String(20)	The transaction ID of the refund transaction for future actions.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
status ^String(20)	The status of merchant’s API request/call. Possible values: SUCCESS, ERROR, PENDING.
transactionStatus ^String(20)	The Gateway transaction status. Possible values: APPROVED, DECLINED, ERROR
authCode ^String(128)	Authorization code of the transaction.
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, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
paymentMethodErrorCode ^Integer(11)	If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason ^String(400)	If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode ^Integer(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^Integer(11)	Error code if error occurred on the bank’s side. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
customData ^String(255)	Can be used to pass any type of information. If sent in the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back office tool for transaction reporting and is returned in the response.
version ^String(10)	The current version of the API method. The current version is 1.
clientRequestId ^String(255)	The client’s Request ID as defined by the merchant for record-keeping.
userPaymentOptionId ^String(45)	Is returned only for an unreferenced refund.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system. Is returned only for an unreferenced refund.
isAFT ^String	Indicates whether the transaction was processed as a Sale transaction or as an AFT. Possible values: True – Transaction was processed as an AFT. False – Transaction was processed as a Sale transaction.
merchantAdviceCode ^String	Guides Mastercard merchants on how to proceed after an authorization request is declined. Press here for possible values.
processedBrand ^String(50)	The brand with which the transaction was processed.

/voidTransaction

Endpoint URL

1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "clientUniqueId": "12345",
    "amount": "200",
    "currency": "USD",
    "relatedTransactionId": "2110000000001208909",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
2
3
4
5
6
7
8
9
10
11
12
//Initialize the SDK (see https://docs.nuvei.com/?p=53443#initializing-the-sdk)

safecharge.paymentService.voidTransaction({
    clientRequestId: "1C6CT7V1L",
    clientUniqueId: "12345",
    amount: "200",
    currency: "USD",
    relatedTransactionId: "2110000000001208909",
}, function (stlErr, stlRes, reqData) {
    console.log(stlErr, stlRes);

});

1
2
3
4
5
6
7
8
9
10
11
12
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
//voidTransaction
$voidResponse = $safeCharge->getPaymentService()->voidTransaction([
    "clientUniqueId"          => "12345",
    "clientRequestId"         => "1C6CT7V1L",
    "amount"                  => "200",
    "currency"                => "USD",
    "relatedTransactionId"    => "2110000000001208909",
]);
?>

1
2
3
4
5
6
7
8
9
10
11
12
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    String clientUniqueId = "12345";
    String clientRequestId = "1C6CT7V1L";
    String currency = "USD";
    String amount = "200";
    String relatedTransactionId = "2110000000001208909";

    Safecharge safecharge = new Safecharge();
    SafechargeResponse response = safecharge.voidTransaction(clientRequestId, relatedTransactionId, amount, currency, null, clientUniqueId, null, null, null, null, null, null);
}

1
2
3
4
5
6
7
8
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.VoidTransaction(
    "US",
    "200",
    relatedTransactionId: "<transactionId returned from /payment>",
    clientRequestId: "1C6CT7V1L",
    clientUniqueId: "12345");

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "internalRequestId": 45,
    "transactionId": "8498764859",
    "externalTransactionId": "",
    "status": "SUCCESS",
    "transactionStatus": "APPROVED",
    "authCode": "8378749",
    "errCode": 0,
    "errReason": "",
    "paymentMethodErrorCode": 0,
    "paymentMethodErrorReason": "",
    "gwErrorCode": 0,
    "gwErrorReason": "",
    "gwExtendedErrorCode": 0,
    "customData": "",
    "version": "1"
}

Use this method to void a previous payment.

Press here for more information on voiding transactions.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(128) ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in a DMN as the merchant_unique_id parameter.
relatedTransactionId ^String(19) ~Required	The transactionId from the response to the original transaction.
timeStamp ^String(14) ~Required	The local time (in 24-hour format) when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the input parameters, which must be concatenated in the following order: merchantId, merchantSiteId, clientRequestId, clientUniqueId, amount, currency, relatedTransactionId, authCode, comment, urlDetails, timeStamp, merchantSecretKey. Press here to see an example. NOTE: clientRequestId, authCode, comment, and urlDetails are optional and do not need to be included in the concatenation.
amount ^Decimal(12) ^Optional	The transaction amount. NOTE: If the amount is provided, it must be equal to the amount sent in the related transaction that this void aims to cancel. NOTE: This parameter is supported for backwards compatibility.
currency ^String(3) ^Optional	The 3-letter ISO currency code. NOTE: If the currency is provided, it must be the same currency as the one sent previously for the related transaction. NOTE: This parameter is supported for backwards compatibility.
digitalAssetType ^String(1) %%Conditional	Visa code for type of digital asset. REQUIRED for Visa Ramp Providers. Currently supported with the following values: 0 – Default. 1 – Purchase of Central Bank Digital Currency (CBDC) or Tokenized Deposits. 2 – Purchase of Stablecoin (Fiat-backed). 3 – Purchase of Blockchain Native Token/Coin. 4 – Purchase of Non-Fungible Token (NFT).
subMerchant ^Class ^Optional	countryCode (String, 2) – The 2-letter ISO country code of the PayFac’s submerchant. city (String, 20) – The city name of the PayFac’s submerchant. id (String, 15) – Represents the internal merchant’s ID, which is sent to the relevant card scheme. address (String, 48, CONDITIONAL) – The physical location where the transaction occurred, or the business location for virtual transactions. REQUIRED for PayFac-enabled transactions. state (String, 6, CONDITIONAL) – The ISO country subdivision code of the PayFac’s submerchant. REQUIRED for PayFac-enabled transactions. phone (String, 18) – The phone number of the PayFac’s submerchant that can be used for transaction inquiries. Recommended for PayFac-enabled transactions. Press here for more information.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
authCode ^String(128) ^Optional	The authorization code of the related transaction, to be compared to the original one.
comment ^String(255) ^Optional	Enables the addition of a free text comment to the request.
urlDetails ^Class ^Optional	notificationUrl (String, 1000) – The URL to which DMNs are sent.
customSiteName ^String(50) ^Optional	The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
productId ^String(50) ^Optional	A free text parameter used to identify the product/service sold. If this parameter is not sent or is sent with an empty value, then it contains the concatenation of all item names up until parameter maximum length.
customData ^String(255) ^Optional	Can be used to pass any type of information. If sent in request, then it is visible in Nuvei’s back office tool transaction reporting and is returned in response.
webMasterId ^String(255) ^Optional	An affiliate parameter that the merchant can send. This is used by Nuvei’s eCommerce plugins (Magento, Demandware) and by Nuvei REST API SDKs to send the plugin/SDK name and version so that Support is able to identify from where the transaction arrived at the REST API Gateway.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
transactionId ^String(255)	The transaction ID of the void transaction for future actions.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
status ^String(20)	The status of merchant’s API request/call. Possible values: SUCCESS, ERROR.
transactionStatus ^String(20)	The Gateway transaction status. Possible values: APPROVED, DECLINED, ERROR
authCode ^String(128)	Authorization code of the transaction.
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, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
paymentMethodErrorCode ^Integer(11)	If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason ^String(400)	If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode ^Integer(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^Integer(11)	Error code if error occurred on the bank’s side. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
customData ^String(255)	Can be used to pass any type of information. If sent in the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back office tool for transaction reporting and is returned in the response.
version ^String(10)	The current version of the API method. The current version is 1.
clientRequestId ^String(255)	The unique ID of the API request in the merchant system.

/payout

Endpoint URL

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientRequestId": "1C6CT7V1L",
    "clientUniqueId": "12345",
    "amount": "200",
    "currency": "USD",
    "userPaymentOption": {
        "userPaymentOptionId": "1459503"
    },
    "deviceDetails": { 
        "ipAddress": "192.168.2.38"
    },
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
//Initialize the SDK (see https://docs.nuvei.com/?p=53443#initializing-the-sdk)

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/payout.do', // the method's endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    String userTokenId = "230811147";
    String clientUniqueId = "12345";
    String clientRequestId = "1C6CT7V1L";
    String currency = "USD";
    String amount = "200";

    UserPaymentOption upo = new UserPaymentOption();
    upo.setUserPaymentOptionId("id");

    UserDetails userDetails = new UserDetails();
    userDetails.setCity("city");
    userDetails.setCountry("country");

    Safecharge safecharge = new Safecharge();
    SafechargeResponse response = safecharge.payout(userTokenId, clientUniqueId, clientRequestId, amount, currency, upo, null,
    null, null, null, null, null, null, userDetails);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
$payoutRequest = $SafeCharge->getPayoutService()->payout([
    "userTokenId" => "230811147",
    "clientRequestId" => "1C6CT7V1L",
    "clientUniqueId" => "12345",
    "amount" => "200",
    "currency" => "USD",
    "userPaymentOption" => [
        "userPaymentOptionId" => 1459503
    ],
    "deviceDetails"     => [
        "ipAddress"  => "192.168.2.38"
    ],
    "merchantId" => "427583496191624621",
    "merchantSiteId" => "142033",
    "timeStamp" => "20240915143321",
    "checksum" => "1cff28783432713e5dfc4fdc8f011b76"
]);
?>

1
2
3
4
5
6
7
8
9
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.Payout(
    "230811147",
    "12345",
    "200",
    "USD",
    new UserPaymentOption { UserPaymentOptionId = "1459503" },
    deviceDetails: new DeviceDetails { IpAddress = "192.168.2.38" });

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": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
    "internalRequestId": 866,
    "transactionId": "8498764859",
    "externalTransactionId": "",
    "status": "SUCCESS",
    "transactionStatus": "APPROVED",
    "merchantDetails": {
        "customField1": ""
    },
    "userPaymentOptionId": "12442",
    "errCode": 0,
    "reason": "",
    "paymentMethodErrorCode": 0,
    "paymentMethodErrorReason": "",
    "gwErrorCode": 0,
    "gwErrorReason": "",
    "gwExtendedErrorCode": 0,
    "version": "1",
    "merchantAdviceCode": "02"
}

The /payout method allows performing a payout (a transfer of funds from the merchant to the consumer) with no connection to a previous transaction.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system. This must be sent when using the User Payment Management feature.
clientUniqueId ^String(45) ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in a DMN as the merchant_unique_id parameter.
amount ^String(12) ~Required	The transaction amount.
currency ^String(3) ~Required	The 3-letter ISO currency code.
timeStamp ^String(14) ~Required	The local time (in 24-hour format) when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the input parameters, which must be concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey. Press here to see an example. NOTE: clientRequestId is optional and does not need to be included in the concatenation.
deviceDetails ^Class ~ipAddress Required	ipAddress (String, 15, REQUIRED) deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255)
userPaymentOption ^Class %%Conditional	REQUIRED if cardData and externalToken are not provided. userPaymentOptionId (String, 45) The first time a consumer uses a payment method, Nuvei assigns a unique ID to it. The next time the consumer uses this payment method, the assigned ID is returned as the value of this parameter.
cardData ^Class %%Conditional	REQUIRED if userPaymentOptionId is not provided. NOTE: A merchant has to be PCI certified to use this class, as it uses clear text card numbers. NOTE: When sending cardData, you still must also send userTokenId. Relevant when: • Processing a new card (without UPO).  cardNumber (String, 20, REQUIRED)  cardHolderName (String, 70, REQUIRED)  expirationMonth (String, 2, REQUIRED)  expirationYear (String, 4, REQUIRED)  CVV (String, 4)  For an example, press here. OR • Processing with a network token.  expirationMonth (String, 2, REQUIRED) – The token’s expiration month.  expirationYear (String, 4, REQUIRED) – The token’s expiration year.  For an example, press here.
externalToken ^Class %%Conditional	REQUIRED if userPaymentOption is not provided. Relevant when: • Providing a network (card scheme) token.  networkTokenNumber (String, 20) – Alternative to the Primary Account Number (PAN) and unique to each shopper-merchant pairing.  tokenAssuranceLevel (String, 2) – Value indicating the confidence level of the token-to-Account-PAN binding.  tokenRequestorId (String, 11) – Identifies the token requestor.  For an example, press here. OR • When using an external token provider.  externalTokenProvider (String, 45) – The name of the external token provider (Apple Pay, Google Pay).
companyDetails ^Class %%Conditional	Mastercard requires Acquirers to send this class to provide additional data for authorizing and clearing domestic transactions in France. taxId (String, 55) – The Tax ID of the merchant’s company.
userDetails ^Class ^Optional	Press here for more information about using the userDetails class in a /payout call. firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (String, 100) birthdate (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This represents the customer’s identification number in their respective country.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
subMerchant ^Class ^Optional	countryCode (String, 2) – The 2-letter ISO country code of the PayFac’s submerchant. city (String, 20) – The city name of the PayFac’s submerchant. id (String, 15) – Represents the internal merchant’s ID, which is sent to the relevant card scheme. address (String, 48, CONDITIONAL) – The physical location where the transaction occurred, or the business location for virtual transactions. REQUIRED for PayFac-enabled transactions. state (String, 6, CONDITIONAL) – The ISO country subdivision code of the PayFac’s submerchant. REQUIRED for PayFac-enabled transactions. phone (String, 18) – The phone number of the PayFac’s submerchant that can be used for transaction inquiries. Recommended for PayFac-enabled transactions. Press here for more information.
dynamicDescriptor ^Class ^Optional	Special configuration is required for this class. For more information, please contact Nuvei’s Integration Support Team. merchantName (String, 25) – The merchant name, as is displayed for the transaction on the consumer’s card statement. For PayFac only, the maximum length of the parameter is 22, consisting of the following structure: XXX*<merchant name> where:  • XXX – The PayFac prefix, approved by Nuvei Underwriting Team.  Can be a length of 3, 7, 9, or 12.  • * – A fixed character.  • <merchant name> – Submerchant name.  Can be a length of 18, 14, 12, or 9, respectively. merchantPhone (String, 13) – The merchant contact information, as is displayed for the transaction on the consumer’s card statement. It can also be an email address.
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response.
cardData ^Class ^Optional	An alternative to sending the userPaymentOptionId for card payouts. A merchant has to be PCI certified to use this, as it uses clear text card numbers. NOTE: When sending cardData, you still must also send userTokenId. cardNumber (String, 20) cardHolderName (String, 70) expirationMonth (String, 2) expirationYear (String, 4)
currencyConversion ^Class ^Optional	NOTE: Currency conversion for payouts is only supported for credit cards. type (String, 10) – Indicates the currency conversion type.  Possible values: MCP originalAmount (String, 12) – The original amount of the transaction in the currency that the merchant requested. originalCurrency (String, 3) – The 3-letter ISO currency code of the currency that the merchant requested in the transaction.
customData ^String(255) ^Optional	Can be used to pass any type of information. If sent in request, then it is visible in Nuvei’s back office tool transaction reporting and is returned in response. NOTE: We now support this feature for credit card transactions and APMs transactions.
comment ^String(255) ^Optional	Enables the addition of a free text comment to the request.
urlDetails ^Class ^Optional	notificationUrl (String, 1000) – The URL to which DMNs are sent.
companyDetails ^Class %%Conditional	Mastercard requires Acquirers to send this class to provide additional data for authorizing and clearing domestic transactions in France. NOTE: This is relevant only for unreferenced refunds. taxId (String, 55) – The Tax ID of the merchant’s company.
digitalAssetType ^String(1) %%Conditional	Visa code for type of digital asset. REQUIRED for Visa Ramp Providers. Currently supported with the following values: 0 – Default. 1 – Purchase of Central Bank Digital Currency (CBDC) or Tokenized Deposits. 2 – Purchase of Stablecoin (Fiat-backed). 3 – Purchase of Blockchain Native Token/Coin. 4 – Purchase of Non-Fungible Token (NFT).

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
clientUniqueId ^String(45)	The unique transaction ID in the merchant system. It appears in DMN as merchant_unique_id parameter.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
transactionId ^String(20)	The Gateway transaction ID.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
status ^String(20)	The status of merchant’s API request/call. Possible values: SUCCESS, ERROR.
transactionStatus ^String(20)	The Gateway transaction status. Possible values: APPROVED, DECLINED, ERROR
merchantDetails ^Class	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response.
userPaymentOptionId ^String(45)	The first time a consumer uses a payment method, Nuvei assigns a unique ID to it and returns 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.
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, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
paymentMethodErrorCode ^Integer(11)	If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason ^String(400)	If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode ^Integer(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^Integer(11)	Error code if error occurred on the bank’s side. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
version ^String(10)	The current version of the API method. The current version is 1.
clientRequestId ^String(255)	The unique ID of the API request in the merchant system.
additionalTransactionBankId ^String(250)	Indicates the APM Reference ID of the transaction. NOTE: This parameter is relevant only for certain APMs.
merchantAdviceCode ^String	Guides Mastercard merchants on how to proceed after an authorization request is declined. Press here for possible values.

/p2pPayment

Endpoint URL

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
{
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "amount": "100",
    "currency": "USD",
    "clientUniqueId": "12345",
    "senderDetails":{
        "userTokenId": "230811147",
        "relatedTransactionId": "<transactionId returned from /payment>",
        "deviceDetails":{
            "ipAddress": "192.168.2.38"
        },
        "billingAddress":{
            "firstName": "John",
            "lastName": "Smith",
            "email": "[email protected]",
            "country": "US"
        },
        "paymentOption":{
            "card":{
                "cardNumber": "4000027891380961",
                "cardHolderName": "John Smith",
                "expirationMonth": "12",
                "expirationYear": "2030",
                "CVV": "217",
                "threeD":{
                    "browserDetails":{
                        "acceptHeader": "text/html,application/xhtml+xml",
                        "ip": "192.168.1.11",
                        "javaEnabled": "TRUE",
                        "javaScriptEnabled": "TRUE",
                        "language": "EN",
                        "colorDepth": "48",
                        "screenHeight": "400",
                        "screenWidth": "600",
                        "timeZone": "0",
                        "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)"
                    },
                    "account":{
                        "age": "05",
                        "lastChangeDate": "20240220",
                        "lastChangeInd": "04",
                        "registrationDate": "20240221",
                        "passwordChangeDate": "20240222",
                        "resetInd": "01",
                        "purchasesCount6M": "6",
                        "addCardAttempts24H": "24",
                        "transactionsCount24H": "23",
                        "transactionsCount1Y": "998",
                        "cardSavedDate": "20240223",
                        "cardSavedInd": "02",
                        "addressFirstUseDate": "20240224",
                        "addressFirstUseInd": "03",
                        "nameInd": "02",
                        "suspiciousActivityInd": "01"
                    },
                    "version": "2",
                    "notificationUrl": "<notificationURL>",
                    "merchantUrl": "<merchantURL>",
                    "platformType": "02",
                    "v2AdditionalParams":{
                        "challengeWindowSize": "05"
                    }
                }
            }
        }
    },
    "recipientDetails": {
        "userTokenId": "testUserToken",
        "firstName": "string",
        "lastName": "string",
        "paymentOption": {
            "card": {
                "cardNumber": "5333306956697229",
                "cardHolderName": "John Smith",
                "expirationMonth": "12",
                "expirationYear": "25",
                "CVV": "217"
            }
        }
    },
    "timeStamp": "20240623135114",
    "checksum": "5582d0189dd440f4bbf960569ec22e77"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
    "internalRequestId": 707872868,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "850502379161961074",
    "merchantSiteId": "229708",
    "version": "1.0",
    "clientRequestId": "20230702155935",
    "sessionToken": "2a321522-5515-45d2-8f06-d392663a310e",
    "orderId": "374448258",
    "operationStatus": "APPROVED",
    "senderDetails": {
        "payment": {
            "userTokenId": "<unique request ID in merchant system>",
            "paymentOption": {
                "userPaymentOptionId": "90422508",
                "card": {
                    "ccCardNumber": "4****1390",
                    "bin": "476134",
                    "last4Digits": "1390",
                    "ccExpMonth": "12",
                    "ccExpYear": "25",
                    "acquirerId": "19",
                    "cvv2Reply": "",
                    "avsCode": "",
                    "cardType": "Credit",
                    "cardBrand": "VISA",
                    "issuerBankName": "River Valley Credit Union",
                    "issuerCountry": "SG",
                    "isPrepaid": "false",
                    "threeD": {

                    }
                },
                "paymentAccountReference": "f4iK2pnudYKvTALGdcwEzqj9p4"
            },
            "transactionStatus": "APPROVED",
            "gwErrorCode": 0,
            "gwExtendedErrorCode": 0,
            "issuerDeclineCode": "",
            "issuerDeclineReason": "",
            "transactionType": "Sale",
            "transactionId": "711000000024399711",
            "externalTransactionId": "",
            "authCode": "111426",
            "customData": "",
            "fraudDetails": {
                "finalDecision": "Accept"
            },
            "externalSchemeTransactionId": ""
        }
    },
    "recipientPayoutDetails": {
        "userTokenId": "<unique request ID in merchant system>",
        "transactionStatus": "APPROVED",
        "gwErrorCode": 0,
        "gwExtendedErrorCode": 0,
        "userPaymentOptionId": "92210198",
        "externalTransactionId": "",
        "transactionId": "711000000024399712",
        "cardData": {
            "acquirerId": "19",
            "visaDirect": "NO"
        }
    }
}

The /p2pPayment method is your endpoint for transferring funds from a person to another person.

Supported payment flows:

• Regular card transactions (credit or debit cards)
• 3DS card transactions

Required Parameters

• Authentication credentials – sessionToken, merchantId, merchantSiteId, checksum, and timeStamp
• amount and currency
• ipAddress under the deviceDetails class
• firstName, lastName, country and email under the senderDetails.billingAddress class
• A payment option used by the person transferring funds and by the recipient receiving the funds. This is passed using the senderDetails.paymentOption and the recipientDetails.paymentOption classes, respectively.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The merchant ID provided by Nuvei (part of the authentication credentials).
merchantSiteId ^String(20) ~Required	The merchant site ID provided by Nuvei (part of the authentication credentials).
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
currency ^String(3) ~Required	The 3-letter ISO currency code.
amount ^String(12) ~Required	The transaction amount.
senderDetails ^Class ~Required	The details of the end user who is transferring funds to another person (P2P). userTokenId (String, 255, CONDITIONAL) – This ID uniquely identifies your consumer/user in your system. It is REQUIRED only if you wish to use the userPaymentOptionId parameter for future charging of this user without re-collecting the payment details. Press here for more information. paymentOption (Class) – The option used to send the payment details.  See the card and userPaymentOptionId options. deviceDetails (Class) – Press here for more information about this class. billingAddress (Class) – Press here for more information about this class. userDetails (Class) – Press here for more information about this class. relatedTransactionId (String, 19, CONDITIONAL)  REQUIRED in the following 3DS cases:  • The transaction ID from /initPayment on the first call.   Press here for more information.  • The transaction ID of the first Payment call of the clientUniqueIdsecond call.   Press here for more information.
timeStamp ^String(14) ~Required	The local time (in 24-hour format) when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the input parameters, which must be concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey. Press here to see an example. NOTE: clientRequestId is optional and does not need to be included in the concatenation.
recipientDetails ^Class %%Conditional	Details of the person receiving the funds. userTokenId (String, 255) – This ID uniquely identifies your consumer/user in your system. firstName (String, 30) – Must be in Latin characters. lastName (String, 40) – Must be in Latin characters. paymentOption (Class)  See userPaymentOptionId.  OR  card (Class) – Represents a credit/debit card.   cardNumber (String, 70) – The cardholder name.   expirationMonth (String, 2) – The card expiration month.   expirationYear (String, 4) – The card expiration year.   CVV (String, 4) – The CVV/CVC security code.
webMasterId ^String(255) ^Optional	An affiliate parameter that the merchant can send. This is used by Nuvei’s eCommerce plugins (Magento, Demandware) and by Nuvei REST API SDKs to send the plugin/SDK name and version so that Support is able to identify from where the transaction arrived at the REST API Gateway.
customData ^String(255) ^Optional	Can be used to pass any type of information. If sent in request, then it is visible in Nuvei’s back office tool transaction reporting and is returned in response.
urlDetails ^Class ^Optional	With this class, a merchant can dynamically provide possible URLs to which the end user is redirected after a payment is made, as well as a dynamic URL for DMNs. successUrl (String, 1000) – The URL the customer is directed to after a successful transaction. failureUrl (String, 1000) – The URL the customer is directed to after an unsuccessful transaction. pendingUrl (String, 1000) – The URL the customer is directed to when the transaction response is pending. notificationUrl (String, 1000) – The URL to which DMNs are sent. Although DMN responses can be configured per merchant site, this parameter allows dynamically returning the DMN to the provided address per request. appReturnLink (String, 255) – The deep link used to return to the merchant native application (press here for an example). NOTE: This parameter is not supported for all cases. appUrl (String, 255) – Link to which the provider redirects the user at the end of the payment process (press here for an example). NOTE: This parameter is not supported for all cases.
clientUniqueId ^String(45) ^Optional	The unique transaction ID in the merchant system. It appears in a DMN as the merchant_unique_id parameter.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
subMerchant ^Class ^Optional	countryCode (String, 2) – The 2-letter ISO country code of the PayFac’s submerchant. city (String, 20) – The city name of the PayFac’s submerchant. id (String, 15) – Represents the internal merchant’s ID, which is sent to the relevant card scheme. address (String, 48, CONDITIONAL) – The physical location where the transaction occurred, or the business location for virtual transactions. REQUIRED for PayFac-enabled transactions. state (String, 6, CONDITIONAL) – The ISO country subdivision code of the PayFac’s submerchant. REQUIRED for PayFac-enabled transactions. phone (String, 18) – The phone number of the PayFac’s submerchant that can be used for transaction inquiries. Recommended for PayFac-enabled transactions. Press here for more information.
dynamicDescriptor ^Class ^Optional	Special configuration is required for this class. For more information, please contact Nuvei’s Integration Support Team. merchantName (String, 25) – The merchant name, as is displayed for the transaction on the consumer’s card statement. For PayFac only, the maximum length of the parameter is 22, consisting of the following structure: XXX*<merchant name> where:  • XXX – The PayFac prefix, approved by Nuvei Underwriting Team.  Can be a length of 3, 7, 9, or 12.  • * – A fixed character.  • <merchant name> – Submerchant name.  Can be a length of 18, 14, 12, or 9, respectively. merchantPhone (String, 13) – The merchant contact information, as is displayed for the transaction on the consumer’s card statement. It can also be an email address.

Output Parameters

PARAMETER	DESCRIPTION
senderDetails.payment ^Class	Press here for details.
senderDetails.voidTransaction ^Class	Press here for details.
recipientPayoutDetails ^Class	Press here for details.
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
orderId ^String(20)	The ID returned from the merchantOrderID input parameter in update and payment
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
status ^String(20)	The cashier status of a merchant request. Possible values: SUCCESS, 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, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
operationStatus ^String(20)	The overall P2P operation status. Possible values: APPROVED – If both payment and payout requests got approved. DECLINED – If either of the payment or payout requests got declined. ERROR – If either of the payment or payout requests got an error.
version ^String(10)	The current version of the API method. The current version is 1.

senderDetails.payment Output

This output class is only relevant for the /p2pPayment method.

PARAMETER	DESCRIPTION
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
paymentOption ^Class	Represents the data retrieved from the processed payment method. It can be either card, redirectUrl (in the case of an APM), or userPaymentOptionId. • card (Class) – Information about the card that was processed:  ▫ bin (String) – The BIN number representing the issuer.  ▫ last4Digits (String) – The last four digits of the card number.  ▫ ccCardNumber (String) – The credit card number in a mask (for example: ***1111).  ▫ ccExpMonth (String) – The expiration month.  ▫ ccExpYear (String) – The expiration year.  ▫ cvv2Reply (String) – The CVV2 (card verification value) response.   Possible values:   ▪ M – CVV2 Match   ▪ N – CVV2 No Match   ▪ P – Not Processed. For EU card-on-file (COF) and ecommerce (ECOM) network token transactions, Visa removes any CVV and sends P. If you have fraud or security concerns, Visa recommends using 3DS.   ▪ U – Issuer is not certified and/or has not provided Visa the encryption keys   ▪ S – CVV2 processor is unavailable.  ▫ avsCode (String) – The address verification service (AVS) response.   Possible values:   ▪ A – The street address matches, the ZIP code does not.   ▪ W – Postal code matches, the street address does not.   ▪ Y – Postal code and the street address match.   ▪ X – An exact match of both the 9-digit ZIP code and the street address.   ▪ Z – Postal code matches, the street code does not.   ▪ U – Issuer is unavailable.   ▪ S – AVS not supported by issuer.   ▪ R – Retry.   ▪ B – Not authorized (declined).   ▪ N – Both the street address and postal code do not match.  ▫ acquirerId (String) – The ID of the acquirer that processed the transaction.  ▫ cardType (String) – The type of card used in the transaction.   Possible values: Credit, Debit  ▫ cardBrand (String) – The card brand used in the transaction.   Possible values: VISA, MASTERCARD, AMEX  ▫ threeD (class) – Contains the required 3DS information. Refer to threeD Output Class for details. OR • redirectUrl (String) – For an APM, the URL to which the customer is redirected in order to complete the transaction process. OR • userPaymentOptionId (String) – In addition to the above, this parameter represents the ID for the newly created payment option, which can be referenced in future requests. For full details, refer to Card-on-File.
transactionStatus ^String(20)	The Gateway transaction status. Possible values: APPROVED – The transaction was authorized and approved. DECLINED – The transaction authorization failed. ERROR – An error occurred. Please refer to Response Handling for details. REDIRECT – The transaction was not completed. The end user needs to be redirected to a webpage to complete the transaction.  There are two cases in which this response is returned:  • 3DS – The user needs to be redirected to paymentOption.threeD.acsUrl.  Press here for more information.  • An APM method that requires redirection – The URL is on paymentOption.redirectURL.  Press here for more information.
gwErrorCode ^Integer(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^Integer(11)	The error code if an error occurred on the bank’s side. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
transactionType ^String(45)	The type of transaction: Sale or Auth. Sale – Performs a regular payment request. Auth – Performs an authorization only request. Press here for more information.
transactionId ^String(20)	The Gateway transaction ID.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
authCode ^String(128)	The authorization code of the transaction.
customData ^String(255)	Can be used to pass any type of information. If sent in the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back office tool for transaction reporting and is returned in the response.
fraudDetails ^Class	finalDecision (String) score (decimal) recommendations (String) system (Array) [systemId (String), systemName (String), decision (String)] rules (Array) [ruleId (String), ruleDescription (String)] score refers to a number between 0 and 1 that indicates the probability of a transaction becoming fraudulent, which is calculated using a risk machine learning model. system refers to which risk management system provided the fraud information. The provider can be Nuvei (systemId=1) or an external provider. rules refers to the risk management system rules triggered by the transaction. decision refers to the risk management system decisions regarding the rules that were triggered by the transaction. There are five possible values for the decision parameter: • Accept – The risk management system accepts the transactions. • Reject – The risk management system rejects the transaction. The transaction is not passed to bank for authorization. The reasons are returned in ruleDescription parameter. • Review – The risk management system flags a transaction for review, but still accepts the transaction. • Error – An error occurred during the risk management system operation. The Gateway continues to process the transaction through the bank. • None – No risk analysis was performed. The Gateway continues to process the transaction through the bank. finalDecision refers to when deciding whether to accept or reject a transaction. The risk management system bases its finalDecision on individual decisions made regarding rules triggered. If none of the rules leads to a Reject decision, the finalDecision accepts the transaction. If at least one of the rules leads to a Reject decision, the finalDecision rejects the transaction. To receive this information in the response, special configurations are required. For more information, please contact Nuvei’s Integration Support Team.
partialApproval ^Class	Partial approval is when the deposit completes with a processed amount lower than the requested amount due to a lack of sufficient funds in the consumer payment method. requestedAmount (String, 12) – The original requested amount. requestedCurrency (String, 3) – The currency of the original request. processedAmount (String, 12) – The amount that was actually deposited in the transaction. processedCurrency (String, 3) – The currency used in the processed transaction request.

senderDetails.voidTransaction Output

This output class is only relevant for the /p2pPayment method.

PARAMETER	DESCRIPTION
transactionStatus ^String(20)	The Gateway transaction status. Possible values: APPROVED – The transaction was authorized and approved. DECLINED – The transaction authorization failed. ERROR – An error occurred. Please refer to Response Handling for details. REDIRECT – The transaction was not completed. The end user needs to be redirected to a webpage to complete the transaction.  There are two cases in which this response is returned:  • 3DS – The user needs to be redirected to paymentOption.threeD.acsUrl.  Press here for more information.  • An APM method that requires redirection – The URL is on paymentOption.redirectURL.  Press here for more information.
gwErrorCode ^Integer(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^Integer(11)	The error code if an error occurred on the bank’s side. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
transactionType ^String(45)	The type of transaction: Void.
transactionId ^String(20)	The Gateway transaction ID.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
authCode ^String(128)	The authorization code of the transaction.
customData ^String(255)	Can be used to pass any type of information. If sent in the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back office tool for transaction reporting and is returned in the response.

recipientPayoutDetails Output

This output class is only relevant for the /p2pPayment method.

PARAMETER	DESCRIPTION
cardData ^Class	Contains the card details. acquirerId (String) – The ID of the acquirer that processed the transaction. visaDirect (String) – If OCT was executed via visaDirect or not (YES/NO).
transactionStatus ^String(20)	The Gateway transaction status. Possible values: APPROVED – The transaction was authorized and approved. DECLINED – The transaction authorization failed. ERROR – An error occurred. Please refer to Response Handling for details. REDIRECT – The transaction was not completed. The end user needs to be redirected to a webpage to complete the transaction.  There are two cases in which this response is returned:  • 3DS – The user needs to be redirected to paymentOption.threeD.acsUrl.  Press here for more information.  • An APM method that requires redirection – The URL is on paymentOption.redirectURL.  Press here for more information.
gwErrorCode ^Integer(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^Integer(11)	The error code if an error occurred on the bank’s side. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
transactionId ^String(20)	The Gateway transaction ID.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.

/getTransactionDetails

Endpoint URL

1
2
3
4
5
6
7
8
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientUniqueId": "12345",
    "transactionId": "8498764859",
    "timeStamp": "20240915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
{
  "internalRequestId":987913008,
  "status": "SUCCESS",
  "errCode":0,
  "merchantId": "850502379161961074",
  "merchantSiteId": "229708",
  "version": "1.0",
  "userDetails":{
    "userTokenId": "230811147"
  },
  "deviceDetails":{
    "ipAddress": "93.146.254.172"
  },
  "transactionDetails":{
    "date": "2024-04-07T13:11:24.593Z",
    "originalTransactionDate": "2024-04-07T13:11:24.593Z",
    "transactionStatus": "Approved",
    "transactionType": "Sale",
    "authCode": "111504",
    "credited": "False",
    "transactionId": "711000000034347769",
    "acquiringBankName": "Nuvei Demo Bank"
  },
  "paymentOption":{
    "userPaymentOptionId": "107950408",
    "card":{
      "issuerBankName": "River Valley Credit Union",
      "issuerCountry": "united kingdom",
      "isPrepaid": "false",
      "ccCardNumber": "4****5032",
      "bin": "400002",
      "ccExpMonth": "12",
      "ccExpYear": "25",
      "cardType": "Credit",
      "cardBrand": "Visa",
      "threeD":{
        "whiteListStatus": "false",
        "isLiabilityOnIssuer": "False",
        "isExemptionRequestInAuthentication": "true",
        "exemptionRequest": "No"
      },
      "cardHolderName": "john smith"
    }
  },
  "partialApproval":{
    "requestedAmount": "100.0000",
    "requestedCurrency": "EUR"
  },
  "productDetails":{
    "productId": "NA"
  },
  "fraudDetails":{
    "finalDecision": "Accept"
  }
}

This method allows merchants to retrieve details of a specific credit card transaction by querying transactionId or clientUniqueId.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
timeStamp ^String(14) ~Required	The local time (in 24-hour format) when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the input parameters, which must be concatenated in the following order: merchantId, merchantSiteId, transactionId (if provided), clientUniqueId (if provided), timeStamp, merchantSecretKey. Press here to see an example.
clientUniqueId ^String(45) %%Conditional	The unique transaction ID in the merchant system. Either the transactionId or the clientUniqueId must be provided.
transactionId ^String(20) %%Conditional	The Gateway transaction ID. Either the transactionId or the clientUniqueId must be provided.

Output Parameters

Parameter	Description
userDetails ^Class	userTokenId (String, 255) – The ID of the user in merchant system.
deviceDetails ^Class	deviceName (String 255) deviceOS (String, 255) deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). ipAddress (String, 15)
currencyConversion ^Class	convertedCurrency (String, 3) – The final currency selected by the customer on the payment page in which the transaction was processed with the acquirer bank. convertedAmount (String, 12) – The final amount of the transaction after the customer converted the currency through the payment page. originalAmount (String, 12) – The amount of the transaction in the merchant currency. originalCurrencyCode (String, 3) – The merchant currencyCode of the transaction. rate (String, 12) – The exchange rate of the transaction. markup (Class)  markup (String, 12) – The premium percentage that was added to the rate.  markupAmount (String, 12) – The markup amount.  amountWithoutMarkup (String, 12) – The converted amount using the market rate without the markup  added.  markupAmountUSD (String, 12) – The markup amount in USD.
isCurrencyConverted ^String(12)	Indicates if currency conversion was performed.
transactionDetails ^Class	date (String, 10) – Format is ISO 8601 (YYYY-MM-DDThh:mm:ss. sssZ). originalTransactionDate (String, 10) – Format is ISO 8601 (YYYY-MM-DDThh:mm:ss. sssZ). transactionStatus (String, 20) – The Gateway transaction status.  Possible values: APPROVED, DECLINED, ERROR transactionType (String, 45) – The type of transaction Possible value: auth, sale, payout, refund, settle, void, auth3D, sale3D). authCode (String, 128) – The authorization code of the transaction. clientUniqueId (String, 45) – The unique transaction ID in the merchant system. customData (String, 255) – Can be used to pass any type of information. credited (String) transactionId (String, 20) – The Gateway transaction ID. relatedTransactionId (String, 19) – The ID of the original transaction. creditType (String) – The credit type that was performed. acquiringBankName (String) – The acquiring bank name. isVoided (Integer, 11) – Indicates if the transaction was voided. gwErrorCode (Integer, 11) – If an error occurred in the Gateway, then an error code is returned in this parameter. gwExtendedErrorCode (String, 400) – Error code if error occurred on the bank’s side. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error. gwErrorReason (String, 400) – If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
paymentOption ^Class	Represents the data retrieved from the processed payment method. It can be either card or userPaymentOptionId. • userPaymentOptionId – In addition to the above, this parameter represents the ID for the newly created payment option, which can be referenced in future requests. For full details, refer to Card-on-File. OR • card (Class) – Information about the card that was processed:  ▫ bin (String, 6) – The BIN number representing the issuer.  ▫ ccCardNumber (String, 20) – The credit card number in a mask (for example: ***1111).  ▫ cardHolderName (String, 70, REQUIRED) – The cardholder name.  ▫ ccExpMonth (String, 2) – The expiration month.  ▫ ccExpYear (String, 4) – The expiration year.  ▫ cvv2Reply (String) – The CVV2 (card verification value) response.   Possible values:   ▪ M – CVV2 Match   ▪ N – CVV2 No Match   ▪ P – Not Processed. For EU card-on-file (COF) and ecommerce (ECOM) network token transactions, Visa removes any CVV and sends P. If you have fraud or security concerns, Visa recommends using 3DS.   ▪ U – Issuer is not certified and/or has not provided Visa the encryption keys   ▪ S – CVV2 processor is unavailable.  ▫ issuerBankName (String) – Indicates the issuer bank name.  ▫ issuingCountry (String) – Indicates the name of the issuing country.  ▫ isPrepaid (String) – Indicates if the card is prepaid or not.  ▫ cardType (String) – The type of card used in the transaction.   Possible values: Credit, Debit  ▫ cardBrand (String) – The card brand used in the transaction.   Possible values: VISA, MASTERCARD, AMEX  ▫ threeD (class) – This class contains the 3DS information returned.   Refer to threeD Output Class for details on these parameters:    eci    isLiabilityOnIssuer    flow    isExemptionRequestInAuthentication    authenticationType    authenticationStatus – See the description of result.    challengeCancelReason    challengePreference – Refer to the externalMpi Class.    challengePreferenceReason   These parameters are new for this method:    whiteListStatus (String, 5) – Indicates if this consumer defined this merchant as whitelist or not     Possible values: true, false.    exemptionRequest (String, 25) – Can be used either during an Authentication request when Nuvei    is the 3DS MPI or during an Authorization request without any prior authentication    when the transaction amount allows it.    Please contact our Risk Team to set this threshold amount.     Possible values: ChallengeRequest, ExemptionRequest, NoPreference    challengeStatus – Indicates if a transaction qualifies as an authentication or an account verification.    Possible values:    Y – Authentication Verification Successful.    N – Not Authenticated/Account Not Verified; Transaction denied.    U – Authentication/Account verification could not be performed; technical or other problem,    as indicated in ARes or RReq.    A – Attempts Processing Performed; Not authenticated/verified, but a proof of attempted    authentication/verification is provided.    C – Challenge required; Additional authentication is required using the CReq/CRes.    D – Challenge Required; Decoupled Authentication confirmed.    R – Authentication/Account Verification Rejected; Issuer is rejecting.    NOTE: The Final CRes message can contain only a value of Y or N.    NOTE: If the 3DS Requestor Challenge Indicator = 06 (No Challenge Requested; data share only),    then a Transaction Status of C is not valid.
partialApproval ^Class	Partial approval is when the deposit completes with a processed amount lower than the requested amount due to a lack of sufficient funds in the consumer payment method. requestedAmount (String, 12) – The original requested amount. requestedCurrency (String, 3) – The currency of the original request.
productDetails ^Class	productId (String, 50) – A free text parameter used to identify the product/service sold. If this parameter is not sent or is sent with an empty value, then it contains the concatenation of all item names up until parameter maximum length.
fraudDetails ^Class	fraudScore (String) – Refers to a number between 0 and 1 that indicates the probability of a transaction becoming fraudulent, which is calculated using a risk machine learning model. finalDecision (String) – Refers to when deciding whether to accept or reject a transaction. The risk management system bases its finalDecision on individual decisions made regarding rules triggered. If none of the rules leads to a Reject decision, the finalDecision accepts the transaction. If at least one of the rules leads to a Reject decision, the finalDecision rejects the transaction. To receive this information in the response, special configurations are required. For more information, please contact Nuvei’s Integration Support Team.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
status ^String(20)	The cashier status of a merchant request. Possible values: SUCCESS, ERROR
errCode ^Integer(11)	The error code if the error occurred at the cashier side.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
version ^String(10)	The current version of the API method. The current version is 1.

/getPaymentStatus

Endpoint URL

1
2
3
{
    "sessionToken": "3765655c-c333-47b7-aea6-07c54e59d1fb"
}

1
2
3
4
safecharge.getPaymentStatus({
    "sessionToken": "3765655c-c333-47b7-aea6-07c54e59d1fb" // as returned from /getSessionToken result
}, function (pError, pRes){
});

1
2
3
4
5
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    GetPaymentStatusResponse response = safecharge.getPaymentStatus();
}

1
2
3
4
5
6
7
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
$getPaymentStatusRequest = $SafeCharge->getPaymentService()->getPaymentStatus([
    "sessionToken"  =>  "3765655c-c333-47b7-aea6-07c54e59d1fb",
]);
?>

1
2
3
4
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

// preceded by payment request
var response = safecharge.GetPaymentStatus();

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
{
    "transactionType": "Sale",
    "transactionStatus": "APPROVED",
    "transactionId": "1110000000015619958",
    "paymentOption": {
        "card": {
            "uniqueCC": "ffD9XNu1GNvYPPAiInTBi+dUqOA=",
            "threeD": {
                "eci": "5",
                "version": "2.1.0",
                "cavv": "c3FnTXNQZzJVRWVycXFxcHJhdUI=",
                "result": "Y",
                "isLiabilityOnIssuer": "1",
                "flow": "challenge"
        },
        "alternativePaymentMethod": {
            "externalAccountID": "XULDPMBSWPJZU",
            "externalTransactionId": "5FH47158U3529041Y",
            "APMReferenceID": "3274FEAB2016D682D1D6919ED8A39F8C",
            "orderTransactionId": "1078647708",
            "apmPayerInfo": "Address:Confirmed;Payer:verified;Country:US;FirstName:John;LastName:Smith Coevorden",
            "paymentMethod": "apmgw_expresscheckout"
        }
    },
    "currency": "USD",
    "amount": "200",
    "sessionToken": "da5d9646-faf0-449d-86e5-efc5b008ba82",
    "internalRequestId": 291868078,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantSiteId": "204388",
    "version": "1.0"
}

This method retrieves the status of a payment recently performed. It receives the session ID and queries if a payment was performed. If a payment was performed, the method returns the status of this payment.

Use /getPaymentStatus when you need to retrieve the status of a payment to verify a payment response or to check if the response was not received or was not received correctly or completely.

Use Cases:

• If you have submitted an APM transaction and received a “pending” response.
• If the request you sent timed out and you did not receive any response at all.
• If you wish to verify a transaction that was performed by the Web SDK createPayment() method.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.

Output Parameters

Parameter	Description
sessionToken ^String(36)	The session identifier returned by /getSessionToken or generated by /openOrder.
version ^String(10)	The current version of the API method. The current version is 1.
status ^String(20)	The cashier status of a merchant request. Possible values: SUCCESS, ERROR
transactionStatus ^String(20)	The Gateway transaction status.
amount ^String(12)	The transaction amount.
currency ^String(3)	The 3-letter ISO currency code.
userPaymentOption ^Class	userPaymentOptionId (String, 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.
customData ^String(255)	Can be used to pass any type of information. If sent in the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back office tool for transaction reporting and is returned in the response.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
gwExtendedErrorCode ^Integer(11)	Error code if error occurred on the bank side. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
gwErrorCode ^Integer(11)	The error code if error occurred. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the specific error.
gwErrorReason ^String(400)	The error reason if error occurred at the Gateway side.
paymentMethodErrorCode ^Integer(11)	The error code if error occurred at the APM side.
paymentMethodErrorReason ^String(400)	The error reason if error occurred at the APM side.
authCode ^String(128)	Auth code.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
transactionType ^String(45)	The type of transaction: Sale or Auth. Sale – Performs a regular payment request. Auth – Performs an authorization only request. Press here for more information.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
transactionId ^String(20)	The Gateway transaction ID.
errCode ^Integer(11)	The error code if the error occurred at the cashier side.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if the error occurred at the cashier side.
paymentOption ^Class	Represents the data retrieved from the processed payment method. It can be either card or alternativePaymentmethod. • card (Class) – Information about the card that was processed:  ▫ uniqueCC (String, 28) – Unique identifier for the credit card.  ▫ threeD (Class) – This class contains the 3DS information returned.   Refer to threeD Output Class for details on these parameters:   eci   version   cavv   result   isLiabilityOnIssuer   flow • alternativePaymentmethod (Class) – Represents an alternative payment method (APM) used to process the transaction.  ▫ externalAccountID (String) – This is the consumer’s username or unique identifier provided by the APM.   This value is not returned for all APMs.  ▫ externalAccountDescription (String) – Additional parameters that define the APM account in the   following format:    [parameter name]: [parameter value]    [parameter name]: [parameter value]  Not including the account password.  ▫ externalTransactionId (String, 20) – Bank transaction ID or APM transaction ID  ▫ APMReferenceID (String) – This is Nuvei’s reference identifier for each APM.  ▫ orderTransactionId (String) – This value helps to identify individual transactions that are related to the same orderID.  ▫ paymentMethod (String, 256) – The type of payment method selected by the customer (pre-selected).   Each APM has a different name.  ▫ userPaymentOptionId (String, 45) – This is the ID of the newly-generated userPaymentOption when a new userPaymentOption is generated, or userPaymentOptionId that has been used for transaction processing and has been sent in the request.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.

/getPayoutStatus

Endpoint URL

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

1
COMING SOON

1
2
3
4
5
6
7
8
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    String clientRequestId = "12345";

    Safecharge safecharge = new Safecharge();
    SafechargeResponse response = safecharge.getPayoutStatus(clientRequestId);
}

1
COMING SOON

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientRequestId": "1C6CT7V1L",
    "internalRequestId": 866,
    "transactionId": "8498764859",
    "status": "SUCCESS",
    "amount": "200",
    "currency": "USD",
    "transactionStatus": "APPROVED",
    "userPaymentOptionId": "12442",
    "errCode": 0,
    "reason": "",
    "gwErrorCode": 0,
    "gwErrorReason": "",
    "gwExtendedErrorCode": 0,
    "version": "1"
}

This method retrieves the status of a payout recently performed. It receives the clientRequestId and queries if a payout was performed by the merchant. If so, the method returns the status of the payout.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
clientRequestId ^String(255) ~Required	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
timeStamp ^String(14) ~Required	The local time (in 24-hour format) when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the input parameters, which must be concatenated in the following order: merchantId, merchantSiteId, clientRequestId, timeStamp, merchantSecretKey. Press here to see an example.

Output Parameters

Parameter	Description
version ^String(10)	The current version of the API method. The current version is 1.
status ^String(20)	The cashier status of a merchant request. Possible values: SUCCESS, ERROR
transactionStatus ^String(20)	The Gateway transaction status.
amount ^String(12)	The transaction amount.
currency ^String(3)	The 3-letter ISO currency code.
userPaymentOption ^Class	userPaymentOptionId (String, 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.
gwExtendedErrorCode ^Integer(11)	Error code if error occurred on the bank side. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
gwErrorCode ^Integer(11)	The error code if error occurred. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the specific error.
gwErrorReason ^String(400)	The error reason if error occurred at the Gateway side.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
transactionId ^String(20)	The Gateway transaction ID.
errCode ^Integer(11)	The error code if the error occurred at the cashier side.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if the error occurred at the cashier side.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.

/accountCapture (API)

Endpoint URL

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "paymentMethod": "apmgw_BankPayouts",
    "userTokenId": "230811147",
    "currencyCode": "USD",
    "countryCode": "US",
    "amount": "200",
    "languageCode": "en",
    "urlDetails":{
        "successUrl": "[URL the customer is directed to after a successful transaction]",
        "pendingUrl": "[URL the customer is directed to when the transaction response is pending]",
        "failureUrl": "[URL the customer is directed to after an unsuccessful transaction]",
        "notificationUrl": "[URL to which DMNs are sent]"
    }
}

1
COMING SOON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    String userTokenId = "230811147";
    String paymentMethod = "12345";
    String currency = "USD";
    String country = "US";
    String language = "en";
    String amount = "200";

    UserDetails userDetails = new UserDetails();
    userDetails.setCity("city");
    userDetails.setCountry("country");

    UrlDetails urlDetails = new UrlDetails();
    urlDetails.setSuccessUrl("successUrl");
    urlDetails.setPendingUrl("pendingUrl");
    urlDetails.setFailureUrl("failureUrl");
    urlDetails.setNotificationUrl("notificationUrl");

    Safecharge safecharge = new Safecharge();
    SafechargeResponse response = safecharge.accountCapture(null, userTokenId, paymentMethod, currency, country, language, amount, null, null, userDetails, urlDetails);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
//accountCapture
$accountCaptureResponse = $safeCharge->getPaymentService()->accountCapture([
    "sessionToken"      => "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId"        => "427583496191624621",
    "merchantSiteId"    => "142033",
    "paymentMethod"     => "apmgw_FastBankTansfer",
    "userTokenId"       => "230811147",
    "currencyCode"      => "USD",
    "countryCode"       => "US",
    "amount"            => "200"
    "languageCode"      => "en",
    "urlDetails":      => [
        "successUrl"   => "[URL the customer is directed to after a successful transaction]",
        "pendingUrl"   => "[URL the customer is directed to when the transaction response is pending]",
        "failureUrl"   => "[URL the customer is directed to after an unsuccessful transaction]",
        "notificationUrl"   => "[URL to which DMNs are sent]"
    ]
]);
?>

1
COMING SOON

Example Response

1
2
3
4
5
6
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "redirectUrl": "<redirected URL to enter bank account details>"
}

Once the merchant has successfully obtained a session token by calling /getSessionToken, the merchant can call this method to capture the bank account details of their clients and store them as User Payment Options for subsequent use for payout operations.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system. This must be sent when using the User Payment Management feature.
paymentMethod ^String(50) ~Required	Specifies the payment method name of the payment option to be charged. See: APM Input Parameters.
currencyCode ^String(3) ~Required	The 3-letter ISO currency code.
countryCode ^String(2) ~Required	The 2-letter ISO country code.
amount ^String(12) %%Conditional	The transaction amount. REQUIRED only for certain APMs.
userDetails ^Class %%Conditional	firstName (String, 30) lastName (String, 40) address (String, 50) zip (String, 10) city (String, 30) state (String, 3) – ISO country subdivision code birthdate (String, 10) – Format is YYYY-MM-DD. NOTE: These parameters are REQUIRED only for certain APMs.
deviceDetails ^Class %%Conditional	ipAddress (String, 15) REQUIRED only for certain APMs.
apmData ^Class %%Conditional	List of name-value pairs that contain the parameters of the user payment option. NOTE: This class is relevant only for certain APMs.
languageCode ^String(2) ^Optional	The language in which the transaction is to be completed.
urlDetails ^Class ^Optional	With this class, a merchant can dynamically provide possible URLs to which the end user is redirected after a payment is made, as well as a dynamic URL for DMNs. successUrl (String, 1000) – The URL the customer is directed to after a successful transaction. failureUrl (String, 1000) – The URL the customer is directed to after an unsuccessful transaction. pendingUrl (String, 1000) – The URL the customer is directed to when the transaction response is pending. notificationUrl (String, 1000) – The URL to which DMNs are sent. Although DMN responses can be configured per merchant site, this parameter allows dynamically returning the DMN to the provided address per request. appReturnLink (String, 255) – The deep link used to return to the merchant native application (press here for an example). NOTE: This parameter is not supported for all cases. appUrl (String, 255) – Link to which the provider redirects the user at the end of the payment process (press here for an example). NOTE: This parameter is not supported for all cases.

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by getSessionToken.
merchantId ^String(20)	Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	Merchant Site ID provided by Nuvei.
redirectUrl ^String(1000)	The URL to which the client is redirected in order to enter bank account details.

/getCardDetails (API)

Endpoint URL

1
2
3
4
5
6
7
8
{
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "clientUniqueId": "12345",
    "cardNumber": "4000027891380961"
}

1
2
3
4
5
6
safecharge.getCardDetails({
    "sessionToken": "3765655c-c333-47b7-aea6-07c54e59d1fb", // as returned from /getSessionToken result
    "cardNumber": "4000027891380961",
}, function (pError, pRes){

});

1
2
3
4
5
6
7
8
9
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    String clientUniqueId = "12345";
    String cardNumber = "4000027891380961";

    Safecharge safecharge = new Safecharge();
    SafechargeResponse response = safecharge.getCardDetails(clientUniqueId, null, cardNumber);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
//getCardDetails
$getCardDetailsResponse = $safeCharge->getPaymentService()->getCardDetails([
    "sessionToken"      => "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId"        => "427583496191624621",
    "merchantSiteId"    => "142033",
    "clientRequestId"   => "1C6CT7V1L",
    "clientUniqueId"    => "12345",
    "cardNumber"        => "4000027891380961"
]);
?>

1
2
3
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.GetCardDetails("12345", "4000027891380961");

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "brand": "VISA",
    "secondaryBrand": "BancontactAcquirer",
    "cardType": "Credit",
    "program": "Visa Platinum",
    "visaDirectSupport": "0",
    "mastercardSendSupport": "0",
    "isPrepaid": "true",
    "issuerCountry": "pe",
    "currency": "pen",
    "dccAllowed": "false",
    "sessionToken": "eaeed493-6ed1-4e44-9cc9-7e698efe51e2",
    "internalRequestId": 212986558,
    "status": "SUCCESS",
    "reason": "",
    "errCode": 0,
    "merchantId": "479748173730597238",
    "merchantSiteId": "204388",
    "version": "1.0",
    "clientRequestId": "20201025110518",
    "issuerBankName": "River Valley Credit Union"
}

This method can be used by the merchant to retrieve details about a card, such as card type and brand. In addition, the method also returns the account’s currency, which is needed for DCC.

For a Postman script that simulates this method, please press here, or refer to our guide for testing with Postman.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
cardNumber ^String(20) ~Required	The full credit card number.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
clientUniqueId ^String(45) ^Optional	The unique transaction ID in the merchant system. It appears in a DMN as the merchant_unique_id parameter.

Output Parameters

Parameter	Description
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
brand ^String	The name of the card scheme (for example: Visa).
secondaryBrand ^String(50)	The secondary brand supported by a co-badged card.
cardType ^String	The type of card used in the transaction. Possible values: credit, debit
program ^String	The card program used in the transaction (for example: Visa Platinum).
cardProduct ^String	The code of the card program used in the transaction (for example: Commercial & Business).
visaDirectSupport ^String	Indicates whether Visa Direct is supported or not. Possible values: 0 – Not supported. 1 – Supported. 2 – Supported for domestic transactions only.
mastercardSendSupport ^String	Indicates whether Mastercard Send is enabled or not. Possible values: 0 – Not enabled. 1 – Enabled for domestic and cross-border transactions. 2 – Enabled for domestic transactions only. 3 – Enabled status unknown for BIN.
dccAllowed ^String	Indicates whether DCC is allowed for this card.
issuerCountry ^String(2)	2-letter ISO code of the card issuer’s country.
currency ^String(3)	The 3-letter ISO currency code.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
version ^String(10)	The current version of the API method. The current version is 1.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
errCode ^Integer(11)	If an error occurred on the request side, an error code is returned in this parameter.
status ^String(20)	The cashier status of a merchant request. Possible values: SUCCESS, ERROR
isPrepaid ^String	Indicates if the card is prepaid or not.
issuerBankName ^String	Indicates the issuer bank name.

Currency Conversion Methods

/getMcpRates

Endpoint URL

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "clientUniqueId": "12345",
    "rateType": "payout",
    "fromCurrency": "EUR",
    "toCurrency": [
        "USD"
    ],
    "paymentMethods": [
        "cc_card"
    ]
}

1
COMING SOON

1
2
3
4
5
6
7
8
9
10
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    String clientRequestId = "1C6CT7V1L";
    String clientUniqueId = "12345";
    String fromCurrency = "USD";

    Safecharge safecharge = new Safecharge();
    McpRatesResponse response = safecharge.getMcpRates(clientUniqueId, clientRequestId, fromCurrency, null, null);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
//getMcpRates
$getMcpRatesResponse = $safeCharge->getPaymentService()->getMcpRates([
    "sessionToken"      => "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId"        => "427583496191624621",
    "merchantSiteId"    => "142033",
    "clientRequestId"   => "1C6CT7V1L",
    "clientUniqueId"    => "12345",
    "fromCurrency"      => "EUR",
    "toCurrency"        => [
        "USD"
    ],
    "paymentMethods"    => [
        "cc_card"
    ]
]);
?>

1
COMING SOON

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "reason": "",
    "merchantId": "2502136204546424962",
    "clientUniqueId": "695701003",
    "errCode": 0,
    "clientRequestId": "YWSWQUTBV",
    "rates": [
        {
            "ratesByCurrencies": [
                {
                    "rate": "1.195345",
                    "currency": "USD"
                }
            ],
            "paymentMethod": "cc_card"
        }
    ],
    "sessionToken": "616beb03-df6a-43d6-abef-fbc081c93e08",
    "internalRequestId": 14776101,
    "mcpTimestamp": "Mon Oct 26 14:53:30 EET 2020",
    "version": "1.0",
    "status": "SUCCESS",
    "merchantSiteId": "126006"
}

This method can be used by the merchant to specify a source currency and retrieve the current conversion rates (markup included), per currency and payment method, and timestamp. The timestamp persists in the system next to the relevant rates matrix snapshot.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
fromCurrency ^String(3) ~Required	The original merchant currency.
rateType ^String(12) ^Optional	The preferred method for which to receive the MCP rates. Possible values: payment (default), payout (Visa rates), payoutMC (Mastercard rates) If not provided in the request, the MCP rates are returned for payment.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
clientUniqueId ^String(45) ^Optional	The unique transaction ID in the merchant system. It appears in a DMN as the merchant_unique_id parameter.
toCurrency ^String(200) ^Optional	The list of target currencies, separated by commas. If not supplied, all the merchant site-related currencies are retrieved.
paymentMethod ^String(200) ^Optional	The list of payment methods, separated by commas. If not supplied, all the merchant-related payment methods are retrieved.

Output Parameters

Parameter	Description
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
mcpTimeStamp ^String(14)	The current time stamp (in 24-hour format).
apm ^Class	paymentMethod (String, 50) – Identifies the payment method. For example: apmgw_expresscheckout for PayPal, cc_card for credit card, etc. For a list of possible values, refer to APM Input Parameters.
rates ^Class	paymentMethod (String, 50) – This is Nuvei’s unique name of the payment method. ratesByCurrency, Class – List of rates by currency.   currency (String, 3) – The 3-letter ISO currency code.   rate (String) – The rate with markup.
status ^String(20)	The cashier status of a merchant request. Possible values: SUCCESS, 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, then an error reason is returned in this parameter.
version ^String(10)	The current version of the API method. The current version is 1.

/getDccDetails

Endpoint URL

1
2
3
4
5
6
7
8
9
10
11
{
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "clientUniqueId": "12345",
    "cardNumber": "4000027891380961",
    "originalAmount": "200",
    "originalCurrency": "USD",
    "currency": "EUR"
}

1
COMING SOON

1
2
3
4
5
6
7
8
9
10
11
12
13
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    String clientRequestId = "1C6CT7V1L";
    String clientUniqueId = "12345";
    String originalCurrency = "USD";
    String currency = "EUR";
    String originalAmount = "200";
    String cardNumber = "4000027891380961";

    Safecharge safecharge = new Safecharge();
    DccDetailsResponse response = safecharge.getDccDetails(clientUniqueId, clientRequestId, cardNumber, null, originalAmount, originalCurrency, currency, null);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
//getDccDetails
$getDccDetailsResponse = $safeCharge->getPaymentService()->getDccDetails([
    "sessionToken"      => "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId"        => "427583496191624621",
    "merchantSiteId"    => "142033",
    "clientRequestId"   => "1C6CT7V1L",
    "clientUniqueId"    => "12345",
    "cardNumber"        => "4000027891380961",
    "originalAmount"    => "200",
    "originalCurrency"  => "USD",
    "currency"          => "EUR"
]);
?>

1
2
3
4
5
6
7
8
9
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.GetDccDetails(
    "1C6CT7V1L",
    "12345",
    "4000027891380961",
    55.4,
    "USD",
    "EUR");

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "rateValueWithMarkUp": "0.8914572821049559",
    "amount": "178.29",
    "currency": "EUR",
    "originalAmount": "200",
    "originalCurrency": "USD",
    "dccFullSupport": "false",
    "sessionToken": "24a73293-d7e5-4aa5-a2d3-3d6fe2702c80",
    "internalRequestId": 289971718,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "479748173730597238",
    "merchantSiteId": "204388",
    "version": "1.0",
    "clientRequestId": "560673023851979"
}

The REST returns the DCC information based on the received payment method, source amount, source currency and target currency.

The output of this method is the complete DCC information.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
clientUniqueId ^String(45) ~Required	The unique transaction ID in the merchant system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in a DMN as the merchant_unique_id parameter.
originalAmount ^String(12) ~Required	The original amount of the transaction in the currency that the merchant requested.
originalCurrency ^String(3) ~Required	The 3-letter ISO currency code of the currency that the merchant requested in the transaction.
cardNumber ^String(20) %%Conditional	The card number. REQUIRED if apm is not provided.
apm ^String(50) %%Conditional	The payment method. REQUIRED if cardNumber is not provided. For the values of specific APMs, press here.
currency ^String(3) %%Conditional	The 3-letter ISO currency code of the conversion currency. REQUIRED if country is not provided. If both currency and country are provided in the input, the currency takes precedence.
country ^String(2) %%Conditional	The 2-letter ISO country code of the conversion country. REQUIRED if currency is not provided. If both currency and country are provided in the input, the currency takes precedence.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.

Output Parameters

Parameter	Description
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
rateValueWithMarkup ^String(12)	The rate value with markup.
markUpValue ^String(12)	The markup percentage value.
dccFullSupport ^Boolean	Determines if DCC is fully supported by the issuer or not. Possible values: true – DCC is supported by issuer. false – DCC not supported by issuer.
amount ^String(12)	The converted amount.
currency ^String(3)	The 3-letter ISO currency code of the conversion currency.
originalAmount ^String(12)	The original amount of the transaction in the currency that the merchant requested.
originalCurrency ^String(12)	The 3-letter ISO currency code of the currency that the merchant requested in the transaction.
status ^String(20)	The cashier status of a merchant request. Possible values: SUCCESS, 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, then an error reason is returned in this parameter.
version ^String(10)	The current version of the API method. The current version is 1.

MPI Methods

/authorize3d

Endpoint URL

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
{
    "merchantSiteId": "142033",
    "merchantId": "427583496191624621",
    "sessionToken": "9e07802d-5126-4b02-b4b3-ef09dfb94219",
    "relatedTransactionId": "2110000000001208909",
    "clientUniqueId": "12345",
    "currency": "USD",
    "amount": "200",
    "paymentOption": {
        "card": {
            "cardNumber": "4000027891380961",
            "cardHolderName": "John Smith",
            "expirationMonth": "12",
            "expirationYear": "2030",
            "CVV": "217",
            "threeD": {
                "browserDetails": {
                    "acceptHeader": "text/html,application/xhtml+xml",
                    "ip": "192.168.1.11",
                    "javaEnabled": "TRUE",
                    "javaScriptEnabled": "TRUE",
                    "language": "EN",
                    "colorDepth": "48",
                    "screenHeight": "400",
                    "screenWidth": "600",
                    "timeZone": "0",
                    "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)"
                },
                "version": "2.1.0",
                "notificationURL": "<notificationURL>",
                "merchantUrl": "<merchantUrl>",
                "platformType": "02",
                "v2AdditionalParams": {
                    "challengeWindowSize": "05"
                }
            }
        }
    },
    "deviceDetails": {
        "ipAddress": "192.168.2.38"
    },
    "billingAddress": {
        "firstName": "John",
        "lastName": "Smith",
        "email": "[email protected]",
        "country": "US"
    }
}

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
safecharge.authorize3d({
    sessionToken: "sessionToken", // as returned from /getSessionToken result
    relatedTransactionId: "transactionId", // as returned from /initPayment
    currency: "USD",
    amount: "200",
    paymentOption: {
        card: {
            expirationYear: "2030",
            CVV: "217",
            cardHolderName: "John Smith",
            expirationMonth: "12",
            cardNumber: "4000027891380961"
        }
    },
    deviceDetails: {
        ipAddress: "192.168.2.38"
    },
    billingAddress: {
        firstName: "John",
        lastName: "Smith",
        email: "[email protected]",
        country: "US"
    }
}, function(pError, pRes) {

});

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
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    String userTokenId = "230811147";
    String clientRequestId = "1C6CT7V1L";
    String clientUniqueId = "12345";
    String currency = "USD";
    String amount = "200";
    String relatedTransactionId = "2110000000001208909";

    BrowserDetails browserDetails = new BrowserDetails();
    browserDetails.setAcceptHeader("text/html,application/xhtml+xml");
    browserDetails.setIp("192.168.1.11");
    browserDetails.setJavaEnabled("TRUE");
    browserDetails.setJavaScriptEnabled("TRUE");
    browserDetails.setLanguage("EN");
    browserDetails.setColorDepth("48");
    browserDetails.setScreenHeight("400");
    browserDetails.setScreenWidth("600");
    browserDetails.setTimeZone("0");
    browserDetails.setUserAgent("Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47");

    V2AdditionalParams v2AdditionalParams = new V2AdditionalParams();
    v2AdditionalParams.setChallengeWindowSize("2");

    ThreeD threeD = new ThreeD();
    threeD.setMethodCompletionInd("Y");
    threeD.setVersion("2.1.0");
    threeD.setNotificationURL("<notificationURL>");
    threeD.setMerchantURL("<merchantURL>");
    threeD.setV2AdditionalParams(v2AdditionalParams);
    threeD.setBrowserDetails(browserDetails);

    Card card = new Card();
    card.setCardNumber("4000027891380961");
    card.setCardHolderName("John Smith");
    card.setExpirationMonth("12");
    card.setExpirationYear("25");
    card.setCVV("217");
    card.setThreeD(threeD);

    PaymentOption paymentOption = new PaymentOption();
    paymentOption.setCard(card);

    UserAddress billingAddress = new UserAddress();
    billingAddress.setFirstName("John");
    billingAddress.setLastName("Smith");
    billingAddress.setCountry("US");
    billingAddress.setEmail("[email protected]");

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("192.168.2.38");

    Safecharge safecharge = new Safecharge();
    Authorize3dResponse response = safecharge.authorize3d(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency, amount, null, null, deviceDetails, null, null, billingAddress, null, null, null, null, null, null, null, null, null, null, null, null);
}

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
$authorize3dRequest = $SafeCharge->getPaymentService()->authorize3d([
    "currency" => "USD",
    "amount" => "200",
    "paymentOption" => [
        "card" => [
            "cardNumber" => "4000027891380961",
            "cardHolderName" => "John Smith",
            "expirationMonth" => "12",
            "expirationYear" => "2030",
            "CVV" => "217"
        ]
    ],
    "billingAddress" => [
        "firstName"   => "John",
        "lastName"   => "Smith",
        "country"   => "US",
        "email"     => "[email protected]",
    ],
    "deviceDetails"     => [
        "ipAddress"  => "192.168.2.38"
    ],
    "relatedTransactionId" => "2110000000001208909",
    "sessionToken" => "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId"        => "427583496191624621",
    "merchantSiteId"    => "142033",
    "timeStamp"     =>  "<YYYYMMDDHHmmss>",
]);
?>

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
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.Authorize3d(
    "USD",
    "200",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "John Smith",
            ExpirationMonth = "12",
            ExpirationYear = "26",
            CVV = "217",
            ThreeD = new ThreeD
            {
                BrowserDetails = new BrowserDetails
                {
                    AcceptHeader = "text/html,application/xhtml+xml",
                    Ip = "192.168.1.11",
                    JavaEnabled = "TRUE",
                    JavaScriptEnabled = "TRUE",
                    Language = "EN",
                    ColorDepth = "48",
                    ScreenHeight = "400",
                    ScreenWidth = "600",
                    TimeZone = "0",
                    UserAgent = "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)"
                },
                Version = "2.1.0",
                V2AdditionalParams = new V2AdditionalParams
                {
                    ChallengeWindowSize = "05"
                },
                NotificationURL = "<notificationURL>",
                MerchantURL = "<merchantUrl>",
                PlatformType = "02"
            }
        }
    },
    relatedTransactionId: "2110000000001208909",
    clientUniqueId: "12345",
    deviceDetails: new DeviceDetails { IpAddress = "192.168.2.38" },
    billingAddress: new UserAddress
    {
        FirstName = "John",
        LastName = "Smith",
        Country = "US",
        Email = "[email protected]",
    },
);

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
    {
    "orderId": "241494183",
    "paymentOption": {
        "userPaymentOptionId": "8348263",
        "card": {
            "ccCardNumber": "5****8464",
            "bin": "511580",
            "last4Digits": "8464",
            "ccExpMonth": "01",
            "ccExpYear": "20",
            "cvv2Reply": "",
            "avsCode": "",
            "threeD": {
                "acsUrl": "https://qa1-tlv-acq1:4434/api/ThreeDSACSChallengeController/ChallengePage?eyJub3RpZmlj...",
                "eci": "7",
                "termUrl": "https://srv-bsf-devppptrunk.gw-4u.com/ppp/api/threeDSecure/completePayment.do?sessionToken\u003d04fcc8cf-3789-4936-b690-9801261f83a9",
                "whiteListStatus": "",
                "cavv": "",
                "acsChallengeMandated": "Y",
                "cReq": "eyJ0aHJlZURTU...",
                "authenticationType": "01",
                "cardHolderInfoText": "",
                "result": "C",
                "version": "2.1.0",
                "acsTransId": "541a88a9-f01f-4206-9137-ec1bed295955",
                "dsTransID": "f0ff3e24-cdf6-4561-900b-849a5054d776"
            }
        }
    },
    "transactionStatus": "DECLINED",
    "merchantDetails": { 
        "customField1": "merchantName"
    },
    "gwErrorCode":-1,
    "gwErrorReason": "Decline",
    "gwExtendedErrorCode": 0,
    "transactionType": "Auth3D",
    "transactionId": "1110000000000347161",
    "externalTransactionId": "",
    "authCode": "",
    "customData": "",
    "sessionToken": "5bd76168-844c-4fb1-9cfb-f7812ca31950",
    "clientUniqueId": "uniqueIdCC",
    "internalRequestId": 134148663,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0"
    }

Call this method if you need to use the Nuvei MPI service to perform a 3DS-only request. This method is called after the /initPayment method, and returns the information regarding whether the merchant has to perform a Challenge or if they receive a frictionless response.

This method has the exact same parameters and works the same as the /payment method, with only the following differences:

• For a Frictionless 3DS response, it never proceeds to perform a payment. It just returns that the Challenge is not mandated (and does not provide acsUrl under the threeD Output Class).
• There are several input parameters that have to be added to the request.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The merchant ID provided by Nuvei (part of the authentication credentials).
merchantSiteId ^String(20) ~Required	The merchant site ID provided by Nuvei (part of the authentication credentials).
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
currency ^String(3) ~Required	The 3-letter ISO currency code.
amount ^String(12) ~Required	The transaction amount.
paymentOption ^Class ~Required	The option used to send the payment details. Choose from the following options: If you wish to collect the card details: card (Class) – Represents a credit/debit card.  • cardNumber (String, 20, REQUIRED) – The card number.  • expirationMonth (String, 2, REQUIRED) – Card expiration month.  • expirationYear (String, 4, REQUIRED) – Card expiration year.  • cardHolderName (String, 70, REQUIRED for 3DS card authentication) – The cardholder name.  • CVV (String, 4) – The CVV/CVC security code.  • selectedBrand (String, 128) – The brand selected by the consumer for the transaction processing.  • threeD (class) – Contains the required 3DS information. Refer to threeD Input Class for details. If you are handling a returning user and want to use a previously saved user payment option: userPaymentOptionId (String) – Identifies a payment option that has already been used by the customer and now it is requested for re-use. Nuvei keeps payment option details from a previous use.
relatedTransactionId ^String(19) ~Required	The transactionId from the response to the preceding /initPayment call.
timeStamp ^String(14) ~Required	The local time (in 24-hour format) when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^Hexadecimal String(256) ~Required	UTF-8 encoded SHA-256 hashed values of the input parameters, which must be concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey. Press here to see an example. NOTE: clientRequestId is optional and does not need to be included in the concatenation.
deviceDetails ^Class ~ipAddress Required	ipAddress (String, 15, REQUIRED) deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255)
billingAddress ^Class ~Some Parameters Required	The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters. country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30, REQUIRED) middleName (String, 40, OPTIONAL when the cardHolderNameVerification class is provided) lastName (String, 40, REQUIRED) phone (String, 18, REQUIRED for 3DS card authentication if email not provided) address (String, 50) zip (String, 10) city (String, 30) state (String, 3) – ISO country subdivision code addressLine2 (String, 50) addressLine3 (String, 50) county (String, 255) These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.
cardHolderNameVerification ^Class %%Conditional	Allows the merchant to perform cardholder name verification. REQUIRED when using the cardholder name verification feature. NOTE: The verification is performed on the firstName, lastName, and middleName from the billingAddress class. NOTE: This feature can only be used when amount is 0. performNameVerification (String, 5, REQUIRED)  Possible values:  true – Cardholder name verification is performed.  false (default) – Cardholder name verification is not performed. Press here for an example.
userTokenId ^String(255) %%Conditional	This ID uniquely identifies your consumer/user in your system. It is REQUIRED only if you wish to use the userPaymentOptionId parameter for future charging of this user without re-collecting the payment details. Press here for more information.
subMerchant ^Class ^Optional	countryCode (String, 2) – The 2-letter ISO country code of the PayFac’s submerchant. city (String, 20) – The city name of the PayFac’s submerchant. id (String, 15) – Represents the internal merchant’s ID, which is sent to the relevant card scheme. address (String, 48, CONDITIONAL) – The physical location where the transaction occurred, or the business location for virtual transactions. REQUIRED for PayFac-enabled transactions. state (String, 6, CONDITIONAL) – The ISO country subdivision code of the PayFac’s submerchant. REQUIRED for PayFac-enabled transactions. phone (String, 18) – The phone number of the PayFac’s submerchant that can be used for transaction inquiries. Recommended for PayFac-enabled transactions. Press here for more information.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
clientUniqueId ^String(45) ^Optional	The unique transaction ID in the merchant system. It appears in a DMN as the merchant_unique_id parameter.
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This represents the customer’s identification number in their respective country.
shippingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 50) cell (String, 18) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 3) – ISO country subdivision code email (100) county (String, 255) addressLine2 (String, 50) addressLine3 (String, 50)
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response.
urlDetails ^Class ^Optional	With this class, a merchant can dynamically provide possible URLs to which the end user is redirected after a payment is made, as well as a dynamic URL for DMNs. successUrl (String, 1000) – The URL the customer is directed to after a successful transaction. failureUrl (String, 1000) – The URL the customer is directed to after an unsuccessful transaction. pendingUrl (String, 1000) – The URL the customer is directed to when the transaction response is pending. notificationUrl (String, 1000) – The URL to which DMNs are sent. Although DMN responses can be configured per merchant site, this parameter allows dynamically returning the DMN to the provided address per request. appReturnLink (String, 255) – The deep link used to return to the merchant native application (press here for an example). NOTE: This parameter is not supported for all cases. appUrl (String, 255) – Link to which the provider redirects the user at the end of the payment process (press here for an example). NOTE: This parameter is not supported for all cases.
items ^Class ^Optional	Describes the items in the purchase. name (String, 255) price (String, 10) quantity (String, 10)
customSiteName ^String(50) ^Optional	The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name. Risk rules and traffic management rules are usually built based on this parameter value.
productId ^String(50) ^Optional	A free text parameter used to identify the product/service sold. If this parameter is not sent or is sent with an empty value, then it contains the concatenation of all item names up until the parameter maximum length. Risk rules and traffic management rules are usually built based on this parameter value.
customData ^String(255) ^Optional	Can be used to pass any type of information. If sent in request, then it is visible in Nuvei’s back office tool transaction reporting and is returned in response.
webMasterId ^String(255) ^Optional	An affiliate parameter that the merchant can send. This is used by Nuvei’s eCommerce plugins (Magento, Demandware) and by Nuvei REST API SDKs to send the plugin/SDK name and version so that Support is able to identify from where the transaction arrived at the REST API Gateway.
orderId ^String(45) ^Optional	The order ID provided by Nuvei. This parameter is passed to define which merchant order to update.
addendums ^Class ^Optional	Contains industry specific addendums. For /authorize3d, only localPayment is relevant.

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
status ^String(20)	The cashier status of a merchant request. Possible values: SUCCESS, ERROR
transactionStatus ^String(20)	The Gateway transaction status.
paymentOption ^Class	Represents the data retrieved from the processed payment method. It can be either card, redirectUrl (in the case of an APM), or userPaymentOptionId. • card (Class) – Information about the card that was processed:  ▫ bin (String) – The BIN number representing the issuer.  ▫ last4Digits (String) – The last four digits of the card number.  ▫ ccCardNumber (String) – The credit card number in a mask (for example: ***1111).  ▫ ccExpMonth (String) – The expiration month.  ▫ ccExpYear (String) – The expiration year.  ▫ cvv2Reply (String) – The CVV2 (card verification value) response.   Possible values:   ▪ M – CVV2 Match   ▪ N – CVV2 No Match   ▪ P – Not Processed. For EU card-on-file (COF) and ecommerce (ECOM) network token transactions, Visa removes any CVV and sends P. If you have fraud or security concerns, Visa recommends using 3DS.   ▪ U – Issuer is not certified and/or has not provided Visa the encryption keys   ▪ S – CVV2 processor is unavailable.  ▫ avsCode (String) – The address verification service (AVS) response.   Possible values:   ▪ A – The street address matches, the ZIP code does not.   ▪ W – Postal code matches, the street address does not.   ▪ Y – Postal code and the street address match.   ▪ X – An exact match of both the 9-digit ZIP code and the street address.   ▪ Z – Postal code matches, the street code does not.   ▪ U – Issuer is unavailable.   ▪ S – AVS not supported by issuer.   ▪ R – Retry.   ▪ B – Not authorized (declined).   ▪ N – Both the street address and postal code do not match.  ▫ acquirerId (String) – The ID of the acquirer that processed the transaction.  ▫ cardType (String) – The type of card used in the transaction.   Possible values: Credit, Debit  ▫ cardBrand (String) – The card brand used in the transaction.   Possible values: VISA, MASTERCARD, AMEX  ▫ threeD (class) – Contains the required 3DS information. Refer to threeD Output Class for details. OR • redirectUrl (String) – For an APM, the URL to which the customer is redirected in order to complete the transaction process. OR • userPaymentOptionId – In addition to the above, this parameter represents the ID for the newly created payment option, which can be referenced in future requests. For full details, refer to Card-on-File.
merchantDetails ^Class	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response.
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, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwErrorCode ^Integer(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^Integer(11)	The error code if an error occurred on the bank’s side. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
version ^String(10)	The current version of the API method. The current version is 1.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
transactionId ^String(20)	The Gateway transaction ID.
authCode ^String(128)	The authorization code of the transaction.
partialApprovalDetails ^Class	Determines whether or not the transaction is a partial approval, plus other information regarding the amount. These following parameters are returned only if the partial approval feature was in use, as per the relevant input parameter sent value. isPartialApproval (String – True or False) amountInfo: requestedAmount (String) requestedCurrency (String) processedAmount (String) processedCurrency (String)
transactionType ^String(45)	The type of transaction: Sale or Auth. Sale – Performs a regular payment request. Auth – Performs an authorization only request. Press here for more information.
customData ^String(255)	Can be used to pass any type of information. If sent in the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back office tool for transaction reporting and is returned in the response.
fraudDetails ^Class	finalDecision (String) score (decimal) recommendations (String) system (Array) [systemId (String), systemName (String), decision (String)] rules (Array) [ruleId (String), ruleDescription (String)] score refers to a number between 0 and 1 that indicates the probability of a transaction becoming fraudulent, which is calculated using a risk machine learning model. system refers to which risk management system provided the fraud information. The provider can be Nuvei (systemId=1) or an external provider. rules refers to the risk management system rules triggered by the transaction. decision refers to the risk management system decisions regarding the rules that were triggered by the transaction. There are five possible values for the decision parameter: • Accept – The risk management system accepts the transactions. • Reject – The risk management system rejects the transaction. The transaction is not passed to bank for authorization. The reasons are returned in ruleDescription parameter. • Review – The risk management system flags a transaction for review, but still accepts the transaction. • Error – An error occurred during the risk management system operation. The Gateway continues to process the transaction through the bank. • None – No risk analysis was performed. The Gateway continues to process the transaction through the bank. finalDecision refers to when deciding whether to accept or reject a transaction. The risk management system bases its finalDecision on individual decisions made regarding rules triggered. If none of the rules leads to a Reject decision, the finalDecision accepts the transaction. If at least one of the rules leads to a Reject decision, the finalDecision rejects the transaction. To receive this information in the response, special configurations are required. For more information, please contact Nuvei’s Integration Support Team.
orderId ^String(20)	The ID returned from the merchantOrderID input parameter in update and payment methods. This parameter is returned to define which merchant order to update.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.
processedBrand ^String(50)	The brand with which the transaction was processed.
cardHolderNameVerification ^Class	Indicates the result of the cardholder name verification request. nameVerificationRequestResult (String)  Possible values:  NameVerificationPerformed  NameVerificationNotPerformed  NameVerificationNotSupported nameVerificationResult (String, 50) firstNameVerificationResult (String, 50) middleNameVerificationResult (String, 50) lastNameVerificationResult (String, 50)  Possible values for each of the four parameters above:  Match  PartialMatch  NoMatch  Unverified Press here for more information.

/verify3d

Endpoint URL

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": "142033",
    "merchantId": "427583496191624621",
    "sessionToken": " 9e07802d-5126-4b02-b4b3-ef09dfb94219",
    "relatedTransactionId": "2110000000001208909",
    "currency": "USD",
    "amount": "200",
    "paymentOption": {
        "card": {
            "cardNumber": "4000027891380961",
            "cardHolderName": "john Smith",
            "expirationMonth": "12",
            "expirationYear": "2030",
            "CVV": "217"
        }
    },
    "deviceDetails": {
        "ipAddress": "192.168.2.38"
    },
    "billingAddress": {
        "firstName": "John",
        "lastName": "Smith",
        "email": "[email protected]",
        "country": "US"
    }
}

1
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
safecharge.verify3d({
    sessionToken: "sessionToken", // as returned from /getSessionToken result
    relatedTransactionId: "transactionId", // as returned from /authorize3d result
    currency: "USD",
    amount: "200",
    paymentOption: {
      card: {
        expirationYear: "2030",
        CVV: "217",
        cardHolderName: "John Smith",
        expirationMonth: "12",
        cardNumber: "4000027891380961"
      }
    },
    deviceDetails: {
        "ipAddress": "192.168.2.38"
    },
    billingAddress: {
        firstName: "John",
        lastName: "Smith",
        email: "[email protected]",
        country: "US"
    }
}, function (pError, pRes){

});

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
//Initialize the SDK (see https://docs.nuvei.com/?p=29433#initializing-the-sdk)

{
    String userTokenId = "230811147";
    String clientRequestId = "1C6CT7V1L";
    String clientUniqueId = "12345";
    String currency = "USD";
    String amount = "200";
    String relatedTransactionId = "2110000000001208909";

    Verify3dCard card = new Verify3dCard();
    card.setCardNumber("4000027891380961");
    card.setCardHolderName("John Smith");
    card.setExpirationMonth("12");
    card.setExpirationYear("2030");
    card.setCVV("217");

    Verify3dPaymentOption paymentOption = new Verify3dPaymentOption();
    paymentOption.setCard(card);

    UserAddress billingAddress = new UserAddress();
    billingAddress.setFirstName("John");
    billingAddress.setLastName("Smith");
    billingAddress.setCountry("US");
    billingAddress.setEmail("[email protected]");

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("192.168.2.38");

    Safecharge safecharge = new Safecharge();
    Verify3dResponse response = safecharge.verify3d(clientUniqueId, clientRequestId, amount, currency, billingAddress, null, null, null, relatedTransactionId, null, null, userTokenId, paymentOption);
}

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
//Initialize the SDK (see https://docs.nuvei.com/?p=53233#initializing-the-sdk)

<?php
$verify3dRequest = $SafeCharge->getPaymentService()->verify3d([
    "currency" => "USD",
    "amount" => "200",
    "paymentOption" => [
        "card" => [
            "cardNumber" => "4000027891380961",
            "cardHolderName" => "John Smith",
            "expirationMonth" => "12",
            "expirationYear" => "2030",
            "CVV" => "217"
        ]
    ],
    "billingAddress" => [
        "firstName"   => "John",
        "lastName"   => "Smith",
        "country"   => "US",
        "email"     => "[email protected]",
    ],
    "deviceDetails"     => [
        "ipAddress"  => "192.168.2.38"
    ],

    "relatedTransactionId" => "2110000000001208909",
    "sessionToken" => "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId"        => "427583496191624621",
    "merchantSiteId"    => "142033",
    "timeStamp"     =>  "<YYYYMMDDHHmmss>",
]);
?>

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
//Initialize the SDK (see https://docs.nuvei.com/?p=48413#initializing-the-sdk)

var response = safecharge.Verify3d(
    "USD",
    "200",
    new Verify3dPaymentOption
    {
        Card = new Verify3dCard
        {
            CardNumber = "4000027891380961",
            CardHolderName = "john Smith",
            ExpirationMonth = "12",
            ExpirationYear = "26",
            CVV = "217"
        }
    },
    relatedTransactionId: "2110000000001208909",
    deviceDetails: new DeviceDetails { IpAddress = "192.168.2.38" },
    billingAddress: new UserAddress
    {
        FirstName = "John",
        LastName = "Smith",
        Country = "US",
        Email = "[email protected]",
    },
);

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
{
    "orderId": "29264489",
    "transactionStatus": "APPROVED",
    "transactionType": "VerifyAuth3D",
    "transactionId": "2110000000000644999",
    "customData": "customData",
    "merchantDetails": {
        "customField1": "merchantName"
    },
    "paymentOption": {
        "card": {
            "ccCardNumber": "5****3511",
            "bin": "541333",
            "last4Digits": "3511",
            "ccExpMonth": "12",
            "ccExpYear": "25",
            "threeD": {
                "threeDFlow": "0",
                "eci": "2",
                "version": "2.1.0",
                "serverTransId": "34cfeb35-5ba6-4df3-a5f1-bf4b93e14476",
                "whiteListStatus": "",
                "cavv": "ZkhQRHd3Mzd6Z2t2MlFLQmRMbW8=",
                "sdk": {},
                "result": "Y",
                "acsTransId": "",
                "dsTransID": "9bd98ea9-035e-4ec3-a863-831fc547473f"
            }
        }
    },
    "sessionToken": "9e07802d-5126-4b02-b4b3-ef09dfb94219",
    "clientUniqueId": "clientUniqueId",
    "internalRequestId": 3329188,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0"
}

Call this method if you need to use the Nuvei MPI service to perform a 3DS-only request. This method is called after the /authorize3d method in case of the Challenge.

/verify3d retrieves the generic 3DS result (eci and cavv) that you need to send to your PSP or acquirer to benefit from the 3DS liability shift received from the Nuvei 3DS service.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The merchant site ID provided by Nuvei.
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
currency ^String(3) ~Required	The 3-letter ISO currency code.
amount ^String(12) ~Required	The transaction amount.
paymentOption ^Class ~Required	The option used to send the payment details. Choose from the following options: If you wish to collect the card details: card (Class) – Represents a credit/debit card.  • cardNumber (String, 20, REQUIRED) – The card number.  • expirationMonth (String, 2, REQUIRED) – Card expiration month.  • expirationYear (String, 4, REQUIRED) – Card expiration year.  • cardHolderName (String, 70) – The cardholder name.  • CVV (String, 4) – The CVV/CVC security code. If you are handling a returning user and want to use a previously saved user payment option: userPaymentOptionId (String) – Identifies a payment option that has already been used by the customer and now it is requested for re-use. Nuvei keeps payment option details from a previous use.
relatedTransactionId ^String(19) ~Required	The transactionId from the /authorize3d response.
deviceDetails ^Class ~ipAddress Required	ipAddress (String, 15, REQUIRED) deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255)
billingAddress ^Class ~Some Parameters Required	The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters. country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30, REQUIRED) lastName (String, 40, REQUIRED) address (String, 50) addressLine2 (String, 50) addressLine3 (String, 50) phone (String, 18) zip (String, 10) city (String, 30) state (String, 3) – ISO country subdivision code county (String, 255) These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.
userTokenId ^String(255) %%Conditional	This ID uniquely identifies your consumer/user in your system. It is REQUIRED only if you wish to use the userPaymentOptionId parameter for future charging of this user without re-collecting the payment details. Press here for more information.
subMerchant ^Class ^Optional	countryCode (String, 2) – The 2-letter ISO country code of the PayFac’s submerchant. city (String, 20) – The city name of the PayFac’s submerchant. id (String, 15) – Represents the internal merchant’s ID, which is sent to the relevant card scheme. address (String, 48, CONDITIONAL) – The physical location where the transaction occurred, or the business location for virtual transactions. REQUIRED for PayFac-enabled transactions. state (String, 6, CONDITIONAL) – The ISO country subdivision code of the PayFac’s submerchant. REQUIRED for PayFac-enabled transactions. phone (String, 18) – The phone number of the PayFac’s submerchant that can be used for transaction inquiries. Recommended for PayFac-enabled transactions. Press here for more information.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this parameter is used for idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
clientUniqueId ^String(45) ^Optional	The unique transaction ID in the merchant system. It appears in a DMN as the merchant_unique_id parameter.

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
clientUniqueId ^String(255)	The unique transaction ID in the merchant system.
internalRequestId ^Integer(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
status ^String(20)	The cashier status of a merchant request. Possible values: SUCCESS, ERROR
transactionStatus ^String(20)	The Gateway transaction status.
paymentOption ^Class	Represents the data retrieved from the processed payment method. It can be either card or userPaymentOptionId. • card (Class) – Information about the card that was processed:  ▫ bin (String) – The BIN number representing the issuer.  ▫ last4Digits (String) – The last four digits of the card number.  ▫ ccCardNumber (String) – The credit card number in a mask (for example: ***1111).  ▫ ccExpMonth (String) – The expiration month.  ▫ ccExpYear (String) – The expiration year.  ▫ cardBrand (String) – The card brand used in the transaction.   Possible values: VISA, MASTERCARD, AMEX  ▫ threeD (class) – Contains the required 3DS information. Refer to threeD Output Class for details. OR • userPaymentOptionId (String) – Identifies a payment option that already has been used by the customer and is now requested for re-use. Nuvei keeps the payment option details from a previous use.
merchantDetails ^Class	customField1 (String, 255) … customField15 (String, 255) This allows the merchant to send information with the request to be saved in the API level and returned in response.
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, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwErrorCode ^Integer(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^Integer(11)	The error code if an error occurred on the bank’s side. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
version ^String(10)	The current version of the API method. The current version is 1.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
transactionId ^String(20)	The Gateway transaction ID.
authCode ^String(128)	The authorization code of the transaction.
transactionType ^String(45)	The type of transaction: Sale or Auth. Sale – Performs a regular payment request. Auth – Performs an authorization only request. Press here for more information.
customData ^String(255)	Can be used to pass any type of information. If sent in the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back office tool for transaction reporting and is returned in the response.
fraudDetails ^Class	finalDecision (String) score (decimal) recommendations (String) system (Array) [systemId (String), systemName (String), decision (String)] rules (Array) [ruleId (String), ruleDescription (String)] score refers to a number between 0 and 1 that indicates the probability of a transaction becoming fraudulent, which is calculated using a risk machine learning model. system refers to which risk management system provided the fraud information. The provider can be Nuvei (systemId=1) or an external provider. rules refers to the risk management system rules triggered by the transaction. decision refers to the risk management system decisions regarding the rules that were triggered by the transaction. There are five possible values for the decision parameter: • Accept – The risk management system accepts the transactions. • Reject – The risk management system rejects the transaction. The transaction is not passed to bank for authorization. The reasons are returned in ruleDescription parameter. • Review – The risk management system flags a transaction for review, but still accepts the transaction. • Error – An error occurred during the risk management system operation. The Gateway continues to process the transaction through the bank. • None – No risk analysis was performed. The Gateway continues to process the transaction through the bank. finalDecision refers to when deciding whether to accept or reject a transaction. The risk management system bases its finalDecision on individual decisions made regarding rules triggered. If none of the rules leads to a Reject decision, the finalDecision accepts the transaction. If at least one of the rules leads to a Reject decision, the finalDecision rejects the transaction. To receive this information in the response, special configurations are required. For more information, please contact Nuvei’s Integration Support Team.
orderId ^String(20)	The ID returned from the merchantOrderID input parameter in update and payment methods. This parameter is returned to define which merchant order to update.
clientRequestId ^String(20)	The unique ID of the API request in the merchant system.

Class Objects

threeD Input Class

This class contains the 3DS information required as an input for /payment, /authorize3d or /p2pPayment to perform the 3DS authorization request (the first /payment call).

Press here for more information.

Parameter	Description
v2AdditionalParams ^Class ~Required for 3DS	For the list of parameters in this class, see the v2AdditionalParams class below.
browserDetails ^Class ~Required for 3DS	For the list of parameters in this class, see the browserDetails class below. NOTE: browserDetails is not supported in an /openOrder call.
notificationURL ^String(256) ~Required for 3DS	The notification URL to which the browser is directed after the challenge completion, and to which the issuer should send the CRes message.
merchantURL ^String(2048) ~Required for 3DS	The URL of the merchant’s fully qualified website.
version ^String(8) ~Required for 3DS	The number of the 3DS version used, as indicated by the value returned from /initPayment.
methodCompletionInd ^String(1) ~Required for 3DS	Indicates whether the 3DS fingerprint challenge was successfully completed. Y – Successfully completed N – Did not successfully complete U – Unavailable (3DS Method URL was not provided in the /initPayment response)
platformType ^String(2) ~Required for 3DS	The device channel. 01 – App-based (only for SDK implementation, not in the scope of this document) 02 – Browser
externalMpi ^Class ~Required for External MPI	For the list of parameters in this class, see the externalMpi Class below.
mpiExemptionRequestReason ^String(25) %%Conditional	If the merchant has submitted an exemption requested using mpiChallengePreference, this parameter displays the reason for the request. Possible values: LowValuePayment, TransactionRiskAnalysis NOTE: You can use mpiChallengePreference, mpiExemptionRequestReason, and externalRiskScore to increase the chances for a 3DS exemption.
mpiChallengePreference ^String(25) ^Optional	Can be used either during an Authentication request when Nuvei is the 3DS MPI or during an Authorization request without any prior authentication when the transaction amount allows it. Please contact our Risk Team to set this threshold amount. Possible values: ChallengeRequest, ExemptionRequest, NoPreference NOTE: You can use mpiChallengePreference, mpiExemptionRequestReason, and externalRiskScore to increase the chances for a 3DS exemption.
externalRiskScore ^String(3) ^Optional	If you wish to request an exemption prior to the Authentication request when Nuvei is your 3DS MPI, you should provide the risk assessment that you have calculated for the transaction. Alternatively, you can use this parameter during an Authorization request without any prior authentication when the transaction amount allows it. Please contact our Risk Team to set the risk score below which an exemption can be given. Valid values are 0–100 where 0 is lowest risk and 100 is the highest risk. NOTE: Nuvei’s Fraud Engine considers this value if coordinated in advance with our Risk Team.
account ^Class ^Optional	For the list of parameters in this class, see the account class below.

v2AdditionalParams

Parameter	Description
challengeWindowSize ^String(2) ~Required for 3DS	The dimensions of the challenge window. 01 – 250 x 400 02 – 390 x 400 03 – 500 x 600 04 – 600 x 400 05 – Full screen
rebillExpiry ^String(8) %%Conditional	Recurring Expiry in the format: YYYYMMDD. REQUIRED if isRebilling = 0. We recommend setting rebillExpiry to a value of no more than 5 years from the date of the initial transaction processing date.
rebillFrequency ^String(4) %%Conditional	Recurring Frequency in days. REQUIRED if isRebilling = 0.
challengePreference ^String(2) ^Optional	The merchant’s challenge/exemption preference that is sent to the issuer during the 3DS decision stage. Please contact our Risk Team to set this threshold amount. Possible values: 01 – Challenge requested – The merchant prefers that the issuer performs a challenge, and that the issuer ultimately accepts liability for the payment. 02 – Exemption requested – The merchant is willing to accept the risk (liability) for the payment. 03 – No preference – This is the same as not sending this optional parameter. NOTE: It is preferable not to send the optional challengePreference parameter. Instead, it is highly recommended to use the Nuvei Risk Engine (which is configured with your “challenge preferences” in your merchant account). The Risk Engine makes the “risk decision” based on proven industry best practices, and is customized to your own “challenge preferences”. Contact our Risk Team to enable the Risk Engine in your merchant account and configure your “challenge preferences”.
deliveryEmail ^String(254) ^Optional	For electronic delivery, the email address to which the merchandise was delivered.
deliveryTimeFrame ^String(2) ^Optional	Indicates the merchandise delivery time frame. 01 – Electronic Delivery 02 – Same day shipping 03 – Overnight shipping 04 – 2-day or more shipping
giftCardAmount ^String(15) ^Optional	For a prepaid or gift card purchase, the total purchase amount of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).
giftCardCount ^String(2) ^Optional	For a prepaid or gift card purchase, the total number of individual prepaid or gift cards/codes purchased.
giftCardCurrency ^String(3) ^Optional	For a prepaid or gift card purchase, the 3-letter ISO currency code of the gift card.
preOrderDate ^String(8) ^Optional	For a pre-ordered purchase, the expected date that the merchandise is available in the format: YYYYMMDD.
preOrderPurchaseInd ^String(2) ^Optional	Indicates whether cardholder is placing an order for merchandise with a future availability or release date. 01 – Merchandise available 02 – Future availability
reorderItemsInd ^String(2) ^Optional	Indicates whether the cardholder is reordering previously purchased merchandise. 01 – First time ordered 02 – Reordered
shipIndicator ^String(2) ^Optional	Indicates the selected shipping method for the transaction. 01 – Ship to cardholder’s billing address 02 – Ship to another verified address on file with merchant 03 – Ship to address that is different than the cardholder’s billing address 04 – “Ship to Store”/Pickup at local store (store address shall be populated in shipping address parameters) 05 – Digital goods (includes online services, electronic gift cards and redemption codes) 06 – Travel and event tickets, not shipped 07 – Other (for example: gaming, digital services not shipped, e-media subscriptions, etc.)

browserDetails

Parameter	Description
acceptHeader ^String(2048) ~Required for 3DS	Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder’s browser. Value accepted: If the total length of the accept header sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion.
ip ^String(45) ~Required for 3DS	The IP address of the browser as returned by the HTTP headers to the 3DS Requestor. Value accepted: • IPv4 address is represented in the dotted decimal format of 4 sets of decimal numbers separated by dots. The decimal number in each and every set is in the range 0 to 255. Example IPv4 address: 1.12.123.255 • IPv6 address is represented as eight groups of four hexadecimal digits, each group representing 16 bits (two octets). The groups are separated by colons (“:”). Example IPv6 address: 2011:0db8:85a3:0101:0101:8a2e:0370:7334
javaEnabled ^Boolean %%Conditional for 3DS	Represents the ability of the cardholder browser to execute Java. REQUIRED when javaScriptEnabled is TRUE. Value is returned from the navigator.javaEnabled property. Possible values: TRUE, FALSE
javaScriptEnabled ^Boolean ~Required for 3DS	Determines whether the browser is JavaScript enabled (from navigator.javaScriptEnabled property). Possible values: TRUE, FALSE
language ^String(8) ~Required for 3DS	Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property.
colorDepth ^String(2) ~Required for 3DS	Value representing the bit depth of the color palette for displaying images, in bits per pixel. Obtained from cardholder browser using the screen.colorDepth property. Possible values: 1, 4, 8, 15, 16, 24, 32, 48
screenHeight ^String(6) ~Required for 3DS	Total height of the cardholder’s screen in pixels. Value is returned from the screen.height property.
screenWidth ^String(6) ~Required for 3DS	Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property.
timeZone ^String(5) ~Required for 3DS	Time difference between UTC time and the cardholder browser local time, in minutes. Value accepted: Value is returned from the getTimezoneOffset() method.
userAgent ^String(2048) ~Required for 3DS	Exact content of the HTTP user-agent header. Value accepted: If the total length of the user-agent header sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion.

account

Parameter	Description
age ^String(2) ^Optional	Length of time that the cardholder has had the account with the 3DS Requestor. 01 – No account (payment as a guest). 02 – Created during this transaction. 03 – Less than 30 days. 04 – 30–60 days. 05 – More than 60 days.
lastChangeDate ^String(8) ^Optional	Date (in format YYYYMMDD) that the cardholder’s account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added.
lastChangeInd ^String(2) ^Optional	Length of time since the cardholder’s account information with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added. 01 – Changed during this transaction 02 – Less than 30 days 03 – 30–60 days 04 – More than 60 days
registrationDate ^String(8) ^Optional	Date that the cardholder opened the account with the 3DS Requestor in the format: YYYYMMDD.
passwordChangeDate ^String(8) ^Optional	Date that cardholder’s account with the 3DS Requestor had a password change or account reset in the format: YYYYMMDD.
resetInd ^String(2) ^Optional	Indicates the length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset. 01 – No change 02 – Changed during this transaction 03 – Less than 30 days 04 – 30–60 days 05 – More than 60 days
purchasesCount6M ^String(4) ^Optional	Number of purchases with this cardholder account during the previous six months.
addCardAttempts24H ^String(3) ^Optional	Number of Add Card attempts in the last 24 hours.
transactionsCount24H ^String(3) ^Optional	Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.
transactionsCount1Y ^String(3) ^Optional	Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year. NOTE: The value cannot exceed 3 characters.
cardSavedDate ^String(8) ^Optional	The date on which the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
cardSavedInd ^String(2) ^Optional	Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
addressFirstUseDate ^String(8) ^Optional	Date when the shipping address used for this transaction was first used with the 3DS Requestor in the format: YYYYMMDD.
addressFirstUseInd ^String(2) ^Optional	Indicates when the shipping address used for this transaction was first used with the 3DS Requestor. 01 – This transaction 02 – Less than 30 days 03 – 30–60 days 04 – More than 60 days
nameInd ^String(2) ^Optional	Indicates if the cardholder name on the account is identical to the shipping name used for this transaction. 01 – Account name identical to shipping name 02 – Account name different than shipping name
suspiciousActivityInd ^String(2) ^Optional	Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account. 01 – No suspicious activity has been observed 02 – Suspicious activity has been observed

threeD Output Class

This class contains the 3DS information returned from the call to the /payment or /authorize3d methods after performing the 3DS authorization request (the first /payment call).
Press here for more information.

The output parameters are separated into two parts:

• Parameters returned following the first call to /payment or /verify3d requiring a challenge
• Parameters returned after the challenge or after a successful frictionless (either first or second) call.

First Call 3DS Response Parameters

The following parameters are returned on the first call to /payment or /verify3d:

PARAMETER	DESCRIPTION
acsUrl ^String	URL or endpoint used to redirect the consumer to the card issuer/bank’s 3DS verification page.
acsChallengeMandate ^String(1)	The 3DS challenge required indication. Possible values: N – Not required Y – Required
cReq ^String	The Base64 encoded cReq relevant for 3DS. acsUrl is also sent as a separate parameter.
threeDFlow ^String	Indicates which 3DS flow is taking place: • If the Gateway response parameter for threeDFlow = 1, the transaction is converted from Sale3D to Auth3D after passing the Gateway rule engine (acsUrl is returned and the merchant needs to redirect to issuer and call payment3D method afterwards). • If the Gateway response parameter for threeDFlow = 0, the transaction is converted from Sale3D to Sale or Auth depending on the configured merchant mode of operation after passing the Gateway rule engine. (acsUrl is NOT returned and the merchant does NOT need to redirect to issuer or call payment3Dmethod later on).
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
transactionId ^String(20)	The Gateway transaction ID.
threeDReasonId ^String	Reason ID for a failed 3DS authorization as received from the issuer. Press here for more information.
threeDReason ^String	Reason description for a failed 3DS authorization as received from the issuer. Press here for more information.
challengePreferenceReason ^String	This value is returned following a 3DS challenge and describes the reason for challenge. Press here for more information.
challengeCancelReasonId ^String	Reason ID for a canceled 3DS authorization as received from the issuer.
challengeCancelReason ^String	Reason description for a canceled 3DS authorization as received from the issuer.
isLiabilityOnIssuer ^String	Indicates if there is 3DS liability shift. If equal to “1” – Liability shift is present. If equal to “0”, empty or null – No liability shift has occurred.
isExemptionRequestInAuthentication ^String	Indicates if an exemption was requested during authorization.
flow ^String	The 3DS flow required by the issuer. Possible values: challenge, frictionless, exemption, softDecline, none
acquirerDecision ^String	The acquirer’s request from the merchant to perform a certain flow. Possible values: ChallengeRequest, ExemptionRequest
decisionReason ^String	The description of the acquirer’s decision. Press here to see a table that presents the possible values.

Final Call 3DS Response Parameters

The following parameters are returned after the challenge or after a successful frictionless response (either first or second call):

PARAMETER	DESCRIPTION
result ^String(1)	Returned only from the SECOND payment. Indicates whether a transaction qualifies as an authenticated transaction or as an account verification. Possible values: Y – Authentication Verification Successful. N – Not Authenticated/Account Not Verified; Transaction denied. U – Authentication/Account verification could not be performed; technical or other problem, as indicated in ARes or RReq. A – Attempts Processing Performed; Not authenticated/verified, but a proof of attempted authentication/verification is provided. C – Challenge required; Additional authentication is required using the CReq/CRes. D – Challenge Required; Decoupled Authentication confirmed. R – Authentication/Account Verification Rejected; Issuer is rejecting. NOTE: The Final CRes message can contain only a value of Y or N. NOTE: If the 3DS Requestor Challenge Indicator = 06 (No Challenge Requested; data share only), then a Transaction Status of C is not valid.
whiteListStatus ^String	Indicates if this consumer defined this merchant as whitelist or not. If the consumer defined the merchant, then this is the reason the challenge did not happen. Possible values: Y – 3DS Requestor is whitelisted by cardholder. N – 3DS Requestor is not whitelisted by cardholder. E – Not eligible as determined by issuer. P – Pending confirmation by cardholder. R – Cardholder rejected. U – Whitelist status unknown, unavailable, or does not apply.
cavv ^String(28)	A cryptogram created by the issuer that serves as a proof that the merchant is entitled to this authentication.
eci ^String	Indicates the level of security used in a 3DS program when the cardholder provides payment information to the merchant. Press here for possible eci data values.
threeDReason ^String	If the attempt failed, this parameter is returned by the banks to indicate the reason the transaction was not passed as full 3D. Returned in the end of the 3DS after successful frictionless.
authenticationType ^String(2)	The type of authentication performed during the 3DS challenge. If the merchant wants to react differently for each authentication type, it is possible per the value returned. Possible values: 01 – Static 02 – Dynamic 03 – OOB 04 – Decoupled 05–79 – Reserved for EMVCo future use, values invalid until defined by EMVCo 80–99 – Reserved for DS use Returned on a second call to /payment or /verify3d following a challenge.
cardHolderInfoText ^String(128)	The text provided by the ACS/Issuer to the cardholder during a frictionless transaction that was not authenticated by the ACS/Issuer. For example: “Additional authentication is needed for this transaction. Please contact [Issuer Name] at xxx-xxx-xxxx.” If this parameter is provided, the merchant must display the information to the cardholder.

externalMpi Class

If you use an external MPI provider to perform the 3DS authorization independently from Nuvei, you can use the following set of parameters to process with us, based on the output you received from you other MPI provider.

Press here for more information.

PARAMETER	DESCRIPTION
cavv ^String(50) ~Required	The card authentication verification value as received from the MPI.
dsTransID ^String(36) ~Required	The transaction ID received from the MPI for 3DS.
eci ^String(2) %%Conditional	Indicates the level of security used in a 3DS program when the cardholder provides payment information to the merchant. Press here for possible eci data values. REQUIRED for credit/debit cards and optional for Google Pay and Apple Pay.
exemptionRequestReason ^String(25) %%Conditional	If challengePreference is populated with a value of “ExemptionRequest”, then this parameter becomes REQUIRED and displays the reason for the request. Possible values: AddCard, AccountVerification, LowValuePayment, TransactionRiskAnalysis
externalTokenProvider ^String(45) %%Conditional	The name of the external token provider (Apple Pay, Google Pay). The merchant uses this parameter ONLY when they perform self-decryption of the external token. For an example, press here.
challengePreference ^String(25) ^Optional	If your MPI has already requested an exemption in the authentication and the issuer has approved the exemption request, you should provide Nuvei with this parameter value to allow us to adjust our exemption flag accordingly so it is synchronized according to EMVCO and schemes guidelines. Possible values: ExemptionRequest, NoPreference

externalToken Class

When the merchant provides a network token, include this class in the request.

The externalToken class supports:

• Network (card scheme) tokens – For examples of /payment and /payout requests when the merchant provides the network token and cryptogram, press here.
• External network token providers – For examples of requests, see:
  
  • Apple Pay
  • Google Pay
  To enable external network token providers for your merchant account, contact Nuvei’s Integration Support Team.

PARAMETER	DESCRIPTION
externalTokenProvider ^String(45) %%Conditional	The name of the external token provider. REQUIRED when providing an Apple Pay or Google Pay token. Possible values: ApplePay, GooglePay.
cryptogram ^String(50) %%Conditional	One-time encrypted 3DS CAVV (Cardholder Authentication Verification Value) the external network provider uniquely generates for a specific transaction. If a decrypted Google Pay token does not contain a cryptogram, this parameter is not required. REQUIRED in all other cases when the merchant decrypts the token.
mobileToken ^String(5000) %%Conditional	Encrypted token from Apple Pay or from Google Pay. REQUIRED when Nuvei decrypts the token.
eciProvider ^String(2) ^Optional	When the merchant decrypts the token, the eci value from the card scheme or from the external network provider.
networkTokenNumber ^String(20) %%Conditional	Alternative to the Primary Account Number (PAN) and unique to each shopper-merchant pairing. REQUIRED when providing a network token.
networkTokenCryptogram ^String(28) %%Conditional	Encrypted cryptogram the card schemes provide for all transaction types except MITs. Relevant when the merchant provides a network token.
tokenAssuranceLevel ^String(2) ^Optional	Value indicating the confidence level of the token-to-Account-PAN binding. Relevant when the merchant provides a network token.
tokenRequestorId ^String(11) ^Optional	Identifies the token requestor. Relevant when the merchant provides a network token.

storedCredentials Class

This class is set under the card class and is used by the cardholder to authorize a merchant to store the cardholder’s payment details during a transaction, so that in future transactions, the payment details do not need to be entered again. Press here for an example.

PARAMETER

DESCRIPTION

storedCredentials ^Class ^Optional

storedCredentialsMode This parameter shows whether or not stored tokenized card data is sent to execute the transaction. Possible values: 0 – The card data was entered for the first time, and, upon completion of the transaction, is tokenized and stored for future transactions. 1 – Previously tokenized and stored card data was used to perform the transaction. This parameter is only applicable to merchants that store tokenized card data. Merchants that do not store card data or that are using Nuvei’s tokenization feature should not send this parameter.

addendums Class

This class contains industry specific addendums. The addendum parameters are based on the specific addendum type. Currently, there are 4 main subclasses:

• airlines
• localPayment
• l23processingData
• lodging
• marketplace

airlines

When processing airline ticket payments, simply include the Airline addendum, which specifies details for flights, flight legs and passengers. In addition, by sending these airline payments using our Authorization request, you automatically benefit from Nuvei’s proprietary risk rules, which are optimized for Airline fraud screening.

Press here for more information.

reservationDetails

PARAMETER	DESCRIPTION
pnrCode ^String ~Required	The Passenger Name Record in the airline reservation system (1 passenger per Settle or Sale transaction).
bookingSystemUniqueId ^String ~Required	The unique identifier of the reservation in the global distribution system (1 passenger per Settle or Sale transaction).
computerizedReservationSystem ^String ~Required	The name of the reservation system.
ticketNumber ^String ~Required	The airline company unique ticket number. If multiple tickets are purchased with one transaction, the primary ticket number is provided. Format: [airline’s 3-digit ticketing code]-[4-digit form number]-[6-digit serial number, and sometimes a check digit]
documentType ^String ~Required	The type of the issued document. Possible values: TKT – electronic ticket OT – other/ancillary
flightDateUTC ^String ~Required	The flight date of the first leg according to Global UTC time (“YYYY-MM-DD HH:MM:SS”)
issueDate ^String ~Required	The date that the ticket was last issued in the airline reservation system (“YYYY-MM-DD HH:MM:SS”).
travelAgencyCode ^String ~Required only for travel agency	The IATA travel agency code.
travelAgencyName ^String ~Required only for travel agency	The name of the travel agency.
travelAgencyInvoiceNumber ^String ~Required only for travel agency	The reference number of the invoice that was issued by the travel agency.
travelAgencyPlanName ^String ^Optional	The airplane type code (ICAO code). NOTE: Unfortunately, the travelAgencyPlanName parameter name has a “known-typo”, but you should use it as-is because this is the way it has been coded in the REST API.
restrictedTicketIndicator ^String ^Optional	Indicates whether the ticket is restricted (refundable). Possible values: Restricted, NotRestricted
issuingCarrierCode ^String %%Conditional	The airline code of the airline issuing the ticket. https://en.wikipedia.org/wiki/Airline_codes https://www.iata.org/en/publications/directories/code-search/ REQUIRED for Airline aggregators.
isCardholderTraveling ^String ^Optional	Indicates whether the cardholder is also a passenger.
passengersCount ^String ^Optional	The number of passengers associated with the ticket.
infantsCount ^String ^Optional	The number of infant passengers associated with the ticket.
payerPassportId ^String ~Required	The ticket Payer Unique passport number. This should match the physical passport issue number.
totalFare ^String ^Optional	The total fare for all legs on the ticket excluding taxes and fees.
totalTaxes ^String ^Optional	The total taxes for all legs on the ticket.
totalFee ^String ^Optional	The total fee for all legs on the ticket.
boardingFee ^String ^Optional	The chargeable amount for boarding the plane.
ticketIssueAddress ^String ^Optional	The address of the place/agency that issued the ticket.

reservationDetails.passengerDetails

PARAMETER	DESCRIPTION
passportNumber ^String ~Required	The passenger Unique passport number. This should match the physical passport issue number.
customerCode ^String ^Optional	The unique identifier of the customer in the Airline.
frequentFlyerCode ^String ^Optional	The unique identifier of the customer.
title ^String ~Required	The title of the passenger.
firstName ^String ~Required	The first name of the passenger.
lastName ^String ~Required	The last name of the passenger.
passengerName ^String ~Required	The full name of the passenger.
middleName ^String ~Required (if it exists)	The middle name of the passenger.
dateOfBirth ^String ~Required	The date of birth of the passenger (“YYYY-MM-DD HH:MM:SS”). This should match the passport data.
phoneNumber ^String ^Optional	The passenger phone number. This can contain country code + or () symbols.

reservationDetails.flightLegDetails

PARAMETER	DESCRIPTION
airlineCode ^String ~Required	The 2-character airline code as set by IATA.
flightNumber ^String ~Required	The unique identifier of the flight number.
departureDate ^String ~Required	The date and time of travel in local time at the departure airport.
arrivalDate ^String ~Required	The date and time of travel in local time at the arrival airport.
departureCountry ^String ~Required	The 2-character ISO departure country code.
departureCity ^String ~Required	The departure city name.
departureAirport ^String ~Required	The 3-letter ISO departure airport code of the flight leg according to the IATA official directory.
destinationCountry ^String ~Required	The 2-character ISO destination country code.
destinationCity ^String ~Required	The destination city name.
destinationAirport ^String ~Required	The 3-letter ISO destination airport code of the flight leg according to the IATA official directory
type ^String ^Optional	The flight classification. Possible values: Domestic, International
flightType ^String ~Required if “Risk Pre-authorization Screening” services are required	The route type of the fight. Possible values: round trip, one way
ticketDeliveryMethod ^String ^Optional	Indicates how the ticket was provided to the recipient. Possible values: P – Physical E – Electronic
ticketDeliveryRecipient ^String, ^Optional	The name of the ticket delivery recipient.
fareBasisCode ^String ^Optional	The alphanumeric code for the “booking class” of a ticket such as “Business Class”, “Discounted”, or “Non-refundable” (see https://en.wikipedia.org/wiki/Fare_basis_code).
serviceClass ^String ^Optional	Indicates the class of service and fare level to which the passenger is entitled.
seatClass ^String ^Optional	The seat class.
stopOverCode ^String ~Required	The stopover code(s) and official city airport code(s) for up to four flight segments per addendum record. Possible values: O – Destination city X – Connecting city blank
departureTaxAmount ^String ^Optional	The departure tax amount charged by a country when a person is leaving the country.
departureTaxCurrency ^String ^Optional	The 3-letter ISO code of the departure tax currency.
fareAmount ^String ^Optional	The amount of the ticket for the current leg of the trip, excluding taxes and fees.
feeAmount ^String ^Optional	The fee amount for current leg of the trip.
taxAmount ^String ^Optional	The amount of the taxes for current leg of the trip.
layoutIntegererval ^String ^Optional	The time between flight legs in minutes.

localPayment

This addendum allows your customer to pay in installments when using a credit card.

Press here for more information.

PARAMETER	DESCRIPTION
numberOfInstallments ^String(255) %%Conditional	The total number of installments (including the first installment). REQUIRED for all transactions with installments.
nationalId ^String(255) %%Conditional	The user’s national ID number. REQUIRED when processing is performed by local banks in certain regions or countries, such as Latin America (LATAM) and Israel.
installmentType ^String(1) %%Conditional	The type of installment. Possible values: 1 – Deferred with interest. 2 – Deferred without interest. 3 – Deferred without interest and months of grace. REQUIRED for installment transactions in Mexico.
debitType ^String(255) %%Conditional	The type of debit. Possible values: 1 – Singular payment 2 – Installments 3 – Special debit REQUIRED only for transactions performed via CreditGuard bank.
fundAnticipationType ^String(3) ^Optional	The scheduling plan of the transaction funding. Possible values: STD – Each payment is being funded according to the original payment plan. A01 – The total transaction amount is being funded after one day. A30 – The total transaction amount is being funded after 30 days. Relevant only for transactions performed in Brazil. NOTE: This parameter is relevant for /openOrder and /payment.

The following parameters are relevant for payment in Colombia only. Press here for more information.

PARAMETER	DESCRIPTION
vatAmount ^String(12) ^Optional	The amount of the consumption tax placed on a product whenever value is added at each stage of the production or distribution chain.
nationalConsumptionTaxAmount ^String(12) ^Optional	The amount of the tax levied by the government on the sale of goods and services within a country.
taxAmountBase ^String(12) ^Optional	The purchase amount in the domestic currency and the amount based on the taxes that were calculated.
tipAmount ^String(12) ^Optional	The tip amount paid during the purchase transaction.
taxCurrencyCodeBase ^String(3) ^Optional	The 3-letter ISO currency code.
airportChargeAmount ^String(12) ^Optional	The amount of the fee imposed on passengers to cover the costs associated with airport services and infrastructure.

l23processingData

This addendum allows sending optional data with your settle request to receive a better interchange rate per transaction.

Press here for more information.

lodging

This addendum allows sending optional data with your settle request for lodging or a cruise.

Press here for more information.

marketplace

This addendum class is required by some APM providers for Marketplace merchants to comply with that provider’s payment requirements.

Press here for more information.

Payment Page

Payment Page

The quickest way to integrate with Nuvei and benefit from all our features is via our Payment Page solution. With our Payment Page, you only need to load the page via IFrame or perform a full-page redirect, and all features and functionalities are seamlessly integrated.

In addition, you can even perform basic customization of your payment page via the Page Builder menu located in the Control Panel. Speak to your account manager regarding more complex customization.

For more information, please refer to Payment Page.

Webhooks (DMNs)

Webhooks (DMNs)

After the merchant sends a payment transaction to Nuvei, Nuvei communicates with the customer’s bank to transfer the deposit from the customer’s account to the merchant’s account. When Nuvei receives a response from the bank, Nuvei notifies the merchant of the result of the deposit via a webhook, which in Nuvei documentation is more commonly referred to as a Direct Merchant Notification (DMN).

Additional Services

Additional Services

Nuvei also offers the following additional services, which can be found at the following links:

• Frontend Tokenization API
• Payment Options API
• Advanced APM Integration Overview
• Domain Registration
• Rebilling
• Withdrawals API
• Pre-chargeback
• KYC API