We changed, SafeCharge becomes Nuvei.
Navbar
Icons nuvei logo
Api logo first
JSON Node.JS java php C#

API Reference Home

Introduction

Welcome to the Nuvei API developers portal.

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

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 payment gateway.

Using this API reduces the PCI burden from the merchant side. A merchant is only required to submit a SAQ A-EP form and perform periodical scans by Approved Scanning Vendors (ASV).

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


 

Web SDK

Web SDK Overview

The Web SDK is Nuvei’s newest integration method. This is a JavaScript library that you can use on your own payment page to perform end-to-end payments.

The main strength of the Web SDK is that it is very simple to integrate, yet does not require any PCI whatsoever, giving you complete control over the UI and UX.

For a full explanation of the Web SDK, its advantages and a complete guide, please refer to our Web SDK chapter in our main documentation portal. There you can find the following topics:

 

Web SDK Methods

createPayment()

Use this method to perform end-to-end card payment processing. The method receives any form of cardholder information, either tokenized or not, and performs the process through to the end, including seamlessly performing any 3D-Secure or PCI requirement.

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

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

Code Sample:

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

sfc.createPayment({
    "sessionToken": result.sessionToken, //received from openOrder API 
    "merchantId": '1475082432483184221', //as assigned by Nuvei
    "merchantSiteId": '184941', //as assigned by Nuvei
    "clientUniqueId": "695701003", // optional
    "paymentOption": {
        "card": {
            "cardNumber": "5111426646345761",
            "cardHolderName": document.getElementById('example1-name').value,
            "expirationMonth": "12",
            "expirationYear": "25",
            "CVV": "217"
        },
        "billingAddress": {
            "email": "someone@somedomain.com",
            "county": "GB"
        }

    }
}, function(res) {
    console.log(res)
    if (res.cancelled === true) {
        example.querySelector('.token').innerText = 'cancelled';
    } else {
        example.querySelector('.token').innerText = res.transactionStatus +
            ' - Reference: ' + res.transactionId;
    }
    example.classList.add('submitted');
})

Input

Input Parameters

PARAMETER DESCRIPTION
sessionToken ^String ~Required The sessionToken retrieved from a call to /openOrder that references the created order in Nuvei system.
merchantId ^String(20) ~Required Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required Merchant Site ID provided by Nuvei.
paymentOption ^Class ~Required This class represents the details on the payment method. The best practice is to populate Nuvei Fields.
If you wish to explicitly set it, it can be done with one of 3 options:

• card – Represents a credit/debit card. Fields:
    ▫ cardNumber (String, 20, REQUIRED) – The card number.
    ▫ cardHolderName (String, 70, REQUIRED) – The card holder 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.

OR

• alternativePaymentMethod – Represents an alternative payment method. Please refer to APM Input Fields for details.

OR

• userPaymentOptionId – This is a field identifying 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 previous uses. Can be used with:
    ▫ expirationMonth (String, 2) – For a newer card expiration.
    ▫ expirationYear (String, 4) – For a newer card expiration.
    ▫ CVV (String, 4) – Recommended for high risk merchants.
billingAddress ^Class ~country and email 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)
lastName (String, 40)
address (String, 60)
address2 (String, 60)
phone (String, 18)
zip (String, 10)
city (String, 30)
state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
county (String, 255)

These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.
clientUniqueId ^String(45) ^Optional The ID of the transaction in the merchant’s system. This value must be unique.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.

In addition, you can send the fields that appear in the following table. You can send these fields either with the preceding authentication server-side or /openOrder API call or directly to createPayment().

Additional Input Parameters

PARAMETER DESCRIPTION
userDetails ^Class ^Optional firstName (String, 30)
lastName (String, 40)
address (String, 60)
phone (String, 18)
zip (String, 10)
city (String, 30)
country (String, 2) – 2-letter ISO country code
state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
email (String, 100)
county (String, 255)
language (String, 2) – 2-letter ISO language code.
dateOfBirth (String, 10) – Format is YYYY-MM-DD.
shippingAddress ^Class ^Optional firstName (String, 30)
lastName (String, 40)
address (String, 60)
phone (String, 18)
zip (String, 10)
city (String, 30)
country (String, 2) – 2-letter ISO country code
state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
email (String, 100)
shippingCounty (String, 255)
merchantDetails ^Class ^Optional customField1 (String, 255)
…
customField15
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.

Output

The createPayment response comes in two steps:

Code Sample:

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",
  "userPaymentOptionId": "14958143",
  "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 merchant request. Possible statuses:
APPROVED
DECLINED
ERROR
errCode ^String(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 Errors Handling. In addition, it can have the value of “-5”, which means the 3D-Secure process was aborted.
errorDescription ^String(400) If an error occurred on the request side, an error reason is returned in this parameter; for example, failure in checksum validation, timeout from processing engine, etc.
Values as detailed in Errors Handling. In addition, it can have the value of “General 3D error”, which means the 3D-Secure process was aborted.
Canceled ^Boolean 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(2) 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.
userPaymentOptionId ^String This field represents the ID for the newly created payment option, which can be referenced in future requests.
Refer to Card-on-File for further details.
threeDReasonId ^String Reason ID for a failed 3D-Secure authorization as received from the issuer.
threeDReason ^String Reason description for a failed 3D-Secure authorization as received from the issuer.
challengeCancelReasonId ^String Reason ID for a canceled 3D-Secure authorization as received from the issuer.
ChallengeCancelReason ^String Reason description for a canceled 3D-Secure authorization as received from the issuer.
isLiabilityOnIssuer ^String Indicates if there is 3D-Secure 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.
challengePreferenceReason ^String This value is returned following a 3D-Secure v2 challenge and describes the reason for challenge. Click here for more details.
preventOverride ^Boolean Enables the merchant to override /openOrder with Web SDK fields:
shippingAddress
userDetails
BillingAddress
merchantDetails
If equal to “0” – Allows override by Web SDK. This is the default.
If equal to “1” – Prevents override by Web SDK. Nuvei will ignore any Web SDK input of these fields and will use the ones provided on /openOrder, even if these are blank.

getApms()

This function 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 field 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 function 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.

Code Sample:

1

sfc.getApms({ "type": "withdrawal", "currencyCode": "GBP", "countryCode":"GB", "languageCode":"en"}, function(res){console.log(res)})

Input Parameters

PARAMETER DESCRIPTION
currencyCode ^String(3) ^Optional 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.
The 3-letter ISO currency code.
countryCode ^String(2) ^Optional If countryCode is provided, the returned APM set consists only of APMs supported in this country. If not provided, the APM set includes all APMs regardless of where they are supported.
The 2-letter ISO country code.
languageCode ^String(2) ^Optional The language in which the transaction is to be completed.
type ^String ^Optional This is 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
WITHDRAWAL
If no value is sent, then the default value is DEPOSIT.

Output Parameters

PARAMETER DESCRIPTION
merchantId ^String(20) Merchant ID provided by Nuvei.
merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
internalRequestID ^String(20) Nuvei Internal unique request ID (used for reconciliation purposes, etc.).
paymentMethods ^Class An array of payment methods and their attributes:
paymentMethod (String, 50)
paymentMethodDisplayName {language(String, 2), message(String, 400)},
isDirect (String, 5)
countries (String, 2)
currencies (String, 3)
logoURL (String, 255)
Fields:
name (String, 45)
regex (String, 128)
type (String, 45)
validationMessage {language(String, 2), message(String, 400)},caption {language(String, 2), message(String, 400)}
type ^String The type of the payment methods to be returned.
Possible values:
DEPOSIT
WITHDRAWAL. If no value is sent, then the default value is DEPOSIT.
result ^String(20) The status of merchant’s API request/call.
Possible statuses:
APPROVED or ERROR.
errCode ^String(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, timeout from processing engine, etc.) is returned in this parameter.
version ^Integer(10) The current version of your request.
The current version is 1.
clientRequestId ^String(20) ID of the API request in the merchant system.

Code Sample:

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

{
    "paymentMethods": [
        {
            "paymentMethod": "cc_card",
            "paymentMethodDisplayName": [
                {
                    "language": "en",
                    "message": "Credit Card"
                }
            ],
            "countries": [
                "GB"
            ],
            "currencies": [
                "GBP"
            ],
            "logoURL": "https://cdn-int.safecharge.com/ppp_resources/02251608/resources/img/svg/default_cc_card.svg",
            "fields": [
                {
                    "name": "ccCardNumber",
                    "type": "text",
                    "caption": []
                },
                {
                    "name": "ccExpMonth",
                    "type": "text",
                    "caption": []
                },
                {
                    "name": "ccExpYear",
                    "type": "text",
                    "caption": []
                },
                {
                    "name": "ccNameOnCard",
                    "type": "text",
                    "caption": []
                }
            ]
        },
        {
            "paymentMethod": "apmgw_expresscheckout",
            "paymentMethodDisplayName": [
                {
                    "language": "en",
                    "message": "PayPal"
                }
            ],
            "isDirect": "false",
            "countries": [
                "GB"
            ],
            "currencies": [
                "GBP"
            ],
            "logoURL": "https://cdn-int.safecharge.com/ppp_resources/02251608/resources/img/svg/paypal.svg",
            "fields": []
        },
        {
            "paymentMethod": "apmgw_Sofort",
            "paymentMethodDisplayName": [
                {
                    "language": "en",
                    "message": "Sofortuberweisung"
                }
            ],
            "isDirect": "false",
            "countries": [
                "GB"
            ],
            "currencies": [
                "GBP"
            ],
            "logoURL": "https://cdn-int.safecharge.com/ppp_resources/02251608/resources/img/svg/sofort.svg",
            "fields": []
        }

    ],
    "type": "DEPOSIT",
    "sessionToken": "50dd6b3a-ed65-4bae-bb76-184e4a4a00ba",
    "internalRequestId": 178003768,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "479748173730597238",
    "merchantSiteId": "180083",
    "version": "1.0",
}


 

authenticate3d()

Use this method to perform a 3D-only authorization 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 3D-Secure liability shift.

This is also the quickest way for a merchant to migrate to 3D-Secure v2; just call this method on the client side and use the CAVV and ECI method 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 guides for best use of this function:

Code Sample:

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

sfc.authenticate3d({
    "sessionToken": result.sessionToken, //received from openOrder API 
    "merchantId": '1475082432483184221', //as assigned by Nuvei
    "merchantSiteId": '184941', //as assigned by Nuvei
    "clientUniqueId": "695701003", // optional
    "paymentOption": {
        "card": {
            "cardNumber": "5111426646345761",
            "cardHolderName": document.getElementById('example1-name').value,
            "expirationMonth": "12",
            "expirationYear": "25",
            "CVV": "217"
        },
        "billingAddress": {
            "email": "someone@somedomain.com",
            "county": "GB"
        }

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

Input Parameters

PARAMETER DESCRIPTION
sessionToken ^String ~Required The sessionToken retrieved from a call to /openOrder that references the created order in the Nuvei system.
merchantId ^String(20) ~Required Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required Merchant Site ID provided by Nuvei.
paymentOption ^Class ~Required This class represents the details on the payment method. The best practice is to populate Nuvei Fields.
If you wish to explicitly set it, it can be done with one of 2 options:

• card – Represents a credit/debit card. Fields:
    ▫ cardNumber (String, 20, REQUIRED) – The card number.
    ▫ cardHolderName (String, 70, REQUIRED) – The card holder 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.

OR

• userPaymentOptionId – This is a field identifying 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 previous uses. Can be used with:
    ▫ expirationMonth (String, 2) – For a newer card expiration.
    ▫ expirationYear (String, 4) – For a newer card expiration.
    ▫ CVV (String, 4) – Recommended for high risk merchants.
billingAddress ^Class ~country and email 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.
firstName (String, 30)
lastName (String, 40)
address (String, 60)
address2 (String, 60)
phone (String, 18)
zip (String, 10)
city (String, 30)
state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
email (String, 100)
county (String, 255)

These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.
clientUniqueId ^String(45) ^Optional The ID of the transaction in the merchant’s system. This value must be unique.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.

In addition, you can send the fields that appear in the following table. You can send these fields either with the preceding authentication server-side or using the /openOrder API call or directly to authenticate3d().

Additional Input Parameters

PARAMETER DESCRIPTION
userDetails ^Class ^Optional firstName (String, 30)
lastName (String, 40)
address (String, 60)
phone (String, 18)
zip (String, 10)
city (String, 30)
country (String, 2) – 2-letter ISO country code
state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
email (String, 100)
county (String, 255)
language (String, 2) – 2-letter ISO language code.
dateOfBirth (String, 10) – Format is YYYY-MM-DD.
shippingAddress ^Class ^Optional firstName (String, 30)
lastName (String, 40)
address (String, 60)
phone (String, 18)
zip (String, 10)
city (String, 30)
country (String, 2) – 2-letter ISO country code
state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
email (String, 100)
shippingCounty (String, 255)
merchantDetails ^Class ^Optional customField1 (String, 255)
…
customField15
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.

Output

You can get the response in two separate ways (either or both):

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

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

Code Sample:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
    "result": "APPROVED",
    "errCode": "0",
    "errorDescription": "",
    "userPaymentOptionId": "14958143",
    "cavv": "Vk83Y2t0cHRzRFZzRlZlR0JIQXo=",
    "eci": "2",
    "xid": "",
    "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": "",
    "isLiabilityOnIssuer": "1",
    "challengePreferenceReason": "12",
    "cancelled": false
}

Output Parameters

PARAMETER DESCRIPTION
eci ^String(2) The Electronic Commerce Indicator that indicates the level of security used in a 3D 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 3D-Secure program.
7 – Payment authentication was not performed.
Mastercard
2 – The cardholder was successfully authenticated.
1 – The issuer or cardholder does not participate in a 3D-Secure program.
6 – Payment authentication was not performed.
cavv ^String(50) The card authentication verification value as received from the MPI.
xid ^String(50) The transaction ID received from the MPI for 3D-Secure v1.
dsTransID ^String(36) The transaction ID received from the MPI for 3D-Secure v2.
result ^String(20) The cashier status of merchant request. Possible statuses:
APPROVED
DECLINED
ERROR
errCode ^String(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 Errors Handling. In addition, it can have the value of “-5”, which means the 3D-Secure process was aborted.
errorDescription ^String(400) If an error occurred on the request side, an error reason is returned in this parameter; for example, failure in checksum validation, timeout from processing engine, etc.
Values as detailed in Errors Handling. In addition, it can have the value of “General 3D error”, which means the 3D-Secure process was aborted.
Canceled ^Boolean 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(2) 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.
userPaymentOptionId ^String This field represents the ID for the newly created payment option, which can be referenced in future requests.
Refer to Card-on-File for further details.
threeDReasonId ^String Reason ID for a failed 3D-Secure authorization as received from the issuer.
threeDReason ^String Reason description for a failed 3D-Secure authorization as received from the issuer.
challengeCancelReasonId ^String Reason ID for a canceled 3D-Secure authorization as received from the issuer.
ChallengeCancelReason ^String Reason description for a canceled 3D-Secure authorization as received from the issuer.
isLiabilityOnIssuer ^String Indicates if there is 3D-Secure 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.
challengePreferenceReason ^String This value is returned following a 3D-Secure v2 challenge and describes the reason for challenge. Click here for more details.

getToken()

Use this method to get a temporary token (ccTempToken). This is a temporary one-time token.
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 descope.
The return value from the function is ccTempToken, which can then be used in the server-to-server API /payment API call.

Code Sample:

1
2
3
4
5
6
7
8
9

sfc.getToken(sfcCard).then(function(result) {

        if (result.status === 'SUCCESS') {
             console.log(result.paymentOption) //pass the paymentOption to the payment API call
        } else {
            // handle error.

        }
    });


 

Payment API

Payment API Introduction

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

/getSessionToken

Definition

https://ppp-test.safecharge.com/ppp/api/v1/getSessionToken.do
Example Request
1
2
3
4
5
6
7

{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "timeStamp": "20191105081132",
    "checksum": "7e797f2270a1bffd2608a97ecc0fab550a61254f840b76e166aab9c487718b25"
}
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

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

};

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

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

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

This method is not relevant when using Server SDKs. Please refer to the following guide for initialization instructions:
https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/
Example Request
1
2

This method is not relevant when using Server SDKs. Please refer to the following guide for initialization instructions:
https://docs.safecharge.com/documentation/guides/server-sdks/php-sdk/
Example Request
1
2

This method is not relevant when using Server SDKs. Please refer to the following guide for initialization instructions:
https://docs.safecharge.com/documentation/guides/server-sdks/net-sdk/

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.safecharge.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 when the method call is performed in the following format: YYYYMMDDHHmmss
checksum ^String(256) ~Required The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, timeStamp, merchantSecretKey
Click here to see an example.
clientRequestId ^String(255) ^Optional ID of the API request in merchant’s system. This value must be unique.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.

Output Parameters

PARAMETER DESCRIPTION
sessionToken ^String(36) The returned session identifier returned. To be used as an input.
merchantId ^String(20) ~Required Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required Merchant Site ID provided by Nuvei.
internalRequestId ^String(20) Nuvei’s internal unique request id (used for reconciliation purpose, etc.).
status ^String(20) The status of merchant’s API request/call.
Possible statuses:
SUCCESS
ERROR.
errCode ^String(11) The error code in the event of an error.
reason ^String(400) The error reason in the event of an error (i.e. failure in checksum validation, timeout from processing engine, etc.).
version ^String(10) The current version of the merchant request. Current version is 1.
clientRequestId ^String(20) ID of the API request in merchant’s system.

/openOrder

Definition

https://ppp-test.safecharge.com/ppp/api/v1/openOrder.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId":"1C6CT7V1L",
    "clientUniqueId": "12345",
    "currency": "USD",
    "amount": "200",
    "userTokenId": "230811147",
    "deviceDetails": {
        "ipAddress": "127.0.0.1"
    },
    "billingAddress":{
        "email":"john.smith@email.com",
        "country":"US"
   },
    "timeStamp": "20200118191751",
    "checksum": "6b53666fc048a825be63cbb820da467b"
}
Example Request
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.safecharge.com/documentation/guides/server-sdks/node-js-sdk/)

// openOrder
safecharge.paymentService.openOrder({
    userTokenId: "230811147",
    clientUniqueId: "12345",
    clientRequestId: "1C6CT7V1L",
    currency: "USD",
    amount: "200",
    deviceDetails: {
        ipAddress: "127.0.0.1"
    },
    billingAddress: {
        email: "john.smith@email.com",
        country: "US"
    },
}, function(err, result) {
    console.log(err, result)
});
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

//Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/)

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

    deviceDetails.setIpAddress("127.0.0.1");

    billingAddress.setEmail("john.smith@email.com");
    billingAddress.setCountry("US");

    SafechargeResponse response = safecharge.openOrder(userTokenId, clientRequestId, clientUniqueId, null, null, null, null, currency, amount, null, deviceDetails, null, null, billingAddress, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null);
}
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

//Initialize the SDK (see at https://docs.safecharge.com/documentation/guides/server-sdks/php-sdk/)

<?php
//openOrder
$openOrderRequest = $SafeCharge->getPaymentService()->openOrder([
    'userTokenId'       => '230811147',
    'clientUniqueId'    => '12345',
    'clientRequestId'   => '1C6CT7V1L',
    'currency'          => 'USD',
    'amount'            => '10',
    'deviceDetails'     => [
        "ipAddress"  => "127.0.0.1"
    ],
    'billingAddress' => [
        'country'   => "US",
        "email"     => "john.smith@email.com",
    ],
]);
?>
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

//Initialize the SDK (see the Nuvei .NET SDK at https://docs.safecharge.com/documentation/guides/server-sdks/net-sdk/)

var response = safecharge.OpenOrder(
    "USD",
    "200",
    clientUniqueId: "12345",
    clientRequestId: "1C6CT7V1L",
    userTokenId: "230811147",
    deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" },
    billingAddress: new UserAddress
    {
        Email = "john.smith@email.com",
        Country = "US",
    },

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

For merchants using the Web SDK, this method is needed to authenticate and receive a session token (sessionToken). sessionToken is required to invoke any Web SDK method such as createPayment().

You can use /openOrder to set any user-related parameter (such as shipping details and billing details) to be later recognized and processed by the Web SDK. However, most of these parameters can be submitted directly to the Web SDK method.

The following are the most important and required fields:

For preventOverride, you decide if you wish to submit user-related information on the openOrder API call and if you wish to make sure that information is not being changed by the end user during the Web SDK payment session. You can use the input field as explained in the input table.

@Links URLs

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

@Test https://ppp-test.safecharge.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 ID of the transaction in the merchant’s system. This value must be unique.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
timeStamp ^String(14) ~Required The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^String(256) ~Required The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey
Click here to see an example.
currency ^String(3) ~Required The 3-letter ISO currency code.
This field is required when using the Web SDK createPayment() method.
amount ^String(12) ~Required The transaction amount.
This field is required when using the Web SDK createPayment() method.
subMerchant ^Class ~Required countryCode (String,2) – The payment facilitator’s submerchant’s 2-letter ISO country code.
city (String, 20) – The payment facilitator’s submerchant’s city name.
id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
billingAddress ^Class ~country and email Required country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase.
email (String, 100, REQUIRED)
firstName (String, 30)
lastName (String, 40)
address (String, 60)
cell (String, 18)
phone (String, 18)
zip (String, 10)
city (String, 30)
state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
county (String, 255)
addressMatch (String, 1) – Set to “Y” when address matches shipping address
addressLine2 (String, 50)
addressLine3 (String, 50)
homePhone (String)
workPhone (String)
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)
externalSchemeDetails ^Class ~Conditional Use this class if you want to process an MIT/recurring transaction that was initiated with another processor. Click here for more details.
transactionId (String, 50) – Original transactionId for the initial payment as originated in the external system.
brand (String, 20) – The card brand. Currently supported with the following values:
VISA
MASTERCARD
AMEX
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
INSTALLMENTS
ADDCARD
MAINTAINCARD
ACCOUNTVERIFICATION
userTokenId ^String(255) ~Conditional This ID uniquely identifies your consumer/user in your system.
Required if you wish to use the paymentOptionId field for future charging of this user without re-collecting the payment details (see User Payment Management for details.
clientRequestId ^String(255) ^Optional ID of the API request in the merchant’s system. This value must be unique.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
transactionType ^String(45) ^Optional The type of transaction: Sale, Auth, or PreAuth.
Sale – Performs a regular payment request.
Auth – Performs an authorization-only request. Click here for more details.
PreAuth – Performs an authorization-only request (with a longer settlement period). Click here for more details.
paymentOption.card.threeD ^Class Path ^Optional With the Web SDK, you can use the threeD class (under the card class, under the paymentOption class) to pass certain 3D-Secure parameters. These parameters cannot be passed directly on the Web SDK to avoid user manipulation. Refer to threeD class for class specific fields details.
paymentOption.card.storedCredentials ^Class Path ^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 and is required when the cardData>cardNumber parameter is populated and sent. Merchants that do not store card data or that are using Nuvei’s tokenization feature should not send this parameter.
amountDetails ^Class ^Optional totalShipping
totalHandling
totalDiscount
totalTax

The items and amountDetails prices should be summed up in the amount parameter and sent separately.
items ^Class ^Optional name (String, 255)
price (String, 10)
quantity (String, 10)

The items and amountDetails prices should be summed up in the amount parameter and sent separately.
All prices must be in the same currency.
userDetails ^Class ^Optional firstName (String, 30)
lastName (String, 40)
address (String, 60)
phone (String, 18)
zip (String, 10)
city (String, 30)
country (String, 2) – 2-letter ISO country code
state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
email (String, 100)
county (String, 255)
language (String, 2) – 2-letter ISO language code.
dateOfBirth (String, 10) – Format is YYYY-MM-DD.

If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using billingAddress parameter.
shippingAddress ^Class ^Optional firstName (String, 30)
lastName (String, 40)
address (String, 60)
cell (String, 18)
phone (String, 18)
zip (String, 10)
city (String, 30)
country (String, 2) – 2-letter ISO country code
state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
email (100)
shippingCounty (String, 255)
addressLine2 (String, 50)
addressLine3 (String, 50)
If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using the billingAddress parameter.
dynamicDescriptor ^Class ^Optional merchantName (String, 25) – The merchant name, as is displayed for the transaction on the consumer’s card statement.
For payment facilitator only, the maximum length of the description is 22, maintaining the following structure:
“XXX"<merchant name>”
“XXX” must be 3 characters and identifies the payment facilitator.
“<merchant name>” must be maximum of 18 characters.

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
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.
urlDetails ^Class ^Optional Although DMN responses can be configured per merchant site, it allows dynamically returning the DMN to the provided address per request.
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 (see our DMNs Guide).
addendums ^Class ^Optional This class contains industry specific addendums. The addendum fields that appear are based on the specific addendum type. See addendums Class for more details.
isRebilling ^Integer(2) ^Optional When performing recurring/rebilling, use this field to indicate the recurring step with the following values:
0 – For the initiating recurring event (first recurring transaction).
1 – For all subsequent recurring transactions.
Notes:
  • Rebilling can be performed using userPaymentOptionId or card (under the paymentOption block). If done using card, then it is highly recommended to send its relatedTransactionId as well.
  • If isRebilling=1:
    - It can never be sent with the threeD block (under the paymentOption block)
    - For a 3D-Secure transaction, you also must specify rebillExpiry and rebillFrequency under the v2AdditionalParams block, under the threeD block.
    		•
    currencyConversion ^Class ^Optional type (String, 10) – The DCC flag indicating the type of conversion.
    originalAmount (String, 12) – The original amount of the transaction in the merchant’s own currency.
    originalCurrency (String, 3) – The 3-letter ISO currency code of the merchant’s own currency.

    Output Parameters

    PARAMETER DESCRIPTION
    sessionToken ^String The session identifier to be used by the request that processed the newly opened order.
    merchantId ^String Merchant ID provided by Nuvei.
    merchantSiteId ^String The Merchant Site ID provided by Nuvei.
    userTokenId ^String The ID of the user in the merchant’s system.
    clientUniqueId ^String The ID of the transaction in the merchant’s system.
    internalRequestId ^String Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
    merchantDetails ^Class customField1 (String, 255)
    …
    customField15
    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 The status of merchant’s API request/call.
    Possible statuses: SUCCESS or ERROR.
    errCode ^String If an error occurred on the request side, an error code is returned in this parameter.
    reason ^String If an error occurred on the request side, then an error reason (such as failure in checksum validation, timeout from processing engine, etc.) is returned in this parameter.
    version ^Integer The current version of the request. The current version is 1.
    orderId ^String The order ID provided by Nuvei.
    clientRequestId ^String ID of the API request in the merchant’s system.

    /initPayment

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/initPayment.do
    Example Request
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

    {
    "sessionToken":"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":"2022",
            "CVV":"217",
            "threeD": { "methodNotificationUrl": "<methodNotificationURL>" }
        }
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    }
}
    Example Request
    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.safecharge.com/documentation/guides/server-sdks/node-js-sdk/)

safecharge.paymentService.initPayment({
    userTokenId            : "230811147",
    amount                 : "200",
    currency               : "USD",
    paymentOption  : {
            cardNumber      : "4000027891380961",
            cardHolderName  : "john smith",
            expirationMonth : "12",
            expirationYear  : "2022",
            CVV             : "217",
            threeD          : {
                "methodNotificationUrl": "<methodNotificationURL>" },
            }
    },
    deviceDetails  : {
        ipAddress  : "127.0.0.1"
    },
}, function (initPErr, initPRes, reqData) {
    console.log(initPErr, initPRes);
});
    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/)

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

    deviceDetails.setIpAddress("127.0.0.1");

    threeD.setMethodNotificationUrl("<methodNotificationURL>");

    card.setCardNumber("4000027891380961");
    card.setCardHolderName("John Smith");
    card.setCVV("217");
    card.setExpirationMonth("12");
    card.setExpirationYear("2022");
    card.setThreeD(threeD);

    initPaymentOption.setCard(card);

    SafechargeResponse response = safecharge.initPayment(userTokenId, clientUniqueId, clientRequestId, currency, amount, deviceDetails, initPaymentOption, null, null, null, null);
}
    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/php-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'  => '2022',
            'CVV'             => '217',
            'threeD' =>[
                'methodNotificationUrl'=>'<methodNotificationURL>',
                ]
        ]
    ],
    'deviceDetails'     => [
        "ipAddress"  => "127.0.0.1"
    ],
]);
?>
    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/net-sdk/)

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

    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 the Nuvei Web SDK instead of calling this method directly.

    The method determines the 3D-Secure version for the end user and the method URL information.

    @Links URLs

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

    @Test https://ppp-test.safecharge.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 ID of the transaction in merchant system.
    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 Card payment information inside the card subclass
    paymentOption.card ^Class ~Required Card data that must be passed as a parameter in the payment methods and not prior in the payment flow (/openOrder, updateOrder), as it may not be saved in the cashier/checkout DB.
    cardNumber (String, 20)
    cardHolderName (String, 70)
    expirationMonth (String, 2)
    expirationYear (String, 4)
    cvv (String, 4)

    OR

    ccTempToken (String, 45)
    cardHolderName (String, 70)

    For a 3D-Secure payment, use the threeD class with the following field:
    threeD.methodNotificationUrl (String, 255) – The URL the ACS redirects to after performing the 3D-Secure v2 fingerprinting. Refer to our 3D-Secure Guide for details.
    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)
    userTokenId ^String(255) ^Optional This ID uniquely identifies your consumer/user in your system.
    clientRequestId ^String(255) ^Optional The ID of the API request in the merchant’s system.
    customData ^String(255) ^Optional General data about the customer is provided by the merchant. This parameter can be used to pass any type of information to the gateway, which is returned in a response for the merchant records. This field is visible in Control Panel reports with transaction information.
    webMasterId ^String(255) ^Optional This is an affiliate parameter that the merchant can send and is used by Nuvei’s eCommerce Plugins (Magento, Demandware) and also SC REST API SDK’s to send the Plugin/SDK name and version, so that support is able to identify from where the transaction arrived to the gateway through SC REST API.
    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 ID of the transaction in merchant system.
    internalRequestId ^Long(20) Nuvei’s internal unique request ID (used for reconciliation purpose, etc.).
    transactionId ^String(20) The gateway transaction ID.
    transactionType ^String(45) The type of transaction:
    InitAuth3D
    status ^String(20) The cashier status of merchant request.
    Possible statuses: SUCCESS or ERROR
    transactionStatus ^String(20) The gateway transaction status.
    errCode ^String(11) The error code if an error occurred at the cashier side.
    reason ^String(400) The error reason, if an error occurred on the cashier side.
    For example: failure in checksum validation, timeout from processing engine, etc.
    gwErrorCode ^Integer(11) The error reason code, if an error occurred on the gateway side.
    When a transaction is successful, this field 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 on the gateway side.
    gwExtendedErrorCode ^Integer(11) The error reason code, if an error occurred on the bank side.
    When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
    version ^String(10) The version of the API.
    The current version of the API method. The current version is 1.
    paymentOption ^Class This class contains the card information inside the card subclass and the userPaymentOptionId , as detailed in the following lines.
    paymentOption.userpaymentOptionId ^String(45) If initPayment was processed with userPaymentOptionId rather than having provided the card block, this field echoes back the same userPaymentOptionId that was provided in the input.
    paymentOption.card ^Class 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.
    threeD, Class – A class containing the 3D-Secure information as detailed in the following line.
    paymentOption.card.threeD ^Class methodUrl (String, 256) – The 3D “Method URL” required for 3D-Secure fingerprinting, as described in Implementing Fingerprinting and Authentication Challenges.
    version (String, 8) – The 3D-Secure version.
    Possible values: 2.1.0 (if 3D-Secure v2 flow used) or null (not used).
    v2supported Boolean (1) – Indicates if 3D-Secure v2 is supported. Possible values: true (supported) or null or false (not supported).
    serverTransID (String) – 3D-Secure 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 Implementing Fingerprinting and Authentication Challenges.
    Possible values: 0 (not supported) or 1 (supported).
    directoryServerId (String) – The 3D-Secure directory server ID. Relevant only for the 3D Mobile SDK.
    directoryServerPublicKey (String) – The 3D-Secure directory public encryption key. Relevant only for the 3D Mobile SDK.
    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 ID of the API request in the merchant’s system.

    /payment

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/payment.do
    Example Request
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

    {
    "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":"2022",
            "CVV":"217"
        }
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "billingAddress":{
        "email":"john.smith@email.com",
        "country":"US"
    },
    "timeStamp":"20191105081132",
    "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

    {
    "timeStamp":"20200623135114",
    "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":"2022",
            "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",
                "notificationUrl":"<notificationURL>",
                "merchantUrl":"<merchantURL>",
                "platformType":"02",
                "v2AdditionalParams":{
                    "challengeWindowSize":"05"
                }
            }
        },
        "deviceDetails":{
            "ipAddress":"127.0.0.1"
        },
        "billingAddress":{
            "email":"john.smith@email.com",
            "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

    {
    "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":{
        "country":"US",
        "email":"john.smith@email.com"
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "timeStamp":"20191105081140",
    "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

    {
    "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":"22",
            "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":{
        "country":"US",
        "email":"john.smith@email.com"
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "timeStamp":"20191105091105",
    "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

    {
    "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":"22",
            "CVV":"217"
        }
    },
    "relatedTransactionId":"<transactionId returned from 3D Payment Request>",
    "billingAddress":{
        "country":"US",
        "email":"john.smith@email.com"
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "timeStamp":"20191105091149",
    "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

    {
    "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":"22",
            "CVV":"217",
            "threeD":{
                "externalMpi":{
                    "eci":"2",
                    "cavv":"ejJRWG9SWWRpU2I1M21DelozSXU=",
                    "dsTransID":"9e6c6e9b-b390-4b11-ada9-0a8f595e8600"
                }
            }
        }
    },
    "billingAddress":{
        "country":"US",
        "email":"john.smith@email.com"
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "timeStamp":"20191105091144",
    "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":{
        "card":{
            "externalToken":{
                "externalTokenProvider":"Apple Pay",
                "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":{
        "email":"john.smith@email.com",
        "country":"US"
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "timeStamp":"20200517130543",
    "checksum":"de0e48812c269933d9eb37e74db45f1c"
}
    Example Request
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/node-js-sdk/)

safecharge.paymentService.createPayment({
    amount       : "100",
    currency     : "USD",
    sessionToken : "9610a8f6-44cf-4c4f-976a-005da69a2a3b", /* taken from openOrder result */
    paymentOption: {
        card: {
            expirationYear : "2022",
            CVV            : "217",
            cardHolderName : "John Smith",
            expirationMonth: "12",
            cardNumber     : "4000027891380961"
        }
    },
}, 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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/node-js-sdk/)

safecharge.paymentService.createPayment({
    currency       : "USD",
    amount         : "100",
    userTokenId    : "230811147",
    clientRequestId: "1C6CT7V1L",
    clientUniqueId : "12345",
    paymentOption  : {
        card : {
            cardNumber      : "4000027891380961",
            cardHolderName  : "John Smith",
            expirationMonth : "12",
            expirationYear  : "2022",
            CVV             : "217",
            threeD :{
                version              : "2",
                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/5.0 (Windows NT 6.1; Win64; x64; rv:47"
                }
            }
        }
    },
    billingAddress : {
        country   : "US",
        email     : "john.smith@email.com",
    },
    deviceDetails  : {
        ipAddress  : "127.0.0.1"
    },
}, 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.safecharge.com/documentation/guides/server-sdks/node-js-sdk/)

$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    currency       : "USD",
    amount         : "200",
    userTokenId    : "230811147",
    clientRequestId: "1C6CT7V1L",
    clientUniqueId : "12345",
    paymentOption  : {
        alternativePaymentMethod : {
            paymentMethod      : "apmgw_MoneyBookers",
            account_id  : "SkrillTestUser3"
        }
    },
    billingAddress : {
        country   : "US",
        email     : "john.smith@email.com",
    },
    deviceDetails  : {
        ipAddress  : "127.0.0.1"
    },
}, 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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/node-js-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  : "2022",
            CVV             : "217",
            threeD :{
                version:"2.1.0",
                notificationUrl      : "<notificationURL>",
                merchantUrl          : "<merchantURL>",
                platformType         : "02",
                v2AdditionalParams :{
                    challengeWindowSize : "05"
                browserDetails :{      // collected on the 3D 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 : {
        country   : "US",
        email     : "john.smith@email.com",
    },
    deviceDetails  : {
        ipAddress  : "127.0.0.1"
    },
}, 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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/node-js-sdk/)

$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    currency       : "USD",
    amount         : "200",
    userTokenId    : "230811147",
    clientRequestId: "1C6CT7V1L",
    clientUniqueId : "12345",
    paymentOption  : {
            cardNumber      : "4000027891380961",
            cardHolderName  : "john smith",
            expirationMonth : "12",
            expirationYear  : "2022",
            CVV             : "217",
        }
    },
    relatedTransactionId : "2110000000001208909", //as returned from 1st payment call
    billingAddress : {
        country   : "US",
        email     : "john.smith@email.com",
    },
    deviceDetails  : {
        ipAddress  : "127.0.0.1"
    },
}, 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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/node-js-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  : "2022",
            CVV             : "217",
            threeD :{
                externalMpi :{
                    eci       : "2",
                    cavv          : "ejJRWG9SWWRpU2I1M21DelozSXU",
                    dsTransID         : "9e6c6e9b-b390-4b11-ada9-0a8f595e8600"  //xid in case of 3Dv1  
                }
            }
        }
    },
    billingAddress : {
        country   : "US",
        email     : "john.smith@email.com",
    },
    deviceDetails  : {
        ipAddress  : "127.0.0.1"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult)
});
    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/)

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

    deviceDetails.setIpAddress("127.0.0.1");

    card.setCardNumber("4000027891380961");
    card.setCardHolderName("John Smith");
    card.setCVV("217");
    card.setExpirationMonth("12");
    card.setExpirationYear("2022");

    paymentOption.setCard(card);

    billingAddress.setEmail("john.smith@email.com");
    billingAddress.setCountry("US");

    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/)

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

    deviceDetails.setIpAddress("127.0.0.1");

    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.setChallengeWindowSize("2");

    threeD.setBrowserDetails(browserDetails);
    threeD.setV2AdditionalParams(v2AdditionalParams);
    threeD.setVersion("2");
    threeD.setNotificationURL("<notificationURL>");
    threeD.setMerchantURL("<merchantURL>");
    threeD.setPlatformType("02");

    card.setCardNumber("4000027891380961");
    card.setCardHolderName("John Smith");
    card.setCVV("217");
    card.setExpirationMonth("12");
    card.setExpirationYear("2022");
    card.setThreeD(threeD);

    paymentOption.setCard(card);

    billingAddress.setEmail("john.smith@email.com");
    billingAddress.setCountry("US");

    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk

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

    deviceDetails.setIpAddress("127.0.0.1");

    alternativePaymentMethod.put("paymentMethod", "apmgw_MoneyBookers");
    alternativePaymentMethod.put("account_id", "SkrillTestUser3");

    paymentOption.setAlternativePaymentMethod(alternativePaymentMethod);

    billingAddress.setEmail("john.smith@email.com");
    billingAddress.setCountry("US");

    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/)

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

    v2AdditionalParams.setChallengeWindowSize("05");

    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.setMethodCompletionInd("Y");
    threeD.setVersion("2.1.0");
    threeD.setNotificationURL("<notificationURL>");
    threeD.setMerchantURL("<merchantURL>");
    threeD.setV2AdditionalParams(v2AdditionalParams);
    threeD.setBrowserDetails(browserDetails);

    card.setCardNumber("4000027891380961");
    card.setCardHolderName("john smith");
    card.setExpirationMonth("12");
    card.setExpirationYear("25");
    card.setCVV("217");
    card.setThreeD(threeD);

    paymentOption.setCard(card);

    billingAddress.setCountry("US");
    billingAddress.setEmail("john.smith@email.com");

    deviceDetails.setIpAddress("127.0.0.1");

    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/)

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

    card.setCardNumber("4000027891380961");
    card.setCardHolderName("john smith");
    card.setExpirationMonth("12");
    card.setExpirationYear("25");
    card.setCVV("217");

    paymentOption.setCard(card);

    billingAddress.setCountry("US");
    billingAddress.setEmail("john.smith@email.com");

    deviceDetails.setIpAddress("127.0.0.1");

    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/)

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

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

    threeD.setExternalMpi(externalMpi);

    card.setCardNumber("4000027891380961");
    card.setCardHolderName("john smith");
    card.setExpirationMonth("12");
    card.setExpirationYear("25");
    card.setCVV("217");
    card.setThreeD(threeD);

    paymentOption.setCard(card);

    billingAddress.setCountry("US");
    billingAddress.setEmail("john.smith@email.com");

    deviceDetails.setIpAddress("127.0.0.1");

    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);
}
    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/php-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'  => '2022',
            'CVV'             => '217',
        ]
    ],
    'billingAddress' => [
        'country'   => "US",
        "email"     => "john.smith@email.com",
    ],
    'deviceDetails'  => [
        "ipAddress"  => "127.0.0.1",
    ],
]);
?>

    

    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/php-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'  => '2022',
            'CVV'             => '217',
            'threeD' =>[
                'version'=>'2',
                '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/5.0 (Windows NT 6.1; Win64; x64; rv:47'
                ]
            ]
        ]
    ],
    'billingAddress' => [
        'country'   => 'US',
        'email'     => 'john.smith@email.com',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '127.0.0.1',
    ],
]);
?>

    

    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.safecharge.com/documentation/guides/server-sdks/php-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' => [
        'country'   => 'US',
        'email'     => 'john.smith@email.com',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '127.0.0.1',
    ],
]);
?>

    

    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.safecharge.com/documentation/guides/server-sdks/php-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'  => '2022',
            'CVV'             => '217',
            'threeD' =>[
                'version'=>'2.1.0',
                'notificationUrl'      => '<notificationURL>',
                'merchantUrl'          => '<merchantURL>',
                'platformType'         => '02',
                'v2AdditionalParams' =>[
                    'challengeWindowSize' =>'05',
                ],
                'browserDetails' =>[        // collected on the 3D 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' => [
        'country'   => 'US',
        'email'     => 'john.smith@email.com',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '127.0.0.1',
    ],
]);
?>

    

    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.safecharge.com/documentation/guides/server-sdks/php-sdk/)

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'USD',
    'amount'         => '200',
    'userTokenId'    => '230811147',
    'clientRequestId'=> '1C6CT7V1L',
    'clientUniqueId'=> '12345',
    'paymentOption'  => [
            'cardNumber'      => '4000027891380961',
            'cardHolderName'  => 'john smith',
            'expirationMonth' => '12',
            'expirationYear'  => '2022',
            'CVV'             => '217',
        ]
    ],
    'relatedTransactionId' => '2110000000001208909', //as returned from 1st payment call
    'billingAddress' => [
        'country'   => 'US',
        'email'     => 'john.smith@email.com',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '127.0.0.1',
    ],
]);
?>

    

    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/php-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'  => '2022',
            'CVV'             => '217',
            'threeD' =>[
                'externalMpi' =>[
                    'eci'       => '2',
                    'cavv'          => 'ejJRWG9SWWRpU2I1M21DelozSXU',
                    'dsTransID'         => '9e6c6e9b-b390-4b11-ada9-0a8f595e8600'  //xid in case of 3Dv1        
                ]
            ]
        ]
    ],
    'billingAddress' => [
        'country'   => 'US',
        'email'     => 'john.smith@email.com',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '127.0.0.1',
    ],
]);
?>
    Example Request
    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.safecharge.com/documentation/guides/server-sdks/net-sdk/)

var response = safecharge.Payment(
    "USD",
    "100",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "John Smith",
            ExpirationMonth = "12",
            ExpirationYear = "22",
            CVV = "217"
        }
    },
    clientRequestId: "1C6CT7V1L",
    userTokenId: "230811147",
    clientUniqueId: "12345",
    deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" });

    

    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.safecharge.com/documentation/guides/server-sdks/net-sdk/)

var response = safecharge.Payment(
    "USD",
    "100",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "John Smith",
            ExpirationMonth = "12",
            ExpirationYear = "22",
            CVV = "217",
            ThreeD = new ThreeD
            {
                Version = "2",
                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",
    deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" },
    billingAddress: new UserAddress
    {
        Email = "john.smith@email.com",
        Country = "US",
    },
);

    

    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.safecharge.com/documentation/guides/server-sdks/net-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
    {
        Country = "US",
        Email = "john.smith@safecharge.com"
    },
    deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" });

    

    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.safecharge.com/documentation/guides/server-sdks/net-sdk/)

var response = safecharge.Payment(
    "USD",
    "200",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "john smith",
            ExpirationMonth = "12",
            ExpirationYear = "22",
            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
    {
        Country = "US",
        Email = "john.smith@email.com",
    },
    deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" });

    

    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.safecharge.com/documentation/guides/server-sdks/net-sdk/)

var response = safecharge.Payment(
    "USD",
    "200",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "john smith",
            ExpirationMonth = "12",
            ExpirationYear = "22",
            CVV = "217"
        }
    },
    clientUniqueId: "12345",
    clientRequestId: "1C6CT7V1L",
    userTokenId: "230811147",
    relatedTransactionId: "2110000000001208909", // as returned from 1st payment call
    billingAddress: new UserAddress
    {
        Country = "US",
        Email = "john.smith@email.com",
    },
    deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" });

    

    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/net-sdk/)

var response = safecharge.Payment(
    "USD",
    "200",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "john smith",
            ExpirationMonth = "12",
            ExpirationYear = "22",
            CVV = "217",
            ThreeD = new ThreeD
            {
                ExternalMpi = new ExternalMpi
                {
                    Eci = "2",
                    Cavv = "ejJRWG9SWWRpU2I1M21DelozSXU",
                    DsTransID = "9e6c6e9b-b390-4b11-ada9-0a8f595e8600", //xid in case of 3Dv1 
                }
            }
        }
    },
    clientUniqueId: "12345",
    clientRequestId: "1C6CT7V1L",
    userTokenId: "230811147",
    billingAddress: new UserAddress
    {
        Country = "US",
        Email = "john.smith@email.com",
    },
    deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" });

    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

    {
    "orderId": "271308078",
    "userTokenId": "230811147",
    "paymentOption": {
        "userPaymentOptionId": "53959588",
        "card": {
            "ccCardNumber": "4****2535",
            "bin": "400002",
            "last4Digits": "2535",
            "ccExpMonth": "12",
            "ccExpYear": "22",
            "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"
}

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

    Required Fields

    Selecting a Payment Method (paymentOption Class)

    This class represents the details of the payment method of the transaction, which can be one of the following three options:

    @Links URLs

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

    @Test https://ppp-test.safecharge.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 Session identifier returned by /getSessionToken.
    timeStamp ^String(14) ~Required The local time when the method call is performed in the format: YYYYMMDDHHmmss. Needed for the “checksum” hashing calculation.
    checksum ^String(256) ~Required The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey
    Click here to see an example.
    currency ^String(3) ~Required The 3-letter ISO currency code.
    amount ^String(12) ~Required The transaction amount.
    This amount must be identical to the amount listed in the dynamic3D.
    paymentOption ^Class ~Required This class represents the details on the payment method. Set it with one of 3 options:

    • card – Represents a credit/debit card. Fields:
        ▫ cardNumber (String, 20, REQUIRED) – The card number.
        ▫ cardHolderName (String, 70, REQUIRED) – The card holder 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.

       For advanced card scenarios (instead of card details):
          ▫ For 3D-Secure, please refer to threeD Input Class.
          ▫ When using an external token provider such as Apple Pay or Visa Checkout, refer to externalToken Class.
          ▫ For storing card credentials, refer to storedCredentials Class.
          ▫ For payment with a temporary token generated by getToken():
               ccTempToken (String, 45)
               cardHolderName (String, 70)

    OR

    • alternativePaymentMethod – Represents an alternative payment method. For details, please refer to alternativePaymentMethod Class.

    OR

    • userPaymentOptionId – This is a field identifying 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 previous uses. Can be used with:
        ▫ expirationMonth (String, 2) – For a newer card expiration.
        ▫ expirationYear (String, 4) – For a newer card expiration.
        ▫ CVV (String, 4) – Recommended for high risk merchants.
    subMerchant ^Class ~Required countryCode (String,2) – The payment facilitator’s submerchant’s 2-letter ISO country code.
    city (String, 20) – The payment facilitator’s submerchant’s city name.
    id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
    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 ~country and email 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)
    lastName (String, 40)
    address (String, 60)
    address2 (String, 60)
    phone (String, 18)
    zip (String, 10)
    city (String, 30)
    state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
    county (String, 255)

    These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.
    relatedTransactionId ^String(19) ~Conditional Required in the following cases:
    • For 3D-Secure v2 (refer to our 3D-Secure Guide for details):
        ▫ The transaction ID of the initPayment on the first call.
        ▫ The transaction ID of the first Payment call of the second call.
    • For 3D-Secure (Version 1) or non-3D:
        ▫ The Transaction ID of the first payment call on the second call.
    • For recurring/rebilling and MIT:
        ▫ Represents the reference to the original transaction ID of the initial transaction (see Merchant Initiated Payments for details).
    externalSchemeDetails ^Class ~Conditional Use this class if you want to process an MIT/recurring transaction that was initiated with another processor. Click here for more details.
    transactionId (String, 50) – Original transactionId for the initial payment as originated in the external system.
    brand (String, 20) – The card brand. Currently supported with the following values:
    VISA
    MASTERCARD
    AMEX
    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
    INSTALLMENTS
    ADDCARD
    MAINTAINCARD
    ACCOUNTVERIFICATION
    userTokenId ^String(255) ~Conditional This ID uniquely identifies your consumer/user in your system.
    Required if you wish to use the paymentOptionId field for future charging of this user without re-collecting the payment details (see User Payment Management for details.
    clientRequestId ^String(255) ^Optional Use this advanced field to prevent idempotency. Use it to uniquely identify the request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
    clientUniqueId ^String(45) ^Optional This ID identifies the transaction in your system. Optionally, you can pass this value to us and we will store it with the transaction record created in our system for your future reference.
    subMethodDetails ^Class ^Optional subMethod (String) – See details below.
    email (String) – See details below.

    This JSON class is for advanced APMs flows. See APM Submethods for details.
    The submethod parameter enables working with a specific payment method in a few different flows.

    Supported Flows:
  • PayPal quick registration mode
         subMethod should be set to QuickRegistration. No other fields are required.
  • PayPal Membership Agreement
         subMethod should be set to referenceTransaction.
  • Skrill1tap
         subMethod should be set to skrill1Tap. No other submethod fields are required.
         email field should be provided.
  • Trustly PayNPlay
         subMethod should be set to PayNPlay.
  • Post Finance Alias Recurring
         subMethod should be set to AliasRegistration.
    		•
    amountDetails ^Class ^Optional totalShipping (String)
    totalHandling (String)
    totalDiscount (String)
    totalTax (String)

    The items and amountDetails prices should be summed up in the amount parameter and sent separately.
    All prices must be in the same currency.
    items ^Class ^Optional An array describing the items in the purchase.
    name (String, 255, REQUIRED if items is used)
    price (String, 10, REQUIRED if items is used)
    quantity (String, 10, REQUIRED if items is used)

    The items price should be summed up to the amount parameter sent separately. All items must be in the same currency.
    userDetails ^Class ^Optional firstName (String, 30)
    lastName (String, 40)
    address (String, 60)
    phone (String, 18)
    zip (String, 10)
    city (String, 30)
    country (String, 2) – 2-letter ISO country code
    state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
    email (String, 100)
    county (String, 255)
    language (String, 2) – 2-letter ISO language code.
    dateOfBirth (String, 10) – Format is YYYY-MM-DD.
    shippingAddress ^Class ^Optional firstName (String, 30)
    lastName (String, 40)
    address (String, 60)
    phone (String, 18)
    zip (String, 10)
    city (String, 30)
    country (String, 2) – 2-letter ISO country code
    state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
    email (String, 100)
    shippingCounty (String, 255)
    dynamicDescriptor ^Class ^Optional merchantName (String, 25) – The merchant name, as is displayed for the transaction on the consumer’s card statement.
    For payment facilitator only, the maximum length of the description is 22, maintaining the following structure:
    “XXX"<merchant name>”
    “XXX” must be 3 characters and identifies the payment facilitator.
    “<merchant name>” must be maximum of 18 characters.

    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 field 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
    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.
    urlDetails ^Class ^Optional Although DMN responses can be configured per merchant site, it allows dynamically returning the DMN to the provided address per request.
    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 (see our DMNs Guide).
    transactionType ^String(45) ^Optional The type of transaction: Sale, Auth, or PreAuth.
    Sale – Performs a regular payment request.
    Auth – Performs an authorization-only request. Click here for more details.
    PreAuth – Performs an authorization-only request (with a longer settlement period). Click here for more details.
    isRebilling ^Integer(2) ^Optional When performing recurring/rebilling, use this field to indicate the recurring step with the following values:
    0 – For the initiating recurring event (first recurring transaction).
    1 – For all subsequent recurring transactions.
    Notes:
  • Rebilling can be performed using userPaymentOptionId or card (under the paymentOption block). If done using card, then it is highly recommended to send its relatedTransactionId as well.
  • If isRebilling=1:
    - It can never be sent with the threeD block (under the paymentOption block)
    - For a 3D-Secure transaction, you also must specify rebillExpiry and rebillFrequency under the v2AdditionalParams block, under the threeD block.
    		•
    isPartialApproval ^String(1) ^Optional This 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 field value.
    productId ^String(50) ^Optional A free text field 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 field value.
    customData ^String(255) ^Optional This parameter can be used to pass any type of information.
    If sent in request, then it is passed on to the payments gateway, and is visible in Nuvei’s back-office tool transaction reporting and is returned in response.
    webMasterId ^String(255) ^Optional This is an affiliate parameter that the merchant can send.
    This is used by Nuvei’s eCommerce Plugins (Magento, Demandware) and also Nuvei API SDKs to send the Plugin/SDK name and version, so that support is able to identify from where the transaction arrived to the gateway through Nuvei API.
    orderId ^String(45) ^Optional The order ID provided by Nuvei.
    This parameter is passed to define which merchant order to update.
    addendums ^Class ^Optional This class contains industry specific addendums. The addendum fields that appear are based on the specific addendum type. See addendums Class for more details.
    currencyConversion ^Class ^Optional type (String, 10) – The DCC flag indicating the type of conversion.
    originalAmount (String, 12) – The original amount of the transaction in the merchant’s own currency.
    originalCurrency (String, 3) – The 3-letter ISO currency code of the merchant’s own currency.

    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 ID of the transaction in merchant system.
    internalRequestId ^Long(20) Nuvei’s internal unique request ID (used for reconciliation purpose, etc.).
    status ^String(20) The cashier status of merchant request.
    Possible statuses: SUCCESS or 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 Error 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:
  • 3D-Secure – The user needs to be redirected to paymentOption.threeD.acsUrl. See the 3D-Secure Guide for full details.
  • Alternative payment method that requires redirection – The URL is on paymentOption.redirectURL.
    		•
    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 This class represents the data retrieved from the processed payment method. Can be either card, or in case of alternative payment method, it shows the redirectUrl. In addition, the userPaymentOptionId field is retrieved as detailed below:

    • redirectUrl (String) – The redirect URL to follow for an alternative payment method, which needs to be redirected to in order to process.

    OR

    • card – 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).
      ▫ avsCode (String) – The AVS (address verification) response.
      ▫ acquirerId (String) – The acquirer ID of the acquirer which processed the transaction.
      ▫ threeD (class) – Contains the required 3D-Secure information. Refer to threeD (out) for details.

    OR

    • userPaymentOptionId – In addition to the above, this field 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
    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.
    errCode ^String(11) If an error occurred on the request side, an error code is returned in this parameter.
    reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter, for example failure in checksum validation, timeout from processing engine, etc.
    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 is returned in this parameter, for example failure in checksum validation, timeout from processing engine, etc.
    gwExtendedErrorCode ^Integer(11) The error code if an error occurred on the bank’s side.
    When a transaction is successful, this field is 0.
    When a transaction is not successful, the parameter is the code of the generic error.
    version ^Integer(10) The version of the request.
    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. Click here for more details.
    customData ^String(255) This parameter can be used to pass any type of information.
    If sent in the request, then it is passed on to the payments gateway, and is visible in Nuvei’s back-office tool transaction reporting and is returned in response.
    fraudDetails ^Class finalDecision (String)
    score (decimal)
    recommendations (String)
    system {systemId (String),systemName (String),decision (String)
    rules [ruleId (String),ruleDescription (String)]}

    The '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.
    The ‘system’ refers to which risk management system provided the fraud information. The provider can be Nuvei (systemId=1) or an external provider.
    The ‘rule’ refers to the risk management system rules triggered by the transaction.
    The ‘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.
    The 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 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 ID of the API request in the merchant’s system.

    /settleTransaction

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/settleTransaction.do
    Example Request
    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 a payment>",
    "timeStamp": "20190915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
    Example Request
    1
2
3
4
5
6
7
8
9
10

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/node-js-sdk/)

safecharge.paymentService.settleTransaction({
    clientUniqueId         : "12345",
    amount                 : "200",
    currency               : "USD",
    relatedTransactionId   : "2110000000001208909",
}, function (stlErr, stlRes) {
    console.log(stlErr, stlRes);
});
    Example Request
    1
2
3
4
5
6
7
8
9
10
11

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/)

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

    SafechargeResponse response = safecharge.settleTransaction(clientUniqueId, null, null, null, null, null, amount, null, null, null, currency, null, null, relatedTransactionId, null);
}
    Example Request
    1
2
3
4
5
6
7
8
9
10
11

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/php-sdk/)

<?php
//settleTransaction
$settleResponse = $safeCharge->getPaymentService()->settleTransaction([
    'clientUniqueId'          => '12345',
    'amount'                  => '10',
    'currency'                => 'USD',
    'relatedTransactionId'    => '2110000000001208909',
]);
?>
    Example Request
    1
2
3
4
5
6
7
8

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/net-sdk/)

var response = safecharge.SettleTransaction(
    "USD",
    "200",
    relatedTransactionId: "<transactionId returned from a 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

    {
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "internalRequestId":"45",
    "transactionId":"8498764859",
    "externalTransactionId":"",
    "status":"SUCCESS",
    "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 a 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.

    @Links URLs

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

    @Test https://ppp-test.safecharge.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(255) ~Required The ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    Appears in DMN as 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 ID of the original Auth transaction to be settled.
    timeStamp ^String(14) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
    checksum ^String(256) ~Required The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, clientUniqueId, amount, currency, relatedTransactionId, authCode, MerchantName, MerchantPhone, comment, urlDetails, timeStamp, merchantSecretKey
    Click here to see an example.
    subMerchant ^Class ~Required countryCode (String,2) – The payment facilitator’s submerchant’s 2-letter ISO country code.
    city (String, 20) – The payment facilitator’s submerchant’s city name.
    id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
    clientRequestId ^String(128) ^Optional ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    authCode ^String(128) ^Optional The authorization code of the original Auth transaction to be settled.
    descriptorMerchantName ^String(25) ^Optional Allows the merchant to define a dynamic descriptor, which appears in the payment statement. The name field should contain the merchant name.

    If you work in an Auth-Settle mode then you must provide a value for this field for it to appear in the payment statement.

    For dynamic descriptor, special configuration 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 field 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.

    If you work in an Auth-Settle mode, then you must provide a value for this field for it to appear in the payment statement.

    For dynamic descriptor, special configuration required. For more information, please contact Nuvei’s Integration Support Team.
    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 (see our DMNs Guide).
    addendums ^Class ^Optional This class contains industry specific addendums. The addendum fields that appear are based on the specific addendum type. See addendums Class for more details.
    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 field 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 This parameter can be used to pass any type of information.
    If sent in request, then is passed on to the payments gateway, is visible in Nuvei’s back-office tool transaction reporting and is returned in response.
    webMasterId ^String(255) ^Optional This is an affiliate parameter that the merchant can send.

    Output Parameters

    PARAMETER DESCRIPTION
    merchantId ^String(20) Merchant ID provided by Nuvei.
    merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
    internalRequestId ^String(20) ID of the API request in the merchant’s system.
    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 statuses: SUCCESS or ERROR.
    transactionStatus ^String(20) The gateway transaction status.
    Possible values:
    APPROVED
    DECLINED
    ERROR
    authCode ^String(128) Authorization code of the transaction.
    errCode ^String(11) If an error occurred on the request side, an error code is returned in this parameter.
    reason ^String(400) If an error occurred on the request side, then an error reason (such as failure in checksum validation, timeout from processing engine, etc.) 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, timeout from processing engine, etc.) is returned in this parameter.
    gwExtendedErrorCode ^Integer(11) Error code if error occurred on the bank’s side.
    When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
    customData ^String(255) This parameter can be used to pass any type of information.
    If sent in request, then is passed on to the payments gateway, is visible in Nuvei’s back-office tool transaction reporting and is returned in response.
    version ^Integer(10) The current version of the request. The current version is 1.
    clientRequestId ^String(255) The client’s request ID as defined by the merchant for record-keeping.

    /refundTransaction

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/refundTransaction.do
    Example Request
    1
2
3
4
5
6
7
8
9
10

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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/node-js-sdk/)

safecharge.paymentService.refundTransaction({
    clientRequestId     : "1C6CT7V1L",
    clientUniqueId      : "12345",
    amount              : "200",
    currency            : "USD",
    relatedTransactionId: "2110000000001208909",
}, function (stlErr, stlRes, reqData) {
    console.log(stlErr, stlRes);
});
    Example Request
    1
2
3
4
5
6
7
8
9
10
11

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/php-sdk/)

<?php
//refundTransaction
$refundResponse = $safeCharge->getPaymentService()->refundTransaction([
    'clientUniqueId'          => '12345',
    'amount'                  => '10',
    'currency'                => 'USD',
    'relatedTransactionId'    => '2110000000001208909',
]);
?>
    Example Request
    1
2
3
4
5
6
7
8
9
10
11

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/)

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

    SafechargeResponse response = safecharge.refundTransaction(clientUniqueId, clientRequestId, null, amount, null, null, currency, null, null, null, relatedTransactionId, null);
}
    Example Request
    1
2
3
4
5
6
7
8

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/net-sdk/)

var response = safecharge.RefundTransaction(
    "US",
    "200",
    relatedTransactionId: "<transactionId returned from a 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"
}

    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.

    @Links URLs

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

    @Test https://ppp-test.safecharge.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(255) ~Required The ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    Appears in DMN as 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 ID of the Settle/Sale transaction.
    timeStamp ^String(14) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
    checksum ^String(256) ~Required The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, clientUniqueId, amount, currency, relatedTransactionId, authCode, comment, urlDetails, timeStamp, merchantSecretKey
    Click here to see an example.
    subMerchant ^Class ~Required countryCode (String,2) – The payment facilitator’s submerchant’s 2-letter ISO country code.
    city (String, 20) – The payment facilitator’s submerchant’s city name.
    id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
    clientRequestId ^String(128) ^Optional ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    authCode ^String(128) ^Optional The authorization code of the related Settle/Sale transaction, to be compared to the original one.
    This is required for cards, non-required for APMs.
    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 (see our DMNs Guide).
    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 field 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 This parameter can be used to pass any type of information.
    If sent in request, then is passed on to the payments gateway, is visible in Nuvei’s back-office tool transaction reporting and is returned in response.
    webMasterId ^String(255) ^Optional This is an affiliate parameter that the merchant can send.

    Output Parameters

    PARAMETER DESCRIPTION
    merchantId ^String(20) Merchant ID provided by Nuvei.
    merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
    internalRequestId ^String(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
    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 statuses: SUCCESS or ERROR.
    transactionStatus ^String(20) The gateway transaction status.
    Possible values:
    APPROVED
    DECLINED
    ERROR
    authCode ^String(128) Authorization code of the transaction.
    errCode ^String(11) If an error occurred on the request side, an error code is returned in this parameter.
    reason ^String(400) If an error occurred on the request side, then an error reason (such as failure in checksum validation, timeout from processing engine, etc.) 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, timeout from processing engine, etc.) is returned in this parameter.
    gwExtendedErrorCode ^Integer(11) Error code if error occurred on the bank’s side.
    When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
    customData ^String(255) This parameter can be used to pass any type of information.
    If sent in request, then is passed on to the payments gateway, is visible in Nuvei’s back-office tool transaction reporting and is returned in response.
    version ^Integer(10) The current version of the request. The current version is 1.
    clientRequestId ^String(255) The client’s request ID as defined by the merchant for record-keeping.

    /voidTransaction

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/voidTransaction.do
    Example Request
    1
2
3
4
5
6
7
8
9
10

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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/node-js-sdk/)

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

});
    Example Request
    1
2
3
4
5
6
7
8
9
10
11

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/php-sdk/)

<?php
//voidTransaction
$voidResponse = $safeCharge->getPaymentService()->voidTransaction([
    'clientUniqueId'          => '12345',
    'amount'                  => '10',
    'currency'                => 'USD',
    'relatedTransactionId'    => '2110000000001208909',
]);
?>
    Example Request
    1
2
3
4
5
6
7
8
9
10
11

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/)

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

    SafechargeResponse response = safecharge.voidTransaction(clientRequestId, relatedTransactionId, amount, currency, null, clientUniqueId, null, null, null, null, null, null);
}
    Example Request
    1
2
3
4
5
6
7
8

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/net-sdk/)

var response = safecharge.VoidTransaction(
    "US",
    "200",
    relatedTransactionId: "<transactionId returned from a 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. Click here for more details on voiding transactions.

    @Links URLs

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

    @Test https://ppp-test.safecharge.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(255) ~Required The ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    Appears in DMN as merchant_unique_id parameter.
    amount ^Decimal(12) ~Required The transaction amount.
    It is required to send an amount that is equal to the amount sent in the related transaction that this void aim to cancel.
    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 ID of the original transaction.
    timeStamp ^String(14) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
    checksum ^String(256) ~Required The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, clientUniqueId, amount, currency, relatedTransactionId, authCode, comment, urlDetails, timeStamp, merchantSecretKey
    Click here to see an example.
    subMerchant ^Class ~Required countryCode (String,2) – The payment facilitator’s submerchant’s 2-letter ISO country code.
    city (String, 20) – The payment facilitator’s submerchant’s city name.
    id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
    clientRequestId ^String(128) ^Optional ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    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 (see our DMNs Guide).
    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 field 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 This parameter can be used to pass any type of information.
    If it is sent in the request, then it is passed on to the payments gateway and is visible in Nuvei’s back-office tool for transaction reporting and is returned in response.
    webMasterId ^String(255) ^Optional This is an affiliate parameter that the merchant can send.

    Output Parameters

    PARAMETER DESCRIPTION
    merchantId ^String(20) The Merchant ID provided by Nuvei.
    merchantSiteId ^String(20) The Merchant Site ID provided by Nuvei.
    internalRequestId ^String(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
    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 statuses: SUCCESS or ERROR.
    transactionStatus ^String(20) The gateway transaction status.
    Possible values:
    APPROVED
    DECLINED
    ERROR
    authCode ^String(128) Authorization code of the transaction.
    errCode ^String(11) If an error occurred on the request side, an error code is returned in this parameter.
    reason ^String(400) If an error occurred on the request side, then an error reason (such as failure in checksum validation, timeout from processing engine, etc.) 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, timeout from processing engine, etc.) is returned in this parameter.
    gwExtendedErrorCode ^Integer(11) Error code if error occurred on the bank’s side.
    When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
    customData ^String(255) This parameter can be used to pass any type of information.
    If it is sent in the request, then it is passed on to the payments gateway and is visible in Nuvei’s back-office tool for transaction reporting and is returned in response.
    version ^Integer(10) The current version of the request. The current version is 1.
    clientRequestId ^String(20) The ID of the API request in the merchant’s system.

    /payout

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/payout.do
    Example Request
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

    {
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
    "amount": "200",
    "currency": "USD",
    "deviceDetails":{ 
        "ipAddress":"127.0.0.1"
   },
    "userPaymentOption":{
        "userPaymentOptionId":"1459503"
    },
    "timeStamp": "20190915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
    Example Request
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/node-js-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 methods endpoint
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

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

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

    COMING SOON
    Example Request
    1
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.safecharge.com/documentation/guides/server-sdks/php-sdk/)

<?php
$payoutRequest = $SafeCharge->getPaymentService()->payout([
    'userTokenId'=> '230811147',
    'clientRequestId'=> '1C6CT7V1L',
    'clientUniqueId'=> '12345',
    'amount'=> '10',
    'currency'=> 'USD',
    'userPaymentOption'=> [
        'userPaymentOptionId'=> 1459503,
        'CVV'=> '217'
    ],
    'deviceDetails'     => [
        "ipAddress"  => "127.0.0.1"
    ],
    'merchantId'=> '427583496191624621',
    'merchantSiteId'=> '142033',
    'timeStamp'=> '20200929110947',
    'checksum'=> '<checksum>',
    'timeStamp'     =>  '<timeStamp>'
]);
?>
    Example Request
    1
2
3
4
5
6
7
8
9

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/net-sdk/)

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

    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

    {
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "userTokenId":"230811147",
    "clientUniqueId":"12345",
    "internalRequestId":"866",
    "transactionId":"8498764859",
    "externalTransactionId":"",
    "status":"SUCCESS",
    "cardData":{
        "acquirerId":"1",
        "visaDirect":"YES"
    },
    "transactionStatus":"APPROVED",
    "merchantDetails":{
        "customField1":""
    },
    "userPaymentOptionId":"12442",
    "errCode":"0",
    "reason":"",
    "paymentMethodErrorCode":"0",
    "paymentMethodErrorReason":"",
    "gwErrorCode":"0",
    "gwErrorReason":"",
    "gwExtendedErrorCode":"0",
    "version":"1"
}

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

    @Links URLs

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

    @Test https://ppp-test.safecharge.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 The ID of the user in the merchant’s system.
    clientUniqueId ^String(45) ~Required The ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    Appears in DMN as merchant_unique_id parameter.
    amount ^String(12) ~Required The transaction amount.
    currency ^String(3) ~Required The 3-letter ISO currency code.
    userPaymentOption ^Class ~Required 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.
    timeStamp ^String(14) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
    checksum ^String(256) ~Required The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey
    Click here to see an example.
    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)
    clientRequestId ^String(255) ^Optional ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    dynamicDescriptor ^Class ^Optional merchantName (String, 25) – The merchant name, as is displayed for the transaction on the consumer’s card statement.
    For payment facilitator only, the maximum length of the description is 22, maintaining the following structure:
    “XXX"<merchant name>”
    “XXX” must be 3 characters and identifies the payment facilitator.
    “<merchant name>” must be maximum of 18 characters.

    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
    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.
    cardData ^Class ^Optional cardNumber (String, 20)
    cardHolderName (String, 70)
    expirationMonth (String, 2)
    expirationYear (String, 4)

    An alternative to sending the paymentOptionId for card payouts. Merchant has to be PCI certified to use this, as it uses clear text card numbers.
    When sending cardData you must also send userTokenId
    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 (see our DMNs Guide).
    addendums ^Class ^Optional This class contains industry specific addendums. For /payout, only localpayment is relevant.

    Output Parameters

    PARAMETER DESCRIPTION
    merchantId ^String(20) The Merchant ID provided by Nuvei.
    merchantSiteId ^String(20) The Merchant Site ID provided by Nuvei.
    userTokenId ^String(255) The ID of the user in the merchant’s system.
    clientUniqueId ^String(45) The ID of the transaction in the merchant’s system.
    Appears in DMN as merchant_unique_id parameter.
    internalRequestId ^String(20) The ID of the API request in the merchant’s system.
    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 statuses: SUCCESS or ERROR.
    transactionStatus ^String The gateway transaction status.
    Possible values:
    APPROVED
    DECLINED
    ERROR
    merchantDetails ^Class customField1 (String, 255)
    …
    customField15
    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.
    userPaymentOptionId ^String 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 ^String(11) If an error occurred on the request side, an error code is returned in this parameter.
    reason ^String(400) If an error occurred on the request side, then an error reason (such as failure in checksum validation, timeout from processing engine, etc.) 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, timeout from processing engine, etc.) is returned in this parameter.
    gwExtendedErrorCode ^Integer(11) Error code if error occurred on the bank’s side.
    When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
    version ^Integer(10) The current version of the request. The current version is 1.
    clientRequestId ^String(255) ID of the API request in the merchant’s system.

    /getPaymentStatus

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/getPaymentStatus.do
    Example Request
    1
2
3

    {
    "sessionToken":"274ff0d9-c859-42f5-ae57-997641f93471"
}
    Example Request
    1
2
3
4
5

    safecharge.getPaymentStatus({
    "sessionToken": "3765655c-c333-47b7-aea6-07c54e59d1fb" // taken from getSessionToken result
}, function (pError, pRes){

})
    Example Request
    1
2
3
4
5

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/)

{
    GetPaymentStatusResponse response = safecharge.getPaymentStatus();
}
    Example Request
    1
2
3
4
5
6
7

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/php-sdk/)

<?php
$getPaymentStatusRequest = $SafeCharge->getPaymentService()->getPaymentStatus([
    'sessionToken'  =>  '<sessionToken>',
]);
?>
    Example Request
    1
2
3
4

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/net-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

    {
    "gwExtendedErrorCode": 0,
    "gwErrorCode": 0,
    "gwErrorReason": "",
    "authCode": "1234567",
    "transactionType": "Sale",
    "transactionStatus": "APPROVED",
    "amount": "200",
    "currency": "USD",
    "userTokenId": "230811147",
    "transactionId": "1110000000004198292",
    "paymentOption": {
        "userPaymentOptionId": "14958143",
        "card": {
            "uniqueCC": "8/AOqY3oRC28rNNtUbtVPXjEtX0=",
            "threeD": {
                "isLiabilityOnIssuer": "1"
            }
        }
    },
    "sessionToken": "274ff0d9-c859-42f5-ae57-997641f93471",
    "clientUniqueId": "256623868",
    "internalRequestId": 177988948,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantSiteId": "180083",
    "version": "1.0",
    "clientRequestId": "d9819a40-5b8c-11ea-b626-b159cf3c9542"
}

    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 this method 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:

    @Links URLs

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

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

    Input Parameters

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

    Output Parameters

    Parameter Description
    sessionToken ^String(36) Session identifier returned by /getSessionToken or generated by /openOrder.
    version ^String(10) The current version of the API method.
    Current version is 1.
    status ^String(20) The cashier status of merchant request.
    Possible statuses:
    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 ~Required 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) General data about the customer provided by the merchant. This parameter can be used to pass any type of information to the gateway, which is returned in response for the merchant records.
    This field is visible in cPanel reports with transaction information.
    clientUniqueId ^String(255) The ID of the transaction in merchant system.
    gwExtendedErrorCode ^Integer(11) Error code if error occurred on the bank side.
    When a transaction is successful, this field 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 on the gateway side.
    When a transaction is successful, this field 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. Click here for more details.
    userTokenId ^String(255) This ID uniquely identifies your consumer/user in your system.
    transactionId ^String(20) The gateway transaction ID.
    errCode ^String(11) The error code if the error occurred at the cashier side.
    reason ^String(400) The error reason if the error occurred at the cashier side.
    For example: failure in checksum validation, timeout from processing engine, etc.)
    paymentOption.card ^Class uniqueCC (String, 28) – Unique identifier for the credit card.
    paymentOption.alternativePaymentmethod ^Class 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 it has been sent into the request.
    clientRequestId ^String(20) The ID of the API request in the merchant’s system.
    isLiabilityOnIssuer ^String Indicates if there is 3D-Secure liability shift.
    If equal to “1” – Liability shift is present.
    If equal to “0”, empty or null – No liability shift has occurred.

    /accountCapture

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/accountCapture.do
    Example Request
    1
2
3
4
5
6
7
8
9
10
11

    {
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "paymentMethod":"apmgw_FastBankTansfer",
    "userTokenId":"230811147",
    "currencyCode":"USD",
    "countryCode":"US",
    "languageCode":"en",
    "notificationUrl":"<notificationURL>"
}
    Example Request
    1

    COMING SOON
    Example Request
    1

    COMING SOON
    Example Request
    1

    COMING SOON
    Example Request
    1

    COMING SOON

    Example Response

    1
2
3
4
5
6

    {
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "redirectUrl":"<redirectRL>"
}

    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.safecharge.com/ppp/api/v1/accountCapture.do

    Input Parameters

    PARAMETER DESCRIPTION
    sessionToken ^String(36) ~Required Session identifier returned by /getSessionToken.
    merchantId ^String(20) ~Required The Merchant ID provided by Nuvei.
    merchantSiteId ^String(20) ~Required The Merchant Site ID provided by Nuvei.
    userTokenId ^String(255) ~Required The ID of the user in the merchant’s system.
    paymentMethod ^String(50) ~Required Specifies the payment method name of the payment option to be charged.
    See: APM Input Fields.
    currencyCode ^String(3) ~Required The three-letter ISO currency code.
    countryCode ^String(2) ~Required The two-letter ISO country code.
    languageCode ^String(2) ^Optional The language in which the transaction is to be completed.
    notificationUrl ^String(1000) ^Optional The URL to which DMNs are sent (see our DMNs Guide).

    Output Parameters

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

    DCC Methods

    /getCardDetails

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/getCardDetails.do
    Example Request
    1
2
3
4
5
6
7
8

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

    safecharge.getCardDetails({
    "sessionToken": "3765655c-c333-47b7-aea6-07c54e59d1fb", // taken from getSessionToken result
    "cardNumber": "4000027891380961",
}, function (pError, pRes){

})
    Example Request
    1
2
3
4
5
6
7
8

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/)

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

    SafechargeResponse response = safecharge.getCardDetails(clientUniqueId, null, cardNumber);
}
    Example Request
    1

    COMING SOON
    Example Request
    1
2
3

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/net-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

    {
    "brand": "VISA",
    "cardType": "Credit",
    "program": "Visa Platinum",
    "visaDirectSupport": "0",
    "issuerCountry": "pe",
    "currency": "pen",
    "dccAllowed": false,
    "sessionToken": "eaeed493-6ed1-4e44-9cc9-7e698efe51e2",
    "internalRequestId": 212986558,
    "status": "SUCCESS",
    "errCode": 0,
    "merchantId": "479748173730597238",
    "merchantSiteId": "204388",
    "version": "1.0",
    "clientRequestId": "20201025110518"
}

    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 click 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.safecharge.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 credit card number.
    cardNumber or bin must be populated.
    clientRequestId ^String(255) ^Optional The ID of the API request in the merchant’s system.
    clientUniqueId ^String(45) ^Optional The ID of the transaction in the merchant’s system.

    Output Parameters

    Parameter Description
    sessionToken ^String(36) The session identifier returned by /getSessionToken.
    clientRequestId ^String(20) The ID of the API request in merchant system.
    clientUniqueId ^String(255) The ID of the transaction in merchant system.
    brand ^String The name of the card scheme; for example: Visa
    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 “N” for Visa Platinum
    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 ^String(20) Nuvei 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 ^String(11) If an error occurred on the request side, an error code is returned in this parameter.
    status ^String The cashier status of merchant request.
    Possible statuses:
    SUCCESS
    ERROR

    /getMcpRates

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/getMcpRates.do
    Example Request
    1
2
3
4
5
6
7
8

    {
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "clientUniqueId": "12345",
    "fromCurrency": "USD"
}
    Example Request
    1

    COMING SOON
    Example Request
    1

    COMING SOON
    Example Request
    1

    COMING SOON
    Example Request
    1

    COMING SOON

    Example Response

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

    {
    "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 PM, 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.safecharge.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.
    clientRequestId ^String(255) ^Optional The ID of the API request in the merchant’s system. This value must be unique.
    clientUniqueId ^String(45) ^Optional The ID of the transaction in the merchant’s system.
    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 ^String(20) Nuvei internal unique request ID (used for reconciliation purposes).
    clientRequestId ^String(20) The ID of the API request in merchant system.
    clientUniqueId ^String(255) The ID of the transaction in merchant system.
    mcpTimeStamp ^String(14) The current time stamp
    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 Fields.
    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 merchant request.
    Possible statuses:
    SUCCESS
    ERROR
    errCode ^String(11) If an error occurred on the request side, an error code is returned in this parameter.
    reason ^String(400) The version of the API
    version ^String(10) The current version of the API method.
    The current version is 1.

    /getDccDetails

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/getDccDetails.do
    Example Request
    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"
}
    Example Request
    1

    COMING SOON
    Example Request
    1

    COMING SOON
    Example Request
    1

    COMING SOON
    Example Request
    1

    COMING SOON

    Example Response

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

    {
    "rateValueWitMarkUp": "1.236739013895",
    "markUpValue": "0.05",
    "amount": "18.551085208425",
    "currency": "EUR",
    "originalAmount": "15",
    "originalCurrency": "GBP",
    "sessionToken": "0573655a-a321-4cc3-8ffa-43593bd91b66",
    "clientUniqueId": "695701003",
    "internalRequestId": 214036488,
    "status": "SUCCESS",
    "errCode": 0,
    "merchantId": "479748173730597238",
    "merchantSiteId": "204388",
    "version": "1.0",
    "clientRequestId": "20201101131808"
}

    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.safecharge.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.
    clientRequestId ^String(255) ~Required The ID of the API request in the merchant’s system.
    clientUniqueId ^String(45) ~Required The ID of the transaction in the merchant’s system.
    originalAmount ^String(12) ~Required The original amount of the transaction in the merchant’s own currency.
    originalCurrency ^String(3) ~Required The 3-letter ISO currency code of the merchant’s own currency.
    cardNumber ^String(20) ~Conditional The card number (REQUIRED if apm is not populated).
    apm ^String(50) ~Conditional The payment method (REQUIRED if cardNumber is not populated).
    currency ^String(3) ~Conditional The 3-letter ISO currency code of the conversion currency (REQUIRED if country is not populated).
    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 populated).
    If both currency and country are provided in the input, the currency takes precedence.

    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 ^String(20) Nuvei internal unique request ID (used for reconciliation purposes).
    clientRequestId ^String(20) The ID of the API request in merchant system.
    clientUniqueId ^String(255) The ID of the transaction in merchant system.
    rateValueWithMarkup ^String(12) The rate value with markup.
    markUpValue ^String(12) The markup percentage value.
    amount ^String(12) The converted Amount.
    currency ^String(3) The 3-letter ISO currency code of the original currency.
    originalAmount ^String(12) The original amount in the merchant’s own currency.
    originalCurrency ^String(12) The merchant’s own currency.
    status ^String(20) The cashier status of merchant request.
    Possible statuses:
    SUCCESS
    ERROR
    errCode ^String(11) If an error occurred on the request side, an error code is returned in this parameter.
    reason ^String(400) The version of the API
    version ^String(10) The current version of the API method.
    The current version is 1.

    MPI Methods

    /authorize3d

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/authorize3d.do
    Example Request
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

    {
    "merchantSiteId":"142033",
    "merchantId":"427583496191624621",
    "sessionToken":"9e07802d-5126-4b02-b4b3-ef09dfb94219",
    "clientUniqueId":"12345",
    "currency":"USD",
    "amount":"200",
    "paymentOption":{
        "card":{
            "cardNumber":"4000027891380961",
            "cardHolderName":"John Smith",
            "expirationMonth":"12",
            "expirationYear":"2022",
            "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":"127.0.0.1"
    },
    "billingAddress":{
        "email":"john.smith@email.com",
        "country":"US"
    }
}
    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

    safecharge.authorize3d({
    "sessionToken": "sessionToken", // taken from getSessionToken result
    "currency": "USD",
    "amount": "200",
    "paymentOption": {
        "card": {
            "expirationYear": "2022",
            "CVV": "217",
            "cardHolderName": "John Smith",
            "expirationMonth": "12",
            "cardNumber": "4000027891380961"
        }
    },
    "deviceDetails": {
        "ipAddress": "127.0.0.1"
    },
    "billingAddress": {
        "email": "john.smith@email.com",
        "county": "US"
    }
}, function(pError, pRes) {

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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/)

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

    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");

    acquirer.setBin("665544");
    acquirer.setMerchantId("9876556789");
    acquirer.setMerchantName("Merchant Inc.");

    v2AdditionalParams.setChallengeWindowSize("2");

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

    card.setCardNumber("4000027891380961");
    card.setCardHolderName("john smith");
    card.setExpirationMonth("12");
    card.setExpirationYear("25");
    card.setCVV("217");
    card.setThreeD(threeD);

    paymentOption.setCard(card);

    billingAddress.setCountry("US");
    billingAddress.setEmail("john.smith@email.com");

    deviceDetails.setIpAddress("127.0.0.1");

    Authorize3dResponse response = safecharge.authorize3d(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency, amount, null, null, deviceDetails, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null);
}
    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/php-sdk/)

<?php
$authorize3dRequest = $SafeCharge->getPaymentService()->authorize3d([
    'currency'=> 'USD',
    'amount'=> '10',
    'paymentOption'=> [
        'card'=> [
            'cardNumber'=> '4000027891380961',
            'cardHolderName'=> 'John Smith',
            'expirationMonth'=> '12',
            'expirationYear'=> '2022',
            'CVV'=> '217'
        ]
    ],
    'billingAddress' => [
        'country'   => 'US',
        'email'     => 'john.smith@email.com',
    ],
    'deviceDetails'     => [
        "ipAddress"  => "127.0.0.1"
    ],
    'relatedTransactionId'=> '2110000000001208909',
    'sessionToken'=> '3993eb0c-5f64-4a6c-b16c-485818eb76eb',
    'merchantId'        => '427583496191624621',
    'merchantSiteId'    => '142033',
    'timeStamp'     =>  '<YYYYMMDDHHmmss>',
]);
?>
    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/net-sdk/)

var response = safecharge.Authorize3d(
    "USD",
    "200",
    new PaymentOption
    {
        Card = new Card
        {
            CardNumber = "4000027891380961",
            CardHolderName = "John Smith",
            ExpirationMonth = "12",
            ExpirationYear = "22",
            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"
            }
        }
    },
    "2110000000001208909",
    clientUniqueId: "12345",
    deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" },
    billingAddress: new UserAddress
    {
        Country = "US",
        Email = "john.smith@email.com",
    },
);

    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

        {  
    "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":"",
                "xid":"",
                "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 3D-Secure 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 fields and works the same as the /payment method, with only the following differences:

    @Links URLs

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

    @Test https://ppp-test.safecharge.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 Session identifier returned by /getSessionToken.
    timeStamp ^String(14) ~Required The local time when the method call is performed in the format: YYYYMMDDHHmmss. Needed for the “checksum” hashing calculation.
    checksum ^String(256) ~Required The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey
    Click here to see an example.
    currency ^String(3) ~Required The 3-letter ISO currency code.
    amount ^String(12) ~Required The transaction amount.
    This amount must be identical to the amount listed in the dynamic3D.
    paymentOption ^Class ~Required This class represents the details about the payment method.
    Can have either card or userPaymentOptionId:

    • card class has the following fields:
    ▫ cardNumber String(20) – The card number.
    ▫ cardHolderName String(70) – The card holder name.
    ▫ expirationMonth String(2) – Card expiration month.
    ▫ expirationYear string4() – Card expiration year.
    ▫ CVV String(4) – The CVV/CVC security code.
    ▫ threeD (class) – Contains the required 3D-Secure information. Refer to threeD (in) for details.

    OR

    • userPaymentOptionId – This is a field identifying a payment option that has already been used by the customer and is now requested for re-use. Nuvei keeps payment option details from previous uses.
    relatedTransactionId ^String(19) ~Required Sets the transactionId returned from the preceding initPayment call.
    subMerchant ^Class ~Required countryCode (String,2) – The payment facilitator’s submerchant’s 2-letter ISO country code.
    city (String, 20) – The payment facilitator’s submerchant’s city name.
    id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
    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 ~country and email 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)
    lastName (String, 40)
    address (String, 60)
    address2 (String, 60)
    phone (String, 18)
    zip (String, 10)
    city (String, 30)
    state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
    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.
    Required if you wish to use the paymentOptionId field for future charging of this user without re-collecting the payment details (see User Payment Management for details.
    clientRequestId ^String(255) ^Optional Use this advanced field to prevent idempotency. Use it to uniquely identify the request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
    clientUniqueId ^String(45) ^Optional This ID identifies the transaction in your system. Optionally, you can pass this value to us and we will store it with the transaction record created in our system for your future reference.
    transactionType ^String(45) ^Optional The type of transaction: Sale, Auth, or PreAuth.
    Sale – Performs a regular payment request.
    Auth – Performs an authorization-only request. Click here for more details.
    PreAuth – Performs an authorization-only request (with a longer settlement period). Click here for more details.
    bin ^String ^Optional The BIN number representing the acquirer with which the transaction is eventually processed, following the 3D authentication process.
    merchantId ^String ^Optional Your merchant ID (MID) with the acquirer with which you are going to process the transaction.
    merchantName ^String ^Optional Your merchant name as registered with the acquirer with which you are going to process the transaction.
    userDetails ^Class ^Optional firstName (String, 30)
    lastName (String, 40)
    address (String, 60)
    phone (String, 18)
    zip (String, 10)
    city (String, 30)
    country (String, 2) – 2-letter ISO country code
    state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
    email (String, 100)
    county (String, 255)
    language (String, 2) – 2-letter ISO language code.
    dateOfBirth (String, 10) – Format is YYYY-MM-DD.
    shippingAddress ^Class ^Optional firstName (String, 30)
    lastName (String, 40)
    address (String, 60)
    phone (String, 18)
    zip (String, 10)
    city (String, 30)
    country (String, 2) – 2-letter ISO country code
    state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
    email (String, 100)
    shippingCounty (String, 255)
    merchantDetails ^Class ^Optional customField1 (String, 255)
    …
    customField15
    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.
    urlDetails ^Class ^Optional Although DMN responses can be configured per merchant site, it allows dynamically returning the DMN to the provided address per request.
    pendingUrl (String, 1000) – The URL the customer is directed to when the transaction response is pending.
    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 field value.
    productId ^String(50) ^Optional A free text field 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 field value.
    customData ^String(255) ^Optional This parameter can be used to pass any type of information.
    If sent in request, then it is passed on to the payments gateway, and is visible in Nuvei’s back-office tool transaction reporting and is returned in response.
    webMasterId ^String(255) ^Optional This is an affiliate parameter that the merchant can send.
    This is used by Nuvei’s eCommerce Plugins (Magento, Demandware) and also Nuvei API SDKs to send the Plugin/SDK name and version, so that support is able to identify from where the transaction arrived to the gateway through Nuvei API.
    orderId ^String(45) ^Optional The order ID provided by Nuvei.
    This parameter is passed 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 ID of the transaction in merchant system.
    internalRequestId ^Long(20) Nuvei’s internal unique request ID (used for reconciliation purpose, etc.).
    status ^String(20) The cashier status of merchant request.
    Possible statuses: SUCCESS or ERROR
    transactionStatus ^String(20) The gateway transaction status.
    paymentOption ^Class This class represents the data retrieved from the processed payment method. Can be either card, or in case of alternative payment method, it shows the redirectUrl. In addition, the userPaymentOptionId field is retrieved as detailed below:
    • redirectUrl (String) – The redirect URL to follow in case of alternative payment method, which to process needs to be redirected to.

    OR

    • Card – 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).
      ▫ avsCode (String) – The AVS (address verification) response.
      ▫ acquirerId (String) – The acquirer ID of the acquirer which processed the transaction.
      ▫ threeD (class) – Contains the required 3D-Secure information. Refer to threeD (out) for details.

    OR

    • userPaymentOptionId – In addition to the above, this field 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

    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.
    errCode ^String(11) If an error occurred on the request side, an error code is returned in this parameter.
    reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter, for example failure in checksum validation, timeout from processing engine, etc.
    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 is returned in this parameter, for example failure in checksum validation, timeout from processing engine, etc.
    gwExtendedErrorCode ^Integer(11) The error code if an error occurred on the bank’s side.
    When a transaction is successful, this field is 0.
    When a transaction is not successful, the parameter is the code of the generic error.
    version ^Integer(10) The version of the request.
    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 This 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. Click here for more details.
    customData ^String(255) This parameter can be used to pass any type of information.
    If sent in the request, then it is passed on to the payments gateway, and is visible in Nuvei’s back-office tool transaction reporting and is returned in response.
    fraudDetails ^Class finalDecision (String)
    score (decimal)
    recommendations (String)
    system {systemId (String),systemName (String),decision (String)
    rules [ruleId (String),ruleDescription (String)]}

    The '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.
    The ‘system’ refers to which risk management system provided the fraud information. The provider can be Nuvei (systemId=1) or an external provider.
    The ‘rule’ refers to the risk management system rules triggered by the transaction.
    The ‘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 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.
    The 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 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 ID of the API request in the merchant’s system.

    /verify3d

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/verify3d.do
    Example Request
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

    {
    "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":"2022",
            "CVV":"217"
        }
    },
    "billingAddress":{
        "email":"john.smith@email.com",
        "country":"US"
    }
}
    Example Request
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

    safecharge.verify3d({
    "sessionToken": "sessionToken", // taken from getSessionToken result
    "relatedTransactionId": "transactionId", // taken from authorize3d result
    "currency":"USD",
    "amount":"200",
    "paymentOption":{
      "card": {
        "expirationYear" : "2022",
        "CVV"            : "217",
        "cardHolderName" : "John Smith",
        "expirationMonth": "12",
        "cardNumber"     : "4000027891380961"
      }
    },
    "billingAddress": {
      "email": "john.smith@email.com",
      "county": "US"
    }
}, function (pError, pRes){

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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/java-sdk/)

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

    card.setCardNumber("4000027891380961");
    card.setCardHolderName("john smith");
    card.setExpirationMonth("12");
    card.setExpirationYear("2022");
    card.setCVV("217");

    paymentOption.setCard(card);

    billingAddress.setCountry("US");
    billingAddress.setEmail("john.smith@email.com");

    Verify3dResponse response = safecharge.verify3d(clientUniqueId, clientRequestId, amount, currency, billingAddress, null, null, null, relatedTransactionId, null, null, userTokenId, paymentOption);
}
    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/php-sdk/)

<?php
$verify3dRequest = $SafeCharge->getPaymentService()->verify3d([
    'currency'=> 'USD',
    'amount'=> '10',
    'paymentOption'=> [
        'card'=> [
            'cardNumber'=> '4000027891380961',
            'cardHolderName'=> 'John Smith',
            'expirationMonth'=> '12',
            'expirationYear'=> '2022',
            'CVV'=> '217'
        ]
    ],
    'billingAddress' => [
        'country'   => 'US',
        'email'     => 'john.smith@email.com',
    ],
    'deviceDetails'     => [
        "ipAddress"  => "127.0.0.1"
    ],

    'relatedTransactionId'=> '2110000000001208909',
    'sessionToken'=> '3993eb0c-5f64-4a6c-b16c-485818eb76eb',
    'merchantId'        => '427583496191624621',
    'merchantSiteId'    => '142033',
    'timeStamp'     =>  '<YYYYMMDDHHmmss>',
]);
?>
    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

    //Initialize the SDK (see https://docs.safecharge.com/documentation/guides/server-sdks/net-sdk/)

var response = safecharge.Verify3d(
    "USD",
    "200",
    new Verify3dPaymentOption
    {
        Card = new Verify3dCard
        {
            CardNumber = "4000027891380961",
            CardHolderName = "john Smith",
            ExpirationMonth = "12",
            ExpirationYear = "22",
            CVV = "217"
        }
    },
    "2110000000001208909",
    deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" },
    billingAddress: new UserAddress
    {
        Country = "US",
        Email = "john.smith@email.com",
    },
);

    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

    {
    "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": {},
                "xid": "",
                "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 3D-Secure only request. This method is called after the /authorize3d method in case of the Challenge.

    This method retrieves the generic 3D-Secure result (ECI and CAVV) that you need to send to your PSP or acquirer to benefit from the 3D-Secure liability shift received from the Nuvei 3D-Secure service.

    @Links URLs

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

    @Test https://ppp-test.safecharge.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 Session identifier returned by /getSessionToken.
    currency ^String(3) ~Required The 3-letter ISO currency code.
    amount ^String(12) ~Required The transaction amount.
    This amount must be identical to the amount listed in the dynamic3D.
    paymentOption ^Class ~Required This class represents the details about the payment method.
    Can have either card or userPaymentOptionId:

    • card class has the following fields:
    ▫ cardNumber String(20) – The card number.
    ▫ cardHolderName (String, 70) – The card holder name.
    ▫ expirationMonth (String, 2) – Card expiration month.
    ▫ expirationYear – String(4)– Card expiration year.
    ▫ CVV (String, 4) – The CVV/CVC security code
    ▫ threeD.paResponse (class) – Only relevant if 3D-Secure is v1. To verify, you need to provide the paResponse retrieved from the termUrl. See the 3D-Secure Guide for a full explanation. For 3D-Secure v2, no threeD field needs to be submitted.

    OR

    • userPaymentOptionId – This is a field identifying 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 transaction ID of the of the call to /authorize3d.
    subMerchant ^Class ~Required countryCode (String,2) – The payment facilitator’s submerchant’s 2-letter ISO country code.
    city (String, 20) – The payment facilitator’s submerchant’s city name.
    id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
    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 ~country and email 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)
    lastName (String, 40)
    address (String, 60)
    address2 (String, 60)
    phone (String, 18)
    zip (String, 10)
    city (String, 30)
    state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
    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.
    Required if you wish to use the paymentOptionId field for future charging of this user without re-collecting the payment details (see User Payment Management for details.

    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 ID of the transaction in merchant system.
    internalRequestId ^Long(20) Nuvei’s internal unique request id (used for reconciliation purpose, etc.).
    status ^String(20) The cashier status of merchant request.
    Possible statuses: SUCCESS or ERROR
    transactionStatus ^String(20) The gateway transaction status.
    paymentOption ^Class This class represents the details of the payment method. This can be one of two options:

    • card – Represents the credit/debit card details.

    OR

    • alternativePaymentMethod – Represents an alternative payment method.

    In addition, if a user option ID was either created or an existing one was used in the transaction, it returns the ID to this payment option:
    userPaymentOptionId – This is a field identifying 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 previous uses.
    merchantDetails ^Class customField1 (String, 255)
    …
    customField15
    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.
    errCode ^String(11) If an error occurred on the request side, an error code is returned in this parameter.
    reason ^String(400) If an error occurred on the request side, an error reason is returned in this parameter, for example failure in checksum validation, timeout from processing engine, etc.
    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 is returned in this parameter, for example failure in checksum validation, timeout from processing engine, etc.
    gwExtendedErrorCode ^Integer(11) The error code if an error occurred on the bank’s side.
    When a transaction is successful, this field is 0.
    When a transaction is not successful, the parameter is the code of the generic error.
    version ^Integer(10) The version of the request.
    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. Click here for more details.
    customData ^String(255) This parameter can be used to pass any type of information.
    If sent in the request, then it is passed on to the payments gateway, and is visible in Nuvei’s back-office tool transaction reporting and is returned in response.
    fraudDetails ^Class finalDecision (String)
    score (decimal)
    recommendations (String)
    system {systemId (String),systemName (String),decision (String)
    rules [ruleId (String),ruleDescription (String)]}

    The '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.
    The ‘system’ refers to which risk management system provided the fraud information. The provider can be Nuvei (systemId=1) or an external provider.
    The ‘rule’ refers to the risk management system rules triggered by the transaction.
    The ‘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 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.
    The 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 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 ID of the API request in the merchant’s system.

    Class Objects

    threeD Input Class

    This class contains the 3D-Secure information required as an input for /payment or /authorize3d to perform the 3D authorization request (the first /payment call) as defined in the 3D-Secure Guide.

    Most of the fields specified in the table below are required for 3D only for the first call to /payment (or /authorize3d) that performs the 3D authorization before proceeding for payment.

    The following are exceptions to this:

    Additional Class Parameters

    Parameter Description
    v2AdditionalParams ^Class ~Required for 3DS v2 For the list of parameters in this class, please see the v2AdditionalParams table below.
    browserDetails ^Class ~Required for 3DS v2 For the list of parameters in this class, please see the browserDetails table below.
    notificationURL ^String ~Required for 3DS v2 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 ~Required for 3DS v2 The merchant website fully-qualified URL.
    version ^String ~Required for 3DS v2 The number of the 3D-Secure version used, as indicated by the value returned from /initPayment)
    methodCompletionInd ^String ~Required for 3DS v2 Indicates whether the 3D-Secure v2 fingerprint challenge was successfully completed.
    Y – Successfully completed
    N – Did not successfully complete
    U – Unavailable (3D-Secure Method URL was not provided in the /initPayment) response)
    platformType ^String ~Required for 3DS v2 The device channel.
    01 – App-based (only for SDK implementation, not in the scope of this document)
    02 – Browser
    paResponse ^String ~Conditional The payment authorization response returned by the card issuer/bank. Relevant only to the second payment call and only if 3D-Secure v1 authentication was performed.
    externalMpi ^Class ~External MPI eci (String, 2) – The Electronic Commerce Indicator that indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant.
    cavv (String, 50) – The card authentication verification value as received from the MPI.
    xid (String, 50) – The transaction ID received from the MPI for 3D-Secure v1.
    dsTransID (String, 36) – The transaction ID received from the MPI for 3D-Secure v2. Required for 3D-Secure v2; do not send at all in 3D-Secure v1.

    You can also use challengePreference and externalRiskScore to increase the chances for 3D-Securev2 exemption. For details, please scroll down and view the descriptions of these fields.
    account ^Class ^Optional For the list of parameters in this class, please see the account table below.
    mpiChallengePreference ^String(2) ^Optional If your MPI has already requested an exemption in the Authentication, you should provide Nuvei with this field value to allow us to adjust our exemption flag accordingly, so it is synchronized according to EMVCO and schemes guidelines.
    Possible values:
    01 – Challenge requested
    02 – Exemption requested
    03 – No preference
    convertNonEnrolled ^String ^Optional Set this field to automatically convert the request for payment in case of 3D-Secure v1 failure to authenticate. The transaction in this case is non-3D-Secure.
    externalRiskScore ^String(3) ^Optional If you wish to request an exemption prior to the Authentication request when Nuvei is your 3D-Secure v2 MPI, you should populate 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 will consider this value if coordinated in advance with our Risk Team.

    v2AdditionalParams

    Parameter Description
    challengeWindowSize ^String(2) ~Required for 3DS v2 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 format YYYYMMDD. Required if isRebilling = 0
    rebillFrequency ^String(4) ~Conditional Recurring Frequency in days. Required if isRebilling = 0
    challengePreference ^String(2) ^Optional Determines the preference of the merchant.
    This can be used either during an Authentication request when Nuvei is the 3D-Secure v2 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:
    01 – Challenge requested
    02 – Exemption requested
    03 – No preference
    deliveryEmail ^String(254) ^Optional For electronic delivery, the email address to which the merchandise was delivered.
    deliveryTimeFrame ^String(2) ^Optional Indicates the merchandise delivery timeframe.
    01 – Electronic Delivery
    02 – Same day shipping
    03 – Overnight shipping
    04 – Two-day or more shipping
    giftCardAmount ^String(15) ^Optional For 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 prepaid or gift card purchase, the total number of individual prepaid or gift cards/codes purchased.
    giftCardCurrency ^String(3) ^Optional For prepaid or gift card purchase, the ISO 4217 3-letter currency code of the gift card.
    preOrderDate ^String(8) ^Optional For a pre-ordered purchase, the expected date that the merchandise is available (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 fields)
    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 v2 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 3D-Secure Server truncates the excess portion.
    ip ^String(45) ~Required for 3DS v2 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 ^String(5) ~Required for 3DS v2 Boolean that represents the ability of the cardholder browser to execute Java.
    REQUIRED when javaScriptEnabled is TRUE.
    Value is returned from the navigator.javaEnabled property.
    Values accepted:
    TRUE
    FALSE
    javaScriptEnabled ^String(5) ~Required for 3DS v2 Determines whether the browser is JavaScript enabled (from navigator.javaEnabled property).
    Values accepted:
    TRUE
    FALSE
    language ^String(8) ~Required for 3DS v2 Value representing the browser language as defined in IETF BCP47.
    Returned from navigator.language property.
    colorDepth ^String(2) ~Required for 3DS v2 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.
    Values accepted:
    1 – 1 bit
    4 – 4 bits
    8 – 8 bits
    15 – 15 bits
    16 – 16 bits
    24 – 24 bits
    32 – 32 bits
    48 – 48 bits
    screenHeight ^String(6) ~Required for 3DS v2 Total height of the Cardholder’s screen in pixels.
    Value is returned from the screen.height property.
    screenWidth ^String(6) ~Required for 3DS v2 Total width of the cardholder’s screen in pixels.
    Value is returned from the screen.width property.
    timeZone ^String(5) ~Required for 3DS v2 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 v2 Exact content of the HTTP user-agent header.
    Value accepted:
    If the total length of the User-Agent sent by the browser exceeds 2048 characters, the 3D-Secure 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 (guest checkout)
    02 – Created during this transaction
    03 – Less than 30 days
    04 – 30–60 days
    05 – More than 60 days
    lastChangeDate ^String(8) ^Optional Date 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.
    YYYYMMDD
    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.
    YYYYMMDD
    passwordChangeDate ^String(8) ^Optional Date that cardholder’s account with the 3DS Requestor had a password change or account reset.
    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 that 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.
    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 3D-Secure information returned from the call to the /payment or /authorize3d methods after performing the 3D authorization request (the first /payment call) as defined in the 3D-Secure Guide.

    The output table is separate into 2 parts:

    The following fields 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 3D-Secure verification page.
    acsChallengeMandate ^String(1) The 3D-Secure v2 challenge required indication.
    Possible values:
    N – Not required
    Y – Required (only in case of 3D-Secure v2)
    cReq ^String The Base64 encoded cReq relevant for the 3D-Secure v2.
    acsUrl is also sent as a separate field (only in case of 3D-Secure v2)
    paRequest ^String The 3D-Secure request data for the card issuer/bank (only in case of 3D-Secure v1)
    threeDFlow ^String Indicates which 3D 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. (paRequest and acsUrl are returned and the merchant needs to redirect to issuer and call payment3D method afterwards).
  • If the gateway response parameter for threeDFlow= 0, the transaction converted from Sale3D to Sale or Auth depending on the configured merchant mode of operation after passing the gateway rule engine. (paRequest and acsUrl are 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 3D-Secure authorization as received from the issuer.
    threeDReason ^String Reason description for a failed 3D-Secure authorization as received from the issuer.
    challengeCancelReasonId ^String Reason ID for a canceled 3D-Secure authorization as received from the issuer.
    ChallengeCancelReason ^String Reason description for a canceled 3D-Secure authorization as received from the issuer.
    isLiabilityOnIssuer ^String Indicates if there is 3D-Secure 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.
    challengePreferenceReason ^String This value is returned following a 3D-Secure v2 challenge and describes the reason for challenge. Click here for more details.
    cascadedTo3Dv1 ^String(5) Indicates if a transaction failed for a technical reason and was downgraded from 3Dv2 to 3Dv1 after /payment or /authorize3d was invoked.
    Possible values:
    TRUE – The transaction was downgraded.
    FALSE or Null – No downgrade was performed.
    This parameter is included in the response only if its value is TRUE.

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

    PARAMETER DESCRIPTION
    result ^String(1) This field is 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 Did this consumer define this merchant as whitelist or not. If the consumer defined the merchant, then this is the reason why 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 The Electronic Commerce Indicator that indicates the level of security used in a 3D 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 3D-Secure program.
    7 – Payment authentication was not performed.
    Mastercard
    2 – The cardholder was successfully authenticated.
    1 – The issuer or cardholder does not participate in a 3D-Secure program.
    6 – Payment authentication was not performed.
    threeDReason ^String If the attempt failed, this parameter is returned by the banks to indicate the reason why the transaction was not passed as full 3D.
    Returned in the end of the 3D-Secure after successful frictionless.
    authenticationType ^String(2) The type of authentication performed during the 3D-Secure v2 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 field is populated, the merchant must display the information to the cardholder.

    externalToken class

    This class is set under the card class and is to be used if you wish to submit a payment with an external token provider as the card input.

    PARAMETER DESCRIPTION
    externalTokenProvider ^String(45) ^Optional The name and ID of the external token provider; for example: Apple Pay.
    mobileToken ^String(5000) ^Optional The token received from Apple during Dynamic Server to Server JS Button Solution.
    To work with external token, provider special configurations are required. For more information, please contact Nuvei’s Integration Support Team.

    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.

    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 and is required when the cardData>cardNumber parameter is populated and sent. 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 fields that appear are based on the specific addendum type. Currently, there are 3 main subclasses:

    PARAMETER DESCRIPTION
    addendums.airlines.reservationDetails ^Class ^Optional addendumSent(String)
    pnrCode(String)
    bookingSystemUniqueId(String)
    computerizedReservationSystem(String)
    ticketNumber(String)
    documentType(String)
    flightDateUTC(String)
    issueDate(String)
    travelAgencyCode(String)
    travelAgencyName(String)
    travelAgencyInvoiceNumber(String)
    travelAgencyPlanName(String)
    restrictedTicketIndicator(String)
    issuingCarrierCode(String)
    isCardholderTraveling(String)
    passengersCount(String)
    infantsCount(String)
    payerPassportId(String)
    totalFare(String)
    totalTaxes(String)
    totalFee(String)
    boardingFee(String)
    ticketIssueAddres(String)
    addendums.airlines.reservationDetails.passengerDetails ^Class ^Optional passengerId(String)
    passportNumber(String)
    customerCode(String)
    frequentFlyerCode(String)
    title(String)
    firstName(String)
    lastName(String)
    middleName(String)
    dateOfBirth(String)
    phoneNumber(String)
    passengerName (String)
    addendums.airlines.reservationDetails.flightLegDetails ^Class ^Optional flightLegId(String)
    airlineCode(String)
    flightNumber(String)
    departureDate(String)
    arrivalDate(String)
    departureCountry(String)
    departureCity(String)
    departureAirport(String)
    destinationCountry(String)
    destinationCity(String)
    destinationAirport(String)
    legType(String)
    flightType(String)
    ticketDeliveryMethod(String)
    ticketDeliveryRecipient(String)
    fareBasisCode(String)
    serviceClass(String)
    seatClass(String)
    stopOverCode(String)
    departureTaxAmount(String)
    departureTaxCurrency(String)
    fareAmount(String)
    feeAmount(String)
    taxAmount(String)
    layoutIntegererval(String)

    PARAMETER DESCRIPTION
    cardPresentPointOfSale ^Class ^Optional terminalId(String)
    trackData(String)
    trackType(String)
    icc(String)
    pinData(String)
    entryMode(String)
    terminalCapability(String)
    terminalAttendance(String)
    cardSequenceNum(String)
    offlineResCode(String)
    localTime(String)
    localDate(String)
    cvMethod(String)
    cvEntity(String)
    outputCapability(String)
    autoReversal(String)
    autoReversalAmount(String)
    autoReversalCurrency(String)
    suppressAuth(String)
    terminalCity(String)
    terminalAddress(String)
    terminalCountry(String)
    terminalZip(String)
    terminalState(String)
    terminalModel(String)
    terminalManufacturer(String)
    terminalMacAddress(String)
    terminalKernel(String)
    terminalImei(String)
    mobileTerminal(String)

    PARAMETER DESCRIPTION
    localpayment ^Class ^Optional nationalId (String, 255) – Must be sent when processing is performed by local banks in certain countries, such as: Israel and Latin America (LATAM).
    debitType (String, 255).
    Possible values:
    1 – Singular payment.
    2 – Installments.
    3 – Special debit.
    firstInstallment (String, 255)
    periodicalInstallment (String, 255)
    numberOfInstallments (String, 255)

    alternativePaymentMethod Class

    This class passes to Nuvei the information of the APM that the merchant wishes to use to process with Nuvei.

    Parameter Description
    paymentMethod ^String(50) ~Required Specifies the payment method name of the payment option to be charged.
    See: APM Input Fields.
    Payment method fields ^Variables See: APM Input Fields.

    The following Excel table shows the countries and currencies supported for each APM.

     

    @_Download@apm_unique_names_deposit_table@You can download the list of supported countries and supported currencies for each APM by clicking 'Export as CSV’.@APM Unique SafeCharge Names (Payin)

    Deprecated Methods

    This section describes deprecated payment methods that are still valid, but should not be used for new integrations. They do not support newer features and do not support the new 3D-Secure v2 initiative.

    The 3D-Secure flow is implemented in the following four stages:
    1. dynamic3D method – Provides the merchant with the 3D-Secure payment data (paRequest), as well as the 3D-Secure verification page URL (acsUrl) for the card issuer/bank.
    2. Merchant required actions – Redirect the user’s browser to the issuing bank’s 3D-Secure authentication page (according to the value of the acsUrl parameter). Redirect should be done using POST and sending the parameters paRequest, termUrl to the acsUrl as shown in the HTML example below: 

    1
2
3
4
5
6
7
8
9

    <body OnLoad="OnLoadEvent();" >
<form name="mainform" action="ACS_URL" method="POST">
<h1>3D-Secure Transactions</h1>
<h3>Click Submit to process your 3D-Secure transaction.</h3>
<input type="submit" value="Submit">
<input type="hidden" name="PaReq" value="PAREQ">
<input type="hidden" name="TermUrl" value="TERM_URL">
</form>
</body>



    3. Card issuer/bank required actions – Following the successful 3D-Secure verification, the card issuer/bank redirects the consumer back to the merchant website (using termUrl), performs the needed actions, and provides the 3D-Secure payment data (paResponse).
    4. payment3D method – Performs the actual payment transaction.

    These four stages are described in detail in the following sections.

    /dynamic3D

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/dynamic3D.do
    Example Request
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
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

    {
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "isDynamic3D": "1",
    "dynamic3DMode":"",
    "isRebilling":"0",
    "isPartialApproval":"0",
    "currency": "EUR",
    "amount": "200",
    "amountDetails": {
        "totalShipping": "0",
        "totalHandling": "0",
        "totalDiscount": "0",
        "totalTax": "0"
    },
     "items": [{
        "name": "name",
        "price": "200",
        "quantity": "1"
    }],
    "deviceDetails": {
        "ipAddress": "127.0.0.1"
    },
    "userDetails": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "shippingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "shippingCounty":""
    },
    "billingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "merchantDetails": {
        "customField1": ""
    },
    "cardData": {
        "cardNumber": "4111111111111111",
        "cardHolderName": "test name",
        "expirationMonth": "01",
        "expirationYear": "2020",
        "CVV":"",
        "ccTempToken": ""
    },
    "userPaymentOption":{
        "userPaymentOptionId":"1459503",
        "CVV":"234"
    },
    "relatedTransactionId": "2110000000001208909",
    "urlDetails": {
        "notificationUrl": "http://notificationUrl.com"
    },
    "externalMpi": {
        "eci":"",
        "cavv":"",
        "xid":""
    },
    "storedCredentials": {
        "storedCredentialsMode":""
    },
    "productId":"",
    "customData":"",
    "externalTokenProvider": {
        "externalTokenProvider":"",
        "mobileToken":""
    },
    "webMasterId":"",
    "timeStamp": "20190118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
    Example Request
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

    jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

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

};

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

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

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

    Example Response

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

    {
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "internalRequestId": "866",
    "threeDFlow": "0",
    "status": "SUCCESS",
    "transactionStatus": "APPROVED",
    "merchantDetails": {
        "customField1": ""
    },
    "errCode": "0",
    "reason": "",
    "gwErrorCode": "0",
    "gwErrorReason": "",
    "gwExtendedErrorCode": "0",
    "version": "1.0",
    "userPaymentOptionId": "12442",
    "externalTransactionId": "2345346589",
    "transactionId": "1000030724",
    "authCode": "08AF6E",
    "eci": "",
    "threeDReason": "",
    "paRequest": "",
    "acsUrl": "www.issuer3Dsite.com",
    "externalToken":{
        "externalToken_blockedCard":"",
        "externalToken_cardAcquirerId":"",
        "externalToken_cardAcquirerName":"",
        "externalToken_cardBin":"",
        "externalToken_cardBrandId":"",
        "externalToken_cardBrandName":"",
        "externalToken_cardExpiration":"",
        "externalToken_cardLength":"",
        "externalToken_cardMask":"",
        "externalToken_cardName":"",
        "externalToken_cardTypeId":"",
        "externalToken_cardTypeName":"",
        "externalToken_clubName":"",
        "externalToken_creditCompanyId":"",
        "externalToken_creditCompanyName":"",
        "externalToken_extendedCardType":"",
        "externalToken_Indication":"",
        "externalToken_tokenValue":"",
        "externalToken_tokenProvider":""
    },
    "partialApprovalDetails":{
        "isPartialApproval": "",
        "amountInfo":{
            "requestedAmount": "",
            "requestedCurrency": "",
            "processedAmount": "",
            "processedCurrency": ""
        }
    },
    "cvv2Reply":"",
    "avsCode":"",
    "transactionType":"",
    "customData":"",
    "fraudDetails":{
        "finalDecision":"",
        "recommendations": "",
        "system":{
            "systemId":"1",
            "systemName":"SafeCharge",
            "decision":"",
            "rules":[{
               "ruleId": "",
               "ruleDescription":""
            }]
        }
    }
}

    This is the initial stage of the 3D-Secure payment process, providing the merchant with the necessary data, and provides the card issuer/bank with the verification page URL.

    @Links URLs

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

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

    Input Parameters

    PARAMETER DESCRIPTION
    sessionToken ^String(36) ~Required The session identifier returned by /getSessionToken.
    merchantId ^String(20) ~Required The Merchant ID provided by Nuvei.
    merchantSiteId ^String(20) ~Required The Merchant Site ID provided by Nuvei.
    clientUniqueId ^String(45) ~Required The ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    Appears in DMN as merchant_unique_id parameter.
    isDynamic3D ^String(1) ~Required Always send isDynamic3D = 1.
    currency ^String(3) ~Required The 3-letter ISO currency code.
    amount ^String(12) ~Required The transaction amount.
    amountDetails ^Class ~Required totalShipping (String, 255)
    totalHandling (String, 10)
    totalDiscount
    totalTax (String, 10)

    The items and amountDetails prices should be summed up (if device type cannot be recognized) in the amount parameter and sent separately.
    All prices must be in the same currency.
    items ^Class ~Required name (String, 255)
    price (String, 10)
    quantity (String, 10)

    The items and amountDetails prices should be summed up in the amount parameter and sent separately.
    All prices must be in the same currency.
    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 ~country and email Required country (String, 2, REQUIRED) – 2-letter ISO country code
    email (String, 100, REQUIRED)
    firstName (String, 30)
    lastName (String, 40)
    address (String, 60)
    cell (String, 18)
    phone (String, 18)
    zip (String, 10)
    city (String, 30)
    state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
    county (String, 255)

    These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.

    If billingAddress is provided when the user payment option (UPO) is created/updated, then it is used for the transaction.
    If billingAddress is sent in the request of /openOrder or /payment as a separate parameter, then it is used for the transaction, and after the transaction is performed, it overrides the one saved in the UPO.
    If billingAddress was not saved in the UPO, and was not sent in the request of /openOrder or /payment as a separate parameter, then the value from userDetails parameter is used, but billingAddress is not saved in the UPO.
    relatedTransactionId ^String(19) ~Required The ID of the original transaction. It is required in case recurring/rebilling transaction was requested (isRebilling=1 sent) using cardData and not using userPaymentOptionId.

    The value sent must contain digits only, meaning this string value cannot contain any character that is not a digit.
    timeStamp ^String(14) ~Required The local time when the method call is performed in the format: YYYYMMDDHHmmss
    checksum ^String(256) ~Required The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey
    Click here to see an example.
    clientRequestId ^String(255) ^Optional ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    userPaymentOption ^Class ^Optional userPaymentOptionId (String, 45)
    CVV (String, 4)

    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.

    This is required if cardData (above) is not sent.

    CVV can be required or non-required per configuration.
    userTokenId ^String(255) ^Optional ID of the user in the merchant’s system.

    If userPaymentOption is sent in the request, then userTokenId must be sent in the request as well.
    transactionType ^String(45) ^Optional The type of transaction: Sale, Auth, or PreAuth.
    Sale – Performs a regular payment request.
    Auth – Performs an authorization-only request. Click here for more details.
    PreAuth – Performs an authorization-only request (with a longer settlement period). Click here for more details.
    dynamic3DMode ^String ^Optional If the merchant wants to force the transaction to go to 3D, send dynamic3DMode = ON.
    isRebilling ^Integer(2) ^Optional When performing recurring/rebilling, use this field to indicate the recurring step with the following values:
    0 – For the initiating recurring event (first recurring transaction).
    1 – For all subsequent recurring transactions.
    isPartialApproval ^String(1) ^Optional This 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 from the desired payment method.
    Partial approval is supported only 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.
    userDetails ^Class ^Optional firstName (String, 30)
    lastName (String, 40)
    address (String, 60)
    phone (String, 18)
    zip (String, 10)
    city (String, 30)
    country (String, 2) – 2-letter ISO country code
    state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
    email (String, 100)
    county (String, 255)

    If you have only one set of this information to send in request (name/address/email etc.), it must be sent using the billingAddress parameter.
    shippingAddress ^Class ^Optional firstName (String, 30)
    lastName (String, 40)
    address (String, 60)
    cell (String, 18)
    phone (String, 18)
    zip (String, 10)
    city (String, 30)
    country (String, 2) – 2-letter ISO country code
    state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
    email (String, 100)
    shippingCounty (String, 255)

    If you have only one set of this information to send in request (name/address/email etc.), it must be sent using the billingAddress parameter.
    dynamicDescriptor ^Class ^Optional merchantName (String, 25) – The merchant name, as is displayed for the transaction on the consumer’s card statement.
    For payment facilitator only, the maximum length of the description is 22, maintaining the following structure:
    “XXX"<merchant name>”
    “XXX” must be 3 characters and identifies the payment facilitator.
    “<merchant name>” must be maximum of 18 characters.

    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
    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.
    cardData ^Class ^Optional This may be one of two options:
    cardNumber (String, 20)
    cardHolderName (String, 70)
    expirationMonth (String, 2)
    expirationYear (String, 4)
    CVV (String, 4)

    OR

    ccTempToken (String, 45)
    CVV (String, 4)
    cardHolderName (String, 70)

    This is required if the userPaymentOption (below) is not sent.

    CVV can be required or non-required per configuration.

    If CVV is not required, you need to send it with NULL value or to not provide the CVV parameter at all in the request.

    Please avoid sending a card that was expired as it may cause a transaction to be declined.
    addendums ^Class ^Optional This class contains industry specific addendums. The addendum fields that appear are based on the specific addendum type. See addendums Class for more details.
    urlDetails ^Class ^Optional notificationUrl (String, 1000) – The URL to which DMNs are sent (see our DMNs Guide).
    externalMpi ^Class ^Optional Allows the merchant to provide the 3D-Secure authentication result as input.

    eci (String, 2) – The Electronic Commerce Indicator that indicates the level of security used in a 3D 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 3D-Secure program.
    7 – Payment authentication was not performed.
    Mastercard
    2 – The cardholder was successfully authenticated.
    1 – The issuer or cardholder does not participate in a 3D-Secure program.
    6 – Payment authentication was not performed
    cavv (String, 50) – The card holder authentication verification value.
    xid (String, 50) – The transaction identification value.
    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 and is required when the cardData>cardNumber parameter is populated and sent. Merchants that do not store card data or that are using Nuvei’s tokenization feature should not send this parameter.
    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 field 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 This parameter can be used to pass any type of information.
    If sent in request, then it is passed on to the payments gateway, is visible in Nuvei’s back-office tool transaction reporting, and is returned in response.
    externalTokenProvider ^Class ^Optional externalTokenProvider (String, 45)
    mobileToken (String, 5000)

    External token provider is a type of entity in the payment industry with its own flow; for example: Apple Pay.
    For Apple Pay, the following values must be passed:
    externalTokenProvider – “Apple Pay”
    mobileToken – The token received from Apple during Dynamic Server to Server JS Button Solution.
    To work with external token, providers special configurations are required. For more information, please contact Nuvei’s Integration Support Team.
    webMasterId ^String(255) ^Optional This is an affiliate parameter that the merchant can send.
    orderId ^String(45) ^Optional The order ID provided by Nuvei.

    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) The ID of the user in the merchant’s system.
    clientUniqueId ^String(255) The ID of the transaction in the merchant’s system.
    Appears in DMN as merchant_unique_id parameter.
    internalRequestId ^String(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
    threeDFlow ^String If the value sent in isDynamic3D input parameter equals 1 (i.e. 3D-Secure was configured to be managed by Nuvei’s Rules Engine) then this parameter indicates whether the performed transaction was auth3D (1), or whether the performed transaction was auth/sale(0). For the merchant required actions once the response is received, see Possible Scenarios Table.
    status ^String(20) The status of merchant’s API request/call.
    Possible statuses: SUCCESS or ERROR.
    transactionStatus ^String(20) The gateway transaction status.
    Possible values: APPROVED, DECLINED, ERROR.
    merchantDetails ^Class customField1 (String, 255)
    …
    customField15

    This allows the merchant to send information with the request to be saved in the API level and returned in response. It is not passed to the payments gateway and is not used for processing.
    errCode ^String(11) If an error occurred on the request side, an error code is returned in this parameter.
    reason ^String(400) If an error occurred on the request side, then an error reason (such as failure in checksum validation, timeout from processing engine, etc.) 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, timeout from processing engine, etc.) is returned in this parameter.
    gwExtendedErrorCode ^Integer(11) Error code if error occurred on the bank’s side. When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
    version ^Integer(10) The current version of the request. The current version is 1.
    userPaymentOptionId ^String(45) The first time a consumer uses a payment method, Nuvei assigns a unique ID to it and return it. The next time the consumer uses a payment method that Nuvei has previously assigned an ID to, the ID is returned as the value of this parameter.
    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) Authorization code of the transaction.
    paRequest ^String The 3D-Secure request data for the card issuer/bank.
    acsUrl ^String URL/endpoint used to redirect the consumer to the card issuer/bank’s 3D-Secure verification page.
    externalToken ^Class externalToken_blockedCardSt (String)
    externalToken_cardAcquirerId (String)
    externalToken_cardAcquirerName (String)
    externalToken_cardBin (String)
    externalToken_cardBrandId (String)
    externalToken_cardBrandName (String)
    externalToken_cardExpiration (String)
    externalToken_cardLength (String)
    externalToken_cardMask (String)
    externalToken_cardName (String)
    externalToken_cardTypeId (String)
    externalToken_cardTypeName (String)
    externalToken_clubName (String)
    externalToken_creditCompanyId (String)
    externalToken_creditCompanyName(String)
    externalToken_extendedCardType (String)
    externalToken_Indication (String)
    externalToken_tokenValue (String)
    externalToken_tokenProvider (String)

    Parameters arriving from a third-party payment provider that also generate card tokens (currently relevant only to CreditGuard as a third-party payment provider which generate card tokens).
    partialApprovalDetails ^Class This determines whether or not the transaction is a partial approval, plus other information regarding the amount.
    These parameters are returned only if the partial approval feature was in use, per the relevant input parameter sent value.

    isPartialApproval (String, True or False),
    amountInfo:
    requestedAmount (String)
    requestedCurrency (String)
    processedAmount (String)
    processedCurrency (String)
    eci ^String The Electronic Commerce Indicator that indicates the level of security used in a 3D 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 3D-Secure program.
    7 – Payment authentication was not performed.
    Mastercard
    2 – The cardholder was successfully authenticated.
    1 – The issuer or cardholder does not participate in a 3D-Secure program.
    6 – Payment authentication was not performed.
    threeDReason ^String If the attempt failed this parameter is returned by the banks to indicate the reason why the transaction was not passed as full 3D.
    cvv2Reply ^String The CVV2 response.
    Possible values:
    M – CVV2 Match.
    N – CVV2 No Match.
    P – Not Processed.
    U – Issuer is not certified and/or has not provided Visa the encryption keys.
    S – CVV2 processor is unavailable.
    avsCode ^String The AVS response.
    Possible values:
    A – The street address matches, the zip code does not.
    W – Whole 9-digit zip code match, the street address does not.
    Y – Both the 5-digit zip code and the street address match.
    X – An exact match of both the 9-digit zip code and the street address.
    Z – Only the 5-digit zip code matches, the street code does not.
    U – Issuer is unavailable.
    S – Not Supported.
    R – Retry.
    B – Not authorized (declined).
    N – Both street address and zip code do not match.
    transactionType ^String(45) The type of transaction: Auth3D or Sale or Auth.
    customData ^String(255) This parameter can be used to pass any type of information.
    If sent in request, then is passed on to the payments gateway, is visible in Nuvei’s back-office tool transaction reporting and is returned in response.
    fraudDetails ^Class finalDecision (String)
    score (decimal)
    recommendations (String)
    system{systemId (String), systemName (String), decision (String)
    rules[ruleId (String), ruleDescription (String)]}

    score – 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 – Which risk management system provided the fraud information. The provider can be Nuvei (systemId=1) or an external provider.
    rules – The risk management system rules triggered by the transaction.
    decision – 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 not passed to bank for authorization. The reasons returned in ruleDescription parameter.
  • Review – The risk management system flags a transaction for review but still accept the transaction.
  • Error – An error occurred during 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 – 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 is to accept the transaction. If at least one of the rules leads to a Reject decision, the finalDecision is to reject the transaction.

    To receive this information in response special configurations are required. For more information, please contact Nuvei’s Integration Support Team.
    		•
    orderId ^String(20) The order ID provided by Nuvei.
    clientRequestId ^String(20) ID of the API request in the merchant’s system.

    Possible Scenarios Table

    The below describes possible scenarios for this method and the merchant’s required actions after receiving the method’s response:

    Possible Scenarios for Dynamic 3D (isDynamic3D = 1)

    Possible Scenario Parameter Values Meaning Merchant Required Action
    1 Input:
    isDynamic3D = 1 and
    Output:
    acsUrl is returned and threeDFlow = 1    		 auth3D transaction was performed successfully (3D-Secure managed by Nuvei’s rule engine) and the card is enrolled to 3D OR card is not enrolled for 3D, but the issuer allows registration. 1. Merchant should redirect to acsUrl.
    2. Merchant should call payment3D method afterwards.
    2 Input:
    isDynamic3D = 1 and
    Output:
    acsUrl is NOT returned and threeDFlow = 1    		 auth3D transaction was performed successfully (3D-Secure managed by Nuvei’s rule engine) and the card is NOT enrolled for 3D. 1. Merchant should NOT redirect to acsUrl.
    2. Merchant should call payment3D method (The performed transaction is 'sale’ to complete the 'auth3D’ transaction previously performed in dynamic3D method).
    3 Input:
    isDynamic3D = 1 and
    Output:
    acsUrl is NOT returned and threeDFlow = 0    		 The performed transaction in dynamic3D is 'sale’ or 'auth’, depending on the merchant’s configured mode of operation. If the merchant’s configured mode of operation is sale, then no further action is required.
    If the merchant’s configured mode of operation is Auth-Settle, then the merchant should call settleTransaction method afterwards.



    /payment3D

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/payment3D.do
    Example Request
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

    {
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "transactionType": "Auth",
    "isPartialApproval": "0",
    "currency": "EUR",
    "amount": "200",
    "amountDetails": {
        "totalShipping": "0",
        "totalHandling": "0",
        "totalDiscount": "0",
        "totalTax": "0"
    },
     "items": [{
        "name": "name",
        "price": "200",
        "quantity": "1"
    }],
    "deviceDetails": {
        "ipAddress": "127.0.0.1"
    },
    "userDetails": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "shippingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "shippingCounty":""
    },
    "billingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "merchantDetails": {
        "customField1": ""
    },
    "cardData": {
        "cardNumber": "4111111111111111",
        "cardHolderName": "some name",
        "expirationMonth": "01",
        "expirationYear": "2020",
        "CVV": "122",
        "ccTempToken": ""
    },
    "userPaymentOption":{
        "userPaymentOptionId":"1459503",
        "CVV":"234"
    },
    "paResponse": "",
    "urlDetails": {
        "notificationUrl": "http://notificationUrl.com"
    },
    "storedCredentials": {
        "storedCredentialsMode":""
    },
    "productId":"",
    "customData":"",
    "webMasterId":"",
    "timeStamp": "20190118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
    Example Request
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

    jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

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

};

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

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

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

    Example Response

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

    {
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "internalRequestId": "866",
    "status": "SUCCESS",
    "transactionStatus": "APPROVED",
    "merchantDetails": {
        "customField1": ""
    },
    "errCode": "0",
    "reason": "",
    "gwErrorCode": "0",
    "gwExtendedErrorCode": "0",
    "version": "1.0",
    "userPaymentOptionId": "12442",
    "externalTransactionId": "2345346589",
    "transactionId": "1000030724",
    "authCode": "08AF6E",
    "eci": "",
    "threeDReason": "",
    "externalToken":{
        "externalToken_blockedCard":"",
        "externalToken_cardAcquirerId":"",
        "externalToken_cardAcquirerName":"",
        "externalToken_cardBin":"",
        "externalToken_cardBrandId":"",
        "externalToken_cardBrandName":"",
        "externalToken_cardExpiration":"",
        "externalToken_cardLength":"",
        "externalToken_cardMask":"",
        "externalToken_cardName":"",
        "externalToken_cardTypeId":"",
        "externalToken_cardTypeName":"",
        "externalToken_clubName":"",
        "externalToken_creditCompanyId":"",
        "externalToken_creditCompanyName":"",
        "externalToken_extendedCardType":"",
        "externalToken_Indication":"",
        "externalToken_tokenValue":"",
        "externalToken_tokenProvider":""
    },
    "partialApprovalDetails":{
        "isPartialApproval": "",
        "amountInfo":{
            "requestedAmount": "",
            "requestedCurrency": "",
            "processedAmount": "",
            "processedCurrency": ""
        }
    },
    "cvv2Reply":"",
    "avsCode":"",
    "transactionType":"",
    "customData":"",
    "fraudDetails":{
        "finalDecision":"",
        "recommendations": "",
        "system":{
            "systemId":"1",
            "systemName":"SafeCharge",
            "decision":"",
            "rules":[{
               "ruleId": "",
               "ruleDescription":""
            }]
        }
    }
}

    This final stage performs the actual payment transaction.

    @Links URLs

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

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

    Input Parameters

    PARAMETER DESCRIPTION
    sessionToken ^String(36) ~Required The session identifier returned by /getSessionToken.
    merchantId ^String(20) ~Required The Merchant ID provided by Nuvei.
    merchantSiteId ^String(20) ~Required The Merchant Site ID provided by Nuvei.
    clientUniqueId ^String(45) ~Required The ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    Appears in DMN as merchant_unique_id parameter.
    currency ^String(3) ~Required The 3-letter ISO currency code.
    amount ^String(12) ~Required The transaction amount.
    amountDetails ^Class ~Required totalShipping (String)
    totalHandling (String)
    totalDiscount (String)
    totalTax (String)

    The items and amountDetails prices should be summed up in the amount parameter and sent separately.
    All prices must be in the same currency.
    items ^Class ~Required name (String, 255)
    price (String, 10)
    quantity (String, 10)

    The items and amountDetails prices should be summed up in the amount parameter and sent separately.
    All prices must be in the same currency.
    billingAddress ^Class ~country and email Required country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase.
    email (String, 100, REQUIRED)
    firstName (String, 30)
    lastName (String, 40)
    address (String, 60)
    cell (String, 18)
    phone (String, 18)
    zip (String, 10)
    city (String, 30)
    state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
    county (String, 255)

    It is recommended that you use the getMerchantPaymentMethods to see what Nuvei configuration is to be received.

    If billingAddress is provided when the user payment option (UPO) is created/updated, then it is used for the transaction.
    If billingAddress is sent in the request of /openOrder or /payment as a separate parameter, then it is used for the transaction, and after the transaction is performed, it overrides the one saved in the UPO.
    If billingAddress was not saved in the UPO, and was not sent in the request of /openOrder or /payment as a separate parameter, then the value from userDetails is used, but billingAddress is not saved in the UPO.
    paymentMethod ^String(50) ~Required Nuvei’s unique name of the payment method (for example apmgw_Neteller). For a list of possible values, see the “API Name” column in the table in APM Input Fields.

    This is required if userPaymentOption (below) is not sent. One of these two parameters, paymentMethod or userPaymentOption, MUST be sent, but NEVER both.
    timeStamp ^String(14) ~Required The local time of the method call is performed in the format: YYYYMMDDHHmmss
    checksum ^String(256) ~Required The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey
    Click here to see an example.
    deviceDetails ^Class ~ipAddress Required ipAddress (String, 15, REQUIRED)
    deviceType (String, 10) – Supported device types: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (if device type cannot be recognized).
    deviceName (String, 255)
    deviceOS (String, 255)
    browser (String, 255)
    clientRequestId ^String(255) ^Optional ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    userTokenId ^String(255) ^Optional ID of the user in the merchant’s system.

    If userPaymentOption is sent in the request, then userTokenId must be sent in the request as well.
    userDetails ^Class ^Optional firstName (String, 30)
    lastName (String, 40)
    address (String, 60)
    phone (String, 18)
    zip (String, 10)
    city (String, 30)
    country (2-letter ISO country code)(String, 2)
    state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only)
    email (String, 100)
    county (String, 255)
    language (String, 2) – 2-letter ISO language code.
    dateOfBirth (String, 10) – Format is YYYY-MM-DD.

    If you have only one set of this information to send in request (name/address/email etc.), it must be sent it using the billingAddress parameter.
    shippingAddress ^Class ^Optional firstName (String, 30)
    lastName (String, 40)
    address (String, 60)
    cell (String, 18)
    phone (String, 18)
    zip (String, 10)
    city (String, 30)
    country (String, 2) – 2-letter ISO country code
    state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
    email (String, 100)
    shippingCounty (String, 255)

    If you have only one set of this information to send in request (name/address/email etc.), it must be sent using the billingAddress parameter.
    dynamicDescriptor ^Class ^Optional merchantName (String, 25) – The merchant name, as is displayed for the transaction on the consumer’s card statement.
    For payment facilitator only, the maximum length of the description is 22, maintaining the following structure:
    “XXX"<merchant name>”
    “XXX” must be 3 characters and identifies the payment facilitator.
    “<merchant name>” must be maximum of 18 characters.

    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
    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.
    addendums ^Class ^Optional This class contains industry specific addendums. The addendum fields that appear are based on the specific addendum type. See addendums Class for more details.
    userAccountDetails ^Class ^Optional Nuvei’s account identifiers of the payment methods. For more information, see APM Input Fields.

    This is required if paymentMethod (above) is sent and userPaymentOption (below) is not sent.
    userPaymentOption ^Class ^Optional 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.

    This is required if the user wishes to pay with an existing UPO, and paymentMethod and userAccountDetails (above) were not sent.

    This is required if paymentMethod (above) is not sent. One of these two parameters, paymentMethod or userPaymentOption, MUST be sent, but NEVER both.
    urlDetails ^Class ^Optional Although DMN responses can be configured per merchant site, it allows dynamically returning the DMN to the provided address per request.
    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 (see our DMNs Guide).
    subMethodDetails ^Class ^Optional subMethod (String)
    subMethodField1 (String)
    subMethodField2 (String)

    This JSON class is for advanced APMs flows. See APM Submethods for details.
    The submethod parameter enables working with a specific payment method in multiple flows.

    Supported Flows
    PayPal quick registration mode.
    - subMethod should be set to QuickRegistration. No other fields are required.
    PayPal Membership Agreement
    - subMethod should be set to referenceTransaction. No other submethod fields are required.
    customData ^String(255) ^Optional This parameter can be used to pass any type of information.
    If it is sent in the request, then it is passed on to the payments gateway and is visible in Nuvei’s back-office tool transaction reporting.
    webMasterId ^String(255) ^Optional This is an affiliate parameter that the merchant can send.
    orderId ^String(45) ^Optional The order ID provided by Nuvei.

    Output Parameters

    PARAMETER DESCRIPTION
    sessionToken ^String(36) Session identifier returned by /getSessionToken.
    merchantId ^String(20) Merchant ID provided by Nuvei.
    merchantSiteId ^String(20) Merchant Site ID provided by Nuvei.
    userTokenId ^String(20) ID of the user in the merchant’s system.
    clientUniqueId ^String(20) The ID of the transaction in the merchant’s system.
    Appears in DMN as merchant_unique_id parameter.
    internalRequestId ^String(20) Nuvei’s internal unique request ID, used for reconciliation purpose, etc.
    status ^String(20) The status of merchant’s API request/call.
    Possible statuses: SUCCESS or ERROR.
    transactionStatus ^String(20) The gateway transaction status.
    Possible values: APPROVED, DECLINED, ERROR, PENDING
    merchantDetails ^Class customField1 (String, 255)
    …
    customField15
    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.
    errCode ^String(11) If an error occurred on the request side, an error code is returned in this parameter.
    reason ^String(400) If an error occurred on the request side, then an error reason (such as failure in checksum validation, timeout from processing engine, etc.) 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, timeout from processing engine, etc.) is returned in this parameter.
    gwExtendedErrorCode ^Integer(11) Error code if error occurred on the bank’s side.
    When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
    version ^Integer The current version of the request. The current version is 1.
    userPaymentOptionId ^Long(45) The first time a consumer uses a payment method, Nuvei assigns a unique ID to it and return it. The next time the consumer uses a payment method that Nuvei has previously assigned an ID to, the ID is returned as the value of this parameter.
    externalTransactionId ^String(20) A unique ID generated by Nuvei that represents the APM transaction.
    transactionId ^String(20) The gateway transaction ID.
    authCode ^String(128) Authorization code of the transaction.
    redirectURL ^String The URL used by the merchant to redirect consumers to the payment method for authentication and authorization of the payment. This is returned only if the APM payment is conducted using redirect APM flow.
    orderId ^String(20) The order ID provided by Nuvei.
    clientRequestId ^String(255) ID of the API request in the merchant’s system.

    /cardTokenization

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/cardTokenization.do
    Example Request
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

    {
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "userTokenId": "487106",
    "cardData": {
        "cardNumber": "4111111111111111",
        "cardHolderName": "some name",
        "expirationMonth": "01",
        "expirationYear": "2020",
        "CVV": "122"
    },
    "billingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    }
}
    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

    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/cardTokenization.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);
    });
});

reqPost.write(jsonObject);
reqPost.end();
reqPost.on('error', function(e) {
    console.error(e);
});

    Example Response

    1
2
3
4
5
6
7
8
9
10
11
12

    {
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "internalRequestId": "866",
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "",
    "version": "1.0",
    "ccTempToken": "65432",
    "cardType": "Debit",
    "issuerCountry": "US",
    "isVerified":"true"
}

    Card tokenization enables the retrieval of a temporary card token based on card data.

    High-level PCI certified merchants can work with this API fully server to server, as well as perform credit card payments by sending the card data itself in the API call request, either using the dynamic3D and payment3D methods (recommended) or using the paymentCC method.

    Card tokenization is intended for low-level PCI certified merchants implementing card tokenization.

    For security and PCI reasons, low-level PCI certified merchants that cannot enter card data on their side and use a native mobile application are not required to use the credit card tokenization client SDK. However, they are able to call the cardTokenization method directly.

    Low-level PCI certified merchants that cannot enter card data on their side and use an online website must use the credit card tokenization client SDK, according to the instructions below, which performs credit card tokenization for them.

    @Links URLs

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

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

    Input Parameters

    PARAMETER DESCRIPTION
    sessionToken ^String(36) ~Required Session identifier returned by /getSessionToken.
    cardData ^Class ~Required cardNumber (String, 20)
    cardHolderName (String, 70)
    expirationMonth (String, 2)
    expirationYear (String, 4)
    CVV (String, 4)

    CVV can be required or non-required per configuration.

    If CVV is not required, then you need to send it with NULL value or not provide CVV parameter at all in the request.

    Please avoid sending a card that was expired as it may cause a transaction to be declined.
    billingAddress ^Class ~country and email Required country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase.
    email (String, 100, REQUIRED)
    firstName (String, 30)
    lastName (String, 40)
    address (String, 60)
    cell (String, 18)
    phone (String, 18)
    zip (String, 10)
    city (String, 30)
    state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only).
    county (String, 255)

    These parameters can be defined as required or non-required per need by Nuvei Integration Support Team.
    userTokenId ^String(255) ^Optional ID of the user in the merchant’s system.

    Output Parameters

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


     

    Checkout Page

    Checkout Page Overview

    Nuvei’s Checkout Page is an online solution that enables merchants selling products and services over the web to process online customer deposits and withdrawals through the Cashier Deposit and Withdrawal pages. These pages can be customized per request for web and mobile pages that provide an easy to use interface for depositing and withdrawing funds. Nuvei’s Checkout Page uniquely identifies each customer and presents their preferred language, currency, and previous payment methods. This creates an individual deposit and withdrawal experience for each customer increasing conversion. Connected to the Nuvei Gateway, the Checkout Page securely processes cards and dozens of alternative/local deposit methods.

    Creating HTTPS Requests

    To use our Checkout Page, you need to create an HTTPS request, redirect your user to our page (or IFrame), and provide the transaction input encoded as a query string as follows:

    field1=value1&field2=value2&field3=value3…

    Here are guidelines to some of the key input fields:

    Endpoints

    @Links URLs

    @Live https://secure.safecharge.com/ppp/purchase.do

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

    Checksums

    The checksum is a field that contains a SHA-256 hashing of all request fields and is needed to secure and authenticate the request.

    To calculate the checksum value:

    Step 1:

    Concatenate the secret key with all the requests field values. The order has to be the same order as sent in the request.

    Example:

    For the following request, concatenate the following string (assuming the secret value is secret123):

    1

    merchant_id=283475&merchant_site_id=89123755&total_amount=15&currency=USD&user_token_id=test@test.com&item_name_1=item1&item_amount_1=15&time_stamp=2011-01-056:04:26&item_quantity_1=1<br>

    


    1

    Secret1232834758912375515USDtest@test.comitem1152011-01-056:04:261

    Step 2:

    Run them through a SHA-256 function. The output should be placed in the checksum field.

    Total Amount Calculation

    The calculation can be made either per item or on the entire subtotal; however, tax can only be applied on a global level and is calculated as a percentage. For example, total_tax = 5.67 means that the tax is 5.67% of the sum calculated for all items, including their shipping, handling, discounts, etc.

    The parameters supported by this function include:

    To apply the total calculation to a subtotal:

    Each item’s final price must be calculated as follows:

    Calculation Example:

    Input Parameters

    The following tables contain the full list and description of all parameters available for the merchant to send to Cashier Deposit page via an HTTP request.

    Basic Parameters

    Parameter Description
    merchant_id ^Integer(64) ~Required The merchant’s ID provided by Nuvei.
    merchant_site_id ^Integer(64) ~Required The merchant website’s ID provided by Nuvei.
    checksum ^String(102400) ~Required A hashing of the request to secure and authenticate the request (refer to checksum)
    time_stamp ^String(19) ~Required Current GMT time in the following format: YYY-MM-DD.HH:MM:SS.
    currency ^String(3) ~Required The currency used in the transaction.
    invoice_id ^String(100) ^Optional A unique invoice identifier provided by the merchant or randomly generated.
    payment_method ^String(256) ^Optional The type of payment method selected by the customer. The possible values of this parameter:
    Credit Card: cc_card
    Debit Card: dc_card
    Alternative Payment Methods: Please refer to APM Input Fields for details.
    payment_method_mode=filter ^Optional This parameter filters out any payment method that is not the payment method sent in the payment_method parameter.
    merchantLocale ^String(5) ^Optional The default language. Unless specified the default is English. The possible values of this parameter:
    English (US): en_US
    English (UK): en_UK
    German: de_DE
    Chinese(PRC): zh_CN
    Hebrew: iw_IL
    French: fr_FR
    Dutch(Standard): nl_NL
    Indonesia: in_ID
    Italian: it_IT
    Japanese: ja_JP
    Korean: ko_KR
    Lithuanian: lt_LT
    Spanish: es_ES
    English (Canada): en_CA
    English (Australia): en_AU
    Russian: ru_RU
    Arabic: ar_AA
    Portuguese: pt_BR
    Swedish: sv_SE
    Turkish: tr_TR
    Slovenian: sl_SI
    Danish: da_DK
    Romanian: ro_RO
    Bulgarian: bg_BG
    Polish: pl_PL
    Hungarian: hu_HU
    userid ^String(50) ^Optional The customer’s ID as per the merchant’s userid.
    theme_id ^Integer(64) ^Optional Use this field overrides
    customData ^String(255) ^Optional General data about the customer provided by the merchant.
    merchant_unique_id ^String(64) ^Optional The unique ID (identifier) of the transaction in the merchant’s database.
    encoding ^String (20) ^Optional The type of character encoding. Default value is ISO-8859-1.
    webMasterId ^String(255) ^Optional This is an affiliate parameter that the merchant can send to Cashier.
    allow_installments ^Integer(64) ^Optional This parameter indicates whether payment may be made in installments or not, if this feature is supported by the merchant. The possible value of this parameter is either '1’ (yes) or '0’ (no).
    max_num_installments ^Integer(64) ^Optional This parameter indicates the maximum amount of installments with which the payment can be made.
    processingChannel ^String(4) ^Optional Sends “MOTO” value whenever the processing channel is from MOTO type (mail or telephone order)

    Item Details

    *N represents the item count number. The first item is item_name_1 up to item_name_n.

    **Currently item names can only include ISO-8859-1 character set encoding.

    Parameter Description
    item_name_N* ^String(400) ~Required The name of item number N.**
    item_number_N ^String(400) ~Required The first part of the items list, the serial number. Counted from item_number_1 to item_number_N.
    item_amount_N ^Double(64) ~Required The cost of the item numbered in the item_number_N parameter.
    Item_shipping_N ^Double(64) ^Optional Shipping costs of the item numbered in the item_number_N parameter.
    item_handling_N ^Double(64) ^Optional Handling costs of the item numbered in the item_number_N parameter.
    item_discount_N ^Double(64) ^Optional Discount rate of the item numbered in the item_number_N parameter.
    item_quantity_N ^Integer(64) ~Required Number of pieces of the item numbered in the item_number_N parameter. Default value is 1.
    discount ^Double(64) ^Optional The total discount out of the total amount.
    shipping ^Double(64) ^Optional Total shipping costs.
    handling ^Double(64) ^Optional Total handling costs.
    total_amount ^Double(64) ~Required Total transaction charge.
    total_tax ^Double(64) ^Optional Total taxes.
    productId ^String(50) ^Optional Merchant’s product ID. If this parameter is left empty, Cashier inserts a concatenation of all item names.
    promoCode ^String(512) ^Optional This value is a promotional code you define that you can use to apply discounts to your products or services. To activate this field, contact Nuvei’s Integration Support Team.
    nettelerAccount ^String ~Neteller The customer’s Neteller account number.
    nettelerSecureId ^String ~Neteller The customer’s Neteller SecureID.
    qiwi_phonenumber ^String ~Qiwi The customer’s phone number registered with Qiwi.

    User Token

    Parameter Description
    user_token ^String(8) ^Optional This parameter determines if the payment page requires existing customers to register for each transaction.
    register – Always register, even if registered already
    auto – Register only new users
    readonly – Cannot register new payment option, only use existing one.
    registeronly – Always register. Will not show existing payment options previously added by the user
    readonlyUPO – User can select only existing specific UPO specified with the userPaymentOptionId
    user_token_id ^String(255) ~Required ID for the user. Based on which we managed the user’s payment methods.
    userPaymentOptionId ^String ^Optional this ID specifies the user payment option to use for the transaction when user_token=readonlyUPO

    Customer Details

    *Indicates that this parameter must be sent as part of the HTTPS request for Nuvei’s risk checks.

    Parameter Description
    first_name* ^String(30) ~Required Customer’s first name.
    last_name* ^String(40) ~Required Customer’s last name.
    email* ^String(100) ~Required Customer’s email address.
    address1* ^String(60) ~Required Customer’s address.
    address2 ^String(60) ^Optional Customer’s address.
    city* ^String(30) ~Required Customer’s city.
    country* ^String(20) ~Required Customer’s 2-letter ISO country code.
    state* ^String(20) ~Required Customer’s state in ISO code (for customers based in the US, Canada and India only)
    zip* ^String(10) ~Required Customer’s zip code.
    phone1* ^String(18) ~Required Customer’s phone1.
    phone2 ^String(18) ^Optional Customer’s phone2.
    phone3 ^String(18) ^Optional Customer’s phone3.
    personal_id ^String(11) ^Optional The personal ID is the customer’s ID number issued by his/her respective country. This is only required for South American customers.
    dateOfBirth ^String(10) ^Optional The date of birth of the registering user. (YYYY-MM-DD)

    3D-Secure v2

    The Nuvei payment page handles the SCA 3D-Secure v2 process for the merchant. The merchant only needs to add parameters to the call for the web cashier URL to assist in completing the SCA process. For further information about the 3D-Secure v2, click here.

    Even though most of the below parameters are optional, it is highly recommended to pass as many details as possible in the call to increase the chances of a frictionless authentication rather than invoking a challenge of the end user.

    The following table displays the parameters that need to be added to fully support the 3D-Secure v2 process.

    Parameter Description
    deliveryEmail ^String(254) ^Optional For electronic delivery, the email address to which the merchandise is delivered: deliveryEmail@somedomain.com
    deliveryTimeFrame ^String(2) ^Optional This parameter indicates the merchandise delivery timeframe.
    01 – Electronic delivery
    02 – Same day shipping
    03 – Overnight shipping
    04 – Two-day or more shipping
    giftCardAmount ^String(15) ^Optional For prepaid or gift card purchase, this represents 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 prepaid or gift card purchase, this represents the total number of individual prepaid or gift cards/codes purchased.
    giftCardCurrency ^String(3) ^Optional For prepaid or gift card purchase, this represents ISO 4217 3-letter currency code of the gift card.
    preOrderDate ^String(8) ^Optional For a pre-ordered purchase, this represents the expected date that the merchandise is available.
    Format: YYYMMDD
    preOrderPurchaseInd ^String(2) ^Optional This indicates whether the cardholder is placing an order for merchandise with a future availability or release date.
    01 – Merchandise available
    02 – Future availability
    reorderItemsInd ^String(2) ^Optional This indicates whether the cardholder is reordering previously purchased merchandise.
    01 – First time ordered
    02 – Reordered
    shipIndicator ^String(2) ^Optional Indicates shipping method chosen for the transaction.
    Merchants must choose the Shipping Indicator code that most accurately describes the cardholder’s specific transaction, not their general business.
    If one or more items are included in the sale, use the Shipping Indicator code for the physical goods, or if all digital goods, use the Shipping Indicator code that describes the most expensive item.
    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 fields)
    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.)
    threeDSChallengeWindowSize ^String(2) ^Optional Challenge Window Size
    01 – 250 x 400
    02 – 390 x 400
    03 – 500 x 600
    04 – 600 x 400
    05 – Full screen
    Note: If no value is sent, the default value is 03.
    accountAge ^String(2) ^Optional Length of time that the cardholder has had the account with the 3DS Requestor.
    01 – No account (guest checkout)
    02 – Created during this transaction
    03 – Less than 30 days
    04 – 30–60 days
    05 – More than 60 days
    accountLastChangeDate ^String(8) ^Optional Date 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.
    YYYYMMDD
    accountLastChangeInd ^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
    accountRegistrationDate ^String(8) ^Optional Date that the cardholder opened the account with the 3DS Requestor.
    YYYYMMDD
    accountPasswordChangeDate ^String(8) ^Optional Date that cardholder’s account with the 3DS Requestor had a password change or account reset.
    YYYYMMDD
    accountResetInd ^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
    accountPurchasesCount6M ^String(4) ^Optional Number of purchases with this cardholder account during the previous six months.
    accountAddCardAttempts24H ^String(3) ^Optional Number of Add Card attempts in the last 24 hours.
    accountTransactionsCount24H ^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.
    accountTransactionsCount1Y ^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 that the value cannot exceed 3 characters.
    accountAddressFirstUseDate ^String(8) ^Optional Date when the shipping address used for this transaction was first used with the 3DS Requestor.
    YYYYMMDD
    accountAddressFirstUseInd ^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
    accountNameInd ^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
    accountSuspiciousActivityInd ^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

    Shipping Details

    Parameter Description
    shippingFirstName ^String(30) ^Optional Recipient’s first name.
    shippingLastName ^String(40) ^Optional Recipient’s last name.
    shippingAddress ^String(60) ^Optional Recipient’s address.
    shippingCity ^String(30) ^Optional Recipient’s city.
    shippingCountry ^String(20) ^Optional Recipient’s 2-letter ISO country code.
    shippingZip ^String(10) ^Optional Recipient’s zip code.
    Parameter Description
    skip_review_tab ^String(5) ^Optional A switch (true, false) indicating whether or not to skip the Cashier’s review page.
    success_url ^String(2048) ^Optional The URL the customer is directed to after a successful transaction.
    error_url ^String(2048) ^Optional The URL the customer is directed to after an unsuccessful transaction.
    pending_url ^String(2048) ^Optional The URL the customer is directed to when the transaction response is pending.
    back_url ^String(2048) ^Optional The URL the customer is directed to when pressing the 'Back’ button.
    notify_url ^String(2048) ^Optional The URL to which DMNs are sent (see our DMNs Guide).
    isNative ^Boolean(1) ^Optional Possible values:
    1 – Opens a redirect-based APM in a new window.
    0 – Opens the redirect APM in the same window (IFrame)
    quick_Deposit ^Boolean(1) ^Optional For more information, please contact Nuvei’s Integration Support Team

    Merchant Custom Fields

    Parameter Description
    MerchantName ^String(25) ^Optional Allows the merchant to define a dynamic descriptor for the merchant’s name.
    MerchantPhone ^String(13) ^Optional Allows the merchant to define a dynamic descriptor for the merchant’s phone number.
    customSiteName ^String(50) ^Optional The merchant’s site name that should replace the default MerchantSite name.
    customField1
    …
    customField15 ^String(64) ^Optional    		 Custom fields for the merchant to update miscellaneous data. This is sent to the Cashier in the HTTP request and returned in its response.

    Output Parameters

    When Nuvei redirects your customers to a Success, Pending, or Error page, the URL of the page contains output parameters that contain customer, transaction, and payment data similar to DMN notifications. The tables below provide a list of the parameters sent by Nuvei back to the customer’s browser upon completing the payment process.

    In addition to redirecting you to a response page, Nuvei sends you a Direct Merchant Notification notifying you of the status of the transaction. You must provide Nuvei with the URL of the server that receives the DMN. For more information, please refer to our DMNs Guide.

    Transaction Parameters

    Parameter Description
    status ^String Status of the executed transaction: Approved, Declined, etc.
    totalAmount ^String Total transaction charge.
    transactionID ^String A 64-bit unique integer ID generated by Nuvei, used for tracking purposes.
    clientUniqueID ^String Custom data parameter. If this parameter is not specified, the default value is the name of the merchant’s account.
    errCode ^String The error code of a failed transaction. For more information, see Filter Error Codes.
    exErrCode ^String The extended error code of a failed transaction. For more information, see Filter Error Codes.
    authCode ^String The authentication code received by Nuvei for the transaction.
    reason ^String The reason for a failed transaction, where relevant. For more information, see Decline Reasons.
    token ^String The token of the credit card that was returned by Nuvei. This value represents the customer’s credit card number stored on Nuvei’s database.
    reasonCode ^String The failed transaction’s reason’s code. For more information, see Decline Reasons.
    responsechecksum ^String Deprecated output checksum parameter.
    advanceResponseChecksum ^String Output checksum parameter.
    cardCompany ^String The name of the credit card company.
    The possible values are: Visa, Amex, MasterCard, Diners, Diners, Discover, JCB, LaserCard, Maestro, Solo, and Switch.
    eci ^String The Electronic Commerce Indicator that indicates the level of security used in a 3D 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 3D-Secure program.
    7 – Payment authentication was not performed.
    Mastercard
    2 – The cardholder was successfully authenticated.
    1 – The issuer or cardholder does not participate in a 3D-Secure program.
    6 – Payment authentication was not performed.

    Payment Parameters

    Parameter Description
    nameOnCard ^String The name on the credit card.
    first_name ^String The customer’s first name.
    last_name ^String The customer’s last name.
    address1 ^String The address of the customer.
    city ^String The city of the customer.
    country ^String The country of the customer.
    email ^String The email address of the customer.
    zip ^String The zip code of the customer when available.
    phone1 ^String The phone number of the customer.
    currency ^String The currency used in the transaction.

    General Items

    Parameter Description
    total_discount ^String Total discount for current order.
    total_handling ^String Total handling for current order.
    total_shipping ^String Total shipping for current order.
    total_tax ^String Total tax for current order.
    item_number_N ^String The number of item number N.
    item_amount_N ^String The cost of item number N.
    item_quantity_N ^String The quantity of item number N.
    item_discount_N ^String The discount for item number N.
    item_handling_N ^String The handling costs for item number N.
    item_shipping_N ^String The shipping costs for item number N.
    promoCode ^String This value is a promotional code you define that you can use to apply discounts to your products or services.

    Other Parameters

    Parameter Description
    customData ^String Custom data sent to Nuvei.
    merchant_unique_id ^String The merchant_unique_id value as provided by the merchant to Nuvei in the HTTPS request.
    merchant_site_id ^String The unique ID (identifier) of the Transaction in the merchant’s database as provided by the merchant to the PPP in the HTTPS request.
    merchant_id ^String The unique merchant ID supplied by Nuvei.
    requestVersion ^String The processed Nuvei request’s version.
    message ^String A message sent from Nuvei regarding the transaction.
    error ^String An error message sent from Nuvei.
    instantDmnStatus ^String The status of the Instant DMN notification. This parameter is only returned when Instant DMN notifications are active.
    ppp_TransactionID ^String The ID number of the transaction’s history table in the Nuvei database.
    userID ^String The UserID value transferred by the merchant in the HTTPS request.
    ProductID ^String The purchased product’s ID as provided by the merchant in the HTTPS request.
    ppp_status ^String The status of the transaction. OK indicates that the transaction was approved. Pending occurs only for APM transactions in which the final status is not immediately returned. FAIL indicates that the transaction was declined or there was an error.
    merchantLocale ^String Merchant’s location as sent to Nuvei.
    unknownParameters ^String All unknown parameters sent with the current transaction.
    webMasterId ^String Affiliate parameter (an additional parameter that a merchant can send to PPP).
    customField1
    …
    customField15 ^String    		 Custom fields for the merchant to update miscellaneous data. This is sent to the Cashier in the HTTP request and returned in its response.


     

    DMNs

    Direct Merchant Notifications

    After the merchant sends a 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 Direct Merchant Notification (DMN), also known as a webhook.

    For more details, please refer to our DMNs Guide.

    Additional Services

    Additional Services

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

    JSON Node.JS java php C#