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.

The API supports merchants of all levels of PCI certification from their online and mobile merchant applications, and is compatible with a large variety of payment options, i.e. payment cards, APMs, etc.

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 the Web SDK chapter in our main documentation portal. There you can find the following topics:

• Quick Start for Web SDK
• Nuvei Fields
• Nuvei Fields Stylizing
• APMs for Web SDK
• Web SDK Additional Functions
• FAQs

 

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.

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
sfc.createPayment({
    "sessionToken": result.sessionToken, //received from openOrder API 
    "merchantId": '1475082432483184221', //as assigned by Nuvei
    "merchantSiteId": '184941', //as assigned by Nuvei
    "userTokenId": "230811147",
    "clientUniqueId": "695701003", // optional
    "currency": "USD",
    "amount": "500",
    "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.
userTokenId ^String(255) ~Required	ID of the user in the merchant’s system.
currency ^String(3) ~Required	The three-letter ISO currency code. This field is mandatory when using the Web SDK createPayment method.
amount ^Double(12) ~Required	The transaction amount. This field is mandatory when using the Web SDK createPayment() method.
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: 1. card – Represents a credit/debit card. Fields:    - cardNumber, string(20)(MANDATORY) – The card number    - cardHolderName, string(70)(MANDATORY) – The card holder name.    - expirationMonth, string(2)(MANDATORY) – The card expiration month.    - expirationYear, string(4)(MANDATORY) – The card expiration year.    - CVV, string(4)(MANDATORY) – The CVV/CVC security code. -or- 2. alternativePaymentMethod – Represents an alternative payment method. Please refer to APM Input Fields for details. -or- 3. 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 mandatory	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. firstName (String, 30) lastName (String, 40) address (String, 60) address2 (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (two-letter ISO country code)(String, 2, MANDATORY), must be entered in Uppercase state(String, 2) - Two-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100, MANDATORY) county (String, 255) These parameters can be defined as mandatory or non-mandatory 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, not mandatory) lastName (String, 40, not mandatory) address (String, 60, not mandatory) phone (String, 18, not mandatory) zip (String, 10, not mandatory) city (String, 30, not mandatory) country (two-letter ISO country code)(String, 2, not mandatory) state(String, 2, not mandatory) - Two-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100, not mandatory) county (String, 255, not mandatory) language (String, 2, not mandatory) – 2-letter ISO language code. dateOfBirth (String, 10, not mandatory) – 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 (two-letter ISO country code)(String, 2) state(String, 2) - Two-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, not mandatory) … 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:

• The createPayment returned values (as detailed in the following example and output table).

  These contain the fiscal result field (approved, declined, error) and is useful to provide instant feedback to the end user.

• Verifying the response.

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

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 cancelled 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 3DS authorization as received from the issuer.
threeDReason ^String	Reason description for a failed 3DS authorization as received from the issuer.
challengeCancelReasonId ^String	Reason ID for a cancelled 3DS authorization as received from the issuer.
ChallengeCancelReason ^String	Reason description for a cancelled 3DS 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	If a challenge is requested, this field provides the reason for it (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 the /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(20) ^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 three-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 two-letter ISO country code.
languageCode ^String(5) ^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 is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
version ^Integer(10)	The current version of your request. 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 2.0, just by calling this method on the client side and using 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:

• Perform a 3D Secure Only Request (without payment)
• Nuvei Fields guide (for full PCI descoping)

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
sfc.authenticate3d({
    "sessionToken": result.sessionToken, //received from openOrder API 
    "merchantId": '1475082432483184221', //as assigned by Nuvei
    "merchantSiteId": '184941', //as assigned by Nuvei
    "userTokenId": "230811147",
    "clientUniqueId": "695701003", // optional
    "currency": "USD",
    "amount": "500",
    "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.
userTokenId ^String(255) ~Required	ID of the user in the merchant’s system.
currency ^String(3) ~Required	The three-letter ISO currency code. This field is mandatory when using the Web SDK createPayment method.
amount ^Double(12) ~Required	The transaction amount. This field is mandatory when using the Web SDK createPayment() method.
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: 1. card – Represents a credit/debit card. Fields:    - cardNumber, string(20)(MANDATORY) – The card number    - cardHolderName, string(70)(MANDATORY) – The card holder name.    - expirationMonth, string(2)(MANDATORY) – The card expiration month.    - expirationYear, string(4)(MANDATORY) – The card expiration year.    - CVV, string(4)(MANDATORY) – The CVV/CVC security code. -or- 2. 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 ~Only country	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. firstName (String, 30) lastName (String, 40) address (String, 60) address2 (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (two-letter ISO country code)(String, 2, MANDATORY), must be entered in Uppercase state(String, 2) - Two-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 mandatory or non-mandatory 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 authenticate3d().

Additional Input Parameters

PARAMETER	DESCRIPTION
userDetails ^Class ^Optional	firstName (String, 30, not mandatory) lastName (String, 40, not mandatory) address (String, 60, not mandatory) phone (String, 18, not mandatory) zip (String, 10, not mandatory) city (String, 30, not mandatory) country (two-letter ISO country code)(String, 2, not mandatory) state(String, 2, not mandatory) - Two-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100, not mandatory) county (String, 255, not mandatory) language (String, 2, not mandatory) – 2-letter ISO language code. dateOfBirth (String, 10, not mandatory) – 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 (two-letter ISO country code)(String, 2) state(String, 2) - Two-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, not mandatory) … 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):

• Directly from the createPayment return value (as detailed below).
• By our Direct Merchant Notification (DMNs) service, submitted directly to your server to a predefined endpoint.

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

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

• 3D Secure Authorization Fields: The values you need to use in your follow-up call to the payment request. These fields are stored under the threeD block, under the card block, under the paymentOption block in the response:
  • ECI
  • CAVV

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "result": "APPROVED",
  "errCode": "0",
  "errorDescription": "",
  "userPaymentOptionId": "14958143",
  "cavv": "Vk83Y2t0cHRzRFZzRlZlR0JIQXo=",
  "eci": "2",
  "xid": "",
  "dsTransID": "737eace8-353c-481e-9504-d496aa40485a",
  "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
eci ^String(2)	The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant. Possible ECI data values are: ECI = 5(VISA), 2(MC): The cardholder was successfully authenticated. ECI = 6(VISA), 1(MC): The issuer or cardholder does not participate in a 3D Secure program. ECI = 7: 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 v1.
dsTransID ^String(36)	The transaction ID received from the MPI for 3D 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 cancelled 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 3DS authorization as received from the issuer.
threeDReason ^String	Reason description for a failed 3DS authorization as received from the issuer.
challengeCancelReasonId ^String	Reason ID for a cancelled 3DS authorization as received from the issuer.
ChallengeCancelReason ^String	Reason description for a cancelled 3DS 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	If a challenge is requested, this field provides the reason for it (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.

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

/getSessionToken

Definition

1
2
3
4
5
6
7
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "20200603105852",
    "timeStamp": "20200603105852",
    "checksum": "b8f1552ecf5e814ef2139447961a7a9bd5f0abf573aac472fc7740313c6560e1"
}

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

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
using System;
using Safecharge.Model;
using Safecharge.Request;
using Safecharge.Response;
using Safecharge.Utils;
using Safecharge.Utils.Enum;

namespace Safecharge.Sample
{
    class GetSessionTokenSample
    {
        static void Main()
        {
            var requestExecutor = new SafechargeRequestExecutor();

            var merchantInfo = new MerchantInfo(
                "MERCHANT_KEY_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE",
                ApiConstants.IntegrationHost,
                HashAlgorithmType.SHA256);

            var getSessionTokenRequest = new GetSessionTokenRequest(merchantInfo);

            var response = requestExecutor.GetSessionToken(getSessionTokenRequest).GetAwaiter().GetResult();

            PrintResponseResult(response);
        }

        private static void PrintResponseResult(GetSessionTokenResponse response)
        {
            if (response.Status == ResponseStatus.Error)
            {
                Console.WriteLine("Reason: " + response.Reason);
            }
            else
            {
                Console.WriteLine("Status: " + response.Status);
                Console.WriteLine("Session token: " + response.SessionToken);
            }
        }
    }
}

Example Response

1
2
3
4
5
6
7
8
9
10
11
{
    "sessionToken": "153368e8-fed1-4d37-bd81-bd1c59772bfa",
    "internalRequestId": 192031408,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0",
    "clientRequestId": "20200603105852"
}

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 UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId merchantSiteId clientRequestId timeStamp merchantSecretKey.
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

1
2
3
4
5
6
7
8
9
10
11
12
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientUniqueId": "12345",
    "currency": "USD",
    "amount": "10",
    "deviceDetails": {
        "ipAddress": "10.12.13.14"
    },
    "timeStamp": "20200118191751",
    "checksum": "6b53666fc048a825be63cbb820da467b"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
const safecharge = require('safecharge');
safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>);
// env is optional can be 'test' or 'prod'. default value is 'prod'

// openOrder
safecharge.paymentService.openOrder({
    'userTokenId'      : '354687',
    'clientUniqueId'   : '12334565',
    'clientRequestId'   : '78789789',
    'currency'         : 'USD',
    'amount'           : '10',
    'deviceDetails'    : {
        "ipAddress" : "192.168.1.54"
    },
}, function (err, result) {
    console.log(err, result)
});

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 SDK. See the Nuvei Java SDK at https://docs.safecharge.com/documentation/guides/server-sdks/nuvei-java-sdk/.
{
    // Parameters needed to openOrder call
    String userTokenId = "Тest_0065";
    String clientUniqueId = "12345";
    String clientRequestId = "111899";
    String currency = "EUR";
    String amount = "10";

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setDeviceOS("Linux");
    deviceDetails.setBrowser("Firefox");
    deviceDetails.setDeviceType("DESKTOP");
    deviceDetails.setDeviceName("CP1532");
    deviceDetails.setIpAddress("93.146.254.172");

    try {
        Safecharge = new Safecharge();
        SafechargeResponse response = safecharge.openOrder(userTokenId, clientRequestId,
                clientUniqueId, null, null, null, null, currency, amount,
                null, deviceDetails, null, null, null, null, null, null,
                null, null, null, null, null, null, null);
    } catch (SafechargeException e) {
        e.printStackTrace();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<?php
$SafeCharge = new \SafeCharge\Api\SafeCharge([
    'environment'       => 'test',
    'merchantId'        => '<merchantId>',
    'merchantSiteId'    => '<merchantSiteId>',
    'merchantSecretKey' => '<merchantSecretKey>',
    'hashAlgorithm'     => '<hashAlgorithm>'
]);

//openOrder
$openOrderRequest = $SafeCharge->getPaymentService()->openOrder([
    'userTokenId'       => 'someone@company.com',
    'clientUniqueId'    => '1321313213',
    'clientUniqueId'    => '1321313213',
    'currency'          => 'EUR',
    'amount'            => '10',
    'deviceDetails'     => [
        "ipAddress"  => "192.168.1.54"
    ]

]);
?>

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
using System;
using Safecharge.Model.Payment;
using Safecharge.Response;
using Safecharge.Utils;
using Safecharge.Utils.Enum;

namespace Safecharge.Sample
{
    class Sample
    {
        static void Main()
        {
            var safecharge = new Safecharge(
                "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_KEY_PROVIDED_BY_SAFECHARGE",
                ApiConstants.IntegrationHost,
                HashAlgorithmType.SHA256);

            var response = safecharge.OpenOrder(
                "USD",
                "10",
                userTokenId: "354687",
                clientUniqueId: "12345",
                clientRequestId: "78789789",
                deviceDetails: new DeviceDetails { IpAddress = "10.12.13.14" });

            PrintResponseResult(response);
        }

        private static void PrintResponseResult(OpenOrderResponse response)
        {
            if (response.Status == ResponseStatus.Error)
            {
                Console.WriteLine("Reason: " + response.Reason);
            }
            else
            {
                Console.WriteLine("Status: " + response.Status);
                Console.WriteLine("Session token: " + response.SessionToken);
            }
        }
    }
}

Example Response

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

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 mandatory fields:

• merchantId – Identifies the merchant
• siteId – Identifies the merchant’s site
• timestamp
• checksum – A cryptographic hash that encrypts the above credentials with the merchant’s given “secret key”.
• amount and currency – So they cannot be manipulated by the end user.
  

For preventOverride, you decide if you wish to submit user-related information on the openOrder 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 UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId merchantSiteId clientRequestId amount currency timeStamp merchantSecretKey.
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.
currency ^String(3) ~Conditional	The three-letter ISO currency code. This field is mandatory when using the Web SDK createPayment() method.
amount ^Double(12) ~Conditional	The transaction amount. This field is mandatory when using the Web SDK createPayment() method.
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.
subMerchant ^Class ~Conditional	countryCode (String,2) – The payment facilitator’s sub-merchant’s two-letter ISO country code. city (String, 20) – The payment facilitator’s sub-merchant’s city name. id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
userTokenId ^String(255) ^Optional	ID of the user in the merchant’s system.
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.
deviceDetails ^Class ^Optional	deviceType (String, 10) deviceName (String, 255) deviceOS (String, 255) browser (String, 255) ipAddress (String, 15) Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized).
userDetails ^Class ^Optional	firstName(String, 30) lastName(String, 40) address(String, 60) phone(String, 18) zip(String, 10) city(String, 30) country (two-letter ISO country code)(String, 2) state(String, 2) - Two-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100) county (String, 255) language (String, 2, not mandatory) – 2-letter ISO language code. dateOfBirth (String, 10, not mandatory) – 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 (two-letter ISO country code)(String, 2) state(String, 2) - Two-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.
billingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 60) cell (String, 18) phone (String, 18) zip (String, 10) city (String, 30) country (two-letter ISO country code)(String, 2) state(String, 2) - Two-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100) county (String, 255) addressMatch (String, 1) – Set to “Y” when address matches shipping address addressLine2(String, 50) addressLine3(String, 50) homePhone(String) workPhone (String)
dynamicDescriptor ^Class ^Optional	merchantName (String, 25) merchantPhone (String, 13) merchantName - 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 - 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, not mandatory) … 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) failureUrl (string, 1000) pendingUrl (string, 1000) notificationUrl (string, 1000)
addendums ^Class ^Optional	This block contains industry specific addendums. The addendum fields that appear are based on the specific addendum type. For example, the localPayment addendum will include: nationalId debitType firstInstallment periodicalInstallment numberOfInstallments Please note that the possible values for the debitType parameter are: 1 – Singular payment 2 – Instalments 3 – Special debit The nationalId parameter must be sent during processing by local banks in certain countries, for example: Israel, Latin America (LATAM). For more information, please contact Nuvei’s Integration Support Team.
isRebilling ^Integer(2) ^Optional	When performing recurring/rebilling, use this field to indicate the recurring step with the following vales: 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 3DS transaction, you also must specify rebillExpiry and rebillFrequency under the v2AdditionalParams block, under the threeD block.
rebillingType ^String ^Optional	When performing recurring/rebilling, use this field to indicate the recurring type with the following vales: RECURRING – Regular, recurring charging of the consumer MIT – Merchant Initiated Transaction. In case this is a one-time payment, initiated by the merchant.

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, not mandatory) … 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, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
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.

/payment

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{ 
   "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
   "merchantId":"427583496191624621",
   "merchantSiteId":"142033",
   "clientRequestId":"1C6CT7V1L",
   "amount":"10",
   "currency":"USD",
   "userTokenId":"230811147",
   "clientUniqueId":"12345",
   "paymentOption":{ 
      "card":{ 
         "cardNumber":"4000023104662535",
         "cardHolderName":"John Smith",
         "expirationMonth":"12",
         "expirationYear":"2022",
         "CVV":"217"
      }
   },
   "deviceDetails":{ 
      "ipAddress":"93.146.254.172"
   },
   "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
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
{
    "timeStamp": "20200623135114",
    "sessionToken": "3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "amount": "10",
    "currency": "USD",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
    "isRebilling": "0",
    "paymentOption": {
        "card": {
            "cardNumber": "5115806139808464",
            "cardHolderName": "test name",
            "expirationMonth": "01",
            "expirationYear": "2020",
            "CVV": "122",
            "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",
                "challengePreference": "1",
                "notificationUrl": "https://www.merchant.com/notificationURL/",
                "merchantUrl": "https://www.merchant-website.com",
                "platformType": "02",
                "deliveryEmail": "deliveryEmail@somedomain.com",
                "deliveryTimeFrame": "1",
                "giftCardAmount": "456",
                "giftCardCount": "10",
                "giftCardCurrency": "826",
                "preOrderDate": "20190219",
                "preOrderPurchaseInd": "2",
                "reorderItemsInd": "2",
                "shipIndicator": "1",
                "rebillExpiry": "",
                "rebillFrequency": "",
                "ChallengeWindowSize": "2"
            }
        }
    },
    "deviceDetails": {
        "ipAddress": "127.0.0.1"
    },
    "userDetails": {
        "firstName": "first_name",
        "lastName": "last_name",
        "email": "email@email.com",
        "phone": "phone"
    },
    "shippingAddress": {
        "address": "address",
        "city": "city",
        "country": "DE",
        "state": "",
        "zip": "1340"
    },
    "billingAddress": {
        "email": "asd@asdasd.com",
        "address": "address",
        "city": "city",
        "country": "DE",
        "state": "",
        "zip": "1335"
    },
    "dynamicDescriptor": {
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "merchantDetails": {
        "customField1": "customField1"
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{ 
  "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
   "merchantId":"427583496191624621",
   "merchantSiteId":"142033",
   "clientRequestId":"1C6CT7V1L",
   "amount":"10",
   "currency":"USD",
   "userTokenId":"230811147",
   "clientUniqueId":"12345",
   "paymentOption":{ 
      "alternativePaymentMethod":{ 
         "paymentMethod":"apmgw_MoneyBookers",
         "account_id":"SkrillTestUser3"
      }
   },
   "billingAddress":{ 
      "firstName":"John",
      "lastName":"Smith",
      "address":"340689 main St.",
      "city":"London",
      "country":"GB",
      "email":"john.smith@safecharge.com"
   },
   "deviceDetails":{ 
      "ipAddress":"93.146.254.172"
   },
   "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
{ 
   "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
   "merchantId":"427583496191624621",
   "merchantSiteId":"142033",
   "clientRequestId":"1C6CT7V1L",
   "amount":"10",
   "currency":"USD",
   "userTokenId":"230811147",
   "clientUniqueId":"12345",
   "paymentOption":{ 
      "alternativePaymentMethod":{ 
         "paymentMethod":"apmgw_Neteller",
         "nettelerAccount":"453313818311",
         "nettelerSecureId":"173419"
      }
   },
   "billingAddress":{ 
      "firstName":"John",
      "lastName":"Smith",
      "address":"340689 main St.",
      "city":"London",
      "country":"GB",
      "email":"john.smith@safecharge.com"
   },
   "deviceDetails":{ 
      "ipAddress":"93.146.254.172"
   },
   "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
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
{ 
   "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
   "merchantId":"427583496191624621",
   "merchantSiteId":"142033",
   "clientRequestId":"1C6CT7V1L",
   "amount":"10",
   "currency":"USD",
   "userTokenId":"230811147",
   "clientUniqueId":"12345",
   "paymentOption":{ 
      "card":{ 
         "cardNumber":"5111426646345761",
         "cardHolderName":"john smith",
         "expirationMonth":"12",
         "expirationYear":"25",
         "CVV":"217",
         "threeD":{ 
            "methodCompletionInd":"Y",
            "version":"2.1.0",
            "notificationURL":"wwww.Test-Notification-URL-After-The-Challange-Is-Complete-Which-Recieves-The-CRes-Message.com",
            "merchantURL":"www.The-Merchant-Website-Fully-Quallified-URL.com",
            "platformType":"02",
            "v2AdditionalParams":{ 
               "challengePreference":"02",
               "deliveryEmail":"The_Email_Address_The_Merchandise_Was_Delivered@yoyoyo.com",
               "deliveryTimeFrame":"03",
               "giftCardAmount":"1",
               "giftCardCount":"41",
               "giftCardCurrency":"USD",
               "preOrderDate":"20220511",
               "preOrderPurchaseInd":"02",
               "reorderItemsInd":"01",
               "shipIndicator":"06",
               "rebillExpiry":"20200101",
               "rebillFrequency":"13",
               "challengeWindowSize":"05"
            },
            "browserDetails":{ 
               "acceptHeader":"Y",
               "ip":"190.0.23.160",
               "javaEnabled":"true",
               "javaScriptEnabled":"true",
               "language":"BG",
               "colorDepth":"64",
               "screenHeight":"1024",
               "screenWidth":"1024",
               "timeZone":"+3",
               "userAgent":"Mozilla"
            },
            "account":{ 
               "age":"05",
               "lastChangeDate":"20190220",
               "lastChangeInd":"04",
               "registrationDate":"20190221",
               "passwordChangeDate":"20190222",
               "resetInd":"01",
               "purchasesCount6M":"6",
               "addCardAttempts24H":"24",
               "transactionsCount24H":"23",
               "transactionsCount1Y":"998",
               "cardSavedDate":"20190223",
               "cardSavedInd":"02",
               "addressFirstUseDate":"20190224",
               "addressFirstUseInd":"03",
               "nameInd":"02",
               "suspiciousActivityInd":"01"
            },
            "acquirer":{ 
               "bin":"665544",
               "merchantId":"9876556789",
               "merchantName":"Acquirer Merchant Name"
            }
         }
      }
   },
   "relatedTransactionId":"2110000000001208909",
   "billingAddress":{ 
      "firstName":"John",
      "lastName":"Smith",
      "address":"340689 main St.",
      "city":"London",
      "country":"GB",
      "email":"john.smith@safecharge.com"
   },
   "shippingAddress":{ 
      "firstName":"John",
      "lastName":"Smith",
      "address":"340689 main St.",
      "city":"London",
      "country":"GB",
      "email":"john.smith@safecharge.com"
   },
   "deviceDetails":{ 
      "ipAddress":"93.146.254.172"
   },
   "dynamicDescriptor":{ 
      "merchantName":"Sample Merchant Name",
      "merchantPhone":"359889526524"
   },
   "merchantDetails":{ 
      "customField1":"customField1-valueU"
   },
   "productId":"5RS2LR2HUVGB",
   "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
30
31
32
33
34
35
36
37
38
39
40
41
42
{ 
   "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
   "merchantId":"427583496191624621",
   "merchantSiteId":"142033",
   "clientRequestId":"1C6CT7V1L",
   "amount":"10",
   "currency":"USD",
   "userTokenId":"230811147",
   "clientUniqueId":"12345",
   "paymentOption":{ 
      "card":{ 
         "cardNumber":"5111426646345761",
         "cardHolderName":"john smith",
         "expirationMonth":"12",
         "expirationYear":"25",
         "CVV":"217"
      }
   },
   "relatedTransactionId":"2110000000001209192",
   "billingAddress":{ 
      "firstName":"John",
      "lastName":"Smith",
      "address":"340689 main St.",
      "city":"London",
      "country":"GB",
      "email":"john.smith@safecharge.com"
   },
   "shippingAddress":{ 
      "firstName":"John",
      "lastName":"Smith",
      "address":"340689 main St.",
      "city":"London",
      "country":"GB",
      "email":"john.smith@safecharge.com"
   },
   "deviceDetails":{ 
      "ipAddress":"93.146.254.172"
   },
   "webMasterId":"IE79LFWZ4EL6",
   "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
36
37
38
39
40
41
{ 
   "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
   "merchantId":"427583496191624621",
   "merchantSiteId":"142033",
   "clientRequestId":"1C6CT7V1L",
   "amount":"10",
   "currency":"USD",
   "userTokenId":"230811147",
   "clientUniqueId":"12345",
   "paymentOption":{ 
      "card":{ 
         "cardNumber":"5111426646345761",
         "cardHolderName":"john smith",
         "expirationMonth":"12",
         "expirationYear":"25",
         "CVV":"217",
         "threeD":{ 
            "externalMpi":{ 
               "eci":"2",
               "threeDProtocolVersion":"2",
               "cavv":"ejJRWG9SWWRpU2I1M21DelozSXU=",
               "dsTransID":"9e6c6e9b-b390-4b11-ada9-0a8f595e8600"
            }
         }
      }
   },
   "billingAddress":{ 
      "firstName":"John",
      "lastName":"Smith",
      "address":"340689 main St.",
      "city":"London",
      "country":"GB",
      "email":"john.smith@safecharge.com"
   },
   "deviceDetails":{ 
      "ipAddress":"93.146.254.172"
   },
   "webMasterId":"22FB9M9NZ08U",
   "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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
{
   "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
   "merchantId":"427583496191624621",
   "merchantSiteId":"142033",
   "clientRequestId":"1C6CT7V1L",
   "amount":"10",
   "currency":"USD",
   "userTokenId":"230811147",
   "clientUniqueId":"12345",
                "items": [
                                {"name": "Item 1U", "price": "10", "quantity": "1"}
                ],
                "paymentOption": {
                                "card": {
                                                "externalToken": {
                                                                                "externalTokenProvider": "ApplePay",
                                                                                "mobileToken": "{\"paymentData\":{\"version\":\"EC_v1\",\"data\":\"2uhvZkdQfbZw8I4X9tZ8FijeTufEdcU61hMiuRKPyk43zqC9e6bnyNANZkbeZPyEvoZY1HtAQcmKm04GyoP+wG9L4OHIPi0SXd1GOR0mB7iVTQqcBElNYQfHESh9xj480o8A1KrkI5YW3rxEOxgjpi6520fXe9Tvs4r9iF9Bmc4lbWKyyZxLH7L12ThxdGoIcR25E4NADv4EidgTPjavEeF1xuBXuej+bD2WnEGOUtJpj8V43qvpZz2NUDxAC0yRxgOBomEMPjcJWVlWGuKFI700rs4Fx+UkIHhl\/diRM71OmPeoaTRyf\/qShuCNBz\/cxdyG\/rZtFLFY\/coUS3MHWzCYgdPNetPImf1jTrh+k4VFsJb9uh54b7h6mNUQEzFV\/EGVJJoNtDaT4cVYn\/xywUAkrCcOmEWyFrM90ukwPg0=\",\"signature\":\"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID5jCCA4ugAwIBAgIIaGD2mdnMpw8wCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE2MDYwMzE4MTY0MFoXDTIxMDYwMjE4MTY0MFowYjEoMCYGA1UEAwwfZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtU0FOREJPWDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgjD9q8Oc914gLFDZm0US5jfiqQHdbLPgsc1LUmeY+M9OvegaJajCHkwz3c6OKpbC9q+hkwNFxOh6RCbOlRsSlaOCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwHQYDVR0OBBYEFAIkMAua7u1GMZekplopnkJxghxFMAwGA1UdEwEB\/wQCMAAwHwYDVR0jBBgwFoAUI\/JJxE+T5O8n5sT2KGw\/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB\/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB\/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0kAMEYCIQDaHGOui+X2T44R6GVpN7m2nEcr6T6sMjOhZ5NuSo1egwIhAL1a+\/hp88DKJ0sv3eT3FxWcs71xmbLKD\/QJ3mWagrJNMIIC7jCCAnWgAwIBAgIISW0vvzqY2pcwCgYIKoZIzj0EAwIwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcNMTQwNTA2MjM0NjMwWhcNMjkwNTA2MjM0NjMwWjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwFxGEGddkhdUaXiWBB3bogKLv3nuuTeCN\/EuT4TNW1WZbNa4i0Jd2DSJOe7oI\/XYXzojLdrtmcL7I6CmE\/1RFo4H3MIH0MEYGCCsGAQUFBwEBBDowODA2BggrBgEFBQcwAYYqaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZXJvb3RjYWczMB0GA1UdDgQWBBQj8knET5Pk7yfmxPYobD+iu\/0uSzAPBgNVHRMBAf8EBTADAQH\/MB8GA1UdIwQYMBaAFLuw3qFYM4iapIqZ3r6966\/ayySrMDcGA1UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB\/wQEAwIBBjAQBgoqhkiG92NkBgIOBAIFADAKBggqhkjOPQQDAgNnADBkAjA6z3KDURaZsYb7NcNWymK\/9Bft2Q91TaKOvvGcgV5Ct4n4mPebWZ+Y1UENj53pwv4CMDIt1UQhsKMFd2xd8zg7kGf9F3wsIW2WT8ZyaYISb1T4en0bmcubCYkhYQaZDwmSHQAAMYIBjDCCAYgCAQEwgYYwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTAghoYPaZ2cynDzANBglghkgBZQMEAgEFAKCBlTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0yMDA1MTQxMTEzMDJaMCoGCSqGSIb3DQEJNDEdMBswDQYJYIZIAWUDBAIBBQChCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIJPkOnv7VCVYvnXUWwIchmkON4dVtXHsTssY1uMJkn0XMAoGCCqGSM49BAMCBEcwRQIhAMzNQ\/Xw8dxOD3V\/tizLXRpV77PpcfTpYUUpN0gJztrqAiBWqco9HpLSoVN5ySEmZdAGRuer2Az06xRkmsToV03rnQAAAAAAAA==\",\"header\":{\"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEAnHMlqALgHhQoT5tf1Df9WApE6gFx6LgZaSUAOkikr4Tn97T2pgi3Iz9guCcHOCcfelv+qfPcHzfBbvs4UWilg==\",\"publicKeyHash\":\"STh9vCW6aUGJLEEtdHr1w0AHd1uDXgrNOGNZqKcKW9g=\",\"transactionId\":\"e5cf25993cbf76cac2467aece05ad07be7aeebcc439efe2e957dd1b6f556ffae\"}},\"paymentMethod\":{\"displayName\":\"Visa 4228\",\"network\":\"Visa\",\"type\":\"debit\"},\"transactionIdentifier\":\"E5CF25993CBF76CAC2467AECE05AD07BE7AEEBCC439EFE2E957DD1B6F556FFAE\"}"
                                                }
                                }
                },
                "billingAddress": {
                                "firstName": "Wxjtyskuuj","lastName": "Pauwbeuyid","email": "jhahn.jhnui@srzaw.cb","phone": "359888797070","cell": "359881797073","address": "340689 Billing Str. Updated.",
                                "city": "Billing City Updated","zip": "BNE 4895U","county": "BCountyU","state": "","country": "DE"
                                },
                "userDetails": {
                                "firstName": "Doefvvblct","lastName": "Vxbfcfwoii","email": "fihay.ymfgd@fwfla.mq","phone": "359888440549","cell": "3598874405493","dateOfBirth": "1972-06-02",
                                "address": "22 Automation Str. Updated.","city": "Chiprovci Updated","zip": "CH 233242U","county": "UCountyU","state": "","country": "DE"
                                },
                "shippingAddress": {
                                "firstName": "Mlxdwieffa","lastName": "Uvnoirngbg","email": "gmwch.bphmv@ducdb.qz","phone": "359888576900","cell": "359887576903","address": "33 Shipping Str. Updated.",
                                "city": "Shipping City Updated","zip": "SDC 33334U","county": "SCountyU","state": "","country": "US"
                                },
                "deviceDetails": {
                                "ipAddress": "93.146.254.172"
                                },
                "dynamicDescriptor": {
                                "merchantName": "Joe Cashier API U","merchantPhone": "359889526524"
                                },
                "merchantDetails": {
                                "customField1": "customField1-valueU"
                                },
                "urlDetails": {
                                "successUrl": "https://srv-bsf-devppptrunk.gw-4u.com/ppp/defaultSuccess.do",
                                "pendingUrl": "https://srv-bsf-devppptrunk.gw-4u.com/ppp/defaultPending.do",
                                "failureUrl": "https://srv-bsf-devppptrunk.gw-4u.com/ppp/defaultCancel.do",
                                "notificationUrl": "http://srv-bsf-devppptrunk.gw-4u.com/ppptest/NotifyMerchantTest"
                },
                "productId": "DU1UU2J3HS0Z",
                "customData": "Custom Data Inserted By Joe!",
                "webMasterId": "GFQIEQ0ZBRPP",
                "timeStamp": "20200517130543",
                "checksum": "de0e48812c269933d9eb37e74db45f1c"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
const safecharge = require('safecharge');
safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>);
// env is optional can be 'test' or 'prod'. default value is 'prod'

safecharge.paymentService.createPayment({
    "amount"       : "10.02",
    "currency"     : "USD",
    "sessionToken" : '<sessionToken>', /* taken from openOrder result */
    "paymentOption": {
        "card": {
            "expirationYear" : "2024",
            "CVV"            : "123",
            "cardHolderName" : "Jane Smith",
            "expirationMonth": "01",
            "cardNumber"     : "4000020951595032"
        }
    },
    "items"        : [
        {
            "quantity": "1",
            "price"   : "0.01",
            "name"    : "Item 1U"
        },
        {
            "quantity": "1",
            "price"   : "10.01",
            "name"    : "Item 2U"
        }
    ],
}, function (pErr, pResult) {
    console.log(pErr, pResult)
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
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
safecharge.paymentService.createPayment({
    "currency"       : "EUR",
    "amount"         : "10",
    "userTokenId"    : "73fdd373b171299e692932ac01052001",
    "paymentOption"  : {
        "card" : {
            "cardNumber"      : "4012001037141112",
            "cardHolderName"  : "some name",
            "expirationMonth" : "01",
            "expirationYear"  : "2020",
            "CVV"             : "122",
            "threeD" :{
                "version":"2",
                "challengePreference"  : "1",
                "notificationUrl"      : "https://www.merchant.com/notificationURL/",
                "merchantUrl"          : "https://www.merchant-website.com",
                "platformType"         : "02",
                "deliveryEmail"        : "deliveryEmail@somedomain.com",
                "deliveryTimeFrame"    : "1",
                "giftCardAmount"       : "456",
                "giftCardCount"        : "10",
                "giftCardCurrency"     : "826",
                "preOrderDate"         : "20190219",
                "preOrderPurchaseInd"  : "2",
                "reorderItemsInd"      : "2",
                "shipIndicator"        : "1",
                "rebillExpiry"         : "",
                "rebillFrequency"      : "",
                "ChallengeWindowSize"  : "2"    
                "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"
                }
            }
        }
    },
    "shippingAddress" : {
        "firstName" : "some first name",
        "lastName"  : "some last name",
        "address"   : "some street",
        "phone"     : "972502457558",
        "zip"       : "123456",
        "city"      : "some city",
        "country"   : "DE",
        "state"     : "",
        "email"     : "someemail@somedomain.com",
        "county"    : "Anchorage",
    },
    "dynamicDescriptor"  : {
        "merchantName"  : "merchant Name"
        "merchantPhone"  : "merchant Phone"
    },
    "billingAddress" : {
        "firstName" : "some first name",
        "lastName"  : "some last name",
        "address"   : "some street",
        "phone"     : "972502457558",
        "zip"       : "123456",
        "city"      : "some city",
        "country"   : "DE",
        "state"     : "",
        "email"     : "someemail@somedomain.com",
        "county"    : "Anchorage",
    },
    "deviceDetails"  : {
        "ipAddress"  : "192.168.1.54"
    },
}, 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
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    "currency"       : "EUR",
    "amount"         : "10",
    "userTokenId"    : "73fdd373b171299e692932ac01052001",
    "paymentOption"  : {
        "alternativePaymentMethod" : {
            "paymentMethod"      : "apmgw_MoneyBookers",
            "account_id"  : "SkrillTestUser3"
        }
    },
    "billingAddress" : {
        "firstName" : "some first name",
        "lastName"  : "some last name",
        "address"   : "some street",
        "phone"     : "972502457558",
        "zip"       : "123456",
        "city"      : "some city",
        "country"   : "DE",
        "state"     : "",
        "email"     : "someemail@somedomain.com",
        "county"    : "Anchorage",
    },
    "deviceDetails"  : {
        "ipAddress"  : "192.168.1.54"
    },
}, 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
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    "currency"       : "EUR",
    "amount"         : "10",
    "userTokenId"    : "73fdd373b171299e692932ac01052001",
    "paymentOption"  : {
        "alternativePaymentMethod" : {
            "paymentMethod"      : "apmgw_Neteller",
            "nettelerAccount"  : "453313818311",
            "nettelerSecureId"  : "173419"
        }
    },
    "billingAddress" : {
        "firstName" : "some first name",
        "lastName"  : "some last name",
        "address"   : "some street",
        "phone"     : "972502457558",
        "zip"       : "123456",
        "city"      : "some city",
        "country"   : "DE",
        "state"     : "",
        "email"     : "someemail@somedomain.com",
        "county"    : "Anchorage",
    },
    "deviceDetails"  : {
        "ipAddress"  : "192.168.1.54"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult)
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
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
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    "currency"       : "EUR",
    "amount"         : "10",
    "userTokenId"    : "73fdd373b171299e692932ac01052001",
    "paymentOption"  : {
        "card" : {
            "cardNumber"      : "4012001037141112",
            "cardHolderName"  : "some name",
            "expirationMonth" : "01",
            "expirationYear"  : "2020",
            "CVV"             : "122",
            "threeD" :{
                "version":"2",
                "challengePreference"  : "1",
                "notificationUrl"      : "https://www.merchant.com/notificationURL/",
                "merchantUrl"          : "https://www.merchant-website.com",
                "platformType"         : "02",
                "deliveryEmail"        : "deliveryEmail@somedomain.com",
                "deliveryTimeFrame"    : "1",
                "giftCardAmount"       : "456",
                "giftCardCount"        : "10",
                "giftCardCurrency"     : "826",
                "preOrderDate"         : "20190219",
                "preOrderPurchaseInd"  : "2",
                "reorderItemsInd"      : "2",
                "shipIndicator"        : "1",
                "rebillExpiry"         : "",    //in case of recurring
                "rebillFrequency"      : "",    //in case of recurring
                "ChallengeWindowSize"  : "2"    
                "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"
                }
                "account" :{                //in case you have user account management
                    "age"                  :"05",
                    "lastChangeDate"       :"20190220",
                    "lastChangeInd"        :"04",
                    "registrationDate"     :"20190221",
                    "passwordChangeDate"   :"20190222",
                    "resetInd"             :"01",
                    "purchasesCount6M"     :"6",
                    "addCardAttempts24H"   :"24",
                    "transactionsCount24H" :"23",
                    "transactionsCount1Y"  :"998",
                    "cardSavedDate"        :"20190223",
                    "cardSavedInd"         :"02",
                    "addressFirstUseDate"  :"20190224",
                    "addressFirstUseInd"   :"03",
                    "nameInd"              :"02",
                    "suspiciousActivityInd":"01"                
                }
            }
        }
    },
    "relatedTransactionId" = > "2110000000001208909", //as returned from initPayment
    "shippingAddress" : {
        "firstName" : "some first name",
        "lastName"  : "some last name",
        "address"   : "some street",
        "phone"     : "972502457558",
        "zip"       : "123456",
        "city"      : "some city",
        "country"   : "DE",
        "state"     : "",
        "email"     : "someemail@somedomain.com",
        "county"    : "Anchorage",
    },
    "billingAddress" : {
        "firstName" : "some first name",
        "lastName"  : "some last name",
        "address"   : "some street",
        "phone"     : "972502457558",
        "zip"       : "123456",
        "city"      : "some city",
        "country"   : "DE",
        "state"     : "",
        "email"     : "someemail@somedomain.com",
        "county"    : "Anchorage",
    },
    "deviceDetails"  : {
        "ipAddress"  : "192.168.1.54"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult)
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
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
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    "currency"       : "EUR",
    "amount"         : "10",
    "userTokenId"    : "73fdd373b171299e692932ac01052001",
    "paymentOption"  : {
        "userPaymentOptionId" : "8348263" //in case using tokenization
        /* instead can also be the full cardholder information, without the threeD section*/
            "cardNumber"      : "4012001037141112",
            "cardHolderName"  : "some name",
            "expirationMonth" : "01",
            "expirationYear"  : "2020",
            "CVV"             : "122",
            "threeD" :{
                "version":"2",
                "challengePreference"  : "1",
                "notificationUrl"      : "https://www.merchant.com/notificationURL/",
                "merchantUrl"          : "https://www.merchant-website.com",
                "platformType"         : "02",
                "deliveryEmail"        : "deliveryEmail@somedomain.com",
                "deliveryTimeFrame"    : "1",
                "giftCardAmount"       : "456",
                "giftCardCount"        : "10",
                "giftCardCurrency"     : "826",
                "preOrderDate"         : "20190219",
                "preOrderPurchaseInd"  : "2",
                "reorderItemsInd"      : "2",
                "shipIndicator"        : "1",
                "rebillExpiry"         : "",    //in case of recurring
                "rebillFrequency"      : "",    //in case of recurring
                "ChallengeWindowSize"  : "2"    
                "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"
                }
                "account" :{                //in case you have user account management
                    "age"                  :"05",
                    "lastChangeDate"       :"20190220",
                    "lastChangeInd"        :"04",
                    "registrationDate"     :"20190221",
                    "passwordChangeDate"   :"20190222",
                    "resetInd"             :"01",
                    "purchasesCount6M"     :"6",
                    "addCardAttempts24H"   :"24",
                    "transactionsCount24H" :"23",
                    "transactionsCount1Y"  :"998",
                    "cardSavedDate"        :"20190223",
                    "cardSavedInd"         :"02",
                    "addressFirstUseDate"  :"20190224",
                    "addressFirstUseInd"   :"03",
                    "nameInd"              :"02",
                    "suspiciousActivityInd":"01"                
                }
            }
        }
    },
    "relatedTransactionId" = > "2110000000001208909", //as returned from 1st payment call
    "billingAddress" : {
        "firstName" : "some first name",
        "lastName"  : "some last name",
        "address"   : "some street",
        "phone"     : "972502457558",
        "zip"       : "123456",
        "city"      : "some city",
        "country"   : "DE",
        "state"     : "",
        "email"     : "someemail@somedomain.com",
        "county"    : "Anchorage",
    },
    "deviceDetails"  : {
        "ipAddress"  : "192.168.1.54"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult)
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    "currency"       : "EUR",
    "amount"         : "10",
    "userTokenId"    : "73fdd373b171299e692932ac01052001",
    "paymentOption"  : {
        "card" : {
            "cardNumber"      : "4012001037141112",
            "cardHolderName"  : "some name",
            "expirationMonth" : "01",
            "expirationYear"  : "2020",
            "CVV"             : "122",
            "threeD" :{
                "externalMpi" :{
                    "eci"       : "2",
                    "cavv"          : "ejJRWG9SWWRpU2I1M21DelozSXU",
                    "dsTransID"         : "9e6c6e9b-b390-4b11-ada9-0a8f595e8600"  //xid in case of 3Dv1        
                }
                    "age"                  :"05",
                    "lastChangeDate"       :"20190220",
                    "lastChangeInd"        :"04",
                    "registrationDate"     :"20190221",
                    "passwordChangeDate"   :"20190222",
                    "resetInd"             :"01",
                    "purchasesCount6M"     :"6",
                    "addCardAttempts24H"   :"24",
                    "transactionsCount24H" :"23",
                    "transactionsCount1Y"  :"998",
                    "cardSavedDate"        :"20190223",
                    "cardSavedInd"         :"02",
                    "addressFirstUseDate"  :"20190224",
                    "addressFirstUseInd"   :"03",
                    "nameInd"              :"02",
                    "suspiciousActivityInd":"01"                
                }
            }
        }
    },
    "billingAddress" : {
        "firstName" : "some first name",
        "lastName"  : "some last name",
        "address"   : "some street",
        "phone"     : "972502457558",
        "zip"       : "123456",
        "city"      : "some city",
        "country"   : "DE",
        "state"     : "",
        "email"     : "someemail@somedomain.com",
        "county"    : "Anchorage",
    },
    "deviceDetails"  : {
        "ipAddress"  : "192.168.1.54"
    },
}, 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
//Initialize SDK. See the Nuvei Java SDK at https://docs.safecharge.com/documentation/guides/server-sdks/nuvei-java-sdk/.
{     
    // Parameters needed for payment simple card call
    String userTokenId = "230811147";
    String clientUniqueId = "12345";
    String clientRequestId = "1C6CT7V1L";
    String currency = "EUR";
    String amount = "9.0";

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setDeviceOS("Linux");
    deviceDetails.setBrowser("Firefox");
    deviceDetails.setDeviceType("DESKTOP");
    deviceDetails.setDeviceName("CP1532");
    deviceDetails.setIpAddress("93.146.254.172");

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

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

    try {
        Safecharge safecharge = new Safecharge();
        safecharge.initialize(merchantId, merchantSiteId, merchantKey, APIConstants.Environment.PRODUCTION_HOST.getUrl(), Constants.HashAlgorithm.SHA256);
        SafechargeResponse response = safecharge.payment(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);
    } catch (SafechargeException e) {
        e.printStackTrace();
    }
}

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
//Initialize SDK. See the Nuvei Java SDK at https://docs.safecharge.com/documentation/guides/server-sdks/nuvei-java-sdk/.
{         
    // Parameters needed for payment full card call
    String userTokenId = "230811147";
    String clientUniqueId = "12345";
    String clientRequestId = "1C6CT7V1L";
    String currency = "USD";
    String amount = "10";
    Integer isRebilling = 0;

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setDeviceOS("Linux");
    deviceDetails.setBrowser("Firefox");
    deviceDetails.setDeviceType("DESKTOP");
    deviceDetails.setDeviceName("CP1532");
    deviceDetails.setIpAddress("127.0.0.1");

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

    V2AdditionalParams v2AdditionalParams = new V2AdditionalParams();
    v2AdditionalParams.setChallengePreference("1");
    v2AdditionalParams.setDeliveryEmail("deliveryEmail@somedomain.com");
    v2AdditionalParams.setDeliveryTimeFrame("1");
    v2AdditionalParams.setGiftCardAmount("456");
    v2AdditionalParams.setGiftCardCount("10");
    v2AdditionalParams.setGiftCardCurrency("BGN");
    v2AdditionalParams.setPreOrderDate("20190219");
    v2AdditionalParams.setPreOrderPurchaseInd("2");
    v2AdditionalParams.setReorderItemsInd("2");
    v2AdditionalParams.setShipIndicator("1");
    v2AdditionalParams.setChallengeWindowSize("2");

    ThreeD threeD = new ThreeD();
    threeD.setBrowserDetails(browserDetails);
    threeD.setV2AdditionalParams(v2AdditionalParams);
    threeD.setVersion("2");
    threeD.setNotificationURL("https://www.merchant.com/notificationURL/");
    threeD.setMerchantURL("https://www.merchant-website.com");
    threeD.setPlatformType("02");
    threeD.setMerchantURL("deliveryEmail@somedomain.com");

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

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

    CashierUserDetails userDetails = new CashierUserDetails();
    userDetails.setFirstName("first_name");
    userDetails.setLastName("last_name");
    userDetails.setEmail("email@email.com");
    userDetails.setPhone("+44123456789");

    UserAddress shippingAddress = new UserAddress();
    shippingAddress.setAddress("4 Sand Rd");
    shippingAddress.setCity("Manchester");
    shippingAddress.setCountry("UK");
    shippingAddress.setZip("1340");

    UserAddress billingAddress = new UserAddress();
    billingAddress.setEmail("someone@somewhere.com");
    billingAddress.setAddress("4 Sand Rd");
    billingAddress.setCity("Manchester");
    billingAddress.setCountry("UK");
    billingAddress.setState("");
    billingAddress.setZip("1340");

    DynamicDescriptor dynamicDescriptor = new DynamicDescriptor();
    dynamicDescriptor.setMerchantName("merchantName");
    dynamicDescriptor.setMerchantPhone("merchantPhone");

    MerchantDetails merchantDetails = new MerchantDetails();
    merchantDetails.setCustomField1("customField1");

    try {
        Safecharge safecharge = new Safecharge();
        safecharge.initialize(merchantId, merchantSiteId, merchantKey, APIConstants.Environment.PRODUCTION_HOST.getUrl(), Constants.HashAlgorithm.SHA256);
        SafechargeResponse response = safecharge.payment(userTokenId, clientUniqueId,
                clientRequestId, paymentOption, isRebilling, currency, amount, null, null,
                deviceDetails, userDetails, shippingAddress, billingAddress, dynamicDescriptor, merchantDetails, null,
                null, null, null, null, null, null, null, null, null);
    } catch (SafechargeException e) {
        e.printStackTrace();
    }
}

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 SDK. See the Nuvei Java SDK at https://docs.safecharge.com/documentation/guides/server-sdks/nuvei-java-sdk/.
{ 
        // Parameters needed for payment apm redirect call
        String userTokenId = "230811147";
        String clientUniqueId = "12345";
        String clientRequestId = "1C6CT7V1L";
        String currency = "USD";
        String amount = "10";

        DeviceDetails deviceDetails = new DeviceDetails();
        deviceDetails.setDeviceOS("Linux");
        deviceDetails.setBrowser("Firefox");
        deviceDetails.setDeviceType("DESKTOP");
        deviceDetails.setDeviceName("CP1532");
        deviceDetails.setIpAddress("93.146.254.172");

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

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

        UserAddress shippingAddress = new UserAddress();

        UserAddress billingAddress = new UserAddress();
        billingAddress.setFirstName("John");
        billingAddress.setLastName("Smith");
        billingAddress.setEmail("john.smith@safecharge.com");
        billingAddress.setAddress("340689 Main St.");
        billingAddress.setCity("London");
        billingAddress.setCountry("GB");
        billingAddress.setState("");
        billingAddress.setZip("1340");

        try {
            Safecharge safeCharge = new Safecharge();
            SafechargeResponse response = safeCharge.payment(userTokenId, clientUniqueId,
                    clientRequestId, paymentOption, null, currency, amount, null, null,
                    deviceDetails, null, shippingAddress, billingAddress, null, null, null, null,
                    null, null, null, null, null, null, null);
        } catch (SafechargeException e) {
            e.printStackTrace();
        }
}

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
<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'EUR',
    'amount'         => '10',
    'userTokenId'    => '73fdd373b171299e692932ac01052001',
    'paymentOption'  => [
        'card' => [
            'cardNumber'      => '4012001037141112',
            'cardHolderName'  => 'some name',
            'expirationMonth' => '01',
            'expirationYear'  => '2020',
            'CVV'             => '122',
        ]
    ],
    'billingAddress' => [
        "firstName" => "some first name",
        "lastName"  => "some last name",
        "address"   => "some street",
        "phone"     => "972502457558",
        "zip"       => "123456",
        "city"      => "some city",
        'country'   => "DE",
        "state"     => "",
        "email"     => "someemail@somedomain.com",
        "county"    => "Anchorage",
    ],
    'deviceDetails'  => [
        "ipAddress"  => "192.168.1.54"
    ],
]);
?>

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
<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'EUR',
    'amount'         => '10',
    'userTokenId'    => '73fdd373b171299e692932ac01052001',
    'paymentOption'  => [
        'card' => [
            'cardNumber'      => '4012001037141112',
            'cardHolderName'  => 'some name',
            'expirationMonth' => '01',
            'expirationYear'  => '2020',
            'CVV'             => '122',
            'threeD' =>[
                'version'=>'2',
                'challengePreference'  => '1',
                'notificationUrl'      => 'https=>//www.merchant.com/notificationURL/',
                'merchantUrl'          => 'https://www.merchant-website.com',
                'platformType'         => '02',
                'deliveryEmail'        => 'deliveryEmail@somedomain.com',
                'deliveryTimeFrame'    => '1',
                'giftCardAmount'       => '456',
                'giftCardCount'        => '10',
                'giftCardCurrency'     => '826',
                'preOrderDate'         => '20190219',
                'preOrderPurchaseInd'  => '2',
                'reorderItemsInd'      => '2',
                'shipIndicator'        => '1',
                'rebillExpiry'         => '',
                'rebillFrequency'      => '',
                'ChallengeWindowSize'  => '2'    
                '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'
                ]
            ]
        ]
    ],
    'shippingAddress' => [
        'firstName' => 'some first name',
        'lastName'  => 'some last name',
        'address'   => 'some street',
        'phone'     => '972502457558',
        'zip'       => '123456',
        'city'      => 'some city',
        'country'   => 'DE',
        'state'     => '',
        'email'     => 'someemail@somedomain.com',
        'county'    => 'Anchorage',
    ],
    'dynamicDescriptor'  => [
        'merchantName'  => 'merchant Name'
        'merchantPhone'  => 'merchant Phone'
    ],
    'billingAddress' => [
        'firstName' => 'some first name',
        'lastName'  => 'some last name',
        'address'   => 'some street',
        'phone'     => '972502457558',
        'zip'       => '123456',
        'city'      => 'some city',
        'country'   => 'DE',
        'state'     => '',
        'email'     => 'someemail@somedomain.com',
        'county'    => 'Anchorage',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '192.168.1.54'
    ],
]);
?>

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
<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'EUR',
    'amount'         => '10',
    'userTokenId'    => '73fdd373b171299e692932ac01052001',
    'paymentOption'  => [
        'alternativePaymentMethod' => [
            'paymentMethod'      => 'apmgw_MoneyBookers',
            'account_id'  => 'SkrillTestUser3'
        ]
    ],
    'billingAddress' => [
        'firstName' => 'some first name',
        'lastName'  => 'some last name',
        'address'   => 'some street',
        'phone'     => '972502457558',
        'zip'       => '123456',
        'city'      => 'some city',
        'country'   => 'DE',
        'state'     => '',
        'email'     => 'someemail@somedomain.com',
        'county'    => 'Anchorage',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '192.168.1.54'
    ],
]);
?>

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
<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'EUR',
    'amount'         => '10',
    'userTokenId'    => '73fdd373b171299e692932ac01052001',
    'paymentOption'  => [
        'alternativePaymentMethod' => [
            'paymentMethod'      => 'apmgw_Neteller',
            'nettelerAccount'  => '453313818311',
            'nettelerSecureId'  => '173419'
        ]
    ],
    'billingAddress' => [
        'firstName' => 'some first name',
        'lastName'  => 'some last name',
        'address'   => 'some street',
        'phone'     => '972502457558',
        'zip'       => '123456',
        'city'      => 'some city',
        'country'   => 'DE',
        'state'     => '',
        'email'     => 'someemail@somedomain.com',
        'county'    => 'Anchorage',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '192.168.1.54'
    ],
]);
?>

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
<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'EUR',
    'amount'         => '10',
    'userTokenId'    => '73fdd373b171299e692932ac01052001',
    'paymentOption'  => [
        'card' => [
            'cardNumber'      => '4012001037141112',
            'cardHolderName'  => 'some name',
            'expirationMonth' => '01',
            'expirationYear'  => '2020',
            'CVV'             => '122',
            'threeD' =>[
                'version'=>'2',
                'challengePreference'  => '1',
                'notificationUrl'      => 'https=>//www.merchant.com/notificationURL/',
                'merchantUrl'          => 'https://www.merchant-website.com',
                'platformType'         => '02',
                'deliveryEmail'        => 'deliveryEmail@somedomain.com',
                'deliveryTimeFrame'    => '1',
                'giftCardAmount'       => '456',
                'giftCardCount'        => '10',
                'giftCardCurrency'     => '826',
                'preOrderDate'         => '20190219',
                'preOrderPurchaseInd'  => '2',
                'reorderItemsInd'      => '2',
                'shipIndicator'        => '1',
                'rebillExpiry'         => '',    //in case of recurring
                'rebillFrequency'      => '',    //in case of recurring
                'ChallengeWindowSize'  => '2'    
                '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'
                ]
                'account' =>[                //in case you have user account management
                    'age'                  =>'05',
                    'lastChangeDate'       =>'20190220',
                    'lastChangeInd'        =>'04',
                    'registrationDate'     =>'20190221',
                    'passwordChangeDate'   =>'20190222',
                    'resetInd'             =>'01',
                    'purchasesCount6M'     =>'6',
                    'addCardAttempts24H'   =>'24',
                    'transactionsCount24H' =>'23',
                    'transactionsCount1Y'  =>'998',
                    'cardSavedDate'        =>'20190223',
                    'cardSavedInd'         =>'02',
                    'addressFirstUseDate'  =>'20190224',
                    'addressFirstUseInd'   =>'03',
                    'nameInd'              =>'02',
                    'suspiciousActivityInd'=>'01'                
                ]
            ]
        ]
    ],
    'relatedTransactionId' = > '2110000000001208909', //as returned from initPayment
    'shippingAddress' => [
        'firstName' => 'some first name',
        'lastName'  => 'some last name',
        'address'   => 'some street',
        'phone'     => '972502457558',
        'zip'       => '123456',
        'city'      => 'some city',
        'country'   => 'DE',
        'state'     => '',
        'email'     => 'someemail@somedomain.com',
        'county'    => 'Anchorage',
    ],
    'billingAddress' => [
        'firstName' => 'some first name',
        'lastName'  => 'some last name',
        'address'   => 'some street',
        'phone'     => '972502457558',
        'zip'       => '123456',
        'city'      => 'some city',
        'country'   => 'DE',
        'state'     => '',
        'email'     => 'someemail@somedomain.com',
        'county'    => 'Anchorage',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '192.168.1.54'
    ],
]);
?>

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
<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'EUR',
    'amount'         => '10',
    'userTokenId'    => '73fdd373b171299e692932ac01052001',
    'paymentOption'  => [
        'userPaymentOptionId' => "8348263" //in case using tokenization
        /* instead can also be the full cardholder information, without the threeD section*/
            'cardNumber'      => '4012001037141112',
            'cardHolderName'  => 'some name',
            'expirationMonth' => '01',
            'expirationYear'  => '2020',
            'CVV'             => '122',
            'threeD' =>[
                'version'=>'2',
                'challengePreference'  => '1',
                'notificationUrl'      => 'https=>//www.merchant.com/notificationURL/',
                'merchantUrl'          => 'https://www.merchant-website.com',
                'platformType'         => '02',
                'deliveryEmail'        => 'deliveryEmail@somedomain.com',
                'deliveryTimeFrame'    => '1',
                'giftCardAmount'       => '456',
                'giftCardCount'        => '10',
                'giftCardCurrency'     => '826',
                'preOrderDate'         => '20190219',
                'preOrderPurchaseInd'  => '2',
                'reorderItemsInd'      => '2',
                'shipIndicator'        => '1',
                'rebillExpiry'         => '',    //in case of recurring
                'rebillFrequency'      => '',    //in case of recurring
                'ChallengeWindowSize'  => '2'    
                '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'
                ]
                'account' =>[                //in case you have user account management
                    'age'                  =>'05',
                    'lastChangeDate'       =>'20190220',
                    'lastChangeInd'        =>'04',
                    'registrationDate'     =>'20190221',
                    'passwordChangeDate'   =>'20190222',
                    'resetInd'             =>'01',
                    'purchasesCount6M'     =>'6',
                    'addCardAttempts24H'   =>'24',
                    'transactionsCount24H' =>'23',
                    'transactionsCount1Y'  =>'998',
                    'cardSavedDate'        =>'20190223',
                    'cardSavedInd'         =>'02',
                    'addressFirstUseDate'  =>'20190224',
                    'addressFirstUseInd'   =>'03',
                    'nameInd'              =>'02',
                    'suspiciousActivityInd'=>'01'                
                ]
            ]
        ]
    ],
    'relatedTransactionId' = > '2110000000001208909', //as returned from 1st payment call
    'billingAddress' => [
        'firstName' => 'some first name',
        'lastName'  => 'some last name',
        'address'   => 'some street',
        'phone'     => '972502457558',
        'zip'       => '123456',
        'city'      => 'some city',
        'country'   => 'DE',
        'state'     => '',
        'email'     => 'someemail@somedomain.com',
        'county'    => 'Anchorage',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '192.168.1.54'
    ],
]);
?>

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
<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'EUR',
    'amount'         => '10',
    'userTokenId'    => '73fdd373b171299e692932ac01052001',
    'paymentOption'  => [
        'card' => [
            'cardNumber'      => '4012001037141112',
            'cardHolderName'  => 'some name',
            'expirationMonth' => '01',
            'expirationYear'  => '2020',
            'CVV'             => '122',
            'threeD' =>[
                'externalMpi' =>[
                    'eci'       => '2',
                    'cavv'          => 'ejJRWG9SWWRpU2I1M21DelozSXU',
                    'dsTransID'         => '9e6c6e9b-b390-4b11-ada9-0a8f595e8600'  //xid in case of 3Dv1        
                ]
                    'age'                  =>'05',
                    'lastChangeDate'       =>'20190220',
                    'lastChangeInd'        =>'04',
                    'registrationDate'     =>'20190221',
                    'passwordChangeDate'   =>'20190222',
                    'resetInd'             =>'01',
                    'purchasesCount6M'     =>'6',
                    'addCardAttempts24H'   =>'24',
                    'transactionsCount24H' =>'23',
                    'transactionsCount1Y'  =>'998',
                    'cardSavedDate'        =>'20190223',
                    'cardSavedInd'         =>'02',
                    'addressFirstUseDate'  =>'20190224',
                    'addressFirstUseInd'   =>'03',
                    'nameInd'              =>'02',
                    'suspiciousActivityInd'=>'01'                
                ]
            ]
        ]
    ],
    'billingAddress' => [
        'firstName' => 'some first name',
        'lastName'  => 'some last name',
        'address'   => 'some street',
        'phone'     => '972502457558',
        'zip'       => '123456',
        'city'      => 'some city',
        'country'   => 'DE',
        'state'     => '',
        'email'     => 'someemail@somedomain.com',
        'county'    => 'Anchorage',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '192.168.1.54'
    ],
]);
?>

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
using System.Collections.Generic;
using Safecharge.Model.Payment;
using Safecharge.Utils;
using Safecharge.Utils.Enum;

namespace Safecharge.Sample
{
    class PaymentSimpleCardSample
    {
        static void Main()
        {
            var safecharge = new Safecharge(
                "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_KEY_PROVIDED_BY_SAFECHARGE",
                ApiConstants.IntegrationHost,
                HashAlgorithmType.SHA256);

            // Using the safecharge wrapper
            var response = safecharge.Payment(
                "USD",
                "10.02",
                 new List<Item>
                {
                    new Item
                    {
                        Name = "Item 1U",
                        Price = "0.01",
                        Quantity = "1"
                    },
                    new Item
                    {
                        Name = "testItem1",
                        Price = "10.01",
                        Quantity = "1"
                    }
                },
                new PaymentOption
                {
                    Card = new Card
                    {
                        CardNumber = "4000023104662535",
                        CardHolderName = "John Smith",
                        ExpirationMonth = "12",
                        ExpirationYear = "2022",
                        CVV = "217"
                    }
                });

            PrintResponseResult(response);
        }

        private static void PrintResponseResult(PaymentResponse response)
        {
            if (response.Status == ResponseStatus.Error)
            {
                Console.WriteLine("Reason: " + response.Reason);
            }
            else
            {
                Console.WriteLine("Status: " + response.Status);
                Console.WriteLine("Session token: " + response.SessionToken);
            }
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
using System;
using System.Collections.Generic;
using Safecharge.Model;
using Safecharge.Model.Payment;
using Safecharge.Response.Payment;
using Safecharge.Utils;
using Safecharge.Utils.Enum;

namespace Safecharge.Sample
{
    class PaymentFullCardSample
    {
        static void Main()
        {
            var safecharge = new Safecharge(
                "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_KEY_PROVIDED_BY_SAFECHARGE",
                ApiConstants.IntegrationHost,
                HashAlgorithmType.SHA256);

            var response = safecharge.Payment(
                "USD",
                "10",
                 new List<Item> {},
                new PaymentOption
                {
                    Card = new Card
                    {
                        CardNumber = "5115806139808464",
                        CardHolderName = "test name",
                        ExpirationMonth = "01",
                        ExpirationYear = "2020",
                        CVV = "122",
                        ThreeD = new ThreeD
                        {
                            Version = "2",
                            NotificationURL = "https://www.merchant.com/notificationURL/",
                            MerchantURL = "https://www.merchant-website.com",
                            PlatformType = "02",
                            V2AdditionalParams = new V2AdditionalParams 
                            { 
                                ChallengePreference = "1", 
                                DeliveryEmail = "deliveryEmail@somedomain.com", 
                                DeliveryTimeFrame = "1",
                                GiftCardAmount = "456",
                                GiftCardCount = "10",
                                GiftCardCurrency = "826", // TODO: check
                                PreOrderDate = "20190219",
                                PreOrderPurchaseInd = "2",
                                ReorderItemsInd = "2",
                                ShipIndicator = "1",
                                RebillExpiry = "",
                                RebillFrequency = "",
                                ChallengeWindowSize = "2"
                            },
                            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"
                            }
                        }
                    }
                },
                shippingAddress: new UserAddress
                {
                    FirstName = "some first name",
                    LastName = "some last name",
                    Address = "address",
                    Phone = "972502457558",
                    Zip = "1340",
                    City = "city",
                    Country = "DE",
                    State = "",
                    Email = "someemail@somedomain.com"
                },
                dynamicDescriptor: new DynamicDescriptor { MerchantName = "merchant Name", MerchantPhone = "Phone" },
                billingAddress: new UserAddress
                {
                    FirstName = "some first name",
                    LastName = "some last name",
                    Address = "address",
                    Phone = "972502457558",
                    Zip = "123456",
                    City = "city",
                    Country = "DE",
                    State = "",
                    Email = "asd@asdasd.com",
                    County = "Anchorage"
                },
                deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" });

            PrintResponseResult(response);
        }

        private static void PrintResponseResult(PaymentResponse response)
        {
            if (response.Status == ResponseStatus.Error)
            {
                Console.WriteLine("Reason: " + response.Reason);
            }
            else
            {
                Console.WriteLine("Status: " + response.Status);
                Console.WriteLine("Session token: " + response.SessionToken);
            }
        }
    }
}

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
using System;
using System.Collections.Generic;
using Safecharge.Model;
using Safecharge.Model.Payment;
using Safecharge.Response.Payment;
using Safecharge.Utils;
using Safecharge.Utils.Enum;

namespace Safecharge.Sample
{
    class PaymentApmRedirectSample
    {
        static void Main()
        {
            var safecharge = new Safecharge(
                "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_KEY_PROVIDED_BY_SAFECHARGE",
                ApiConstants.IntegrationHost,
                HashAlgorithmType.SHA256);

            var response = safecharge.Payment(
                "USD",
                "10",
                 new List<Item> {},
                new PaymentOption
                {
                    AlternativePaymentMethod = new Dictionary<string, string>()
                    {
                        { "paymentMethod", "apmgw_MoneyBookers" },
                        { "account_id", "SkrillTestUser3" }
                    }
                },
                billingAddress: new UserAddress
                {
                    FirstName = "John",
                    LastName = "Smithe",
                    Address = "340689 main St.",
                    Phone = "972502457558",
                    Zip = "123456",
                    City = "London",
                    Country = "GB",
                    State = "",
                    Email = "john.smith@safecharge.com"
                },
                deviceDetails: new DeviceDetails { IpAddress = "93.146.254.172" });

            PrintResponseResult(response);
        }

        private static void PrintResponseResult(PaymentResponse response)
        {
            if (response.Status == ResponseStatus.Error)
            {
                Console.WriteLine("Reason: " + response.Reason);
            }
            else
            {
                Console.WriteLine("Status: " + response.Status);
                Console.WriteLine("Session token: " + response.SessionToken);
            }
        }
    }
}

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
using System;
using System.Collections.Generic;
using Safecharge.Model.Payment;
using Safecharge.Response.Payment;
using Safecharge.Utils;
using Safecharge.Utils.Enum;

namespace Safecharge.Sample
{
    class PaymentApmDirectSample
    {
        static void Main()
        {
            var safecharge = new Safecharge(
                "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_KEY_PROVIDED_BY_SAFECHARGE",
                ApiConstants.IntegrationHost,
                HashAlgorithmType.SHA256);

            var response = safecharge.Payment(
                "USD",
                "10",
                 new List<Item> {},
                new PaymentOption
                {
                    AlternativePaymentMethod = new Dictionary<string, string>()
                    {
                        { "paymentMethod", "apmgw_Neteller" },
                        { "nettelerAccount", "453313818311" },
                        { "nettelerSecureId", "173419" }
                    }
                },
                billingAddress: new UserAddress
                {
                    FirstName = "John",
                    LastName = "some last name",
                    Address = "Smith",
                    Phone = "972502457558",
                    Zip = "123456",
                    City = "London",
                    Country = "GB",
                    State = "",
                    Email = "john.smith@safecharge.com"
                },
                deviceDetails: new DeviceDetails { IpAddress = "93.146.254.172" });

            PrintResponseResult(response);
        }

        private static void PrintResponseResult(PaymentResponse response)
        {
            if (response.Status == ResponseStatus.Error)
            {
                Console.WriteLine("Reason: " + response.Reason);
            }
            else
            {
                Console.WriteLine("Status: " + response.Status);
                Console.WriteLine("Session token: " + response.SessionToken);
            }
        }
    }
}

1
2
THE PLACE FOR 1st 3D payment request

1
2
THE PLACE FOR 2st 3D payment 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
using System;
using System.Collections.Generic;
using Safecharge.Model;
using Safecharge.Model.Payment;
using Safecharge.Response.Payment;
using Safecharge.Utils;
using Safecharge.Utils.Enum;

namespace Safecharge.Sample
{
    class PaymentExternalMpiSample
    {
        static void Main()
        {
            var safecharge = new Safecharge(
                "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_KEY_PROVIDED_BY_SAFECHARGE",
                ApiConstants.IntegrationHost,
                HashAlgorithmType.SHA256);

            var response = safecharge.Payment(
                "USD",
                "10",
                 new List<Item> { },
                new PaymentOption
                {
                    Card = new Card
                    {
                        CardNumber = "5111426646345761",
                        CardHolderName = "john smith",
                        ExpirationMonth = "12",
                        ExpirationYear = "25",
                        CVV = "217",
                        ThreeD = new ThreeD
                        {
                            ExternalMpi = new ExternalMpi 
                            {
                                Eci = "2",
                                Cavv = "ejJRWG9SWWRpU2I1M21DelozSXU",
                                DsTransID = "9e6c6e9b-b390-4b11-ada9-0a8f595e8600", //xid in case of 3Dv1 
                            },
                            Account = new Account
                            {
                                Age = "05",
                                LastChangeDate = "20190220",
                                LastChangeInd = "04",
                                RegistrationDate = "20190221",
                                PasswordChangeDate = "20190222",
                                ResetInd = "01",
                                PurchasesCount6M = "6",
                                AddCardAttepmts24H = "24",
                                TransactionsCount24H = "23",
                                TransactionsCount1Y = "998",
                                CardSavedDate = "20190223",
                                CardSavedInd = "02",
                                AddressFirstUseDate = "20190224",
                                AddressFirstUseInd = "03",
                                NameInd = "02",
                                SuspiciousActivityInd = "01"
                            }
                        }
                    }
                },
                billingAddress: new UserAddress
                {
                    FirstName = "John",
                    LastName = "Smith",
                    Address = "340689 main St.",
                    Phone = "972502457558",
                    Zip = "123456",
                    City = "London",
                    Country = "GB",
                    State = "",
                    Email = "john.smith@safecharge.com"
                },
                deviceDetails: new DeviceDetails { IpAddress = "93.146.254.172" });

            PrintResponseResult(response);
        }

        private static void PrintResponseResult(PaymentResponse response)
        {
            if (response.Status == ResponseStatus.Error)
            {
                Console.WriteLine("Reason: " + response.Reason);
            }
            else
            {
                Console.WriteLine("Status: " + response.Status);
                Console.WriteLine("Session token: " + response.SessionToken);
            }
        }
    }
}

1
2
THE PLACE FOR ApplePay

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": "246670583",
    "userTokenId": "someone@website.com",
    "paymentOption": {
        "userPaymentOptionId": "8348263",
        "card": {
            "ccCardNumber": "5****8464",
            "bin": "511580",
           "last4Digits": "8464",
            "ccExpMonth": "01",
            "ccExpYear": "20",
            "acquirerId": "19",
            "cvv2Reply": "",
            "avsCode": "",
            "threeD": {
                "sdk": {}
            }
        }
    },
    "transactionStatus": "DECLINED",
    "merchantDetails": {
        "customField1": "customField1"
    },
    "gwErrorCode": -1,
    "gwErrorReason": "Decline",
    "gwExtendedErrorCode": 0,
    "transactionType": "Auth3D",
    "transactionId": "1110000000000696512",
    "externalTransactionId": "",
    "authCode": "",
    "customData": "",
    "sessionToken": "76f24921-a279-4ad7-9893-142d6e6c2ab6",
    "clientUniqueId": "uniqueIdCC",
    "internalRequestId": 143323743,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0"
}

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

• Regular card transactions – credit or debit cards
  
• 3D Secure card transactions, supporting 3D Secure 2.0
  
• Alternative payment method transactions

Mandatory Fields

• Authentication credentials – sessionToken, merchantId, merchantSiteId, checksum, timeStamp, country under billing Address
  
• Amount and currency
  
• A Payment option – The payment method details by which option the payment is executed. This is passed using the paymentOption JSON block, which is either created by the Web SDK and passed from the client-side or can be constructed by you directly on the server side.

Selecting a Payment Method (paymentOption Class)

This class represents the details of the payment method of the transaction, which can be one of three options that are represented by the sub-class to the paymentOption:

• card – Sub-class for credit/debit cards. This contains the details on the card (number, expiration), as well as the 3D Secure information, if 3D is required.
  
• alternativePaymentMethod – Sub-class for alternative methods. The specific method is marked by the paymentMethod field.
  
• 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.

@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. See /getSessionToken for details.
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 UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId merchantSiteId clientRequestId amount currency timeStamp merchantSecretKey
currency ^String(3) ~Required	The three-letter ISO currency code.
amount ^Double(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. Can be one of 3 options: 1. card – Represents a credit/debit card. Fields:    - cardNumber, string(20)(MANDATORY) – The card number    - cardHolderName, string(70)(MANDATORY) – The card holder name.    - expirationMonth, string(2)(MANDATORY) – The card expiration month.    - expirationYear, string(4)(MANDATORY) – The card expiration year.    - CVV, string(4)(MANDATORY) – The CVV/CVC security code.    For advanced card scenarios (instead of card details):       - For 3D Secure, please refer to threeD class.       - When using an external token provider such as ApplePay or Visa Checkout, refer to externalToken (class). -or- 2. alternativePaymentMethod – Represents an alternative payment method. For details, please refer to alternativePaymentMethod Class. -or- 3. 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.
deviceDetails ^Class ~Only ipAddress	deviceType (String, 10) deviceName (String, 255) deviceOS (String, 255) browser (String, 255) ipAddress (String, 15, MANDATORY) Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (if device type cannot be recognized). The ipAddress parameter can be defined as mandatory or non-mandatory as needed by Nuvei’s Integration Support Team.
relatedTransactionId ^String(19) ~Conditional	Mandatory in the following cases: For 3D Secure 2.0 (refer to the 3D Secure 2.0 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 recurring/rebilling and MIT: Represents the reference to the original transaction ID of the initial transaction (see Merchant Initiated Payments for details).
billingAddress ^Class ~country and email mandatory	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. firstName (String, 30) lastName (String, 40) address (String, 60) address2 (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (two-letter ISO country code)(String, 2, MANDATORY), must be entered in uppercase state(String, 2) - Two-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100, MANDATORY) county (String, 255) These parameters can be defined as mandatory or non-mandatory as needed by Nuvei’s Integration Support Team.
transactionType ^String(45) ^Optional	The type of transaction: Sale or Auth. Sale – is a regular payment request Auth – Performs an authorization only request. For details, see Auth and Settle.
subMethodDetails ^Class ^Optional	subMethod(String) – details below email(String) – 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.
userTokenId ^String(255) ^Optional	This field 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.
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.
isRebilling ^Integer(2) ^Optional	When performing recurring/rebilling, use this field to indicate the recurring step with the following vales: 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 3DS transaction, you also must specify rebillExpiry and rebillFrequency under the v2AdditionalParams block, under the threeD block.
rebillingType ^String ^Optional	When performing recurring/rebilling, use this field to indicate the recurring type with the following vales: RECURRING – Regular, recurring charging of the consumer MIT – Merchant Initiated Transaction. In case this is a one-time payment, initiated by the merchant.
authenticationOnlyType ^String(2) ^Optional	This is an advanced field, intended for merchants using the Zero Authorization feature. Most merchants do not need to use this field, as this is managed by Nuvei. Only merchants that are not using tokenization and/or are not using the user payment option management are required to set this field. The field marks the type of Zero Authorization and the purpose it is being used for. Possible values: 01 = for Recurring transactions 02 = For Instalment transactions 03 = When performing just an “Add card” action for future use 04 = Maintain card information 05 = Account verification only.
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
amountDetails ^Class ^Optional	totalShipping (String, not mandatory) totalHandling (String, not mandatory) totalDiscount (String, not mandatory) totalTax (String, not mandatory) 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	name (String, 255, mandatory) price (String, 10, mandatory) quantity (String, 10, mandatory) An array describing the items in the purchase. 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, not mandatory) lastName (String, 40, not mandatory) address (String, 60, not mandatory) phone (String, 18, not mandatory) zip (String, 10, not mandatory) city (String, 30, not mandatory) country (two-letter ISO country code)(String, 2, not mandatory) state(String, 2, not mandatory) - Two-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100, not mandatory) county (String, 255, not mandatory) language (String, 2, not mandatory) – 2-letter ISO language code. dateOfBirth (String, 10, not mandatory) – 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 (two-letter ISO country code)(String, 2) state(String, 2) - Two-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100) shippingCounty (String, 255)
dynamicDescriptor ^Class ^Optional	descriptorMerchantName (String, 25, not mandatory) descriptorMerchantPhone (String, 13, not mandatory) merchantName - 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 - 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, not mandatory) … 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) failureUrl (string, 1000) pendingUrl (string, 1000) notificationUrl (string, 1000)
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.
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.
subMerchant ^Class ~Conditional	countryCode (String,2) – The payment facilitator’s sub-merchant’s two-letter ISO country code. city (String, 20) – The payment facilitator’s sub-merchant’s city name. id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.

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 merchant 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 3D Secure Guide for full details. Alternative payment method that requires redirection – The URL is on paymentOption.redirectURL.
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 the threeD (out) chapter for details. 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, not mandatory) … 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 – is a regular payment request Auth – Performs an authorization only request. For details, see Auth and Settle.
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
        "clientRequestId": "1C6CT7V1L",
    "clientUniqueId": "12345",
    "amount": "9.0",
    "currency": "EUR",
    "relatedTransactionId": "<transactionId returned from a payment>",
    "descriptorMerchantName": "Name",
    "descriptorMerchantPhone": "+4412378",
    "comment": "some comment",
    "urlDetails": {
        "notificationUrl": ""
    },
    "productId":"",
    "customData":"",
    "webMasterId":"",
    "timeStamp": "20190915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
const safecharge = require('safecharge');
safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>);
// env is optional can be 'test' or 'prod'. default value is 'prod'

safecharge.paymentService.settleTransaction({
    clientUniqueId         : "695701003",
    amount                 : "6.0",
    currency               : "GBP",
    relatedTransactionId   : "<transactionId>",
    descriptorMerchantName : "merchantName",
    descriptorMerchantPhone: "MerchantPhone",
    comment                : "Comment",
    urlDetails             : {
        notificationUrl: "https://example.com"
    },
    productId              : "productId - 123",
    customData             : "customData"
}, function (stlErr, stlRes) {
    console.log(stlErr, stlRes);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
//Initialize SDK. See the Nuvei Java SDK at https://docs.safecharge.com/documentation/guides/server-sdks/nuvei-java-sdk/.
{ 
    String clientUniqueId = "12345";
    String currency = "EUR";
    String amount = "9.0";
    String comment = "some comment";
    String relatedTransactionId = "transactionId returned from a payment request";

    String descriptorMerchantName="Name";
    String descriptorMerchantPhone="+4412378";

    try {
        Safecharge safecharge = new Safecharge();
        safecharge.initialize(merchantId, merchantSiteId, merchantKey, APIConstants.Environment.PRODUCTION_HOST.getUrl(), Constants.HashAlgorithm.SHA256);
        SafechargeResponse response = safecharge.settleTransaction(clientUniqueId, null, null, descriptorMerchantName,
                descriptorMerchantPhone, null, amount, null, null, comment, currency, null, null,
                relatedTransactionId, null);
    } catch (SafechargeException e) {
        e.printStackTrace();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<?php
$safeCharge = new \SafeCharge\Api\SafeCharge([
    'environment'       => 'test',
    'merchantId'        => '<merchantId>',
    'merchantSiteId'    => '<merchantSiteId>',
    'merchantSecretKey' => '<merchantSecretKey>',
    'hashAlgorithm'     => '<hashAlgorithm>'
]);

//settleTransaction
$settleResponse = $safeCharge->getPaymentService()->settleTransaction([
    'clientUniqueId'          => '12345',
    'amount'                  => '10',
    'currency'                => 'EUR',
    'relatedTransactionId'    => '1234567890',
    'descriptorMerchantName'  => 'merchantName',
    'descriptorMerchantPhone' => '+4412378',
    'comment'                 => 'some comment',
    'urlDetails'              => [
        'notificationUrl' => 'https://www.safecharge.com/notification'
    ],
]);
?>

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
using System;
using Safecharge.Model.Payment;
using Safecharge.Response.Transaction;
using Safecharge.Utils;
using Safecharge.Utils.Enum;

namespace Safecharge.Sample
{
    class SettleTransactionSample
    {
        static void Main()
        {
            var safecharge = new Safecharge(
                "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_KEY_PROVIDED_BY_SAFECHARGE",
                ApiConstants.IntegrationHost,
                HashAlgorithmType.SHA256);

            var response = safecharge.SettleTransaction(
                "EUR",
                "9.0",
                "<transactionId>", // returned from the payment auth
                clientUniqueId: "695701003",
                descriptorMerchantName: "Name",
                descriptorMerchantPhone: "+4412378",
                comment: "some comment",
                urlDetails: new UrlDetails { NotificationUrl = "" },
                productId: "");

            PrintResponseResult(response);
        }

        private static void PrintResponseResult(SettleTransactionResponse response)
        {
            if (response.Status == ResponseStatus.Error)
            {
                Console.WriteLine("Reason: " + response.Reason);
            }
            else
            {
                Console.WriteLine("Status: " + response.Status);
                Console.WriteLine("Session token: " + response.SessionToken);
            }
        }
    }
}

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 three-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 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 UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId merchantSiteId clientRequestId clientUniqueId amount currency relatedTransactionId authCode descriptorMerchantName descriptorMerchantPhone comment urlDetails timeStamp merchantSecretKey
subMerchant ^Class ~Conditional	countryCode (String,2) – The payment facilitator’s sub-merchant’s two-letter ISO country code. city (String, 20) – The payment facilitator’s sub-merchant’s city name. id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
authCode ^String(128) ^Optional	The authorization code of the original transaction to be refunded.
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) This parameter determines where to return the DMN. Each parameter is limited for up to 1000 characters.
addendums ^Class ^Optional	This block contains industry specific addendums. The addendum fields that appear are based on the specific addendum type. For example, airline addendum includes: 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) passengerDetails {passengerId(String), passportNumber(String), customerCode(String), frequentFlyerCode(String), title(String), firstName(String), lastName(String), middleName(String), dateOfBirth(String), phoneNumber(String)} flightLegDetails {flightLegId(String), airlineCode(S, 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)} For card airline transactions, it is not required to send airline information during settle as it is sent previously during Auth. For APM airline transactions, it is required to send airline information during settle and not during Auth (currently only PayPal APM is supported for airline transactions). For more information and for required Nuvei configurations settings, please contact Nuvei’s Integration Support Team.
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.
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.

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, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
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 is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientUniqueId": "12345",
    "amount": "9.0",
    "currency": "EUR",
    "relatedTransactionId": "8495798459",
    "authCode": "8378749",
    "comment": "some comment",
    "urlDetails": {
        "notificationUrl": "http://notificationUrl.com"
    },
    "productId":"",
    "customData":"",
    "webMasterId":"",
    "timeStamp": "20190915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
const safecharge = require('safecharge');
safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>);
// env is optional can be 'test' or 'prod'. default value is 'prod'

safecharge.paymentService.refundTransaction({
    clientUniqueId      : "695701003",
    amount              : "6.0",
    currency            : "GBP",
    relatedTransactionId: "<transactionId>",
    authCode            : "<authCode>",
    comment             : "Comment",
    urlDetails          : {
        notificationUrl: "https://www.safecharge.com/notification"
    },
    userDetails         : {
        firstName  : "Enjjwcnnjy",
        lastName   : "Uxorfhkepk",
        email      : "sgkuy.tzizt@eabeq.bq",
        phone      : "359888729302",
        cell       : "3598877293023",
        dateOfBirth: "1992-06-02",
        address    : "22 Automation Str.",
        city       : "Chiprovci",
        zip        : "CH 2332421",
        county     : "UCounty",
        state      : "",
        country    : "GB"
    },
    productId           : "productId - 123",
    customData          : "customData",
    webMasterId         : ""
}, function (stlErr, stlRes, reqData) {
    console.log(stlErr, stlRes);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<?php
$safeCharge = new \SafeCharge\Api\SafeCharge([
    'environment'       => 'test',
    'merchantId'        => '<merchantId>',
    'merchantSiteId'    => '<merchantSiteId>',
    'merchantSecretKey' => '<merchantSecretKey>',
    'hashAlgorithm'     => '<hashAlgorithm>'
]);

//refundTransaction
$refundResponse = $safeCharge->getPaymentService()->refundTransaction([
    'clientUniqueId'          => '12345',
    'amount'                  => '10',
    'currency'                => 'EUR',
    'relatedTransactionId'    => '1234567890',
    'authCode'                => '111353',
    'comment'                 => 'some comment',
    'urlDetails'              => [
        'notificationUrl' => 'https://www.safecharge.com/notification'
    ],
]);
?>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
//Initialize SDK. See the Nuvei Java SDK at https://docs.safecharge.com/documentation/guides/server-sdks/nuvei-java-sdk/.
{    
    String clientUniqueId = "12345";
    String currency = "EUR";
    String amount = "9.0";
    String relatedTransactionId = "8495798459";
    String authCode = "8378749";
    String comment = "some comment";

    UrlDetails urlDetails = new UrlDetails();
    urlDetails.setNotificationUrl("http://notificationUrl.com");

    try {
        Safecharge safecharge = new Safecharge();
        safecharge.initialize(merchantId, merchantSiteId, merchantKey, APIConstants.Environment.PRODUCTION_HOST.getUrl(), Constants.HashAlgorithm.SHA256);
        SafechargeResponse response = safecharge.refundTransaction(clientUniqueId, null, urlDetails, amount, authCode,
                comment, currency, null, null, null, relatedTransactionId, null);
    } catch (SafechargeException e) {
        e.printStackTrace();
    }
}

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
using System;
using Safecharge.Model.Payment;
using Safecharge.Response.Transaction;
using Safecharge.Utils;
using Safecharge.Utils.Enum;

namespace Safecharge.Sample
{
    class RefundTransactionSample
    {
        static void Main()
        {
            var safecharge = new Safecharge(
                "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_KEY_PROVIDED_BY_SAFECHARGE",
                ApiConstants.IntegrationHost,
                HashAlgorithmType.SHA256);

            var response = safecharge.RefundTransaction(
                "EUR",
                "9.0",
                "<transactionId>", // returned from the payment
                clientUniqueId: "12345",
                authCode: "8378749", // returned from the payment
                comment: "some comment",
                urlDetails: new UrlDetails { NotificationUrl = "http://notificationUrl.com" },
                productId: "",
                customData: "");

            PrintResponseResult(response);
        }

        private static void PrintResponseResult(RefundTransactionResponse response)
        {
            if (response.Status == ResponseStatus.Error)
            {
                Console.WriteLine("Reason: " + response.Reason);
            }
            else
            {
                Console.WriteLine("Status: " + response.Status);
                Console.WriteLine("Session token: " + response.SessionToken);
            }
        }
    }
}

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 three-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 transaction.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^String(256) ~Required	The UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId merchantSiteId clientRequestId clientUniqueId amount currency relatedTransactionId authCode comment urlDetails timeStamp merchantSecretKey.
subMerchant ^Class ~Conditional	countryCode (String,2) – The payment facilitator’s sub-merchant’s two-letter ISO country code. city (String, 20) – The payment facilitator’s sub-merchant’s city name. id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
authCode ^String(128) ^Optional	The authorization code of the related settle transaction, to be compared to the original one. This is mandatory for cards, non-mandatory for APMs.
comment ^String(255) ^Optional	Enables the addition of a free text comment to the request.
urlDetails ^Class ^Optional	notificationUrl(String, 1000) This parameter determines where to return the DMN. Each parameter is limited for up to 1000 characters.
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.
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.

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, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
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 is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientUniqueId": "12345",
    "amount": "9.0",
    "currency": "EUR",
    "relatedTransactionId": "8495798459",
    "authCode": "8378749",
    "comment": "some comment",
    "urlDetails": {
        "notificationUrl": "http://notificationUrl.com"
    },
    "productId":"",
    "customData":"",
    "webMasterId":"",
    "timeStamp": "20190915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
const safecharge = require('safecharge');
safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>);
// env is optional can be 'test' or 'prod'. default value is 'prod'

safecharge.paymentService.voidTransaction({
    clientUniqueId         : "695701003",
    amount                 : "6.0",
    currency               : "GBP",
    relatedTransactionId   : "<transactionId>",
    authCode               : "<authCode>",
    descriptorMerchantName : "merchantName",
    descriptorMerchantPhone: "MerchantPhone",
    comment                : "Comment",
    urlDetails             : {
        notificationUrl: "https://example.com"
    },
    productId              : "productId - 123",
    customData             : "customData"
}, function (stlErr, stlRes, reqData) {
    console.log(stlErr, stlRes);

});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<?php
$safeCharge = new \SafeCharge\Api\SafeCharge([
    'environment'       => 'test',
    'merchantId'        => '<merchantId>',
    'merchantSiteId'    => '<merchantSiteId>',
    'merchantSecretKey' => '<merchantSecretKey>',
    'hashAlgorithm'     => '<hashAlgorithm>'
]);

//voidTransaction
$voidResponse = $safeCharge->getPaymentService()->voidTransaction([
    'clientUniqueId'          => '12345',
    'amount'                  => '10',
    'currency'                => 'EUR',
    'relatedTransactionId'    => '1234567890',
    'authCode'                => '111353',
    'descriptorMerchantName'  => 'merchantName',
    'descriptorMerchantPhone' => '+4412378',
    'comment'                 => 'some comment',
    'urlDetails'              => [
        'notificationUrl' => 'https://www.safecharge.com/notification'
    ],
]);
?>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
//Initialize SDK. See the Nuvei Java SDK at https://docs.safecharge.com/documentation/guides/server-sdks/nuvei-java-sdk/.
{ 
    String clientUniqueId = "12345";
    String currency = "EUR";
    String amount = "9.0";
    String relatedTransactionId = "8495798459";
    String authCode = "8378749";
    String comment = "some comment";

    UrlDetails urlDetails = new UrlDetails();
    urlDetails.setNotificationUrl("http://notificationUrl.com");

    try {
        Safecharge safecharge = new Safecharge();
        safecharge.initialize(merchantId, merchantSiteId, merchantKey, APIConstants.Environment.PRODUCTION_HOST.getUrl(), Constants.HashAlgorithm.SHA256);
        SafechargeResponse response = safecharge.voidTransaction(null, relatedTransactionId, amount, currency,
                authCode, clientUniqueId, urlDetails, null, null, null, comment, null)
    } catch (SafechargeException e) {
        e.printStackTrace();
    }
}

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
using System;
using Safecharge.Model.Payment;
using Safecharge.Response.Transaction;
using Safecharge.Utils;
using Safecharge.Utils.Enum;

namespace Safecharge.Sample
{
    class VoidTransactionSample
    {
        static void Main()
        {
            var safecharge = new Safecharge(
                "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_KEY_PROVIDED_BY_SAFECHARGE",
                ApiConstants.IntegrationHost,
                HashAlgorithmType.SHA256);

            var response = safecharge.VoidTransaction(
                "EUR",
                "9.0",
                "<transactionId>", // returned from the payment
                clientUniqueId: "12345",
                authCode: "8378749", // returned from the payment
                comment: "some comment",
                urlDetails: new UrlDetails { NotificationUrl = "http://notificationUrl.com" },
                productId: "",
                customData: "");

            PrintResponseResult(response);
        }

        private static void PrintResponseResult(VoidTransactionResponse response)
        {
            if (response.Status == ResponseStatus.Error)
            {
                Console.WriteLine("Reason: " + response.Reason);
            }
            else
            {
                Console.WriteLine("Status: " + response.Status);
                Console.WriteLine("Session token: " + response.SessionToken);
            }
        }
    }
}

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 three-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.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^String(256) ~Required	The UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId merchantSiteId clientRequestId clientUniqueId amount currency relatedTransactionId authCode comment urlDetails timeStamp merchantSecretKey.
subMerchant ^Class ~Conditional	countryCode (String,2) – The payment facilitator’s sub-merchant’s two-letter ISO country code. city (String, 20) – The payment facilitator’s sub-merchant’s city name. id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
authCode ^String(128) ^Optional	The authorization code of the related settle 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) This parameter determines where to return the DMN. Each parameter is limited for up to 1000 characters.
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.
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.

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, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
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 is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
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

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": "487106",
    "clientUniqueId": "12345",
    "amount": "9.0",
    "currency": "EUR",
    "dynamicDescriptor": {
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "merchantDetails": {
        "customField1": ""
    },
   "deviceDetails":{ 
      "ipAddress":"127.0.0.1"
   },
    "userPaymentOption":{
        "userPaymentOptionId":"1459503"
    },
    "comment": "some comment",
    "urlDetails": {
        "notificationUrl": ""
    },
    "timeStamp": "20190915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

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

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

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/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);
    });
});

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
package com.safecharge.biz;

import com.safecharge.exception.SafechargeException;
import com.safecharge.model.DynamicDescriptor;
import com.safecharge.model.MerchantInfo;
import com.safecharge.model.UserPaymentOption;
import com.safecharge.request.PayoutRequest;
import com.safecharge.response.SafechargeResponse;
import com.safecharge.util.APIConstants;
import com.safecharge.util.Constants;

public class ExamplePayout {

    public static void main(String[] args) {
        String merchantId = "427583496191624621";
        String merchantSiteId = "142033";
        String merchantKey = "7777777";

        String userTokenId = "487106";
        String clientRequestId = "100";
        String clientUniqueId = "12345";
        String currency = "EUR";
        String amount = "9.0";
        String comment = "some comment";

        MerchantInfo merchantInfo = new MerchantInfo(merchantKey, merchantId, merchantSiteId, APIConstants.Environment.PRODUCTION_HOST.getUrl(), Constants.HashAlgorithm.SHA256);

        DynamicDescriptor dynamicDescriptor = new DynamicDescriptor();
        dynamicDescriptor.setMerchantName("merchantName");
        dynamicDescriptor.setMerchantPhone("merchantPhone");

        UserPaymentOption userPaymentOption = new UserPaymentOption();
        userPaymentOption.setUserPaymentOptionId("");

        PayoutRequest payoutRequest = PayoutRequest.builder()
                .addMerchantInfo(merchantInfo)
                .addUserTokenId(userTokenId)
                .addClientRequestId(clientRequestId)
                .addClientUniqueId(clientUniqueId)
                .addAmountAndCurrency(amount, currency)
                .addDynamicDescriptor(dynamicDescriptor)
                .addUserPaymentOption(userPaymentOption)
                .addComment(comment)
                .build();

        SafechargeRequestExecutor requestExecutor = SafechargeRequestExecutor.getInstance();
        try {
            SafechargeResponse response = requestExecutor.execute(payoutRequest);
        } catch (SafechargeException e) {
            e.printStackTrace();
        }
    }
}

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
using System;
using Safecharge.Model;
using Safecharge.Model.Payment;
using Safecharge.Response;
using Safecharge.Utils;
using Safecharge.Utils.Enum;

namespace Safecharge.Sample
{
    class Sample
    {
        static void Main()
        {
            var safecharge = new Safecharge(
                "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_KEY_PROVIDED_BY_SAFECHARGE",
                ApiConstants.IntegrationHost,
                HashAlgorithmType.SHA256);

            var response = safecharge.Payout(
                "487106",
                "12345",
                "9.0",
                "EUR",
                new UserPaymentOption { UserPaymentOptionId = "<paymentResponse.PaymentOption.UserPaymentOptionId>" },
                dynamicDescriptor: new DynamicDescriptor { MerchantName = "merchantName", MerchantPhone = "merchantPhone" },
                merchantDetails: new MerchantDetails { CustomField1 = "" },
                comment: "some comment");

            PrintResponseResult(response);
        }

        private static void PrintResponseResult(PayoutResponse response)
        {
            if (response.Status == ResponseStatus.Error)
            {
                Console.WriteLine("Reason: " + response.Reason);
            }
            else
            {
                Console.WriteLine("Status: " + response.Status);
                Console.WriteLine("Session token: " + response.SessionToken);
            }
        }
    }
}

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

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 ^Double(12) ~Required	The transaction amount.
currency ^String(3) ~Required	The three-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.
deviceDetails ^Class ~Only ipAddress	deviceType (String, 10) deviceName (String, 255) deviceOS (String, 255) browser (String, 255) ipAddress (String, 15, MANDATORY) Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (if device type cannot be recognized). The ipAddress parameter can be defined as mandatory or non-mandatory as needed by Nuvei’s Integration Support Team.
timeStamp ^String(14) ~Required	The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum ^String(256) ~Required	The UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId merchantSiteId clientRequestId amount currency timeStamp merchantSecretKey.
dynamicDescriptor ^Class ^Optional	merchantName(String, 25) merchantPhone(String, 13) merchantName - 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 - 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, not mandatory) … 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) This parameter determines where to return the DMN. Each parameter is limited for up to 1000 characters.
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.

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, not mandatory) … 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, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
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 is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
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

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

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
using System;
using Safecharge.Response;
using Safecharge.Utils;
using Safecharge.Utils.Enum;

namespace Safecharge.Sample
{
    class GetPaymentStatusSample
    {
        static void Main()
        {
            var safecharge = new Safecharge(
                "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_KEY_PROVIDED_BY_SAFECHARGE",
                ApiConstants.IntegrationHost,
                HashAlgorithmType.SHA256);

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

            PrintResponseResult(response);
        }

        private static void PrintResponseResult(GetPaymentStatusResponse response)
        {
            if (response.Status == ResponseStatus.Error)
            {
                Console.WriteLine("Reason: " + response.Reason);
            }
            else
            {
                Console.WriteLine("Status: " + response.Status);
                Console.WriteLine("Session token: " + response.SessionToken);
            }
        }
    }
}

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
{
    "gwExtendedErrorCode": 0,
    "gwErrorCode": 0,
    "gwErrorReason": "",
    "authCode": "1234567",
    "transactionType": "Sale",
    "transactionStatus": "APPROVED",
    "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:

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

@Links URLs

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

@Test https://ppp-test.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 the 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.
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 – is a regular payment request Auth – Performs an authorization only request. For details, see Auth and Settle.
userTokenId ^String(255)	The ID of the user in merchant 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.

/getCardDetails

Definition

1
2
3
4
5
6
7
8
{
   "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
   "merchantId":"2502136204546424962",
   "merchantSiteId":"126006",
   "clientRequestId":"1C6CT7V1L",
   "clientUniqueId":"695701003",
   "cardNumber":"4017356934955740"
}

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "brand": "VISA",
    "cardType": "",
    "cardProduct": "",
    "program": "",
    "visaDirectSupport": "0",
    "issuerCountry": "",
    "dccAllowed": false,
    "sessionToken": "963686d5-e44e-4f79-8742-425befc074e2",
    "clientUniqueId": "695701003",
    "internalRequestId": 205265898,
    "resultStatus": "SUCCESS",
    "merchantId": "479748173730597238",
    "merchantSiteId": "180083",
    "version": "1.0",
    "clientRequestId": "1C6CT7V1L"
}

This method can be used by the merchant to retrieve details about a card, such as card type and brand. In addition, the methods also returns the currency balance for the account, which might be important if you would like to perform currency conversion for this card.

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.
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.
cardNumber ^String(20) ~Required	cardNumber or bin must be populated.

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’s program; for example: Visa Platinum
visaDirectSupport ^String	Indicates whether Visa Direct is supported or not
dccAllowed ^String	Indicates whether this card is allowed for Dynamic Currency Conversion (DCC).
issuerCountry ^String(2)	Two-letter ISO code of the card issuer’s country.
currency ^String(3)	The three-letter ISO currency code.
internalRequestId ^String(20)	Nuvei internal unique request ID (used for reconciliation purposes).
version ^String	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

/initPayment

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
            "sessionToken": "e524e7c5-9855-4ce9-b0f9-1045f34fd526",
            "merchantId": "427583496191624621",
            "merchantSiteId": "142033",
            "userTokenId": "230811147",
            "clientUniqueId": "695701003",
            "amount": "500",
            "currency": "USD",
            "paymentOption": {
                            "card": {
                                            "cardNumber": "5111426646345761",
                                            "cardHolderName": "CL-BRW1",
                                            "expirationMonth": "12",
                                            "expirationYear": "25",
                                            "CVV": "217",
                                            "threeD": {
                                                            "methodNotificationUrl": "www.ThisIsAMethodNotificationURL.com"
                                            }
                            }
            },
            "billingAddress": {
                            "addressMatch": "Y",
                            "city": "Billing City",
                            "country": "DE",
                            "address": "340689 Billing Str.", 
                            "addressLine2": "Billing Address Line 2", 
                            "addressLine3": "Billing Address Line 3",
                            "zip": "48957",
                            "state": "",
                            "email": "mhsbg.xxnbx@udapl.rg",
                            "phone": "359888526527",
                            "cell": "359881526527",
                            "firstName": "Zilsijihrw",
                            "lastName": "Jgethizxrr",
                            "county": "TTT"
            },
            "deviceDetails": {
                            "ipAddress": "FE80::0202:B3FF:FE1E:8329"
            },
            "urlDetails": {
                            "notificationUrl": "http://srv-bsf-devppptrunk.gw-4u.com/ppptest/NotifyMerchantTest"
            },
            "customData": "merchant custom data",
            "webMasterId": "M9UOWGECHKD2",
            "timeStamp": "20190617110903",
            "checksum": "eaca71a67d972fd47b796a02cf02b51844c8adeba734c54fea504c69bb16a171"
}

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
const safecharge = require('safecharge');
safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>);
// env is optional can be 'test' or 'prod'. default value is 'prod'

safecharge.paymentService.initPayment({
    userTokenId            : "695701003",
    amount                 : "6.0",
    currency               : "GBP",
    relatedTransactionId   : "<transactionId>",
    authCode               : "<authCode>",
    descriptorMerchantName : "merchantName",
    descriptorMerchantPhone: "MerchantPhone",
    comment                : "Comment",
    paymentOption          : {
        card: {
            cardNumber     : '4012001037141112',
            cardHolderName : 'some name',
            expirationMonth: '01',
            expirationYear : '2020',
            CVV            : '122'
        }
    },
    billingAddress         : {
        firstName: "Jane",
        lastName : "Smith",
        address  : "Downing St",
        phone    : "472502457558",
        zip      : "123456",
        city     : "Blackpool",
        country  : "GB",
        state    : "",
        email    : "janeSmith@somedomain.com",
        county   : "Blackpool",
    }
}, function (initPErr, initPRes, reqData) {
    console.log(initPErr, initPRes);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
//Initialize SDK. See the Nuvei Java SDK at https://docs.safecharge.com/documentation/guides/server-sdks/nuvei-java-sdk/.
{
        // Parameters needed for initPayment call
        String userTokenId = "230811147";
        String clientUniqueId = "695701003";
        String clientRequestId = "111899";
        String currency = "EUR";
        String amount = "10";
        String customData = "merchant custom data";

        DeviceDetails deviceDetails = new DeviceDetails ();
        deviceDetails.setIpAddress("FE80::0202:B3FF:FE1E:8329");

        InitPaymentThreeD threeD = new InitPaymentThreeD();
        threeD.setMethodNotificationUrl("www.ThisIsAMethodNotificationURL.com");

        InitPaymentCard card = new InitPaymentCard ();
        card.setCardNumber ("4012001037141112");
        card.setCardHolderName ("Sara Brown");
        card.setCVV ("123");
        card.setExpirationMonth ("05");
        card.setExpirationYear ("22");
        card.setThreeD(threeD);

        InitPaymentPaymentOption initPaymentPaymentOption = new InitPaymentPaymentOption ();
        initPaymentPaymentOption.setCard (card);

        UserAddress billingAddress = new UserAddress ();
        billingAddress.setAddress ("Wohlstrasse");
        billingAddress.setCountry ("DE");
        billingAddress.setCity ("Berlin");
        billingAddress.setZip("48957");
        billingAddress.setFirstName("First Name");
        billingAddress.setLastName("Last Name");

        UrlDetails urlDetails = new UrlDetails();
        urlDetails.setNotificationUrl("http://srv-bsf-devppptrunk.gw-4u.com/ppptest/NotifyMerchantTest");

        try {
            Safecharge safecharge = new Safecharge();
            SafechargeResponse response = safecharge.initPayment (userTokenId, clientUniqueId, clientRequestId, currency,
                    amount, deviceDetails, initPaymentPaymentOption, urlDetails, customData, billingAddress);
        } catch (SafechargeException e) {
            e.printStackTrace();
        }
}

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
<?php
$safeCharge = new \SafeCharge\Api\SafeCharge([
    'environment'       => 'test',
    'merchantId'        => '<merchantId>',
    'merchantSiteId'    => '<merchantSiteId>',
    'merchantSecretKey' => '<merchantSecretKey>',
    'hashAlgorithm'     => '<hashAlgorithm>'
]);


//initPayment
$initPaymentResponse = $safeCharge->getPaymentService()->initPayment([
    'currency'       => 'EUR',
    'amount'         => '10',
    'userTokenId'    => 'emilg@safecharge.com',
    'paymentOption'  => [
        'card' => [
            'cardNumber'      => '4012001037141112',
            'cardHolderName'  => 'some name',
            'expirationMonth' => '01',
            'expirationYear'  => '2020',
            'CVV'             => '122',
        ]
    ],
    'billingAddress' => [
        "firstName" => "some first name",
        "lastName"  => "some last name",
        "address"   => "some street",
        "phone"     => "972502457558",
        "zip"       => "123456",
        "city"      => "some city",
        'country'   => "DE",
        "state"     => "",
        "email"     => "someemail@somedomain.com",
        "county"    => "Anchorage",
    ]
]);
?>

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
using System;
using Safecharge.Model.InitPayment;
using Safecharge.Model.Payment;
using Safecharge.Response;
using Safecharge.Utils;
using Safecharge.Utils.Enum;

namespace Safecharge.Sample
{
    class Sample
    {
        static void Main()
        {
            var safecharge = new Safecharge(
                "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_KEY_PROVIDED_BY_SAFECHARGE",
                ApiConstants.IntegrationHost,
                HashAlgorithmType.SHA256);

            var response = safecharge.InitPayment(
                "USD",
                "500",
                new InitPaymentPaymentOption
                {
                    Card = new InitPaymentCard
                    {
                        CardNumber = "5111426646345761",
                        CardHolderName = "CL-BRW1",
                        ExpirationMonth = "12",
                        ExpirationYear = "25",
                        CVV = "217",
                        ThreeD = new InitPaymentThreeD
                        {
                            MethodNotificationUrl = "www.ThisIsAMethodNotificationURL.com"
                        }
                    }
                },
                userTokenId: "230811147",
                billingAddress: new UserAddress
                {
                    FirstName = "Zilsijihrw",
                    LastName = "Jgethizxrr",
                    Address = "340689 Billing Str.",
                    Phone = "359888526527",
                    Zip = "48957",
                    City = "Billing City",
                    Country = "DE",
                    State = "",
                    Email = "mhsbg.xxnbx@udapl.rg",
                    County = "TTT"
                },
                deviceDetails: new DeviceDetails { IpAddress = "FE80::0202:B3FF:FE1E:8329" },
                urlDetails: new UrlDetails { NotificationUrl = "http://srv-bsf-devppptrunk.gw-4u.com/ppptest/NotifyMerchantTest" },
                customData: "merchant custom data");

            PrintResponseResult(response);
        }

        private static void PrintResponseResult(InitPaymentResponse response)
        {
            if (response.Status == ResponseStatus.Error)
            {
                Console.WriteLine("Reason: " + response.Reason);
            }
            else
            {
                Console.WriteLine("Status: " + response.Status);
                Console.WriteLine("Session token: " + response.SessionToken);
            }
        }
    }
}

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": "695701003",
    "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

Request 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 three-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.
deviceDetails ^Class ~Conditional	The device’s details (conditional per configuration). deviceType (string, 10) deviceName (string, 255) deviceOS (string, 255) browser (string, 255) ipAddres (string, 15) Support device types: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized).
paymentOption ^Class ~Required	Card payment information inside the card sub-class
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) cvv(string, 4) cardHolderName (string, 70) threeD class with the following field: threeD.methodNotificationUrl (string, 255) – The URL the ACS redirects to after performing the 3DS 2.0 fingerprinting. Refer to the 3D Secure 2.0 guide for details.
timeStamp ^String(14) ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss.
checksum ^Hexi-decimal ^String(256) ~Required	Hash (used hash algorithm SHA-256) of the values of the request parameters UTF-8 encoded, and concatenated in this order: merchantId merchantSiteId clientRequestId amount currency timestamp merchantSecretKey
userTokenId ^String(255) ^Optional	The ID of the user in merchant 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.
clientRequestId ^String(255) ^Optional	The ID of the API request in the merchant’s system.

Response 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 merchant 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 sub-class 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 two-digit value representing the expiration month. ccExpYear, String(4) – The four-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: 1 or 2. ver2supported 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). ver1supported Boolean (1) – Indicates if 3D Secure v1 is supported. 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)	Two-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.

MPI Methods

/authorize3d

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
{  
   "merchantSiteId":"142033",
   "merchantId":"427583496191624621",
   "sessionToken":"9e07802d-5126-4b02-b4b3-ef09dfb94219",
   "clientUniqueId":"uniqueIdCC",
   "currency":"EUR",
   "amount":"10",
   "paymentOption":{  
      "card":{  
         "cardNumber":"5115806139808464",
         "cardHolderName":"test name",
         "expirationMonth":"01",
         "expirationYear":"2020",
         "CVV":"122",
         "threeD":{  
            "acquirer":{  
               "bin":"411111",
               "merchantId":"123456789",
               "merchantName":"Merchant Inc."
            },
            "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",
            "challengePreference":"1",
            "notificationURL":"https://www.merchant.com/notificationURL/",
            "merchantUrl":"https://www.merchant-website.com",
            "platformType":"02",
            "deliveryEmail":"deliveryEmail@somedomain.com",
            "deliveryTimeFrame":"1",
            "giftCardAmount":"456",
            "giftCardCount":"10",
            "giftCardCurrency":"826",
            "preOrderDate":"20190219",
            "preOrderPurchaseInd":"2",
            "reorderItemsInd":"2",
            "shipIndicator":"1",
            "rebillExpiry":"",
            "rebillFrequency":"",
            "ChallengeWindowSize":"2"
         }
      }
   },
   "deviceDetails":{  
      "ipAddress":"127.0.0.1"
   },
   "shippingAddress":{  
      "address":"address",
      "city":"city",
      "country":"DE",
      "state":"",
      "zip":"1340"
   },
   "billingAddress":{  
      "address":"address",
      "city":"city",
      "country":"DE",
      "state":"",
      "zip":"1335"
   },
   "merchantDetails":{  
      "customField1":"customField1"
   }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
using System;
using Safecharge.Model;
using Safecharge.Model.Payment;
using Safecharge.Response.Payment;
using Safecharge.Utils;
using Safecharge.Utils.Enum;

namespace Safecharge.Sample
{
    class Sample
    {
        static void Main()
        {
            var safecharge = new Safecharge(
                "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_KEY_PROVIDED_BY_SAFECHARGE",
                ApiConstants.IntegrationHost,
                HashAlgorithmType.SHA256);

            var response = safecharge.Authorize3d(
                "EUR",
                "10",
                new PaymentOption
                {
                    Card = new Card
                    {
                        CardNumber = "5115806139808464",
                        CardHolderName = "test name",
                        ExpirationMonth = "01",
                        ExpirationYear = "20",
                        CVV = "122",
                        ThreeD = new ThreeD
                        {
                            Acquirer = new Acquirer { Bin = "411111", MerchantId = "123456789", MerchantName = "Merchant Inc." },
                            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 = "<initPaymentResponse.PaymentOption.Card.ThreeD.Version>",
                            V2AdditionalParams = new V2AdditionalParams
                            {
                                ChallengePreference = "1",
                                DeliveryEmail = "deliveryEmail@somedomain.com",
                                DeliveryTimeFrame = "1",
                                GiftCardAmount = "456",
                                GiftCardCount = "10",
                                GiftCardCurrency = "826",
                                PreOrderDate = "20190219",
                                PreOrderPurchaseInd = "2",
                                ReorderItemsInd = "2",
                                ShipIndicator = "1",
                                RebillExpiry = "",
                                RebillFrequency = "",
                                ChallengeWindowSize = "2"
                            },
                            NotificationURL = "https://www.merchant.com/notificationURL/",
                            MerchantURL = "https://www.merchant-website.com",
                            PlatformType = "02"
                        }
                    }
                },
                "<initPaymentResponse.TransactionId>",
                clientUniqueId: "uniqueIdCC",
                deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" },
                shippingAddress: new UserAddress
                {
                    Address = "address",
                    City = "city",
                    Country = "DE",
                    State = "",
                    Zip = "1340",
                },
                billingAddress: new UserAddress
                {
                    Address = "address",
                    City = "city",
                    Country = "DE",
                    State = "",
                    Zip = "1335",
                },
                merchantDetails: new MerchantDetails { CustomField1 = "customField1" });

            PrintResponseResult(response);
        }

        private static void PrintResponseResult(Authorize3dResponse response)
        {
            if (response.Status == ResponseStatus.Error)
            {
                Console.WriteLine("Reason: " + response.Reason);
            }
            else
            {
                Console.WriteLine("Status: " + response.Status);
                Console.WriteLine("Session token: " + response.SessionToken);
            }
        }
    }
}

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:

• For a Frictionless 3D Secure response, it never proceeds to perform a payment. It just returns that the Challenge is not mandated (and does not provide acUrl under the threeD class).
• There are several input fields that have to be added to the request.
  

@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. See /getSessionToken for details.
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 UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId merchantSiteId clientRequestId amount currency timeStamp merchantSecretKey View hashing calculation for details.
currency ^String(3) ~Required	The three-letter ISO currency code.
amount ^Double(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, alternativePaymentMethod, 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 the threeD (in) section for details. -or- alternativePaymentMethod class – Contains the relevant field required for the specific 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 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.
deviceDetails ^Class ~Only ipAddress	deviceType (String, 10) deviceName (String, 255) deviceOS (String, 255) browser (String, 255) ipAddress (String, 15, MANDATORY) Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (if device type cannot be recognized). The ipAddress parameter can be defined as mandatory or non-mandatory as needed by Nuvei’s Integration Support Team.
billingAddress ^Class ~Only country	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. firstName (String, 30) lastName (String, 40) address (String, 60) address2 (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (two-letter ISO country code)(String, 2, MANDATORY), must be entered in Uppercase state(String, 2) - Two-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 mandatory or non-mandatory as needed by Nuvei’s Integration Support Team.
subMerchant ^Class ~Conditional	countryCode (String,2) – The payment facilitator’s sub-merchant’s two-letter ISO country code. city (String, 20) – The payment facilitator’s sub-merchant’s city name. id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
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.
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.
userTokenId ^String(255) ^Optional	This field 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.
userDetails ^Class ^Optional	firstName (String, 30, not mandatory) lastName (String, 40, not mandatory) address (String, 60, not mandatory) phone (String, 18, not mandatory) zip (String, 10, not mandatory) city (String, 30, not mandatory) country (two-letter ISO country code)(String, 2, not mandatory) state(String, 2, not mandatory) - Two-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100, not mandatory) county (String, 255, not mandatory) language (String, 2, not mandatory) – 2-letter ISO language code. dateOfBirth (String, 10, not mandatory) – 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 (two-letter ISO country code)(String, 2) state(String, 2) - Two-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, not mandatory) … 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)
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.
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.

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 merchant 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 the threeD (out) section 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, not mandatory) … 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 – is a regular payment request Auth – Performs an authorization only request. For details, see Auth and Settle.
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
   "merchantSiteId":"142033",
   "merchantId":"427583496191624621",
   "sessionToken":" 9e07802d-5126-4b02-b4b3-ef09dfb94219",
   "relatedTransactionId":"2110000000000644998",
   "currency":"USD",
   "amount":"0.1",
   "paymentOption":{
      "card":{
         "cardNumber":"5413330056003511",
         "cardHolderName":"john Smith",
         "expirationMonth":"12",
         "expirationYear":"25",
         "CVV":"123"
      }
   },
   "billingAddress":{
      "country":"DE"
   }
}

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
using System;
using Safecharge.Response;
using Safecharge.Utils;
using Safecharge.Utils.Enum;

namespace Safecharge.Sample
{
    class Sample
    {
        static void Main()
        {
            var safecharge = new Safecharge(
                "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_KEY_PROVIDED_BY_SAFECHARGE",
                ApiConstants.IntegrationHost,
                HashAlgorithmType.SHA256);

            var response = safecharge.Verify3d(
                "USD",
                "0.1",
                new Verify3dPaymentOption
                {
                    Card = new Verify3dCard
                    {
                        CardNumber = "5413330056003511",
                        CardHolderName = "john Smith",
                        ExpirationMonth = "12",
                        ExpirationYear = "25",
                        CVV = "123"
                    }
                },
                "<relatedTransactionId>",
                billingAddress: new UserAddress { Country = "DE" });

            PrintResponseResult(response);
        }

        private static void PrintResponseResult(Verify3dResponse response)
        {
            if (response.Status == ResponseStatus.Error)
            {
                Console.WriteLine("Reason: " + response.Reason);
            }
            else
            {
                Console.WriteLine("Status: " + response.Status);
                Console.WriteLine("Session token: " + response.SessionToken);
            }
        }
    }
}

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 three-letter ISO currency code.
amount ^Double(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, alternativePaymentMethod, 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- alternativePaymentMethod class – Contains the relevant field required for the specific 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 a previous use.
relatedTransactionId ^String(19) ~Required	The transaction ID of the of the call to /authorize3d.
billingAddress ^Class ~Only country	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. firstName (String, 30) lastName (String, 40) address (String, 60) address2 (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (two-letter ISO country code)(String, 2, MANDATORY), must be entered in Uppercase state(String, 2) - Two-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 mandatory or non-mandatory as needed by Nuvei’s Integration Support Team.
subMerchant ^Class ~Conditional	countryCode (String,2) – The payment facilitator’s sub-merchant’s two-letter ISO country code. city (String, 20) – The payment facilitator’s sub-merchant’s city name. id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.

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 merchant 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 about the payment method. This can be one of two options: card – Representing credit/debit card. -or- alternativePaymentMethod – Representing 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, not mandatory) … 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 – is a regular payment request Auth – Performs an authorization only request. For details, see Auth and Settle.
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:

• The paResponse field – This field is used for the second call to the /payment (or /authorize3d) following the 3D Secure challenge/redirection and only in case of version 3D 1.x secure handling. This the PaRes output returned form the Issuer.
• External MPI – If you use an external API provider to perform the 3D Secure independently from Nuvei, you can use the following set of fields to process with us, based on the output you received from you other MPI provider:
  • isExternalMpi set to true
  • eci received from the MPI
  • cavv received from the MPI
  • xid received from the MPI (optional)

Additional Class Parameters

Parameter	Description
notificationURL ^String ~3D 2.0	The notification URL for redirecting the browser after the challenge completion, which receives the CRes message.
merchantURL ^String ~3D 2.0	The merchant website fully qualified URL.
version ^String ~3D 2.0	The number of the 3D Secure version used, as indicated by the value returned from /initpayment(API)
methodCompletionInd ^String ~3D 2.0	Indicates whether the 3DS v2.0 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 ~3D 2.0	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 1.0 authentication was performed.
externalMpi ^class ~External MPI	Eci (String,2) – The Electronic Commerce Indicator as received from the MPI Cavv(String50) – The card authentication verification value as received from the MPI. threeDProtocolVersion (String, 2, MANDATORY) – Specifies the 3D Secure version (1 or 2) Xid (string, 50) – The transaction ID received from the MPI for 3D v1. dsTransID (string, 36) – The transaction ID received from the MPI for 3D v2. Mandatory for 3D v2; do not send at all in 3D v1. You can also use challengePreference and externalRiskScore to increase the chances for 3DSv2 exemption. For details, please scroll down and view the descriptions of these fields.
browserDetails ^Class ~3D 2.0	acceptHeader (string) - Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser. Value accepted: If the total length of the accept header sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion. ip (string) - 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) - Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property. Values accepted: • Y=TRUE • N=FALSE javaScriptEnabled (string) - Determines whether the browser is JavaScript enabled (from navigator.javaEnabled property). Values accepted: • Y=TRUE • N=FALSE language (string) - Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property. colorDepth (string) - 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) - Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property. screenWidth (string) - Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property. timeZone (string) - Time difference between UTC time and the Cardholder browser local time, in minutes. Value accepted: Value is returned from the getTimezoneOffset() method. userAgent (string) - 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 3DS Server truncates the excess portion.
v2AdditionalParams ^Class ~3D 2.0	For the list of parameters in this class for the new version of 3D Secure, please see the v2AdditionalParams table below.
sdk ^Class ~3D 2.0 SDK	This class is mandatory for 3D Secure 2.0 for transactions originating from a mobile device. It contains the following 3D mobile relevant information: appSdkInterface – String(2) – Lists all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK. appSdkUIType – String(2) – Lists all UI types that the device supports for displaying specific challenge user interfaces within the SDK. appID – String(36) – SDK App ID - guid encData – String(64000) – SDK Encrypted Data ephemPubKey – String(256) – SDK Ephemeral Public Key (Qc) maxTimeout –String(2) – SDK Maximum Timeout referenceNumber – String(32) – SDK Reference Number transID – String(36) – SDK Transaction ID – guide
convertNonEnrolled ^String ^Optional	Set this field to automatically convert the request for payment in case of 3DS 1.0 failure to authenticate. The transaction in this case is non-3D Secure.
challengePreference ^String(2) ^Optional	If you wish to use our MPI and request an exemption, you can provide this field. This field can also be used in conjunction with the External MPI block. • 01 = No preference • 02 = No challenge requested • 03 = Challenge requested: 3DS Requestor Preference • 04 = Challenge requested: Mandate • 05–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) • 80-99 = Reserved for DS use
externalRiskScore ^String(3)	To increase your chances for exemption, you can provide the third-party risk engine score you are using, specified in this field. This field can be used also in conjunction with the External MPI block. Valid values are 0–100 where 0 is lowest risk and 100 is highest risk

v2AdditionalParams

Parameter	Description
challengePreference ^String ^Optional	The 3DS challenge requestor indication. 01 – No preference 02 – No challenge requested 03 – Challenge requested: 3DS Requestor Preference 04 – Challenge requested: Mandate
deliveryEmail ^String ^Optional	For electronic delivery, the email address to which the merchandise was delivered.
deliveryTimeFrame ^String ^Optional	Indicates the merchandise delivery timeframe. 01 – Electronic Delivery 02 – Same day shipping 03 – Overnight shipping 04 – Two-day or more shipping
giftCardAmount ^String ^Optional	For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).
giftCardCount ^String ^Optional	For prepaid or gift card purchase, the total count of individual prepaid or gift cards/codes purchased.
giftCardCurrency ^String ^Optional	For prepaid or gift card purchase, the ISO 4217 three-letter currency code of the gift card.
preOrderDate ^String ^Optional	For a pre-ordered purchase, the expected date that the merchandise is available (YYYYMMDD).
preOrderPurchaseInd ^String ^Optional	Indicates whether Cardholder is placing an order for merchandise with a future availability or release date. 01 – Merchandise available 02 – Future availability
PreOrderItemsInd ^String ^Optional	Indicates whether the cardholder is reordering previously purchased merchandise. 01 – First time ordered 02 – Reordered
shipIndicator ^String ^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.)
rebillExpiry ^String ^Optional	Recurring Expiry - Required if isRebilling = 0 (format: YYYYMMDD)
rebillFrequency ^String ^Optional	Recurring Frequency - Required if isRebilling = 0 in number of days.
challengeWindowSize ^String ^Optional	The dimensions of the challenge window. 01 – 250 x 4000 02 – 390 x 4000 03 – 500 x 6000 04 – 600 x 4000 05 – Full screen

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

The output table is separate into 2 parts:

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

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 2.0 challenge required indication. Possible values: N – not required Y – required (only in case of 3D Secure 2.0)
cReq ^String	The Base64 encoded cReq relevant for the 3D Secure 2.0. acsUrl is also sent as a separate field (only in case of 3D Secure 2.0)
paRequest ^String	The 3D Secure request data for the card issuer/bank (only in case of 3D 1.0)
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 3DS authorization as received from the issuer.
threeDReason ^String	Reason description for a failed 3DS authorization as received from the issuer.
challengeCancelReasonId ^String	Reason ID for a cancelled 3DS authorization as received from the issuer.
ChallengeCancelReason ^String	Reason description for a cancelled 3DS 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	If a challenge is requested, this field provides the reason for it (click here for more details).

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	This is returned from banks and indicates the 3D Secure result. Possible ECI data values are: ECI = 5(VISA), 2(MC): The cardholder was successfully authenticated. ECI = 6(VISA), 1(MC): The issuer or cardholder does not participate in a 3D Secure program. ECI = 7: Payment authentication was not performed Note: In this method eci is returned in response only in case its value is 1 or 6 or 7.
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 2.0 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. The issuer can opt to provide information to cardholder. For example: “Additional authentication is needed for this transaction. Please contact [Issuer Name] at xxx-xxx-xxxx.” Returned on a second call to /payment or /verify3d following a challenge.

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: ApplePay for ApplePay.
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.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "isDynamic3D": "1",
    "dynamic3DMode":"",
    "isRebilling":"0",
    "isPartialApproval":"0",
    "currency": "EUR",
    "amount": "10",
    "amountDetails": {
        "totalShipping": "0",
        "totalHandling": "0",
        "totalDiscount": "0",
        "totalTax": "0"
    },
     "items": [{
        "name": "name",
        "price": "10",
        "quantity": "1"
    }],
    "deviceDetails": {
        "ipAddress": "93.146.254.172"
    },
    "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":""
    },
    "dynamicDescriptor": {
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "merchantDetails": {
        "customField1": ""
    },
    "cardData": {
        "cardNumber": "4111111111111111",
        "cardHolderName": "test name",
        "expirationMonth": "01",
        "expirationYear": "2020",
        "CVV":"",
        "ccTempToken": ""
    },
    "userPaymentOption":{
        "userPaymentOptionId":"1459503",
        "CVV":"234"
    },
    "relatedTransactionId": "8495798459",
    "urlDetails": {
        "notificationUrl": "http://notificationUrl.com"
    },
    "externalMpi": {
        "isExternalMpi":"0",
        "eci":"",
        "cavv":"",
        "xid":""
    },
    "storedCredentials": {
        "storedCredentialsMode":""
    },
    "productId":"",
    "customData":"",
    "externalTokenProvider": {
        "externalTokenProvider":"",
        "mobileToken":""
    },
    "webMasterId":"",
    "timeStamp": "20190118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}

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 three-letter ISO currency code.
amount ^Double(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 ~Required	deviceType(String, 10) deviceName(String, 255) deviceOS(String, 225) browser(String, 225) ipAddress(String, 15) Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN. ipAddress parameter can be defined as mandatory or non-mandatory as needed by Nuvei’s Integration Support Team.
billingAddress ^Class ~Required	firstName(String, 30) lastName(String, 40) address(String, 60) cell(String, 18) phone(String, 18) zip(String, 10) city(String, 30) country(two-letter ISO country code)(String, 2) state(String, 2) - Two-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 mandatory or non-mandatory as needed by Nuvei’s Integration Support Team. Note that the country parameter is always mandatory. 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 orders/payments methods request 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 orders/payments methods request 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 UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId merchantSiteId clientRequestId amount currency timeStamp merchantSecretKey.
userTokenId ^String(255) ^Optional	ID of the user in the merchant’s system. If userPaymentOption is sent in the request, then it is mandatory to send userTokenId in the request as well.
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 vales: 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(two-letter ISO country code)(String, 2) state(String, 2) - Two-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(two-letter ISO country code)(String, 2) state(String, 2) - Two-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) merchantPhone(String, 13) merchantName - 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 - 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, not mandatory) … 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 mandatory if the userPaymentOption (below) is not sent. CVV can be mandatory or non-mandatory 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.
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 mandatory if cardData (above) is not sent. CVV can be mandatory or non-mandatory per configuration.
addendums ^Class ^Optional	This block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type. For example, localPayment addendum includes: nationalId(String, 255) debitType(String, 255) firstInstallment(String, 255) periodicalInstallment(String, 255) numberOfInstallments(String, 255) Please note that the possible values for the debitType parameter are: 1 – Singular payment 2 – Instalments 3 – Special debit The nationalId parameter must be sent while processing by local banks in certain countries, for example: Israel, Latin America (LATAM). For more information, please contact Nuvei’s Integration Support Team. For example, airline addendum includes: 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) passengerDetails {passengerId(String), passportNumber(String), customerCode(String), frequentFlyerCode(String), title(String), firstName(String), lastName(String), middleName(String), dateOfBirth(String), phoneNumber(String)}, flightLegDetails {flightLegId(String), airlineCode(S, 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)} For cards, while working in Auth-Settle mode, the Auth is done using this API call and Settle is done in a separate clearing batch process. For more information and for required Nuvei configurations settings, please contact Nuvei’s Integration Support Team.
urlDetails ^Class ^Optional	notificationUrl(String, 1000) This parameter determines where to return the DMN. Each parameter is limited to up to 1000 characters.
externalMpi ^Class ^Optional	isExternaMpi(String, 1) eci(String, 2) cavv(String, 50) xid(String, 50) Allows the merchant to provide the 3D Secure authentication result as input. Possible values for isExternalMpi: 1 – External MPI is used (in this case need to send eci, cavv, xid values obtained from the external MPI). 0 – External MPI is not used. Note that eci is the Electronic Commerce Indicator (ECI) that indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant. Possible ECI data values are: ECI = 5(VISA), 2(MC): The cardholder was successfully authenticated ECI = 6(VISA), 1(MC): The issuer or cardholder does not participate in a 3D Secure program ECI = 7: Payment authentication was not performed cavv is the card holder authentication verification value xid is the transaction identification value. Note that if isExternalMpi=1 sent, then you must also send isDynamic3D=1 and dynamic3DMode=OFF.
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 mandatory 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 – “ApplePay”, 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.
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.

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, not mandatory) … 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, an error reason is returned in this parameter. (e.g. 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. (e.g. failure in checksum validation, timeout from processing engine, etc.)
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	isPartialApproval(String, True or False), amountInfo: requestedAmount(String), requestedCurrency(String), processedAmount(String), processedCurrency(String) These parameters are returned only in case “partial approval” feature was in use, per the relevant input parameter sent value.
eci ^String	This is returned from banks and indicates whether the attempted transaction passed as full 3D or failed. The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant. Possible ECI data values are: ECI = 5(VISA), 2(MC): the cardholder was successfully authenticated ECI = 6(VISA), 1(MC): the issuer or cardholder does not participate in a 3D Secure program ECI = 7: Payment authentication was not performed. Note that in this method, eci is returned in response only if its value is 1 or 6 or 7.
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

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
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "transactionType": "Auth",
    "isPartialApproval": "0",
    "currency": "EUR",
    "amount": "10",
    "amountDetails": {
        "totalShipping": "0",
        "totalHandling": "0",
        "totalDiscount": "0",
        "totalTax": "0"
    },
     "items": [{
        "name": "name",
        "price": "10",
        "quantity": "1"
    }],
    "deviceDetails": {
        "ipAddress": "93.146.254.172"
    },
    "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":""
    },
    "dynamicDescriptor": {
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "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"
}

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. It is required to provide the same sessionToken value sent to dynamic3D method that was called before.
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.
transactionType ^String(45) ~Required	The type of transaction: Sale or Auth. Sale – is a regular payment request Auth – Performs an authorization only request. For details, see Auth and Settle.
currency ^String(3) ~Required	The three-letter ISO currency code.
amount ^Double(12) ~Required	The transaction amount. This amount must be identical to the amount listed in the dynamic3D.
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.
deviceDetails ^Class ~Required	deviceType(String, 10) deviceName(String, 255) deviceOS(String, 255) browser(String, 255) ipAddress(String, 15) Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (if device type cannot be recognized). ipAddress parameter can be defined as mandatory or non-mandatory per need by Nuvei Integration Support Team.
billingAddress ^Class ~Required	firstName(String, 30) lastName(String, 40) address(String, 60) cell(String, 18) phone(String, 18) zip(String, 10) city(String, 30) country(two-letter ISO country code)(String, 2) state(String, 2) - Two-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 mandatory or non-mandatory per need by Nuvei Integration Support Team. Note that the country parameter is always mandatory. 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 orders/payments methods request 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 orders/payments methods request as a separate parameter, then the value from userDetails is used, but billingAddress is not saved in the UPO.
paResponse ^String ~Required	The payment authorization response returned by the card issuer/bank.
timeStamp ^String(14) ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum ^String(256) ~Required	The UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId merchantSiteId clientRequestId amount currency timeStamp merchantSecretKey.
orderId ^String(45) ~Required	The order ID provided by Nuvei. It is required to provide the orderId value returned by dynamic3D method that was called before.
userTokenId ^String(255) ^Optional	ID of the user in the merchant’s system. If userPaymentOption is sent in the request, then it is mandatory to send userTokenId in the request as well.
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 – Do 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(two-letter ISO country code)(String, 2) state(String, 2) - Two-letter ISO state code (for customers based in the US, Canada, and India only). email(String, 100) county(String, 255) language (String, 2, not mandatory) – 2-letter ISO language code. dateOfBirth (String, 10, not mandatory) – 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 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(two-letter ISO country code)(String, 2) state(String, 2) - Two-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 is required to send it using billingAddress parameter.
dynamicDescriptor ^Class ^Optional	merchantName(String, 25) merchantPhone(String, 13) merchantName - 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 - 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, not mandatory) … 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 block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type. For example, localPayment addendum includes: nationalId(String, 255) debitType(String, 255) firstInstallment(String, 255) periodicalInstallment(String, 255) numberOfInstallments(String, 255) Please note that the possible values for the debitType parameter are: 1 – Singular payment 2 – Instalments 3 – Special debit nationalId parameter is required to be sent while processing by local banks in certain countries, for example: Israel, Latin America (LATAM).For more information, please contact Nuvei’s Integration Support Team. For example, airline addendum includes: 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), passengerDetails {passengerId(String), passportNumber(String), customerCode(String), frequentFlyerCode(String), title(String), firstName(String), lastName(String), middleName(String), dateOfBirth(String), phoneNumber(String)}, flightLegDetails {flightLegId(String), airlineCode(S, 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)} For cards, while working in Auth-Settle mode, the Auth is done using this API call and settle is done in a separate clearing batch process. For more information and for required Nuvei configurations settings, please contact Nuvei’s Integration Support Team.
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 mandatory if the userPaymentOption (below) is not sent. CVV can be mandatory or non-mandatory per configuration. If CVV not required 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.
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 mandatory if the cardData (above) is not sent. CVV can be mandatory or non-mandatory per configuration.
urlDetails ^Class ^Optional	notificationUrl(String, 1000) This parameter determines where to return the DMN. Each parameter is limited for up to 1000 characters.
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 mandatory when 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 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.
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.

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.
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, not mandatory) … 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. (e.g. 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. (e.g. failure in checksum validation, timeout from processing engine, etc.)
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.
eci ^String	This is returned from banks and indicates whether the attempted transaction passed as full 3D or failed. The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant. Possible ECI data values are: ECI = 5(VISA), 2(MC): The cardholder was successfully authenticated ECI = 6(VISA), 1(MC): The issuer or cardholder does not participate in a 3D Secure program ECI = 7: 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.
externalToken ^Class	externalToken_blockedCard(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	isPartialApproval(String, True or False) amountInfo: requestedAmount(String), requestedCurrency(String), processedAmount(String), processedCurrency(String) These parameters are returned only in case “partial approval” feature was in use, per the relevant input parameter sent value.
cvv2Reply ^String	CVV2 (card verification value) 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 (address verification) response. The following values may be returned: 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 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: Sale or Auth. Sale – is a regular payment request Auth – Performs an authorization only request. For details, see Auth and Settle.
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.

/paymentCC

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "transactionType": "Auth",
    "isRebilling": "0",
    "isPartialApproval": "0",
    "currency": "EUR", 
    "amount": "10",
    "amountDetails": {
        "totalShipping": "0",
        "totalHandling": "0",
        "totalDiscount": "0",
        "totalTax": "0"
    },
    "items": [{
        "name": "name",
        "price": "10",
        "quantity": "1"
    }],
    "deviceDetails": {
        "ipAddress": "192.168.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":""
    },
    "dynamicDescriptor": {
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "merchantDetails": {
        "customField1": ""
    },
    "cardData": {
            "cardNumber": "5101080963349948",
            "cardHolderName": "test name",
            "expirationMonth": "01",
            "expirationYear": "2020",
            "CVV": "122"
    },
    "userPaymentOption":{
        "userPaymentOptionId":"",
        "CVV":""
    },
    "relatedTransactionId": "8495798459",
    "urlDetails": {
        "notificationUrl": "http://notificationUrl.com"
    },
    "externalMpi": {
        "isExternalMpi":"0",
        "eci":"",
        "cavv":"",
        "xid":""
    },
    "storedCredentials": {
        "storedCredentialsMode":""
    },
    "productId":"",
    "customData":"",
    "externalTokenProvider": {
        "externalTokenProvider":"",
        "mobileToken":""
    },
    "webMasterId":"",
    "timeStamp": "20190118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}

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/paymentCC.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
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
{
    "sessionToken":"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",
    "version": "1.0",
    "userPaymentOptionId": "12442",
    "externalTransactionId": "2345346589",
    "transactionId": "1000030724",
    "authCode": "08AF6E",
    "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":""
            }]
        }
    },
    "acquirerId": "19",
    "bin": "400002",
    "last4Digits": "2535",
    "ccCardNumber": "4****2535",
    "ccExpMonth": "10",
    "ccExpYear": "22"
}

This method is used for performing credit card payments, using a card number, credit card, temporary token or user payment option.

@Links URLs

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

@Test https://ppp-test.safecharge.com/ppp/api/v1/paymentCC.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.
transactionType ^String(45) ~Required	The type of transaction: Sale or Auth. Sale – is a regular payment request Auth – Performs an authorization only request. For details, see Auth and Settle.
currency ^String(3) ~Required	The three-letter ISO currency code.
amount ^Double(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.
deviceDetails ^Class ~Required	deviceType(String, 10) deviceName(String, 255) deviceOS(String, 255) browser(String, 255) ipAddress(String, 15) Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (if device type cannot be recognized). ipAddress parameter can be defined as mandatory or non-mandatory per need by Nuvei Integration Support Team.
billingAddress ^Class ~Required	firstName(String, 30) lastName(String, 40) address(String, 60) cell(String, 18) phone(String, 18) zip(String, 10) city(String, 30) country(two-letter ISO country code)(String, 2) state(String, 2) - Two-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 mandatory or non-mandatory per need by Nuvei Integration Support Team. Note that the country parameter is always mandatory. 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 orders/payments methods request 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 orders/payments methods request as a separate parameter, then the value from userDetails is used, but billingAddress is not saved in the UPO.
relatedTransactionId ^String(19) ~Required	The ID of the original transaction. It is required if a 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 UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId merchantSiteId clientRequestId amount currency timeStamp merchantSecretKey.
userTokenId ^String(255) ^Optional	ID of the user in the merchant’s system. If userPaymentOption is sent in the request, then it is mandatory to send userTokenId in the request as well.
isRebilling ^Integer(2) ^Optional	When performing recurring/rebilling, use this field to indicate the recurring step with the following vales: 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(two-letter ISO country code)(String, 2) state(String, 2) - Two-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 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(two-letter ISO country code)(String, 2) state(String, 2) - Two-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 the request (name/address/email etc.), it must be sent using the billingAddress parameter.
dynamicDescriptor ^Class ^Optional	merchantName(String, 25) merchantPhone(String, 13) merchantName - 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 - 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, not mandatory) … 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 mandatory if the userPaymentOption (below) is not sent. CVV can be mandatory or non-mandatory per configuration. If CVV not required 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.
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 mandatory if cardData (above) is not sent. CVV can be mandatory or non-mandatory per configuration.
addendums ^Class ^Optional	This block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type. For example, localPayment addendum includes: nationalId(String, 255) debitType(String, 255) firstInstallment(String, 255) periodicalInstallment(String, 255) numberOfInstallments(String, 255) Please note that the possible values for the debitType parameter are: 1 – Singular payment 2 – Instalments 3 – Special debit The nationalId parameter must be sent while processing by local banks in certain countries, for example: Israel, Latin America (LATAM). For more information, please contact Nuvei’s Integration Support Team. For example, cardPresentPointOfSale addendum includes: 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) Card Present/Point Of Sale transactions are when an employee and the customer are present in the same physical location. The card data can be collected by a card reader through various means such as a magnetic strip or chip (manual entry is also possible). The card reader device reads the magnetic stripe on the back of the card or chip and the reader or your application connected to the reader submits the encoded information to your terminal management server that passes the information to the API. Following Nuvei’s response, when approved, the merchant can print a receipt for the customer. The following are the possible types of Card Present/Point Of Sale physical ways for initiation: Available for immediate merchant integration: Manual (key-entered): Card data was not obtained via the chip or magnetic stripe on the Card, for example, when the transaction is a Mail/Phone Order Transaction, Electronic Commerce Transaction, Recurring Transaction, voice authorized, or when the Chip or magnet stripe on the Card cannot be read. Represented by posEntryMode=1. Magnetic Stripe (swiped): Card data was obtained via the magnetic stripe on the card via swipe. Represented by posEntryMode=2. Will require merchant implementing this API which supports card present in its hardware terminals: ICC Read (chip): Card data was obtained via chip on the card, but does not include PIN entry data by the customer. Represented by posEntryMode=3. Contactless ICC: Card data was obtained via chip on the card that was obtained through a contactless device-read. Represented by posEntryMode=5. Contactless magstripe: Card data was obtained via equivalent track 2 data in ICC block on the Card, originated in contactless device-read. Represented by posEntryMode=6. Currently not supported by Nuvei: ICC Read (chip) + PIN: Card data was obtained via chip on the card, and includes PIN entry data by the customer. Note that for Card Present/Point Of Sale processing, it is mandatory to send the channel parameter with a value of 3. Note that an EMV chip is a contactless card where the chip embedded into the card or smartphone and is placed on or near the terminal. The data collected from the chip must be encoded in a TLV (tag-length-value) format. After a merchant has encoded the data, need to pass it to Nuvei as the value of the parameter posIcc which is a variable length parameter (LLLVAR). Below is a list of the mandatory tags: 9F26 (mandatory): Application cryptogram. This field contains the cryptogram used while authenticating the transaction. This data field contains an Authorization Request Cryptogram (ARQC), transaction certificate (TC) or an application authentication Cryptogram (AAC). In general, an ARQC means that the card determined that the transaction should be sent online, a TC indicates that the transaction was approved offline, and an AAC indicates that the transaction was declined offline. Example: E57BA2A13A84AA19 9F27 (mandatory for MasterCard transactions (authorization + settlement)): Cryptogram Information. This field indicates the type of cryptogram and the actions to be performed by the terminal. Example: 80 9F10 (mandatory): Issuer Application Data. This field contains application data transmitted from the chip to the issuer and is updated by the issuer in the response message. Card Verification Result (CVR) Example: 06010A03A06002 9F37 (mandatory): Unpredictable Number. This field contains an unpredictable number value generated by the POS terminal that is to be used as input to the application cryptogram algorithm. Example: DA00A010 9F36 (mandatory for Visa Mandatory for MC authorization): Application Transaction Counter. This field contains a counter maintained by the application in the ICC (incrementing the ATC is managed by the ICC) Example: 0B0E 95 (mandatory): Terminal Verification Relts (TVR). The TVR is a series of bits set by the terminal reading an EMV card, based on logical tests (for example has the card expired). This data object is used in the terminal’s decision whether to accept, decline or go online for a payment transaction. Example: 0000008000 9A (mandatory): Transaction Date. This field contains the local date that the transaction was performed. Example: 151102 9C (mandatory): Transaction Type. This field Indicates the type of transaction, represented by the values of the first two digits of Processing Code as defined by the payment system. Example: 00 9F02 (mandatory): Amount Authorized. This field contains the authorized amount of the transaction (excluding adjustments). Example: 000000001500 5F2A (mandatory): Transaction Currency Code. This field contains the currency code of the transaction according to ISO 4217. Example: 0978 82 (mandatory): Application Interchange Profile. This field indicates the capabilities of the card to support specific functions in the application. Example: 3C00 9F1A (mandatory): Terminal Country Code. This field indicates the country of the terminal, represented according to ISO 3166. Example: 0376 9F34 (mandatory for MC authorization only): Cardholder Verification Method (CVM) Results. This field indicates the results of the last CVM performed. Example: 1F0002 9F33 (mandatory for Visa): Terminal Capabilities. This field indicates the card data input, CVM, and security capabilities of the Terminal. Example: 6008C8 84 (mandatory for MasterCard): Dedicated File. For more information and for required Nuvei configurations settings, please contact Nuvei’s Integration Support Team. For example, airline addendum includes: 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) passengerDetails {passengerId(String), passportNumber(String), customerCode(String), frequentFlyerCode(String), title(String), firstName(String), lastName(String), middleName(String), dateOfBirth(String), phoneNumber(String)}, flightLegDetails {flightLegId(String), airlineCode(S, 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)} For cards, while working in Auth-Settle mode, the Auth is done using this API call and Settle is done in a separate clearing batch process. For more information and for required Nuvei configurations settings, please contact Nuvei’s Integration Support Team.
urlDetails ^Class ^Optional	notificationUrl(String, 1000) This parameter determines where to return the DMN. Each parameter is limited for up to 1000 characters.
externalMpi ^Class ^Optional	isExternaMpi(String, 1) eci(String, 2) cavv(String, 50) xid(String, 50) Allow the merchant to provide the 3D Secure authentication result as input. Possible values for isExternalMpi: 1 – External MPI is used (in this case need to send eci, cavv, xid values obtained from the external MPI). 0 – External MPI is not used. Note that eci is the Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant. Possible ECI data values are: ECI = 5(VISA), 2(MC): The cardholder was successfully authenticated ECI = 6(VISA), 1(MC): The issuer or cardholder does not participate in a 3D Secure program ECI = 7: Payment authentication was not performed cavv is the card holder authentication verification value xid is 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 mandatory when 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 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 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.
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 – “ApplePay”, mobileToken – The token received from Apple during the following: 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.
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.

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)	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.
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, not mandatory) … 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. (e.g. 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. (e.g. failure in checksum validation, timeout from processing engine, etc.)
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.
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	isPartialApproval(String, True or False) amountInfo: requestedAmount(String), requestedCurrency(String), processedAmount(String), processedCurrency(String) These parameters are returned only in case “partial approval” feature was in use, per the relevant input parameter sent value.
cvv2Reply ^String	CVV2 (card verification value) 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 (address verification) response. The following values may be returned: 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 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: Sale or Auth. Sale – is a regular payment request Auth – Performs an authorization only request. For details, see Auth and Settle.
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.
bin ^String(6)	This parameter returns the BIN number of the card process. Note: BINs are the first 6 numbers of the card, which represent the card issuer.
last4Digits ^String(4)	This parameter returns the last four digits of the card.
ccCardNumber ^String(20)	This parameter returns a masked version of the card, e.g. 4****2535.
ccExpMonth ^String(2)	This parameter returns the card expiration month (MM).
ccExpYear ^String(2)	This parameter returns the card expiration year (YY).
acquirerId ^String(2)	This is an ID representing the acquirer that processed the transaction.
orderId ^String(20)	The order ID provided by Nuvei.
clientRequestId ^String(20)	ID of the API request in the merchant’s system.

/paymentAPM

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "currency": "EUR",
    "amount": "10",
    "amountDetails": {
        "totalShipping": "0",
        "totalHandling": "0",
        "totalDiscount": "0",
        "totalTax": "0"
    },
     "items": [{
        "name": "name",
        "price": "10",
        "quantity": "1"
    }],
    "deviceDetails": {
        "ipAddress": "ipAddress"
    },
    "userDetails": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "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":""
    },
    "dynamicDescriptor": {
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "merchantDetails": {
        "customField1": ""
    },
    "paymentMethod": "apmgw_expresscheckout",
    "userAccountDetails": {
        "email": "user@mail.com"
    },
    "userPaymentOption":{
        "userPaymentOptionId":""
    },
    "urlDetails": {
        "successUrl": "",
        "failureUrl": "",
        "pendingUrl": "",
        "notificationUrl": ""
    },
    "subMethodDetails": {
        "subMethod":"",
        "subMethodField1":"",
        "subMethodField2":""
    },
    "customData":"",
    "webMasterId":"",
    "timeStamp": "20190118191845",
    "checksum": "31010a1101b653fa187bbef2cdd7d6441d6f681bf198efa2e8749cae6d77ca80"
}

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/paymentAPM.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
{
    "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": "", 
    "paymentMethodErrorCode": "0",
    "paymentMethodErrorReason": "",
    "gwErrorCode": "0",
    "gwErrorReason": "",
    "gwExtendedErrorCode": "0",
    "version": "1.0",
    "userPaymentOptionId": "12442",
    "externalTransactionId": "2345346589",
    "transactionId": "1000030724",
    "authCode": "08AF6E",
    "redirectURL": "www.apmurl.com"
}

Performs payments using an alternative payment method, in direct or redirect flow.

The /paymentAPM transaction is implemented in 4 main stages:
1. Ensuring that Nuvei is integrated to the desired APM.

2. The /paymentAPM method call.
3. The required merchant actions (for APMs who work redirect).

Following a positive response from the /paymentAPM method, per output parameter transactionStatus returned value, the merchant is redirected to the APM’s payment page (using redirectURL) to log in and confirm the billing information.

4. The APM required actions (for APMs who work redirect).

Once the credentials are typed and the payment is confirmed, the APM redirects (with some additional information) back to Nuvei’s gateway using a returnUrl from previous APM-Nuvei communications at 1st stage. Afterwards, the Nuvei gateway redirects to a successURL or to a failureURL.

@Links URLs

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

@Test https://ppp-test.safecharge.com/ppp/api/v1/paymentAPM.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 three-letter ISO currency code.
amount ^Double(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 ~Required	firstName(String, 30) (optional) lastName(String, 40) (optional) address(String, 60) (optional) cell(String, 18) (optional) phone(String, 18) (optional) zip(String, 10) (optional) city(String, 30) (optional) country(String, 2) (mandatory, two-letter ISO country code) state(String, 2, optional) - Two-letter ISO state code (for customers based in the US, Canada, and India only). email(String, 100) (mandatory) county(String, 255) (optional) The country parameter is mandatory and must contain the ISO code of a country that is supported by the APM according to the configuration by Nuvei. It is recommended that you use the getMerchantPaymentMethods to see what Nuvei configuration is to be received. Note that the email parameter is mandatory for most APMs. 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 orders/payments methods request 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 orders/payments methods request 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 mandatory 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 UTF-8 encoded SHA-256 hashed values of the request parameters, which are concatenated in the following order: merchantId merchantSiteId clientRequestId amount currency timeStamp merchantSecretKey.
userTokenId ^String(255) ^Optional	ID of the user in the merchant’s system. If userPaymentOption is sent in the request, then it is mandatory to send userTokenId in the request as well.
deviceDetails ^Class ^Optional	deviceType(String, 10) deviceName(String, 255) deviceOS(String, 255) browser(String, 255) ipAddress(String, 15) Supported device types: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (if device type cannot be recognized).
userDetails ^Class ^Optional	firstName(String, 30) lastName(String, 40) address(String, 60) phone(String, 18) zip(String, 10) city(String, 30) country(two-letter ISO country code)(String, 2) state(String, 2) - Two-letter ISO state code (for customers based in the US, Canada, and India only) email(String, 100) county(String, 255) language (String, 2, not mandatory) – 2-letter ISO language code. dateOfBirth (String, 10, not mandatory) – 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(two-letter ISO country code)(String, 2) state(String, 2) - Two-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) merchantPhone(String, 13) merchantName - 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 - 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, not mandatory) … 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 block contains an industry specific addendum. The addendum fields that appear are based on the specific addendum type. For example, localPayment addendum includes: nationalId debitType firstInstallment periodicalInstallment numberOfInstallments Please note that the possible values for the debitType parameter are: 1 – Singular payment 2 – Instalments 3 – Special debit The nationalId parameter must be sent while processing by local banks in certain countries, for example: Israel, Latin America (LATAM). For more information, please contact Nuvei’s Integration Support Team.
userAccountDetails ^Class ^Optional	Nuvei’s account identifiers of the payment methods. For more information, see APM Input Fields. This is mandatory 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 mandatory if the user wishes to pay with an existing UPO, and paymentMethod and userAccountDetails (above) were not sent. This is mandatory if paymentMethod (above) is not sent. One of these two parameters, paymentMethod or userPaymentOption, MUST be sent, but NEVER both.
urlDetails ^Class ^Optional	successUrl(String, 1000) failureUrl(String, 1000) pendingUrl(String, 1000) notificationUrl(String, 1000) Each parameter is limited for up to 1000 characters.
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.
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.

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, not mandatory) … 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. (e.g. failure in checksum validation, timeout from processing engine, etc.)
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 is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
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

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

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 mandatory or non-mandatory 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 ~Required	firstName(String, 30) lastName(String, 40) address(String, 60) cell(String, 18) phone(String, 18) zip(String, 10) city(String, 30) country(two-letter ISO country code)(String, 2) state(String, 2) - Two-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 mandatory or non-mandatory per need by Nuvei Integration Support Team. Note that, country parameter is always mandatory.
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, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
version ^Integer(10)	The current version of the request. The current version is 1.
ccTempToken ^String(36)	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)	Two-letter ISO code of the card issuer’s country.

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.

DMN Parameters Table

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

PARAMETER	DESCRIPTION
ppp_status ~Required	The status of the transaction. OK indicates that the transaction was approved. Pending occurs only for APM transactions when the final status is not immediately returned. FAIL indicates that the transaction was declined or there was an error.
PPP_TransactionID ~Required	A unique 64-bit number that identifies the Nuvei payment page transaction.
totalAmount ~Required	Total amount of items contained in the consumer’s purchase sent to the payment page. For merchants with the currency conversion feature enabled, the value of this parameter is the original total amount of items before the currency is converted.
currency ~Required	The currency, as selected by the consumer, that was sent. For merchants with currency conversion enabled, the value of this parameter is the original currency that was sent to the payment page.
responsechecksum ~Required	Deprecated checksum parameter.
advanceResponseChecksum ~Required	Advanced response checksum that ensures that the DMN callback is authentic.
merchant_site_id ~Required	The ID, provided by Nuvei that uniquely defines a particular merchant customization.
requestVersion ~Required	The version of the request.
message ~Required	A message from Nuvei about the transaction that has been completed.
payment_method ~Required	The payment method used for this transaction such as cc_card, dc_card, giro, etc. For a complete list, see the “API Name” column in the table in APM Input Fields.
merchant_id ~Required	The unique merchant ID supplied by Nuvei.
responseTimeStamp ~Required	The time set by Nuvei (in GMT) that the response is received from the Gateway in the format YYYY-MM-DD.HH:MM:SS for example: 2019-01-10.15.38.40
dynamicDescriptor ~Required	Dynamic descriptor passed to the Nuvei gateway for the current transaction.
item_name_X ~Required	The item name that was passed as the item_name_X parameter when making the initial request to the Public Payment Page. N/A is displayed if it is not a regular transaction.
item_amount_X ~Required	The item amount that was passed as the item_amount_X parameter initially when making the initial request. N/A is displayed if it is not a regular transaction.
client_ip ~Required	The IP address from which the client made the purchase.
convertedCurrency ^Optional	The final currency, as selected by the consumer, in which the transaction was processed through the acquirer bank. This feature is only available for merchants with currency conversion enabled.
convertedAmount ^Optional	The final amount of the transaction after the consumer converted the currency. This is the amount that was processed through the acquirer bank. This feature is only available for merchants with currency conversion enabled.
transactionID ^Optional	A unique 64-bit number that identifies the fiscal transaction in the Nuvei payment gateway. If no fiscal transaction actually occurred, then the ppp_status is FAIL and this parameter is left empty.
transactionType ^Optional	The type of transaction: Sale, Auth, Settle, Credit or Void. This service is only available upon request.
Status ^Optional	Status of the Nuvei Payment Gateway fiscal transaction: Approved, Success, Declined, Error, Pending. If no fiscal transaction actually occurred, the ppp_status is FAIL and this parameter is left empty.
userPaymentOptionId ^Optional	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.
externalTransactionId ^Optional	The transaction ID of the transaction when an external service is used.
userid ^Optional	The value that was initially passed as the userid parameter when making the HTTPS POST request to the payment page.
customData ^Optional	The ID that was initially passed as the customData parameter during the first request.
productId ^Optional	The ID that was initially passed as the productId parameter during the first request.
first_name ^Optional	First name of the user processing the transaction, if provided.
last_name ^Optional	Last name of the user processing the transaction, if provided.
email ^Optional	Email of the user processing the transaction, if provided.
externalEmail ^Optional	For PayPal only. The registered email address that is returned from the PayPal account.
cardCompany ^Optional	The name of the credit card company. Possible values: Visa, Amex, MasterCard, Diners, Discover, JCB, LaserCard, Maestro, Solo, and Switch. This value is provided when the value of the payment_method parameter is cc_card or dc_card.
customFieldX ^Optional	Fifteen custom fields that may be used by replacing X with 1 to 15. The customFieldX that was initially passed as the customFieldX parameter during the first request.
invoice_id ^Optional	The invoice_id that that was initially passed as the invoice_id parameter during the first request.
address1 ^Optional	Street address of the user processing the transaction, if supplied.
address2 ^Optional	Street address of the user processing the transaction, if supplied.
country ^Optional	The country of the user processing the transaction, if supplied.
state ^Optional	State of the user processing the transaction, if supplied.
city ^Optional	City of the user processing the transaction, if supplied.
zip ^Optional	Zip code of the user processing the transaction, if supplied.
phone1 ^Optional	Phone number of the user processing the transaction, if supplied.
phone2 ^Optional	Alternate phone number of the user processing the transaction, if supplied.
phone3 ^Optional	Alternate phone number of the user processing the transaction, if supplied.
nameOnCard ^Optional	Name on card used to process the transaction, if supplied.
cardNumber ^Optional	The masked card number used to process the transaction, if supplied. The parameter is mandatory if the payment method is credit card or debit card. If another payment method is used, an empty string is returned.
expMonth ^Optional	Expiration month of the card used to process the transaction, if supplied. The parameter is mandatory if the payment method is credit card or debit card. If another payment method is used, an empty string is returned.
expYear ^Optional	Expiration year of the card used to process the transaction, if supplied. The parameter is mandatory if the payment method is credit card or debit card. If another payment method is used, an empty string is returned.
token ^Optional	Tokens are strings of random digits, letters, and symbols characters that represent a single credit card number. When a merchant submits their consumers’ full credit card number, Nuvei provides a token in the response representing the consumers’ credit cards.
tokenId ^Optional	Deprecated ID of the token. Used in combination with the token.
orderTransactionId ^Optional	This value helps to identify individual transactions that are related to the same orderID.
3dflow ^Optional	This parameter indicates whether the transaction was processed through the 3D Secure flow or not. 0 – Not processed through 3D Secure. 1 – Processed through 3D Secure.
promoCode ^Optional	This value is a promotional code to apply discounts to products or services. Nuvei does not apply any discounts and only returns the value sent in the HTTPS request.
exErrCode ^Optional	Error indication. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the specific error.
errCode ^Optional	When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
errApmCode ^Optional	The error code returned from an APM.
errApmDescription ^Optional	The error description returned from an APM.
errScCode ^Optional	The error code returned by Nuvei for an APM transaction.
errScDescription ^Optional	The error description returned by Nuvei for an APM transaction.
authCode ^Optional	Authorization code, up to 35 characters, returned for each approved and pending transaction.
acquirerId ^Optional	The acquiring bank’s unique ID. The value 0 represents an invalid bank code.
bin ^Optional	The first six digits from the credit card number used for identifying the processing bank.
shippingCountry ^Optional	Shipping country of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingState ^Optional	Shipping state of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingCity ^Optional	Shipping city of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingAddress ^Optional	Shipping address of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingZip ^Optional	Shipping zip code of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingFirstName ^Optional	Shipping first name of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingLastName ^Optional	Shipping last name of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingPhone ^Optional	Shipping phone of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingCell ^Optional	Shipping mobile phone of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingMail ^Optional	Shipping email of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
total_discount ^Optional	The sum of the values in the item_discount_X parameter.
total_handling ^Optional	The handling parameter that the merchant passed to Nuvei in the HTTPS POST request.
total_shipping ^Optional	The shipping parameter that the merchant initially passed as the shipping parameter during the first request.
total_tax ^Optional	The total tax parameter that that the merchant initially passed during the first request.
buyButtonProductBundleId ^Optional	Contains the ID of the product bundle when the buy button payment is processed.
merchantLocale ^Optional	The language of the payment page. The possible values of this parameter are provided below: 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 Greek: el_GR 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 Norwegian: no_No 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 Vietnamese: vi_VL
unknownParameters ^Optional	When an unknown parameter is sent to Nuvei (i.e. a misspelled parameter), Nuvei returns this parameter whose value is the unknown parameter. This enables the merchant to identify and correct any erroneous parameters.
ID ^Optional	Hebrew ID.
buyButtonProductId ^Optional	Contains the ID of the product when the ‘buy button payment’ was processed.
Reason ^Optional	The reason that the Gateway request was returned if the transaction fails. See Gateway Response Codes and Gateway Filter Error Codes. N/A is returned if it is not a regular transaction.
ReasonCode ^Optional	The reason code that the Gateway request was returned if the transaction fails. See Gateway Response Codes and Gateway Filter Error Codes. N/A is returned if it is not a regular transaction.
item_number_X ^Optional	The item number that was passed as the item_number_X parameter when making the initial request. N/A is displayed if it is not a regular transaction.
item_quantity_X ^Optional	The item quantity that was passed as the item_quantity_X parameter initially when making the initial request. N/A is displayed if it is not a regular transaction.
item_discount_X ^Optional	The item discount that was passed as the item_discount_X parameter initially when making the initial request. N/A is displayed if it is not a regular transaction.
item_handling_X ^Optional	The item handling that was passed as the item_handling_X parameter initially when making the initial request. N/A is displayed if it is not a regular transaction.
item_shipping_X ^Optional	The item shipping that was passed as the item_shipping_X parameter initially when making the initial request. N/A is displayed if it is not a regular transaction.
appliedPromotions ^Optional	Indicates that the purchase was completed using a promotion or coupon. This parameter contacts all successfully applied promotion codes. If more than one promotion was used, the promotion names are separated by a # character.
uniqueCC ^Optional	A unique value assigned to the credit card number.
user_token ^Optional	This parameter shows if the payment page required existing customers to register for the specific transaction. When user_token=register, the payment page required the customer to register even if they are already registered in the system. The previously registered payment methods are deleted. When user_token=auto, the payment page checked the Nuvei database to determine if the customer was already registered.
user_token_id ^Optional	This is a unique identifier for each consumer generated by the merchant.
externalAccountID ^Optional	This is the consumer’s username or unique identifier provided by the APM. This value is not returned for all APMs.
APMReferenceID ^Optional	This is Nuvei’s reference identifier for each APM.
webMasterId ^Optional	The webMasterID passed in the request.
finalFraudDecision ^Optional	This parameter indicates the final fraud analysis decision made by Nuvei Risk Management. Possible values: Accept – The transaction is redirected for processing Reject – The transaction is rejected due to a Fraud Filter.
systemID ^Optional	The value of this parameter is a numeric identifier generated by Nuvei for the fraud analysis service/tool.
systemName ^Optional	The value of this parameter is an internal Nuvei name for the fraud analysis service/tool.
systemDecision ^Optional	The Risk decision. It may be one of the following predefined string values: None – No decision was rendered. Accept – Transaction is recommended for processing. Reject – Transaction is rejected due to a high probability of fraud. Review – Transaction should be manually reviewed before processing. Error – An error has occurred during the analysis and no decision is rendered.
rules ^Optional	This parameter lists all the rules that were activated by the transaction as part of Nuvei’s fraud checks. This parameter is only returned when the value of the SystemDecision parameter is Reject or Review. The format of the value of the Rules parameter is URL encoded. For example: rules=ID%3D1000000260%2CDescription%3DCC+is+changing+more+than+1+Email+Last+24+H+Review+general / In the URL encoded response: %2C represents & and separates the multiple rule values while %3D represents ’=’.
CVV2Reply ^Optional	CVV2 (card verification value) 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 ^Optional	The AVS (address verification) response. The following values may be returned: 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 Unavailable S – Not Supported R – Retry B – Not Authorized (declined) N – Both street address and zip code do not match.
cardType ^Optional	The type of card used in the transaction. Possible values: credit or debit.
upoRegistrationDate ^Optional	The date that the UPO was registered in the following format: YYYMMDDHHmmss
isPartialApproval ^Optional	Indicate if the transaction was requested for partial approval (1) or not (0).
requestedAmount ^Optional	For a partial approval transaction, represent the amount requested. It can be greater than the amount that was able to be processed (totalAmount).
partialApprovalStatus ^Optional	For a partial approval transaction, indicates the status of the approval. Possible values: PENDING, APPROVED, CANCELLED, AUTO_VOID
requestedCurrency ^Optional	For a partial approval transaction, represent the currency of the amount requested. It should be the same as the currency of the amount processed (currency).
isRebilling ^Integer(2) ^Optional	When performing recurring/rebilling, use this field to indicate the recurring step with the following vales: 0 – For the initiating recurring event (first recurring transaction). 1 – For all subsequent recurring transactions.
autoSettleMode ^Optional	Automatic settle feature available for merchants working in an Auth-Settle mode. Possible values: TIME – Automatic settle done after a specific time frame after Auth RISK – Automatic settle done per “Accept” risk decision RISK-TIME – Combination of both time and risk options described before. If automatic settle not performed, then parameter returns empty.
isExternalMpi ^Optional	Allows the merchant to provide the 3D Secure authentication result in the request to Nuvei. Possible values: 1 – External MPI is used. 0 – External MPI is not used.
cavv ^Optional	The card holder authentication verification value. Relevant for external MPI.
xid ^Optional	The transaction identification value. Relevant for external MPI.
eci ^Optional	The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant. Possible ECI data values are: ECI = 5(VISA), 2(MC): The cardholder was successfully authenticated ECI = 6(VISA), 1(MC): The issuer or cardholder does not participate in a 3D Secure program. ECI = 7: Payment authentication was not performed.
type ^Optional	The type of the notification. Possible values: DEPOSIT WITHDRAWAL KYC DOCUP KYC and DOCUP are only relevant for merchants implementing Nuvei’s KYC solutions.
3DauthenticationType ^Optional	Presents whether transaction has been processed via challenge or frictionless authentication flow. The parameter should be calculated based on the combination of acsChallengeMandated/Result parameters in Auth3D response to Cashier by GW. Values: Challenge or Frictionless If the parameter is empty, the parameter is not included in the DMN. This field is relevant only for a 3DS 2.0 deposit flow.
3Dauthentication ^Optional	Result: ThreeDSAuthenticator -> result ->authenticationStatus. For frictionless, result value in Auth3d response to Cashier. For a challenge, send transStatus value from CRes. If the parameter is empty, the parameter is not included in the DMN. This field is relevant only for a 3DS 2.0 deposit flow.
3Dreason ^Optional	From final GW response to Cashier’s Sale TRX. If the parameter is empty, the parameter is not included in the DMN. This field is relevant only for a 3DS 2.0 deposit flow.
3DwhiteListStatus ^Optional	From final GW response to Cashier’s Sale TRX. If the parameter is empty, the parameter is not included in the DMN. This field is relevant only for a 3DS 2.0 deposit flow.
relatedTransactionId ^Optional	The ID of the related transaction used in case it was required for processing.
merchant_unique_id ^Optional	The ID value that was initially passed in the merchant_unique_id parameter when making the original request to the Nuvei Checkout Page.
clientUniqueId ^Optional	If transaction sent through Nuvei API, this parameter is populated by the ID of the transaction in the merchant’s system.
externalTokenProvider ^Optional	External token provider is a type of entity in the payment industry with its own flow (for example: Visa Checkout, Apple Pay). This indicates which external token provider was used in current transaction.
isDecrypeService ^Optional	External token provider is a type of entity in the payment industry with its own flow (for example: Visa Checkout). This indicates whether the payments gateway decrypted the external token data provided, which was required for processing.
apmPayerInfo ^Optional	Additional customer information that is received back from an external alternative payment service provider.
clientRequestId ^Optional	ID of the API request in merchant’s system. This value must be unique. Can be used to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
threeDReason ^Optional	Reason description for a failed 3DS authorization as received from the issuer.
challengeCancelReasonId ^Optional	Reason ID for a cancelled 3DS authentication as received from the issuer.
ChallengeCancelReason ^Optional	Reason for a cancelled 3DS authentication as received from the issuer.
isLiabilityOnIssuer ^Optional	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.
challengePreferenceReason ^Optional	If a challenge is requested, this field provides the reason for it (click here for more details).
houseNumber ^Optional	Indicates the provided house number.
amountWithoutFee ^Optional	The transaction amount without the fee.
feeAmount ^Optional	The amount of the transaction fee.
manage_3d_mode ^Optional	The value of manage3D mode that was submitted on the call: AUTO ON OFF
acquirerBank ^Optional	The name of the acquirer bank or payment processor of the processed transaction.

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.

Calculating the checksum value:

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

   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

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

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:

• Item level fields: item_amount_N, item_discount_N, item_shipping_N, item_handling_N, item_quantity_N
• shipping
• handling
• discount
• total_tax
• version

To apply the total calculation to a subtotal:

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

• calculatedTotalAmount = (item_amount_N – item_discount_N + item_shipping_N + item_handling_N) * item_quantity_N

  The new total is calculated with the shipping & handling costs and discounts.

• calculatedTotalAmount = shipping + handling – discount

  The tax is then added to calculate the total.

• calculatedTotalAmount = calculatedTotalAmount * (total_tax / 100)

Calculation Example:

• Item amount = 350
• Shipping = 10
• Discount = -20
• Total tax = 23% (0.23)

• Total amount = 418.20

  350+10-20=340 (Subtotal)

  340+(0.23*340)=418.20 (Total amount)

Handling the Cashier Response

Nuvei sends you a Direct Merchant Notification (DMN) notifying you of the status of the deposit. You must provide Nuvei with the URL of the server that receives the DMN. For more information, please refer to our DMNs Guide.

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	Type	Size	Mandatory	Description
merchant_id	Integer	64 bits	All	The merchant’s ID provided by Nuvei.
merchant_site_id	Integer	64 bits	All	The merchant website’s ID provided by Nuvei.
checksum	String	Char(102400)	All	A hashing of the request to secure and authenticate the request (refer to checksum)
time_stamp	String	Char(19)	All	Current GMT time in the following format: YYY-MM-DD.HH:MM:SS.
currency	String	Char(3)	All	The currency used in the transaction.
invoice_id	String	Char(100)	No	A unique invoice identifier provided by the merchant or randomly generated.
payment_method	String	Char(256)	No	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			No	This parameter filters out any payment method that is not the payment method sent in the payment_method parameter.
merchantLocale	String	Char(5)	No	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	Char(50)	No	The customer’s ID as per the merchant’s userid.
theme_id	Integer	64 bits	No	Use this field overrides
customData	String	Char(255)	No	General data about the customer provided by the merchant.
merchant_unique_id	String	Char(64)	No	The unique ID (identifier) of the transaction in the merchant’s database.
encoding	String	Char (20)	No	The type of character encoding. Default value is ISO-8859-1.
webMasterId	String	Char(255)	No	This is an affiliate parameter that the merchant can send to Cashier.
allow_installments	Integer	64 bits	No	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 bits	No	This parameter indicates the maximum amount of installments with which the payment can be made.
processingChannel	String	Char (4)	No	Sends “MOTO” value whenever the processing channel is from MOTO type (mail or telephone order)

Item Details

Parameter	Type	Size	Mandatory	Description
item_name_N*	String	Char(400)	Yes	The name of item number N.**
item_number_N	String	Char(400)	Yes	The first part of the items list, the serial number. Counted from item_number_1 to item_number_N.
item_amount_N	Double	64 bits	Yes	The cost of the item numbered in the item_number_N parameter.
Item_shipping_N	Double	64 bits	No	Shipping costs of the item numbered in the item_number_N parameter.
item_handling_N	Double	64 bits	No	Handling costs of the item numbered in the item_number_N parameter.
item_discount_N	Double	64 bits	No	Discount rate of the item numbered in the item_number_N parameter.
item_quantity_N	Integer	64 bits	Yes	Number of pieces of the item numbered in the item_number_N parameter. Default value is 1.
discount	Double	64 bits	No	The total discount out of the total amount.
shipping	Double	64 bits	No	Total shipping costs.
handling	Double	64 bits	No	Total handling costs.
total_amount	Double	64 bits	Yes	Total transaction charge.
total_tax	Double	64 bits	No	Total taxes.
productId	String	Char(50)	No	Merchant’s product ID. If this parameter is left empty, Cashier inserts a concatenation of all item names.
promoCode	String	Char(512)	No	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.

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

User Token

Parameter	Type	Size	Mandatory	Description
user_token	String	Char (8)	No	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	Char (255)	Yes	ID for the user. based on which we managed the user’s payment methods.
userPaymentOptionId	String		No	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	Type	Size	Mandatory	Description
first_name*	String	30	Yes	Customer’s first name.
last_name*	String	40	Yes	Customer’s last name.
email*	String	100	Yes	Customer’s email address.
address1*	String	60	Yes	Customer’s address.
address2	String	60	No	Customer’s address.
city*	String	30	Yes	Customer’s city.
country*	String	20	Yes	Customer’s two-letter ISO country code.
state*	String	20	Yes	Customer’s state in ISO code (for customers based in the US, Canada and India only)
zip*	String	10	Yes	Customer’s zip code.
phone1*	String	18	Yes	Customer’s phone1.
phone2	String	18	No	Customer’s phone2.
phone3	String	18	No	Customer’s phone3.
personal_id	String	Char(11)	No	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	Char(10)	No	The date of birth of the registering user. (YYYY-MM-DD)

3D Secure 2.0

The Nuvei payment page handles the SCA 3DS 2.0 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 3DS 2.0, 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 2.0 process.

Parameters

Parameter	Type	Mandatory	Description
deliveryEmail	String (254)	No	For electronic delivery, the email address to which the merchandise is delivered: deliveryEmail@somedomain.com
deliveryTimeFrame	String (2)	No	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)	No	For prepaid or gift card purchase, this represents the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).
giftCardCount	String (2)	No	For prepaid or gift card purchase, this represents the total count of individual prepaid or gift cards/codes purchased.
giftCardCurrency	String (3)	No	For prepaid or gift card purchase, this represents ISO 4217 three-letter currency code of the gift card.
preOrderDate	String (8)	No	For a pre-ordered purchase, this represents the expected date that the merchandise is available. Format: YYYMMDD
preOrderInd	String (2)	No	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)	No	This indicates whether the cardholder is reordering previously purchased merchandise. 01 = First time ordered 02 = Reordered
shipIndicator	String (2)	No	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)	No	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)	No	Length of time that the cardholder has had the account with the 3DS Requestor. 01 = No account (guest check-out) 02 = Created during this transaction 03 = Less than 30 days 04 = 30–60 days 05 = More than 60 days
accountLastChangeDate	String (8)	No	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)	No	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)	No	Date that the cardholder opened the account with the 3DS Requestor. YYYYMMDD
accountPasswordChangeDate	String (8)	No	Date that cardholder’s account with the 3DS Requestor had a password change or account reset. YYYYMMDD
accountResetInd	String (2)	No	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)	No	Number of purchases with this cardholder account during the previous six months.
accountAddCardAttempts24H	String (3)	No	Number of Add Card attempts in the last 24 hours.
accountTransactionsCount24H	String (3)	No	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)	No	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)	No	Date when the shipping address used for this transaction was first used with the 3DS Requestor. YYYYMMDD
accountAddressFirstUseInd	String (2)	No	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)	No	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)	No	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	Type	Size	Mandatory	Description
shippingFirstName	String	30	No	Recipient’s first name.
shippingLastName	String	40	No	Recipient’s last name.
shippingAddress	String	60	No	Recipient’s address.
shippingCity	String	30	No	Recipient’s city.
shippingCountry	String	20	No	Recipient’s two-letter ISO country code.
shippingZip	String	10	No	Recipient’s zip code.

Navigation Parameters

Parameter	Type	Size	Mandatory	Description
skip_review_tab	String	Char(5)	No	A switch (true, false) indicating whether or not to skip the Cashier’s review page.
success_url	String	Char (2048)	No	the customer is redirected to this URL on successful transaction
error_url	String	Char (2048)	No	the customer is redirected to this URL on error
pending_url	String	Char (2048)	No	the customer is redirected to this URL when response is pending
back_url	String	Char (2048)	No	the customer is redirected to this URL when user presses the 'Back’ button.
notify_url	String	Char (2048)	No	The DMN URL. See our DMNs Guide)
isNative	Boolean	1	No	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	No	For more information, please contact Nuvei’s Integration Support Team

*If some of the page’s mandatory parameters are missing, the customer’s browser is redirected to the “Cancel Page” URL.

Merchant Custom Fields

Parameter	Type	Size	Mandatory	Description
descriptorMerchantName	String	Char(25)	No	Allows the merchant to define a dynamic descriptor for the merchant’s name.
descriptorMerchantPhone	String	Char(13)	No	Allows the merchant to define a dynamic descriptor for the merchant’s phone number.
customSiteName	String	Char(50)	No	The merchant’s site name that should replace the default MerchantSite name.
customField1 … customField15	String	Char(64)	No	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.

Transaction Parameters

Parameter	Description
status	Status of the executed transaction: Approved, Declined, etc.
totalAmount	Total transaction charge.
transactionID	A 64-bit unique integer ID generated by Nuvei, used for tracking purposes.
clientUniqueID	Custom data parameter. If this parameter is not specified, the default value is the name of the merchant’s account.
errCode	The error code of a failed transaction. For more information, see Filter Error Codes.
exErrCode	The extended error code of a failed transaction. For more information, see Filter Error Codes.
authCode	The authentication code received by Nuvei for the transaction.
reason	The reason for a failed transaction, where relevant. For more information, see Decline Reasons.
token	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	The failed transaction’s reason’s code. For more information, see Decline Reasons.
responsechecksum	Deprecated output checksum parameter.
advanceResponseChecksum	Output checksum parameter.
cardCompany	The name of the credit card company. The possible values are: Visa, Amex, MasterCard, Diners, Diners, Discover, JCB, LaserCard, Maestro, Solo, and Switch.
ECI	This is returned from banks and indicates the 3D Secure result. Possible ECI data values are: ECI = 5(VISA), 2(MC): The cardholder was successfully authenticated ECI = 6(VISA), 1(MC): The issuer or cardholder does not participate in a 3D Secure program. ECI = 7: Payment authentication was not performed Note: In this method eci is returned in response only in case its value is 1 or 6 or 7.

Payment Parameters

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

General Items

Parameter	Description
total_discount	Total discount for current order.
total_handling	Total handling for current order.
total_shipping	Total shipping for current order.
total_tax	Total tax for current order.
item_number_N	The number of item number N.
item_amount_N	The cost of item number N.
item_quantity_N	The quantity of item number N.
item_discount_N	The discount for item number N.
item_handling_N	The handling costs for item number N.
item_shipping_N	The shipping costs for item number N.
promoCode	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	Custom data sent to Nuvei.
merchant_unique_id	The merchant_unique_id value as provided by the merchant to Nuvei in the HTTPS request.
merchant_site_id	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	The unique merchant ID supplied by Nuvei.
requestVersion	The processed Nuvei request’s version.
message	A message sent from Nuvei regarding the transaction.
error	An error message sent from Nuvei.
instantDmnStatus	The status of the Instant DMN notification. This parameter is only returned when Instant DMN notifications are active.
ppp_TransactionID	The ID number of the transaction’s history table in the Nuvei database.
userID	The UserID value transferred by the merchant in the HTTPS request.
ProductID	The purchased product’s ID as provided by the merchant in the HTTPS request.
ppp_status	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	Merchant’s location as sent to Nuvei.
unknownParameters	All unknown parameters sent with the current transaction.
webMasterId	Affiliate parameter – additional parameter which merchant can send to PPP.
customFieldn*	The merchant can send up to 15 custom fields to Nuvei to update miscellaneous data.

Additional Services

Additional Services

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

• Payment Options API
• Rebilling
• Withdrawals API
• KYC API