API Reference Home

Introduction

Welcome to the Nuvei API Reference Guide.

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

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

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 API Reference Guide describes the API’s services and functionality, and is intended for developers by providing all necessary integration information, including the necessary requests and responses.

 

Web SDK

Web SDK Overview

The Web SDK integration platform is a JavaScript library that you can use on your own payment page to perform end-to-end payments.

Web SDK 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 Web SDK, its advantages, and a complete guide, please refer to our Web SDK page in our main documentation portal. There you can find the following topics:

• Quick Start for Web SDK
• Nuvei Fields
• Nuvei Fields Stylizing
• APM Payments with Web SDK
• Web SDK Additional Functions
• Tokenization-Only using Web SDK
• Web SDK Flow using ReactJS
• Web SDK FAQs

 

Web SDK Methods

SafeCharge()

This method initializes the Web SDK.

Input

Example Request

1
2
3
4
5
6
7
8
9
sfc = SafeCharge({
    //logLevel: 0,
    sessionToken: result.sessionToken, // received from openOrder API
    env: 'int', // the Nuvei environment you’re running on
    merchantId: '1475082432483184221', // as assigned by Nuvei
    merchantSiteId : '184941', // as assigned by Nuvei
    blockCards: ['visa','credit','corporate'], ['amex', 'GB'], // Visa corporate credit cards and British AMEX cards are blocked
    // support19Digits: true,
});

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(20) ~Required	The sessionToken retrieved from a call to /openOrder that references the order created in the Nuvei system.
merchantId ^String(20) ~Required	Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	Merchant Site ID provided by Nuvei.
env ^String(4) ~Required	If not provided, prod is assumed. Possible values: prod – production int – integration
logLevel ^Integer(1) ^Optional	Determines the level of detail at which data must be shown on the console. Possible values: 0 (default) – No logging 4 – Logging 6 – Stack tracing
blockCards ^Array ^Optional	An array that specifies which sets of cards can be blocked from appearing to the customer in Payment Methods lists. See Blocking Cards for more information.
support19Digits ^Boolean ^Optional	When set to true, Web SDK supports 19-digit card numbers. Possible values: true, false

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 Initiate a Session.

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

Input

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
sfc.createPayment({
    "sessionToken": result.sessionToken, // received from openOrder API 
    "merchantId": '1475082432483184221', // as assigned by Nuvei
    "merchantSiteId": '184941', // as assigned by Nuvei
    "clientUniqueId": "695701003", // optional
    "paymentOption": {
        "card": {
            "cardNumber": "5111426646345761",
            "cardHolderName": "John Smith",
            "expirationMonth": "12",
            "expirationYear": "2026",
            "CVV": "217"
        },
            "subMethod": {
                "subMethod": "Skrill1Tap"
            }
    }
    "billingAddress": {
        "email": "john.smith@email.com",
        "county": "US"
    }
}, 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 Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(20) ~Required	The sessionToken retrieved from a call to /openOrder that references the order created in Nuvei system.
merchantId ^String(20) ~Required	Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	Merchant Site ID provided by Nuvei.
paymentOption ^Class ~Required	This class represents the details on the payment method. The best practice is to populate Nuvei Fields. If you wish to explicitly set it, it can be done with one of 3 options: • card – Represents a credit/debit card.     ▫ cardNumber (String, 20, REQUIRED) – The card number.     ▫ cardHolderName (String, 70, REQUIRED) – The card holder name.     ▫ expirationMonth (String, 2, REQUIRED) – The card expiration month.     ▫ expirationYear (String, 4, REQUIRED) – The card expiration year.     ▫ CVV (String, 4, REQUIRED) – The CVV/CVC security code. OR • alternativePaymentMethod – Represents an alternative payment method (APM). Please refer to APM Input Fields and APIs for details. OR • userPaymentOptionId – This identifies a payment option that has already been used by the customer and now it is requested for re-use. Nuvei keeps payment option details from a previous use. 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. __________ • subMethod – This class allows using an APM but with a different payment flow.     ▫ subMethod (String, 50) – The APM name.     ▫ email (String, 255) – If no email is provided, it is automatically populated from billingAddress. For more information, see APM Submethod Classes.
billingAddress ^Class ~country and email Required	The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters. country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30) lastName (String, 40) address (String, 60) address2 (String, 60) phone (String, 18) zip (String, 10) city (String, 30) state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). county (String, 255) These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.
clientUniqueId ^String(45) ^Optional	The ID of the transaction in the merchant’s system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.

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

Additional Input Parameters

PARAMETER	DESCRIPTION
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This currently represents the social security number (SSN) of United States citizens.
shippingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100) shippingCounty (String, 255)
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 This allows the merchant to send information with the request to be saved in the API level and returned in response.

Output

The createPayment response comes in two steps:

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

  These contain the fiscal result 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 a user’s manipulation, you have to verify the response directly from your server with the /getStatusPayment method (or alternatively with the DMNs). For details regarding the payment verification please refer to our Quick Start Guide.
  

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "result": "DECLINED",
    "errCode": "-1",
    "errorDescription": "Decline",
    "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 values: 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, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter. Values as detailed in Errors Handling. In addition, it can have the value of “General 3D error”, which means the 3D-Secure process was aborted.
Canceled ^Boolean	If the process was canceled by the end user
transactionId ^String(20)	The Gateway transaction ID.
ccCardNumber ^String(20)	The credit card number in a mask, for example: 4****1111.
bin ^String(2)	The BIN number representing the issuer.
last4Digits ^String(4)	The last four digits of the card number.
ccExpMonth ^String(2)	The expiration month
ccExpYear ^String(4)	The expiration year.
userPaymentOptionId ^String	This field represents the ID for the newly created payment option, which can be referenced in future requests. Refer to Card-on-File for further details.
threeDReasonId ^String	Reason ID for a failed 3D-Secure authorization as received from the issuer. Press here for more information.
threeDReason ^String	Reason description for a failed 3D-Secure authorization as received from the issuer. Press here for more information.
challengeCancelReasonId ^String	Reason ID for a canceled 3D-Secure authorization as received from the issuer.
challengeCancelReason ^String	Reason description for a canceled 3D-Secure authorization as received from the issuer.
isLiabilityOnIssuer ^String	Indicates if there is 3D-Secure liability shift. If equal to “1” – Liability shift is present. If equal to “0”, empty or null – No liability shift has occurred.
isExemptionRequestInAuthentication ^String	Indicates if an exemption was requested during 3D-Secure authorization.
challengePreferenceReason ^String	This value is returned following a 3D-Secure v2 challenge and describes the reason for challenge(press here for more details).

getApms()

This method returns the APMs supported with all their metadata needed for displaying them to the user and preparing them for processing, such as their display name, logo, required input to collect from the end user, and so on. One important 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 method can retrieve either the entire APM set supported by your account with Nuvei, or alternatively, a customized set of APMs. For example, you can request to retrieve APMs that correspond to certain criteria such as by transaction currency or by the user country.

Input

Example Request

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

Input Parameters

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

Output

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
{
    "sessionToken":"",
    "merchantId":"",
    "merchantSiteId":"",
    "clientRequestId":"",
    "internalRequestId":"",
    "paymentMethods":[
        {
            "paymentMethod":"cc_card",
            "paymentMethodDisplayName":[
                {
                    "language":"en",
                    "message":"Credit Card"
                }
            ],
            "isDirect":"true",
            "countries":[
                "US",
                "DE"
            ],
            "currencies":[
                "USD"
            ],
            "logoURL":"",
            "fields":[
                {
                    "name":"ccCardNumber",
                    "regex":"",
                    "type":"text",
                    "validationmessage":[
                        {
                            "language":"en",
                            "message":"Invalid Card Number"
                        }
                    ],
                    "caption":[
                        {
                            "language":"en",
                            "message":"Card Number"
                        }
                    ]
                },
                {
                    "name":"ccExpMonth",
                    "regex":"",
                    "type":"text",
                    "validationmessage":[
                        {
                            "language":"en",
                            "message":"Invalid Expiration Month"
                        }
                    ],
                    "caption":[
                        {
                            "language":"en",
                            "message":"Card Expiration Month"
                        }
                    ]
                },
                {
                    "name":"ccExpYear",
                    "regex":"",
                    "type":"text",
                    "validationmessage":[
                        {
                            "language":"en",
                            "message":"Invalid Expiration Year"
                        }
                    ],
                    "caption":[
                        {
                            "language":"en",
                            "message":"Card Expiration Year"
                        }
                    ]
                },
                {
                    "name":"ccNameOnCard",
                    "regex":"",
                    "type":"text",
                    "validationmessage":[
                        {
                            "language":"en",
                            "message":"Invalid Name on Card"
                        }
                    ],
                    "caption":[
                        {
                            "language":"en",
                            "message":"Cardholder name as it appears on your credit card"
                        }
                    ]
                }
            ]
        },
        {
            "paymentMethod":"apmgw_Instant_Open_Banking",
            "paymentMethodDisplayName":[

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

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

Output Parameters

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

 

authenticate3d()

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

This is also the quickest way for a merchant to migrate to 3D-Secure v2; just call this method on the client side and use the CAVV and ECI method with your existing integration – either with Nuvei or any other PSP.

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

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

• 3D-Secure Authentication Only)
• Nuvei Fields guide (for full PCI descoping)

Input

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
sfc.authenticate3d({
    "sessionToken": result.sessionToken, // received from openOrder API 
    "merchantId": '1475082432483184221', // as assigned by Nuvei
    "merchantSiteId": '184941', // as assigned by Nuvei
    "clientUniqueId": "695701003", // optional
    "paymentOption": {
        "card": {
            "cardNumber": "5111426646345761",
            "cardHolderName": document.getElementById('example1-name').value,
            "expirationMonth": "12",
            "expirationYear": "25",
            "CVV": "217"
        },
    }
    "billingAddress": {
        "email": "someone@somedomain.com",
        "country": "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 Parameters

PARAMETER	DESCRIPTION
sessionToken ^String ~Required	The sessionToken retrieved from a call to /openOrder that references the order created in the Nuvei system.
merchantId ^String(20) ~Required	Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	Merchant Site ID provided by Nuvei.
paymentOption ^Class ~Required	This class represents the details on the payment method. The best practice is to populate Nuvei Fields. If you wish to explicitly set it, it can be done with one of 2 options: • card – Represents a credit/debit card.     ▫ cardNumber (String, 20, REQUIRED) – The card number.     ▫ cardHolderName (String, 70, REQUIRED) – The card holder name.     ▫ expirationMonth (String, 2, REQUIRED) – The card expiration month.     ▫ expirationYear (String, 4, REQUIRED) – The card expiration year.     ▫ CVV (String, 4, REQUIRED) – The CVV/CVC security code. OR • userPaymentOptionId – This is a field identifying a payment option that has already been used by the customer and now it is requested for re-use. Nuvei keeps payment option details from a previous use. Can be used with:     ▫ expirationMonth (String, 2) – For a newer card expiration.     ▫ expirationYear (String, 4) – For a newer card expiration.     ▫ CVV (String, 4) – Recommended for high-risk merchants.
billingAddress ^Class ~country and email Required	The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters. country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30) lastName (String, 40) address (String, 60) address2 (String, 60) phone (String, 18) zip (String, 10) city (String, 30) state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). county (String, 255) These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.
clientUniqueId ^String(45) ^Optional	The ID of the transaction in the merchant’s system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.

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

Additional Input Parameters

PARAMETER	DESCRIPTION
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This currently represents the social security number (SSN) of United States citizens.
shippingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100) shippingCounty (String, 255)
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 This allows the merchant to send information with the request to be saved in the API level and returned in response.

Output

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

• Directly from the createPayment() return value (as detailed below).
• By our 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.)

• 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 reason: Shows the error description in case one was received.
  

Example Response

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

Output Parameters

PARAMETER	DESCRIPTION
eci ^String(2)	The Electronic Commerce Indicator (ECI) that indicates the level of security used in a 3D-Secure program when the cardholder provides payment information to the merchant. Possible ECI data values: Visa 5 – The cardholder was successfully authenticated. 6 – The issuer or cardholder does not participate in a 3D-Secure program. 7 – Payment authentication was not performed. Mastercard 2 – The cardholder was successfully authenticated. 1 – The issuer or cardholder does not participate in a 3D-Secure program. 6 – Payment authentication was not performed. 7 – The cardholder was successfully authenticated for the initial merchant-initiated transaction.
cavv ^String(50)	The card authentication verification value as received from the MPI.
xid ^String(50)	The transaction ID received from the MPI for 3D-Secure v1.
dsTransID ^String(36)	The transaction ID received from the MPI for 3D-Secure v2.
result ^String(20)	The cashier status of merchant request. Possible values: 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, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter. Values as detailed in Errors Handling. In addition, it can have the value of “General 3D error”, which means the 3D-Secure process was aborted.
Canceled ^Boolean	If the process was canceled by the end user
transactionId ^String(20)	The Gateway transaction ID.
ccCardNumber ^String(20)	The credit card number in a mask, for example: 4****1111.
ccTempToken ^String	A temporary card token that can be used instead of your card number in your call to the /payment method.
bin ^String(2)	The BIN number representing the issuer.
last4Digits ^String(4)	The last four digits of the card number.
ccExpMonth ^String(2)	The expiration month
ccExpYear ^String(4)	The expiration year.
userPaymentOptionId ^String	This field represents the ID for the newly created payment option, which can be referenced in future requests. Refer to Card-on-File for further details.
threeDReasonId ^String	Reason ID for a failed 3D-Secure authorization as received from the issuer. Press here for more information.
threeDReason ^String	Reason description for a failed 3D-Secure authorization as received from the issuer. Press here for more information.
challengeCancelReasonId ^String	Reason ID for a canceled 3D-Secure authorization as received from the issuer.
challengeCancelReason ^String	Reason description for a canceled 3D-Secure authorization as received from the issuer.
isExemptionRequestInAuthentication ^String	Indicates if an exemption was requested during authorization.
challengePreferenceReason ^String	This value is returned following a 3D-Secure v2 challenge and describes the reason for challenge (press here for more details).

getCardDetails()

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

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

Input

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
sfc.getCardDetails({
    sessionToken   : sessionData.sessionToken,
    merchantId     : 1475082432483184221, // as assigned by Nuvei
    merchantSiteId : 184941, // as assigned by Nuvei
    cardNumber     : 5111426646345761,
    clientRequestId: '1C6CT7V1L',
    clientUniqueId: '12345'


}, function(cardDetails) {
    console.log(cardDetails);
  })

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
cardNumber ^String(20) ~Required	The credit card number. cardNumber or bin must be populated.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this field is used to prevent idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
clientUniqueId ^String(45) ^Optional	The ID of the transaction in the merchant’s system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.

Output

Example Response

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

Output Parameters

Parameter	Description
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
clientRequestId ^String(20)	The ID of the API request in the merchant’s system.
clientUniqueId ^String(255)	The ID of the transaction in the merchant’s system.
brand ^String	The name of the card scheme; for example: Visa
cardType ^String	The type of card used in the transaction. Possible values: credit, debit
program ^String	The card program used in the transaction; for example: Visa Platinum
cardProduct ^String	The code of the card program used in the transaction; for example, “N” for Visa Platinum
visaDirectSupport ^String	Indicates whether Visa Direct is supported or not
dccAllowed ^String	Indicates whether DCC is allowed for this card.
issuerCountry ^String(2)	2-letter ISO code of the card issuer’s country.
currency ^String(3)	The 3-letter ISO currency code.
internalRequestId ^String(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
version ^String(10)	The current version of the API method. The current version is 1.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
errCode ^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 values: SUCCESS, ERROR

clientGetDccDetails()

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

Input

Example Request

1
2
3
4
5
6
7
8
9
sfc.clientGetDccDetails({
    sessionToken: sessionData.sessionToken,
    merchantId: sessionData.merchantId, //as assigned by Nuvei
    merchantSiteId: sessionData.merchantSiteId,
    cardNumber: scard,
    currency: "GBP"
}, function(dccRes) {
    console.log(dccRes);
})

Input Parameters

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

Output

Example Response

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

Output Parameters

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

getToken()

Use this method to get a temporary one-time token (ccTempToken).
A temporary token is valid only for an API session, and is used only if you are processing with our server-to-server API and wish to be PCI descoped.
The return value from the function is ccTempToken, which can then be used in the server-to-server API /payment API call.

Example Request

1
2
3
4
5
6
7
8
9
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

        }
    });

destroy()

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

Example Request

1
destroy()

 

Checkout Methods

checkout()

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

Input

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
function main() {
    document.getElementById('checkout').innerHTML = "";
    checkout({
        maskCvv: true,
        cardAuthMode: "3dAuthOnly", // 3dAuthForNewCardsOnly, paymentForAll (default)
        sessionToken: document.getElementById('session').value,
        env: 'int', // Nuvei API environment - 'int' (integration) or 'prod' (production - default if omitted)
        merchantSiteId: '<your merchantSiteId goes here>',
        merchantId: '<your merchantId goes here>',
        country: 'US',
        currency: 'USD',
        amount: 135,
        userId: '259',
        "billingAddress": {
            "email": "john.smith@email.com",
            "country": "US"
        },
        renderTo: '#checkout', // <div id="container"></div>
        onResult: function(result) {
            console.log("Result", result)
        },
        onReady: function(result) {
            console.log(result);
        },
        selectPaymentMethod: function(paymentDetails) {
            console.log("selectPaymentMethod", paymentDetails);
        },
        upoDeleted: function(paymentDetails) {
            console.log("upoDeleted", paymentDetails);
        },
        prePayment: function(paymentDetails) {
            return new Promise((resolve, reject) => {
                console.log(paymentDetails);
                resolve();
                or
                reject();
                or
                reject('Message'); // Reject payment with message
            });
        },
        userTokenId: '<some userTokenId>',
        useDCC: "disable", // enable or force 
        strictDcc: false, // false means customers can use a card even if it isn't "DCC Allowed"
        savePM: true, // option to save payment method for future use and needed for apm recurring billing 
        subMethod: ["PayNPlay", "QuickRegistration"], // APM providers who support the Customer Registration feature
        pmWhitelist: ["apmgw_QIWI", "apmgw_MoneyBookers"],
        blockCards: [
            ["visa", "credit", "corporate"],
            ["amex", "GB"]
        ], //blocks Visa corporate credit cards, and also blocks British Amex cards
        alwaysCollectCvv: true, // default 
        fullName: document.getElementById('cardHolderName').value,
        email: 'john.smith@email.com',
        locale: 'en', // de, es, fr, it, pt, ru
        textDirection:'ltr', // or rtl 
        autoOpenPM: true
            // logLevel: 0,
            // i18n : {
            //     my_methods : "Meine Zahlungsmethoden*"
            //     card_number : "KARTA",
            //     mm_yy : "MMM / YYY",
            //     cvv : "CVVV"
            // }
    });
}

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String ~Required	The sessionToken retrieved from a call to /openOrder that references the order created in the Nuvei system.
merchantId ^String(20) ~Required	Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	Merchant Site ID provided by Nuvei.
currency ^String(20) ~Required	It is used for visualization in the payment method (button, Apple Pay overlay ), as well as for filtering supported payment methods.
amount ^String(20) ~Required	Mandatory for visualization purposes similar to currency.
country ^String(2) ~Required	The 2-letter ISO country code. Must be entered in uppercase. Used as a filter in retrieving payment methods.
renderTo ^String ~Required	The container used for checkout().
onResult ^Function ~Required	Defines a callback function called to provide the full response information each time a payment request is returned – declines, errors, and approvals.
onReady ^Function ~Required	Defines a callback function for when the checkout form is fully loaded.
prePayment ^Function ~Required	Defines a callback function that allows the merchant to be notified just before a payment is finalized, receive all the payment details, and take an action if desired. Possible values: resolve() – To continue with the payment reject() – To stop the payment reject(<test message>) – To stop the payment with a message
paymentMethodSelected ^Function ^Optional	This callback function is called when a user selects a payment method from the gallery, either an existing UPO or a new one. For an existing UPO, the merchant receives all the information about the UPO. For a new payment option, only the method name is received.
upoDeleted ^Function ^Optional	This callback is called when a user selects and removes a UPO from the gallery. Note: The event is called after the user actually confirms that the UPO should be deleted.
env ^String(4) ~Required	If not provided, “prod” is assumed. Possible values: prod – production int – integration
userTokenId ^String(255) ~Conditional	This ID uniquely identifies your consumer/user in your system. It is REQUIRED if you wish to use the userPaymentOptionId field for future charging of this user without re-collecting the payment details (see User Payment Management for details).
logLevel ^Integer(1) ^Optional	Determines the level of detail at which data must be shown on the console. Possible values: 0 (default) – No logging 4 – Logging 6 – Stack tracing
fullName ^String ^Optional	Used to pre-populate name on card and similar APM fields.
email ^String ^Optional	Used to pre-populate relevant APMs.
hideApms ^String ^Optional	Determines which APMs are hidden.
alwaysCollectCvv ^Boolean ^Optional	Collects the CVV for a stored card. Possible values: true (default), false
showResponseMessage ^Boolean ^Optional	Controls the message dialogs for the checkout. Possible values: True (default) – All pop-ups and messages for the checkout process are displayed. False – The message dialogs are hidden and the merchant is provided only with a callback response from the checkout form.
locale ^String(2) ^Optional	Language in which the text is displayed. Supported languages: de, en (default), es, fr, it, pt, ru
textDirection ^String(3) ^Optional	Sets the text direction. Possible values: ltr (left-to-right) (default), rtl (right-to-left)
subMethod ^Array ^Optional	An array of a list of the APM providers that support the Customer Registration feature (press here for more details). Possible values: QuickRegistration, PayNPlay
strictDcc ^Boolean ^Optional	This parameter allows a merchant to perform a DCC conversion even if the card is not returned by the APM as DCC enabled. Possible values: false (default) – Customers are allowed to use DCC even for cards that do not have the status of “DCC Allowed” (set by the issuing bank). true – Customers are only allowed to use DCC for cards that have the status of “DCC Allowed” (set by the issuing bank).
savePM ^Boolean ^Optional	This parameter is used to display the “Save my details for future use” checkbox for each payment method in the Payment Methods list. Possible values: true – Users can save payment method for UPOs. This is needed for the initial request of an APM Recurring Billing transaction. false – Users cannot save a payment method for UPOs.
payButton ^String(13) ^Optional	Determines how the amount is displayed. Possible values: amountButton (default) – Displays the amount on the pay button. textButton – Displays text on the button. noButton – The button can be displayed outside the checkout user interface. Note: When the user presses the button, it calls the checkout.submitPayment() method, which invokes the payment externally, from Checkout.
pmWhitelist ^Array ^Optional	An array of only the specified APMs that are displayed to the customer in the Payment Methods list. Note: pmWhiteList and pmBlacklist cannot be used together in the same initialization.
pmBlacklist ^Array ^Optional	An array of the specified APMs that are not displayed to the customer in the Payment Methods list even if they are returned by an API. Note: pmWhiteList and pmBlacklist cannot be used together in the same initialization.
blockCards ^Array ^Optional	Specifies which sets of cards can be blocked from appearing to the customer in Payment Methods lists. See Blocking Cards for more information.
autoOpenPM ^Boolean ^Optional	Controls whether payment methods are always open in the presence of a UPM. Possible values: false (default), true
maskCvv ^Boolean ^Optional	Determines if the CVV digits in the CVV text box are masked (true) or visible (false)(default).
useDCC ^String ^Optional	Determines how the DCC is set for the user and/or the user session. Possible values: enable – Enables the checkbox. disable (default) – Disables the checkbox. force – Enables and selects the checkbox. The customer is still able to clear the checkbox.
cardAuthMode ^String ^Optional	Use this field to perform an MPI Only request, which means that a payment request is initiated for the 3DS validation, but an actual payment is not made. Possible values: paymentForAll (default) – Performs a 3D Secure validation and proceeds to payment automatically. 3dAuthOnly – Always performs only the 3DS validation (no payment) 3dAuthForNewCardsOnly – Performs only 3DS validation, but only for the first-time processing (not including UPOs).
i18n ^String ^Optional	Also known as “internationalization”. The merchant can define custom messages to replace existing ones.
fieldStyle ^Object ^Optional	This is used to customize the look and feel of the checkout form to match your payment page by customizing the styles of the checkout payment HTML forms. For more details, please press here.
userId ^String(20) ~Required	The ID of the customer in the merchant system. Note: This is not to be confused with userTokenId.
clientUniqueId ^String(45) ^Optional	The ID of the transaction in the merchant’s system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
billingAddress ^Class ~country and email Required	The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters. country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30) lastName (String, 40) address (String, 60) address2 (String, 60) phone (String, 18) zip (String, 10) city (String, 30) state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). county (String, 255) These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This currently represents the social security number (SSN) of United States citizens.
shippingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100) shippingCounty (String, 255)

Output

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "result": "APPROVED",
    "errCode": "0",
    "errorDescription": "",
    "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 values: 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, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter. 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.
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.
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.
transactionId ^String(20)	The Gateway transaction ID.
threeDReason ^String	Reason description for a failed 3D-Secure authorization as received from the issuer. Press here for more information.
threeDReasonId ^String	Reason ID for a failed 3D-Secure authorization as received from the issuer. Press here for more information.
challengeCancelReasonId ^String	Reason ID for a canceled 3D-Secure authorization as received from the issuer.
challengeCancelReason ^String	Reason description for a canceled 3D-Secure authorization as received from the issuer.
isLiabilityOnIssuer ^String	Indicates if there is 3D-Secure liability shift. If equal to “1” – Liability shift is present. If equal to “0”, empty or null, no liability shift has occurred.
challengePreferenceReason ^String	This value is returned following a 3D-Secure v2 challenge and describes the reason for challenge (press here for more details).
Cancelled ^Boolean	If the process was canceled by the end user.

checkout.applyOverlay()

Once a payment is completed in the checkout, the session token cannot be used for an additional payment (to prevent a double payment). Use this method to make the checkout UI read-only by using an “overlay” that blurs the checkout form.

Example Request

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

checkout.removeOverlay()

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

Example Request

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

checkout.getToken()

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

Example Request

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

checkout.destroy()

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

Example Request

1
checkout.destroy()

checkout.submitPayment()

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

Example Request

1
checkout.submitPayment()

 

Payment API

Payment API Overview

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

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

/getSessionToken

Definition

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

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

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

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

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

Example Response

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

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

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

@Links URLs

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

@Test https://ppp-test.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 This is needed for the “checksum” hashing calculation.
checksum ^String(256) ~Required	The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, timeStamp, merchantSecretKey Press here to see an example.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this field is used to prevent idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.

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 purposes).
status ^String(20)	The status of merchant’s API request/call. Possible values: SUCCESS, ERROR.
errCode ^String(11)	The error code in the event of an error.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”).
version ^String(10)	The current version of the merchant request. The current version is 1.
clientRequestId ^String(20)	The ID of the API request in merchant’s system.

/openOrder

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId":"1C6CT7V1L",
    "clientUniqueId": "12345",
    "currency": "USD",
    "amount": "200",
    "userTokenId": "230811147",
    "billingAddress":{
        "email":"john.smith@email.com",
        "country":"US"
   },
    "timeStamp": "20200118191751",
    "checksum": "6b53666fc048a825be63cbb820da467b"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
//Initialize the SDK (see https://docs.safecharge.com/?p=53443)

// openOrder
safecharge.paymentService.openOrder({
    userTokenId: "230811147",
    clientUniqueId: "12345",
    clientRequestId: "1C6CT7V1L",
    currency: "USD",
    amount: "200",
    billingAddress: {
        email: "john.smith@email.com",
        country: "US"
    },
}, function(err, result) {
    console.log(err, result);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
//Initialize the SDK (see https://docs.safecharge.com/?p=29433)

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

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

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

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

<?php
//openOrder
$openOrderRequest = $SafeCharge->getPaymentService()->openOrder([
    'userTokenId'       => '230811147',
    'clientUniqueId'    => '12345',
    'clientRequestId'   => '1C6CT7V1L',
    'currency'          => 'USD',
    'amount'            => '200',
    'billingAddress' => [
        'country'   => "US",
        "email"     => "john.smith@email.com",
    ],
]);
?>

1
2
3
4
5
6
7
8
9
10
11
12
13
//Initialize the SDK (see https://docs.safecharge.com/?p=48413)

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

Example Response

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

Calling the server-side /openOrder API request is the (recommended) first step in a Web SDK flow. /openOrder authenticates your Nuvei merchant credentials, sets up an order in the Nuvei system, and returns a sessionToken. sessionToken must be included in all subsequent Web SDK method calls in that session, such as for createPayment().

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

@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 must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
timeStamp ^String(14) ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss This is needed for the “checksum” hashing calculation.
checksum ^String(256) ~Required	The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey Press here to see an example.
currency ^String(3) ~Required	The 3-letter ISO currency code. This field is required when using the Web SDK createPayment() method.
amount ^String(12) ~Required	The transaction amount. This field is required when using the Web SDK createPayment() method.
billingAddress ^Class ~country and email Required	country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30) lastName (String, 40) address (String, 60) cell (String, 18) phone (String, 18) zip (String, 10) city (String, 30) state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). county (String, 255) addressMatch (String, 1) – Set to “Y” when address matches shipping address addressLine2 (String, 50) addressLine3 (String, 50) homePhone (String) workPhone (String)
externalSchemeDetails ^Class ~Conditional	Use this class if you want to process an MIT/recurring transaction that was initiated with another processor. Press here for more details. transactionId (String, 50) – Original transactionId for the initial payment as originated in the external system. Press here to view the structure of the parameter. brand (String, 20) – The card brand. Currently supported with the following values:     VISA     MASTERCARD     AMEX
authenticationOnlyType ^String(30) ~Conditional	If you are not using User Payment Management (tokenization) and would like to send Zero Amount Authorization, you need to set authenticationOnlyType to one of the following values: RECURRING INSTALLMENTS ADDCARD MAINTAINCARD ACCOUNTVERIFICATION
userTokenId ^String(255) ~Conditional	This ID uniquely identifies your consumer/user in your system. It is REQUIRED if you wish to use the userPaymentOptionId field for future charging of this user without re-collecting the payment details (see User Payment Management for details).
isRebilling ^Integer(2) ~Conditional	When performing recurring/rebilling, use this field to indicate the recurring step with the following values: 0 – For the initiating recurring event (first recurring transaction). 1 – For all subsequent recurring transactions. Notes:     • Rebilling can be performed using userPaymentOptionId or card (under the paymentOption block).     • If isRebilling=1:         ▫ Send relatedTransactionId.         ▫ isRebilling can never be sent with the threeD block (under the paymentOption block).         ▫ For a 3D-Secure transaction, you also must specify rebillExpiry and rebillFrequency under the           v2AdditionalParams block, under the threeD block.
subMerchant ^Class ^Optional	countryCode (String,2) – The payment facilitator’s sub-merchant’s 2-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 is forwarded to Mastercard as “SubMerchantId”.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this field is used to prevent idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
transactionType ^String(45) ^Optional	The type of transaction: Sale, Auth, or PreAuth. Sale – Performs a regular payment request. Auth – Performs an authorization-only request. Press here for more details. PreAuth – Performs an authorization-only request (with a longer settlement period). Press here for more details.
paymentOption.card.threeD ^Class Path ^Optional	Using Web SDK, you can use the threeD Input Class to pass certain 3D-Secure parameters. These parameters cannot be passed directly using the Web SDK to prevent user manipulation. Refer to threeD Input Class for class specific fields details.
paymentOption.card.storedCredentials ^Class Path ^Optional	For storing card credentials, refer to storedCredentials Class.
deviceDetails ^Class ^Optional	ipAddress (String, 15) deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255)
amountDetails ^Class ^Optional	totalShipping totalHandling totalDiscount totalTax The items and amountDetails prices should be summed up in the amount parameter and sent separately.
items ^Array ^Optional	An array describing the items in the purchase. name (String, 255) price (String, 10) quantity (String, 10) The items and amountDetails prices should be summed up in the amount parameter and sent separately. All prices must be in the same currency.
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This currently represents the social security number (SSN) of United States citizens. If you have only one set of this user information (not including identification) to send in the request, it must be sent using the billingAddress block.
shippingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 60) cell (String, 18) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). email (100) shippingCounty (String, 255) addressLine2 (String, 50) addressLine3 (String, 50) If you have only one set of this user information to send in the request, it must be sent using the billingAddress block.
dynamicDescriptor ^Class ^Optional	merchantName (String, 25) – The merchant name, as is displayed for the transaction on the consumer’s card statement. For payment facilitator only, the maximum length of the parameter is 22, consisting of the following structure: XXX*<merchant name> where:   • XXX – The PayFac prefix, approved by Nuvei Underwriting Team.     Can be a length of 3, 7, 9, or 12.   • * – A fixed character.   • <merchant name> – Sub-merchant name.     Can be a length of 18, 14, 12, or 9, respectively. merchantPhone (String, 13) – The merchant contact information, as is displayed for the transaction on the consumer’s card statement. It can also be an email address.
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 This allows the merchant to send information with the request to be saved in the API level and returned in response.
urlDetails ^Class ^Optional	Although DMN responses can be configured per merchant site, it allows dynamically returning the DMN to the provided address per request. successUrl (String, 1000) – The URL the customer is directed to after a successful transaction. failureUrl (String, 1000) – The URL the customer is directed to after an unsuccessful transaction. pendingUrl (String, 1000) – The URL the customer is directed to when the transaction response is pending. notificationUrl (String, 1000) – The URL to which DMNs are sent.
addendums ^Class ^Optional	This class contains industry specific addendums. The addendum fields that appear are based on the specific addendum type. See addendums Class for more details.
preventOverride ^Boolean ^Optional	Enables the merchant to override /openOrder with the Web SDK input for the following parameters: 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 ignores any Web SDK input of these parameters and uses the ones provided on /openOrder, even if these are blank.
currencyConversion ^Class ^Optional	type (String, 10) – Indicates the currency conversion type.     Possible values: MCP, DCC originalAmount (String, 12) – The original amount of the transaction in the merchant’s own currency. originalCurrency (String, 3) – The 3-letter ISO currency code of the merchant’s own currency.

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier to be used by the request that processed the newly opened order.
merchantId ^String(20)	Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
clientUniqueId ^String(255)	The ID of the transaction in the merchant’s system.
internalRequestId ^String(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
merchantDetails ^Class	customField1 (String, 255) … customField15 This allows the merchant to send information with the request to be saved in the API level and returned in response.
status ^String(20)	The status of merchant’s API request/call. Possible values: SUCCESS, ERROR.
errCode ^String(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
version ^String(10)	The current version of the request. The current version is 1.
orderId ^String(20)	The order ID provided by Nuvei.
clientRequestId ^String(20)	The ID of the API request in the merchant’s system.

/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
{
    "sessionToken":"e524e7c5-9855-4ce9-b0f9-1045f34fd526",
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "userTokenId":"230811147",
    "clientUniqueId":"12345",
    "clientRequestId":"1C6CT7V1L",
    "amount":"200",
    "currency":"USD",
    "paymentOption":{
        "card":{
            "cardNumber":"4000027891380961",
            "cardHolderName":"John Smith",
            "expirationMonth":"12",
            "expirationYear":"2026",
            "CVV":"217",
            "threeD": { "methodNotificationUrl": "<methodNotificationURL>"
            }
        }
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    }
}

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

safecharge.paymentService.initPayment({
    userTokenId            : "230811147",
    amount                 : "200",
    currency               : "USD",
    paymentOption  : {
        "card":{
            cardNumber      : "4000027891380961",
            cardHolderName  : "John Smith",
            expirationMonth : "12",
            expirationYear  : "2026",
            CVV             : "217",
            threeD          : {
                "methodNotificationUrl": "<methodNotificationURL>" }
        }
    },
    deviceDetails  : {
        ipAddress  : "127.0.0.1"
    },
}, 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
//Initialize the SDK (see https://docs.safecharge.com/?p=29433)

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

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
//Initialize the SDK (see https://docs.safecharge.com/?p=53233)

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

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

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

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
    "reason": "",
    "orderId": "33704071",
    "transactionStatus": "APPROVED",
    "customData": "merchant custom data",
    "internalRequestId": 10036001,
    "version": "1.0",
    "transactionId": "2110000000000587378",
    "merchantSiteId": "142033",
    "transactionType": "InitAuth3D",
    "gwExtendedErrorCode": 0,
    "gwErrorCode": 0,
    "merchantId": "427583496191624621",
    "clientUniqueId": "12345",
    "errCode": 0,
    "paymentOption": {
        "card": {
            "ccCardNumber": "5****5761",
            "bin": "511142",
            "threeD": {
                "methodPayload": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImVkNGZlNTkzLWUzMWUtNDEyMC05M2EwLTBkNDBhNzUxNzEzMSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ3d3cuVGhpc0lzQU1ldGhvZE5vdGlmaWNhdGlvblVSTC5jb20ifQ==",
                "methodUrl": "https://srv-azr-acq2:4435/api/ThreeDSMethod/threeDSMethodURL",
                "v2supported": "true",
                "serverTransId": "ed4fe593-e31e-4120-93a0-0d40a7517131",
                "version": "2.1.0",
                "directoryServerId":"A000000003",
                "directoryServerPublicKey":"MIIFrjCCBJagAwIBAgIQB2rJm.."
            },
            "ccExpMonth": "12",
            "ccExpYear": "25",
            "last4Digits": "5761"
        }
    },
    "sessionToken": "e524e7c5-9855-4ce9-b0f9-1045f34fd526",
    "userTokenId": "230811147",
    "status": "SUCCESS"
}

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

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

@Links URLs

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

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

Input Parameters

Parameter	Description
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The merchant site ID provided by Nuvei.
clientUniqueId ^String(45) ~Required	The ID of the transaction in the merchant’s system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
currency ^String(3) ~Required	The 3-letter ISO currency code. If the merchant did not call /openOrder prior, then a value must be sent by the merchant in this parameter.
amount ^String(12) ~Required	The transaction amount. If the merchant did not call /openOrder prior, then a value must be sent by the merchant in this parameter.
paymentOption ^Class ~Required	This class represents the details of the payment method. Set it with one of 2 options: • card – Card data that must be passed as a parameter in the payment methods and not prior in the payment flow (/openOrder), as it may not be saved in the cashier/checkout database.     ▫ cardNumber (String, 20, REQUIRED) – The card number.     ▫ cardHolderName (String, 70, REQUIRED) – The card holder name.     ▫ expirationMonth (String, 2, REQUIRED) – The card expiration month.     ▫ expirationYear (String, 4, REQUIRED) – The card expiration year.     ▫ CVV (String, 4, REQUIRED) – The CVV/CVC security code.     -or-     For payment with a temporary token generated by getToken() instead of card details:            ccTempToken (String, 45)            cardHolderName (String, 70)     Advanced card scenario:     For a 3D-Secure payment, use the threeD class with the following field:     threeD.methodNotificationUrl (String, 255) – The URL the ACS redirects to after performing the 3D-Secure v2 fingerprinting. Refer to 3D-Secure Fingerprinting 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. 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.
urlDetails ^Class ^Optional	Although DMN responses can be configured per merchant site, it allows dynamically returning the DMN to the provided address per request. successUrl (String, 1000) – The URL the customer is directed to after a successful transaction. failureUrl (String, 1000) – The URL the customer is directed to after an unsuccessful transaction. pendingUrl (String, 1000) – The URL the customer is directed to when the transaction response is pending. notificationUrl (String, 1000) – The URL to which DMNs are sent.
billingAddress ^Class ^Optional	addressMatch (String, 1) – Set to “Y” when address matches shipping address city (String, 30) country (String, 2) – 2-letter ISO country code. Must be entered in uppercase. address (String, 60) addressLine2 (String, 50) addressLine3 (String, 50) zip (String, 10) state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100) phone (String, 18) cell (String, 18) firstName (String, 30) lastName (String, 40)
deviceDetails ^Class ~ipAddress Required	ipAddress (String, 15, REQUIRED) deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255)
userTokenId ^String(255) ~Conditional	This ID uniquely identifies your consumer/user in your system. It is REQUIRED if you wish to use the userPaymentOptionId field for future charging of this user without re-collecting the payment details (see User Payment Management for details).
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this field is used to prevent idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
customData ^String(255) ^Optional	This parameter can be used to pass any type of information. If sent in request, then it is visible in Nuvei’s back-office tool transaction reporting and is returned in response.
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 by Nuvei REST API SDKs to send the plugin/SDK name and version so that Support is able to identify from where the transaction arrived at the REST API Gateway.
orderId ^String(45) ^Optional	The ID to be used as an input parameter in the update method and payment methods. The parameter is sent to define which merchant order to update.

Output Parameters

Parameter	Description
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
clientUniqueId ^String(255)	The ID of the transaction in the merchant’s system.
internalRequestId ^String(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 values: SUCCESS, 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 (such as “failure in checksum validation” and “timeout from processing engine”) if an error occurred on the cashier side.
gwErrorCode ^String(11)	The error reason code if an error occurred. 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.
gwExtendedErrorCode ^String(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 current version of the API method. The current version is 1.
paymentOption ^Class	This class contains the card information inside the card subclass and the userPaymentOptionId, as detailed in the following lines.
paymentOption.userpaymentOptionId ^String(45)	If initPayment was processed with userPaymentOptionId rather than having provided the card block, this field echoes back the same userPaymentOptionId that was provided in the input.
paymentOption.card ^Class	bin (String, 6) – The BIN number of the credit card. last4Digits (String, 4) – The last four digits of the credit card number. ccCardNumber (String, 20) – The masked credit card number, for example: 4****1111. ccExpMonth (String, 2) – The 2-digit value representing the expiration month. ccExpYear (String, 4) – The 4-digit value representing the expiration year. ccTempToken (String, 36) – A temporary card token to be used during the same session. threeD (Class) – A class containing the 3D-Secure information.
paymentOption.card.threeD ^Class	methodUrl (String, 256) – The 3D “Method URL” required for 3D-Secure fingerprinting, as described in 3D-Secure Fingerprinting. version (String, 8) – The 3D-Secure version.     Possible values: 2.1.0 (if 3D-Secure v2 flow used) or null (not used). v2supported (Boolean) – 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 3D-Secure Fingerprinting.     Possible values: 0 (not supported) or 1 (supported). directoryServerId (String) – The 3D-Secure directory server ID. Relevant only for the 3D Mobile SDK. directoryServerPublicKey (String) – The 3D-Secure directory public encryption key. Relevant only for the 3D Mobile SDK.
cardType ^String	The type of card used in the transaction. Possible values: credit, debit
issuerCountry ^String(2)	2-letter ISO code of the card issuer’s country.
orderId ^String(20)	The ID returned from the MerchantOrderID input parameter in update and payment methods. This parameter is returned to define which merchant order to update.
clientRequestId ^String(20)	The ID of the API request in the merchant’s system.

/payment

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
    "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "clientRequestId":"1C6CT7V1L",
    "amount":"100",
    "currency":"USD",
    "userTokenId":"230811147",
    "clientUniqueId":"12345",
    "paymentOption":{
        "card":{
            "cardNumber":"4000027891380961",
            "cardHolderName":"John Smith",
            "expirationMonth":"12",
            "expirationYear":"2026",
            "CVV":"217"
        }
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "billingAddress":{
        "email":"john.smith@email.com",
        "country":"US"
    },
    "timeStamp":"20191105081132",
    "checksum":"5582d0189dd440f4bbf960569ec22e77"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
    "timeStamp":"20200623135114",
    "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "clientRequestId":"1C6CT7V1L",
    "amount":"100",
    "currency":"USD",
    "userTokenId":"230811147",
    "clientUniqueId":"12345",
    "paymentOption":{
        "card":{
            "cardNumber":"4000027891380961",
            "cardHolderName":"John Smith",
            "expirationMonth":"12",
            "expirationYear":"2026",
            "CVV":"217",
            "threeD":{
                "browserDetails":{
                    "acceptHeader":"text/html,application/xhtml+xml",
                    "ip":"192.168.1.11",
                    "javaEnabled":"TRUE",
                    "javaScriptEnabled":"TRUE",
                    "language":"EN",
                    "colorDepth":"48",
                    "screenHeight":"400",
                    "screenWidth":"600",
                    "timeZone":"0",
                    "userAgent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)"
                },
                "version":"2",
                "notificationUrl":"<notificationURL>",
                "merchantUrl":"<merchantURL>",
                "platformType":"02",
                "v2AdditionalParams":{
                    "challengeWindowSize":"05"
                }
            }
        },
        "deviceDetails":{
            "ipAddress":"127.0.0.1"
        },
        "billingAddress":{
            "email":"john.smith@email.com",
            "country":"US"
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
    "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "clientRequestId":"1C6CT7V1L",
    "amount":"200",
    "currency":"USD",
    "userTokenId":"230811147",
    "clientUniqueId":"12345",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_MoneyBookers",
            "account_id":"SkrillTestUser3"
        }
    },
    "billingAddress":{
        "country":"US",
        "email":"john.smith@email.com"
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "timeStamp":"20191105081140",
    "checksum":"edfb11a5c5ea8b2a7f53a6bc623226c0"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
    "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "clientRequestId":"1C6CT7V1L",
    "amount":"200",
    "currency":"USD",
    "userTokenId":"230811147",
    "clientUniqueId":"12345",
    "paymentOption":{
        "card":{
            "cardNumber":"4000027891380961",
            "cardHolderName":"John Smith",
            "expirationMonth":"12",
            "expirationYear":"2026",
            "CVV":"217",
            "threeD":{
                "methodCompletionInd":"Y",
                "version":"2.1.0",
                "notificationURL":"<notificationURL>",
                "merchantURL":"<merchantURL>",
                "platformType":"02",
                "v2AdditionalParams":{
                    "challengeWindowSize":"05"
                },
                "browserDetails":{
                    "acceptHeader":"text/html,application/xhtml+xml",
                    "ip":"192.168.1.11",
                    "javaEnabled":"TRUE",
                    "javaScriptEnabled":"TRUE",
                    "language":"EN",
                    "colorDepth":"48",
                    "screenHeight":"400",
                    "screenWidth":"600",
                    "timeZone":"0",
                    "userAgent":"Mozilla"
                }
            }
        }
    },
    "relatedTransactionId":"<transactionId returned from /initPayment>",
    "billingAddress":{
        "country":"US",
        "email":"john.smith@email.com"
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "timeStamp":"20191105091105",
    "checksum":"328bd06ea3f696229d1387c9313dfd1e"
}

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
    "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "clientRequestId":"1C6CT7V1L",
    "amount":"200",
    "currency":"USD",
    "userTokenId":"230811147",
    "clientUniqueId":"12345",
    "paymentOption":{
        "card":{
            "cardNumber":"4000027891380961",
            "cardHolderName":"John Smith",
            "expirationMonth":"12",
            "expirationYear":"2026",
            "CVV":"217",
            "threeD":{
                "externalMpi":{
                    "eci":"2",
                    "cavv":"ejJRWG9SWWRpU2I1M21DelozSXU=",
                    "dsTransID":"9e6c6e9b-b390-4b11-ada9-0a8f595e8600"
                }
            }
        }
    },
    "billingAddress":{
        "country":"US",
        "email":"john.smith@email.com"
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "timeStamp":"20191105091144",
    "checksum":"42b44b5ffe82d625abbd8b2c61b721a3"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
    "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "clientRequestId":"1C6CT7V1L",
    "amount":"200",
    "currency":"USD",
    "userTokenId":"230811147",
    "clientUniqueId":"12345",
     "paymentOption": {
        "userPaymentOptionId": "1459503",
        "card":{
            "CVV":"217"
        }
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "billingAddress":{
        "email":"john.smith@email.com",
        "country":"US"
    },
    "timeStamp":"20191105081132",
    "checksum":"5582d0189dd440f4bbf960569ec22e77"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
    "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "clientRequestId":"1C6CT7V1L",
    "amount":"200",
    "currency":"USD",
    "userTokenId":"230811147",
    "clientUniqueId":"12345",
    "paymentOption":{
        "card":{
            "externalToken":{
                "externalTokenProvider":"ApplePay",
                "mobileToken":"{\"paymentData\":{\"version\":\"EC_v1\",\"data\":\"2uhvZkdQfbZw8I4X9tZ8FijeTufEdcU61hMiuRKPyk43zqC9e6bnyNANZkbeZPyEvoZY1HtAQcmKm04GyoP+wG9L4OHIPi0SXd1GOR0mB7iVTQqcBElNYQfHESh9xj480o8A1KrkI5YW3rxEOxgjpi6520fXe9Tvs4r9iF9Bmc4lbWKyyZxLH7L12ThxdGoIcR25E4NADv4EidgTPjavEeF1xuBXuej+bD2WnEGOUtJpj8V43qvpZz2NUDxAC0yRxgOBomEMPjcJWVlWGuKFI700rs4Fx+UkIHhl\/diRM71OmPeoaTRyf\/qShuCNBz\/cxdyG\/rZtFLFY\/coUS3MHWzCYgdPNetPImf1jTrh+k4VFsJb9uh54b7h6mNUQEzFV\/EGVJJoNtDaT4cVYn\/xywUAkrCcOmEWyFrM90ukwPg0=\",\"signature\":\"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID5jCCA4ugAwIBAgIIaGD2mdnMpw8wCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE2MDYwMzE4MTY0MFoXDTIxMDYwMjE4MTY0MFowYjEoMCYGA1UEAwwfZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtU0FOREJPWDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgjD9q8Oc914gLFDZm0US5jfiqQHdbLPgsc1LUmeY+M9OvegaJajCHkwz3c6OKpbC9q+hkwNFxOh6RCbOlRsSlaOCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwHQYDVR0OBBYEFAIkMAua7u1GMZekplopnkJxghxFMAwGA1UdEwEB\/wQCMAAwHwYDVR0jBBgwFoAUI\/JJxE+T5O8n5sT2KGw\/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB\/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB\/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0kAMEYCIQDaHGOui+X2T44R6GVpN7m2nEcr6T6sMjOhZ5NuSo1egwIhAL1a+\/hp88DKJ0sv3eT3FxWcs71xmbLKD\/QJ3mWagrJNMIIC7jCCAnWgAwIBAgIISW0vvzqY2pcwCgYIKoZIzj0EAwIwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcNMTQwNTA2MjM0NjMwWhcNMjkwNTA2MjM0NjMwWjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwFxGEGddkhdUaXiWBB3bogKLv3nuuTeCN\/EuT4TNW1WZbNa4i0Jd2DSJOe7oI\/XYXzojLdrtmcL7I6CmE\/1RFo4H3MIH0MEYGCCsGAQUFBwEBBDowODA2BggrBgEFBQcwAYYqaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZXJvb3RjYWczMB0GA1UdDgQWBBQj8knET5Pk7yfmxPYobD+iu\/0uSzAPBgNVHRMBAf8EBTADAQH\/MB8GA1UdIwQYMBaAFLuw3qFYM4iapIqZ3r6966\/ayySrMDcGA1UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB\/wQEAwIBBjAQBgoqhkiG92NkBgIOBAIFADAKBggqhkjOPQQDAgNnADBkAjA6z3KDURaZsYb7NcNWymK\/9Bft2Q91TaKOvvGcgV5Ct4n4mPebWZ+Y1UENj53pwv4CMDIt1UQhsKMFd2xd8zg7kGf9F3wsIW2WT8ZyaYISb1T4en0bmcubCYkhYQaZDwmSHQAAMYIBjDCCAYgCAQEwgYYwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTAghoYPaZ2cynDzANBglghkgBZQMEAgEFAKCBlTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0yMDA1MTQxMTEzMDJaMCoGCSqGSIb3DQEJNDEdMBswDQYJYIZIAWUDBAIBBQChCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIJPkOnv7VCVYvnXUWwIchmkON4dVtXHsTssY1uMJkn0XMAoGCCqGSM49BAMCBEcwRQIhAMzNQ\/Xw8dxOD3V\/tizLXRpV77PpcfTpYUUpN0gJztrqAiBWqco9HpLSoVN5ySEmZdAGRuer2Az06xRkmsToV03rnQAAAAAAAA==\",\"header\":{\"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEAnHMlqALgHhQoT5tf1Df9WApE6gFx6LgZaSUAOkikr4Tn97T2pgi3Iz9guCcHOCcfelv+qfPcHzfBbvs4UWilg==\",\"publicKeyHash\":\"STh9vCW6aUGJLEEtdHr1w0AHd1uDXgrNOGNZqKcKW9g=\",\"transactionId\":\"e5cf25993cbf76cac2467aece05ad07be7aeebcc439efe2e957dd1b6f556ffae\"}},\"paymentMethod\":{\"displayName\":\"Visa 4228\",\"network\":\"Visa\",\"type\":\"debit\"},\"transactionIdentifier\":\"E5CF25993CBF76CAC2467AECE05AD07BE7AEEBCC439EFE2E957DD1B6F556FFAE\"}"
            }
        }
    },
    "billingAddress":{
        "email":"john.smith@email.com",
        "country":"US"
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "timeStamp":"20200517130543",
    "checksum":"de0e48812c269933d9eb37e74db45f1c"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
//Initialize the SDK (see https://docs.safecharge.com/?p=53443)

safecharge.paymentService.createPayment({
    amount       : "100",
    currency     : "USD",
    sessionToken : "9610a8f6-44cf-4c4f-976a-005da69a2a3b", /* taken from /openOrder result */
    paymentOption: {
        card: {
            expirationYear : "2026",
            CVV            : "217",
            cardHolderName : "John Smith",
            expirationMonth: "12",
            cardNumber     : "4000027891380961"
        }
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
//Initialize the SDK (see https://docs.safecharge.com/?p=53443)

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

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

$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    currency       : "USD",
    amount         : "200",
    userTokenId    : "230811147",
    clientRequestId: "1C6CT7V1L",
    clientUniqueId : "12345",
    paymentOption  : {
        alternativePaymentMethod : {
            paymentMethod      : "apmgw_MoneyBookers",
            account_id  : "SkrillTestUser3"
        }
    },
    billingAddress : {
        country   : "US",
        email     : "john.smith@email.com"
    },
    deviceDetails  : {
        ipAddress  : "127.0.0.1"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
//Initialize the SDK (see https://docs.safecharge.com/?p=53443)

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

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

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

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

$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    currency       : "USD",
    amount         : "200",
    userTokenId    : "230811147",
    clientRequestId: "1C6CT7V1L",
    clientUniqueId : "12345",
    paymentOption  : {
        card : {
            cardNumber      : "4000027891380961",
            cardHolderName  : "John Smith",
            expirationMonth : "12",
            expirationYear  : "2026",
            CVV             : "217",
            threeD :{
                externalMpi :{
                    eci       : "2",
                    cavv          : "ejJRWG9SWWRpU2I1M21DelozSXU",
                    dsTransID         : "9e6c6e9b-b390-4b11-ada9-0a8f595e8600"  // xid in case of 3Dv1
                }
            }
        }
    },
    billingAddress : {
        country   : "US",
        email     : "john.smith@email.com"
    },
    deviceDetails  : {
        ipAddress  : "127.0.0.1"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
//Initialize the SDK (see https://docs.safecharge.com/?p=53443)

safecharge.paymentService.createPayment({
    amount       : "100",
    currency     : "USD",
    sessionToken : "9610a8f6-44cf-4c4f-976a-005da69a2a3b", /* taken from /openOrder result */
    paymentOption: {
        userPaymentOptionId: "1459503"
        card: {
            CVV : "217"
        }
    },
}, 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
//Initialize the SDK (see https://docs.safecharge.com/?p=29433)

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

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
//Initialize the SDK (see https://docs.safecharge.com/?p=29433)

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

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("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.setChallengeWindowSize("2");

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
//Initialize the SDK (see https://docs.safecharge.com/?p=29433)

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

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
//Initialize the SDK (see https://docs.safecharge.com/?p=29433)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
//Initialize the SDK (see https://docs.safecharge.com/?p=29433)

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

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

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

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
    String clientRequestId = "1C6CT7V1L";
    String clientUniqueId = "12345";
    String currency = "USD";
    String amount = "200";
    String userTokenId = "230811147";

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
//Initialize the SDK (see https://docs.safecharge.com/?p=53233)

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'USD',
    'amount'         => '100',
    'userTokenId'    => '230811147',
    'clientRequestId'=> '1C6CT7V1L',
    'clientUniqueId'=> '12345',
    'paymentOption'  => [
        'card' => [
            'cardNumber'      => '4000027891380961',
            'cardHolderName'  => 'John Smith',
            'expirationMonth' => '12',
            'expirationYear'  => '2022',
            'CVV'             => '217',
        ]
    ],
    'billingAddress' => [
        'country'   => 'US',
        "email"     => 'john.smith@email.com',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '127.0.0.1',
    ],
]);
?>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
//Initialize the SDK (see https://docs.safecharge.com/?p=53233)

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

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

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'USD',
    'amount'         => '200',
    'userTokenId'    => '230811147',
    'clientRequestId'=> '1C6CT7V1L',
    'clientUniqueId'=> '12345',
    'paymentOption'  => [
        'alternativePaymentMethod' => [
            'paymentMethod'      => 'apmgw_MoneyBookers',
            'account_id'  => 'SkrillTestUser3'
        ]
    ],
    'billingAddress' => [
        'country'   => 'US',
        'email'     => 'john.smith@email.com',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '127.0.0.1',
    ],
]);
?>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
//Initialize the SDK (see https://docs.safecharge.com/?p=53233)

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
//Initialize the SDK (see https://docs.safecharge.com/?p=53233)

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'USD',
    'amount'         => '200',
    'userTokenId'    => '230811147',
    'clientRequestId'=> '1C6CT7V1L',
    'clientUniqueId'=> '12345',
    'paymentOption'  => [
        'card' => [
            'cardNumber'      => '4000027891380961',
            'cardHolderName'  => 'John Smith',
            'expirationMonth' => '12',
            'expirationYear'  => '2022',
            'CVV'             => '217',
            'threeD' =>[
                'externalMpi' =>[
                    'eci'       => '2',
                    'cavv'          => 'ejJRWG9SWWRpU2I1M21DelozSXU',
                    'dsTransID'         => '9e6c6e9b-b390-4b11-ada9-0a8f595e8600'  // xid in case of 3Dv1
                ]
            ]
        ]
    ],
    'billingAddress' => [
        'country'   => 'US',
        'email'     => 'john.smith@email.com',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '127.0.0.1',
    ],
]);
?>

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

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'USD',
    'amount'         => '100',
    'userTokenId'    => '230811147',
    'clientRequestId'=> '1C6CT7V1L',
    'clientUniqueId'=> '12345',
    'paymentOption'  => [
        'userPaymentOptionId' => '1459503',
        'card' => [
            'CVV'             => '217',
        ]
    ],
    'billingAddress' => [
        'country'   => "US",
        "email"     => "john.smith@email.com",
    ],
    'deviceDetails'  => [
        "ipAddress"  => "127.0.0.1",
    ],
]);
?>

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
//Initialize the SDK (see https://docs.safecharge.com/?p=48413)

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

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

var response = safecharge.Payment(
    "USD",
    "200",
    new PaymentOption
    {
        AlternativePaymentMethod = new Dictionary<string, string>()
        {
            { "paymentMethod", "apmgw_MoneyBookers" },
            { "account_id", "SkrillTestUser3" }
        }
    },
    clientUniqueId: "12345",
    clientRequestId: "1C6CT7V1L",
    userTokenId: "230811147",
    billingAddress: new UserAddress
    {
        Country = "US",
        Email = "john.smith@safecharge.com"
    },
    deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" });

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
//Initialize the SDK (see https://docs.safecharge.com/?p=48413)

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
//Initialize the SDK (see https://docs.safecharge.com/?p=48413)

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
//Initialize the SDK (see https://docs.safecharge.com/?p=48413)

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

1
COMING SOON

Example Response

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

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 v2
  
• APM transactions

Required Fields

• Authentication credentials – sessionToken, merchantId, merchantSiteId, checksum, timeStamp, and country and email (under billingAddress)
  
• 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 the following three options:

• card – Subclass for credit/debit cards. This contains either the card details (number, expiration, etc.) and 3D-Secure information (if required), or the temporary token information.
  
• alternativePaymentMethod – Subclass 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 a previous use.

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The merchant ID provided by Nuvei (part of the authentication credentials).
merchantSiteId ^String(20) ~Required	The merchant site ID provided by Nuvei (part of the authentication credentials).
sessionToken ^String(36) ~Required	Session identifier returned by /getSessionToken.
timeStamp ^String(14) ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^String(256) ~Required	The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey Press here to see an example.
currency ^String(3) ~Required	The 3-letter ISO currency code.
amount ^String(12) ~Required	The transaction amount.
paymentOption ^Class ~Required	This class represents the details of the payment method. Set it with one of 3 options: • card – Represents a credit/debit card.     ▫ cardNumber (String, 20, REQUIRED) – The card number.     ▫ cardHolderName (String, 70, REQUIRED) – The card holder name.     ▫ expirationMonth (String, 2, REQUIRED) – The card expiration month.     ▫ expirationYear (String, 4, REQUIRED) – The card expiration year.     ▫ CVV (String, 4, REQUIRED) – The CVV/CVC security code.     -or-     For payment with a temporary token generated by getToken() instead of card details:            ccTempToken (String, 45)            cardHolderName (String, 70)     Advanced card scenarios:       ▫ For 3D-Secure, please refer to threeD Input Class.       ▫ When using an external token provider such as Apple Pay or Visa Checkout, refer to externalToken Class.       ▫ For storing card credentials, refer to storedCredentials Class. OR • alternativePaymentMethod – Represents an APM. For details, please refer to APM Input Fields and APIs. 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. 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. __________ • subMethod – This class allows using an APM but with a different payment flow.     ▫ subMethod (String, 50) – The APM name.     ▫ email (String, 255) – If no email is provided, it is automatically populated from billingAddress. For more information, see APM Submethod Classes.
deviceDetails ^Class ~ipAddress Required	ipAddress (String, 15, REQUIRED) deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255)
billingAddress ^Class ~country and email Required	The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters. country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30) lastName (String, 40) address (String, 60) address2 (String, 60) phone (String, 18) zip (String, 10) city (String, 30) state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). county (String, 255) Note: For all cross-border Visa Direct OCTs to/from Canada, the following recipient parameters are REQUIRED: address, city, state, country. These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.
relatedTransactionId ^String(19) ~Conditional	REQUIRED in the following cases: • For 3D-Secure v2 (refer to our 3D-Secure Guide for details):     ▫ The transaction ID of the initPayment on the first call.     ▫ The transaction ID of the first Payment call of the second call. • For 3D-Secure (Version 1) or non-3D:     ▫ The Transaction ID of the first payment call on the second call. • For recurring/rebilling and MIT:     ▫ Represents the reference to the original transaction ID of the initial transaction (see Merchant-Initiated Transactions for details).
externalSchemeDetails ^Class ~Conditional	Use this class if you want to process an MIT/recurring transaction that was initiated with another processor. Press here for more details. transactionId (String, 50) – Original transactionId for the initial payment as originated in the external system. Press here to view the structure of the parameter. brand (String, 20) – The card brand. Currently supported with the following values: VISA MASTERCARD AMEX
authenticationOnlyType ^String(30) ~Conditional	If you are not using User Payment Management (tokenization) and would like to send Zero Amount Authorization, you need to set authenticationOnlyType to one of the following values: RECURRING INSTALLMENTS ADDCARD MAINTAINCARD ACCOUNTVERIFICATION
userTokenId ^String(255) ~Conditional	This ID uniquely identifies your consumer/user in your system. It is REQUIRED if you wish to use the userPaymentOptionId field for future charging of this user without re-collecting the payment details (see User Payment Management for details).
userDetails ^Class ~Conditional	For certain APMs, some fields are REQUIRED, as detailed in the APM Payments table. firstName (String, 30) lastName (String, 40) address (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This currently represents the social security number (SSN) of United States citizens.
isRebilling ^Integer(2) ~Conditional	When performing recurring/rebilling, use this field to indicate the recurring step with the following values: 0 – For the initiating recurring event (first recurring transaction). 1 – For all subsequent recurring transactions. Notes:     • Rebilling can be performed using userPaymentOptionId or card (under the paymentOption block).         In either case, you must send relatedTransactionId as well.     • If isRebilling=1:         ▫ isRebilling can never be sent with the threeD block (under the paymentOption block).         ▫ For a 3D-Secure transaction, you also must specify rebillExpiry and rebillFrequency under the           v2AdditionalParams block, under the threeD block.
subMerchant ^Class ^Optional	countryCode (String,2) – The payment facilitator’s sub-merchant’s 2-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 is forwarded to Mastercard as “SubMerchantId”.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this field is used to prevent idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
clientUniqueId ^String(45) ^Optional	The ID of the transaction in the merchant’s system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
amountDetails ^Class ^Optional	totalShipping (String) totalHandling (String) totalDiscount (String) totalTax (String) The items and amountDetails prices should be summed up in the amount parameter and sent separately. All prices must be in the same currency.
items ^Array ^Optional	An array describing the items in the purchase. name (String, 255, REQUIRED if items is used) price (String, 10, REQUIRED if items is used) quantity (String, 10, REQUIRED if items is used) The items price should be summed up to the amount parameter sent separately. All items must be in the same currency.
shippingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100) shippingCounty (String, 255)
dynamicDescriptor ^Class ^Optional	merchantName (String, 25) – The merchant name, as is displayed for the transaction on the consumer’s card statement. For payment facilitator only, the maximum length of the parameter is 22, consisting of the following structure: XXX*<merchant name> where:   • XXX – The PayFac prefix, approved by Nuvei Underwriting Team.     Can be a length of 3, 7, 9, or 12.   • * – A fixed character.   • <merchant name> – Sub-merchant name.     Can be a length of 18, 14, 12, or 9, respectively. merchantPhone (String, 13) – The merchant contact information, as is displayed for the transaction on the consumer’s card statement. It can also be an email address.
isMoto ^String(1) ^Optional	Set this field to “1” to mark the transaction as MOTO (mail order/telephone order). Leave null or “0” for regular transaction.
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 This allows the merchant to send information with the request to be saved in the API level and returned in response.
urlDetails ^Class ^Optional	Although DMN responses can be configured per merchant site, it allows dynamically returning the DMN to the provided address per request. successUrl (String, 1000) – The URL the customer is directed to after a successful transaction. failureUrl (String, 1000) – The URL the customer is directed to after an unsuccessful transaction. pendingUrl (String, 1000) – The URL the customer is directed to when the transaction response is pending. notificationUrl (String, 1000) – The URL to which DMNs are sent.
transactionType ^String(45) ^Optional	The type of transaction: Sale, Auth, or PreAuth. Sale – Performs a regular payment request. Auth – Performs an authorization-only request. Press here for more details. PreAuth – Performs an authorization-only request (with a longer settlement period). Press here for more details.
isPartialApproval ^String(1) ^Optional	This describes a situation where the deposit was completed and processed with an amount lower than the requested amount due to a consumer’s lack of funds within the desired payment method. Partial approval is only supported by Nuvei acquiring. For partial approval to be available for the merchant it should be configured by Nuvei’s Integration Support Team. Possible values: 1 – Allow partial approval 0 – Not allow partial approval
customSiteName ^String(50) ^Optional	The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name. Risk rules and traffic management rules are usually built based on this field value.
productId ^String(50) ^Optional	A free text field used to identify the product/service sold. If this parameter is not sent or is sent with an empty value, then it contains the concatenation of all item names up until the parameter maximum length. Risk rules and traffic management rules are usually built based on this field value.
customData ^String(255) ^Optional	This parameter can be used to pass any type of information. If sent in request, then it is 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 by Nuvei REST API SDKs to send the plugin/SDK name and version so that Support is able to identify from where the transaction arrived at the REST API Gateway.
orderId ^String(45) ^Optional	The order ID provided by Nuvei. This parameter is passed to define which merchant order to update.
addendums ^Class ^Optional	This class contains industry specific addendums. The addendum fields that appear are based on the specific addendum type. See addendums Class for more details.
currencyConversion ^Class ^Optional	type (String, 10) – Indicates the currency conversion type.     Possible values: MCP, DCC originalAmount (String, 12) – The original amount of the transaction in the merchant’s own currency. originalCurrency (String, 3) – The 3-letter ISO currency code of the merchant’s own currency.

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
clientUniqueId ^String(255)	The ID of the transaction in the merchant’s system.
internalRequestId ^String(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
status ^String(20)	The cashier status of merchant request. Possible values: SUCCESS, ERROR
transactionStatus ^String(20)	The Gateway transaction status. Possible values: APPROVED – The transaction was authorized and approved. DECLINED – The transaction authorization failed. ERROR – An error occurred. Please refer to Error Handling for details. REDIRECT – The transaction was not completed. The end user needs to be redirected to a webpage to complete the transaction. There are two cases in which this response is returned: 3D-Secure – The user needs to be redirected to paymentOption.threeD.acsUrl. See the 3D-Secure Guide for full details. An APM method that requires redirection – The URL is on paymentOption.redirectURL. See our APM Guide for full details.
partialApproval ^Class	Partial approval is when the deposit completes with a processed amount lower than the requested amount due to a lack of sufficient funds in the consumer payment method. requestedAmount (String, 12) – The original requested amount. requestedCurrency (String, 3) – The currency of the original request. processedAmount (String, 12) – The amount that was actually deposited in the transaction. processedCurrency (String, 3) – The currency used in the processed transaction request.
paymentOption ^Class	This class represents the data retrieved from the processed payment method. It can be either card, or in case of APM, it shows the redirectUrl. In addition, the userPaymentOptionId field is retrieved as detailed below: • redirectUrl (String) – The redirect URL to follow for an APM, 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) 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 address verification service (AVS) response.     Possible values:     ◦ A – The street address matches, the ZIP code does not.     ◦ W – Postal code matches, the street address does not.     ◦ Y – Postal code and the street address match.     ◦ X – An exact match of both the 9-digit ZIP code and the street address.     ◦ Z – Postal code matches, the street code does not.     ◦ U – Issuer is unavailable.     ◦ S – AVS not supported by issuer.     ◦ R – Retry.     ◦ B – Not authorized (declined).     ◦ N – Both the street address and postal code do not match.   ▫ acquirerId (String) – The acquirer ID of the acquirer that processed the transaction.   ▫ cardType (String) – The type of card used in the transaction.     Possible values: Credit, Debit   ▫ cardBrand (String) – The card brand used in the transaction.     Possible values: VISA, MASTERCARD, AMEX   ▫ threeD (class) – Contains the required 3D-Secure information. Refer to threeD Output Class for details. OR • userPaymentOptionId – In addition to the above, this field represents the ID for the newly created payment option, which can be referenced in future requests. For full details, refer to Card-on-File.
merchantDetails ^Class	customField1 (String, 255) … customField15 This allows the merchant to send information with the request to be saved in the API level and returned in response.
errCode ^String(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwErrorCode ^String(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^String(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 ^String(10)	The current version of the request. The current version is 1.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
transactionId ^String(20)	The Gateway transaction ID.
authCode ^String(128)	The authorization code of the transaction.
transactionType ^String(45)	The type of transaction: Sale or Auth. Sale – Performs a regular payment request. Auth – Performs an authorization only request. Press here for more details.
customData ^String(255)	This parameter can be used to pass any type of information. If sent in the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back-office tool for transaction reporting and is returned in the response.
fraudDetails ^Class	finalDecision (String) score (decimal) recommendations (String) system (Array) [systemId (String), systemName (String), decision (String)] rules (Array) [ruleId (String), ruleDescription (String)] score refers to a number between 0 and 1 that indicates the probability of a transaction becoming fraudulent, which is calculated using a risk machine learning model. system refers to which risk management system provided the fraud information. The provider can be Nuvei (systemId=1) or an external provider. rules refers to the risk management system rules triggered by the transaction. decision refers to the risk management system decisions regarding the rules that were triggered by the transaction. There are five possible values for the decision parameter: Accept – The risk management system accepts the transactions. Reject – The risk management system rejects the transaction. The transaction is not passed to bank for authorization. The reasons are returned in ruleDescription parameter. Review – The risk management system flags a transaction for review, but still accepts the transaction. Error – An error occurred during the risk management system operation. The Gateway continues to process the transaction through the bank. None – No risk analysis was performed. The Gateway continues to process the transaction through the bank. finalDecision refers to when deciding whether to accept or reject a transaction. The risk management system bases its finalDecision on individual decisions made regarding rules triggered. If none of the rules leads to a Reject decision, the finalDecision accepts the transaction. If at least one of the rules leads to a Reject decision, the finalDecision rejects the transaction. To receive this information in 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
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1C6CT7V1L",
    "clientUniqueId": "12345",
    "amount": "200",
    "currency": "USD",
    "relatedTransactionId": "<transactionId returned from /payment>",
    "timeStamp": "20190915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

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

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

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

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

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

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

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

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

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

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "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 full or partial settlements. When partial settlements are issued, multiple settlement requests can be performed for up to the entire amount of the original authorized transaction.

Press here for more details on settling transactions.

@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 must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
amount ^Decimal(12) ~Required	The transaction amount.
currency ^String(3) ~Required	The 3-letter ISO currency code. It is required to send the same currency as the one sent before for the related transaction.
relatedTransactionId ^String(19) ~Required	The ID of the original Auth transaction to be settled.
timeStamp ^String(14) ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^String(256) ~Required	The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, clientUniqueId, amount, currency, relatedTransactionId, authCode, descriptorMerchantName, descriptorMerchantPhone, comment, urlDetails, timeStamp, merchantSecretKey Press here to see an example.
subMerchant ^Class ^Optional	countryCode (String,2) – The payment facilitator’s sub-merchant’s 2-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 is forwarded to Mastercard as “SubMerchantId”.
clientRequestId ^String(128) ^Optional	Based on the merchant configuration, this field is used to prevent idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
authCode ^String(128) ^Optional	The authorization code of the original Auth transaction to be settled.
descriptorMerchantName ^String(25) ^Optional	Allows the merchant to define a dynamic descriptor, which appears in the payment statement. The name field should contain the merchant name. 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. For dynamic descriptor, special configuration required. For more information, please contact Nuvei’s Integration Support Team.
comment ^String(255) ^Optional	Enables the addition of a free text comment to the request.
urlDetails ^Class ^Optional	notificationUrl (String, 1000) – The URL to which DMNs are sent.
addendums ^Class ^Optional	This class contains industry specific addendums. For /settleTransaction, only airlines is relevant.
customSiteName ^String(50) ^Optional	The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
productId ^String(50) ^Optional	A free text 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 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 by Nuvei REST API SDKs to send the plugin/SDK name and version so that Support is able to identify from where the transaction arrived at the REST API Gateway.
totalSettleCount ^String(12) ^Optional	The number of settlements the merchant wishes to perform in the /settleTransaction method. Possible values: 1 or null – Indicates that the transaction is not a split settlement (normal flow). >1 (integer only) – Indicates the number of settlements into which the transaction is split. Note: This feature is relevant only for merchants with an American merchantId that works via a TSYS bank as an acquirer.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	Merchant Site ID provided by Nuvei.
internalRequestId ^String(20)	The 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 values: SUCCESS, ERROR.
transactionStatus ^String(20)	The Gateway transaction status. Possible values: APPROVED, DECLINED, ERROR
authCode ^String(128)	Authorization code of the transaction.
errCode ^String(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
paymentMethodErrorCode ^String(11)	If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason ^String(400)	If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode ^String(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^String(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 the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back-office tool for transaction reporting and is returned in the response.
version ^String(10)	The current version of the 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
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientUniqueId": "12345",
    "amount": "200",
    "currency": "USD",
    "relatedTransactionId": "2110000000001208909",
    "timeStamp": "20190915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

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

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

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

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

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

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

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

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

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

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "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. To work in this manner, special configuration is required from Nuvei’s side.

Press here for more details on refunding transactions.

@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 must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
amount ^Decimal(12) ~Required	The transaction amount.
currency ^String(3) ~Required	The 3-letter ISO currency code. It is required to send the same currency as the one sent before for the related transaction.
relatedTransactionId ^String(19) ~Required	The ID of the Settle/Sale transaction.
timeStamp ^String(14) ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^String(256) ~Required	The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, clientUniqueId, amount, currency, relatedTransactionId, authCode, comment, urlDetails, timeStamp, merchantSecretKey Press here to see an example.
subMerchant ^Class ^Optional	countryCode (String,2) – The payment facilitator’s sub-merchant’s 2-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 is forwarded to Mastercard as “SubMerchantId”.
clientRequestId ^String(128) ^Optional	Based on the merchant configuration, this field is used to prevent idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
authCode ^String(128) ^Optional	The authorization code of the related Settle/Sale transaction, to be compared to the original one.
comment ^String(255) ^Optional	Enables the addition of a free text comment to the request.
urlDetails ^Class ^Optional	notificationUrl (String, 1000) – The URL to which DMNs are sent.
customSiteName ^String(50) ^Optional	The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
productId ^String(50) ^Optional	A free text 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 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 by Nuvei REST API SDKs to send the plugin/SDK name and version so that Support is able to identify from where the transaction arrived at the REST API Gateway.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	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 purposes).
transactionId ^String(20)	The transaction ID of the refund transaction for future actions.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
status ^String(20)	The status of merchant’s API request/call. Possible values: SUCCESS, ERROR.
transactionStatus ^String(20)	The Gateway transaction status. Possible values: APPROVED, DECLINED, ERROR
authCode ^String(128)	Authorization code of the transaction.
errCode ^String(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
paymentMethodErrorCode ^String(11)	If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason ^String(400)	If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode ^String(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^String(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 the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back-office tool for transaction reporting and is returned in the response.
version ^String(10)	The current version of the 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
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientUniqueId": "12345",
    "amount": "200",
    "currency": "USD",
    "relatedTransactionId": "2110000000001208909",
    "timeStamp": "20190915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

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

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

});

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

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

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

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

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

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

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

Example Response

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

Use this method to void a previous payment.

Press here for more 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 must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
amount ^Decimal(12) ~Required	The transaction amount. It is required to send an amount that is equal to the amount sent in the related transaction that this void aim to cancel.
currency ^String(3) ~Required	The 3-letter ISO currency code. It is required to send the same currency as the one sent before for the related transaction.
relatedTransactionId ^String(19) ~Required	The ID of the original transaction.
timeStamp ^String(14) ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^String(256) ~Required	The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, clientUniqueId, amount, currency, relatedTransactionId, authCode, comment, urlDetails, timeStamp, merchantSecretKey Press here to see an example.
subMerchant ^Class ^Optional	countryCode (String,2) – The payment facilitator’s sub-merchant’s 2-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 is forwarded to Mastercard as “SubMerchantId”.
clientRequestId ^String(128) ^Optional	Based on the merchant configuration, this field is used to prevent idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
authCode ^String(128) ^Optional	The authorization code of the related transaction, to be compared to the original one.
comment ^String(255) ^Optional	Enables the addition of a free text comment to the request.
urlDetails ^Class ^Optional	notificationUrl (String, 1000) – The URL to which DMNs are sent.
customSiteName ^String(50) ^Optional	The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
productId ^String(50) ^Optional	A free text 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 it 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 by Nuvei REST API SDKs to send the plugin/SDK name and version so that Support is able to identify from where the transaction arrived at the REST API Gateway.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
internalRequestId ^String(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
transactionId ^String(255)	The transaction ID of the void transaction for future actions.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
status ^String(20)	The status of merchant’s API request/call. Possible values: SUCCESS, ERROR.
transactionStatus ^String(20)	The Gateway transaction status. Possible values: APPROVED, DECLINED, ERROR
authCode ^String(128)	Authorization code of the transaction.
errCode ^String(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
paymentMethodErrorCode ^String(11)	If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason ^String(400)	If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode ^String(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^String(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 the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back-office tool for transaction reporting and is returned in the response.
version ^String(10)	The current version of the 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
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "230811147",
    "clientUniqueId": "12345",
    "amount": "200",
    "currency": "USD",
    "deviceDetails":{ 
        "ipAddress":"127.0.0.1"
   },
    "userPaymentOption":{
        "userPaymentOptionId":"1459503"
    },
    "timeStamp": "20190915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

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

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

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

};

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

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

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

1
COMING SOON

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

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

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

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

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "userTokenId":"230811147",
    "clientUniqueId":"12345",
    "internalRequestId":"866",
    "transactionId":"8498764859",
    "externalTransactionId":"",
    "status":"SUCCESS",
    "cardData":{
        "acquirerId":"1",
        "visaDirect":"YES"
    },
    "transactionStatus":"APPROVED",
    "merchantDetails":{
        "customField1":""
    },
    "userPaymentOptionId":"12442",
    "errCode":"0",
    "reason":"",
    "paymentMethodErrorCode":"0",
    "paymentMethodErrorReason":"",
    "gwErrorCode":"0",
    "gwErrorReason":"",
    "gwExtendedErrorCode":"0",
    "version":"1"
}

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

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system. This must be sent when using the User Payment Management feature.
clientUniqueId ^String(45) ~Required	The ID of the transaction in the merchant’s system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
amount ^String(12) ~Required	The transaction amount.
currency ^String(3) ~Required	The 3-letter ISO currency code.
userPaymentOption ^Class ~Required	userPaymentOptionId (String, 45) The first time a consumer uses a payment method, Nuvei assigns a unique ID to it. The next time the consumer uses a payment method that Nuvei has previously assigned an ID to, the ID is returned as the value of this parameter.
timeStamp ^String(14) ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^String(256) ~Required	The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey Press here to see an example.
deviceDetails ^Class ~ipAddress Required	ipAddress (String, 15, REQUIRED) deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255)
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this field is used to prevent idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
userDetails ^Class ~Conditional	identification (String, 15) – This currently represents the social security number (SSN) of United States citizens. This class is REQUIRED only for certain APMs.
dynamicDescriptor ^Class ^Optional	merchantName (String, 25) – The merchant name, as is displayed for the transaction on the consumer’s card statement. For payment facilitator only, the maximum length of the parameter is 22, consisting of the following structure: XXX*<merchant name> where:   • XXX – The PayFac prefix, approved by Nuvei Underwriting Team.     Can be a length of 3, 7, 9, or 12.   • * – A fixed character.   • <merchant name> – Sub-merchant name.     Can be a length of 18, 14, 12, or 9, respectively. merchantPhone (String, 13) – The merchant contact information, as is displayed for the transaction on the consumer’s card statement. It can also be an email address.
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 This allows the merchant to send information with the request to be saved in the API level and returned in response.
cardData ^Class ^Optional	An alternative to sending the userPaymentOptionId for card payouts. Merchant has to be PCI certified to use this, as it uses clear text card numbers. When sending cardData you must also send userTokenId. cardNumber (String, 20) cardHolderName (String, 70) expirationMonth (String, 2) expirationYear (String, 4)
customData ^String(255) ^Optional	This parameter can be used to pass any type of information. If sent in request, then it is visible in Nuvei’s back-office tool transaction reporting and is returned in response. Note: This is only relevant for credit card transactions and not for APMs.
comment ^String(255) ^Optional	Enables the addition of a free text comment to the request.
urlDetails ^Class ^Optional	notificationUrl (String, 1000) – The URL to which DMNs are sent.
addendums ^Class ^Optional	This class contains industry specific addendums. For /payout, only localpayment is relevant.

Output Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
clientUniqueId ^String(45)	The ID of the transaction in the merchant’s system. It 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 values: SUCCESS, ERROR.
transactionStatus ^String(20)	The Gateway transaction status. Possible values: APPROVED, DECLINED, ERROR
merchantDetails ^Class	customField1 (String, 255) … customField15 This allows the merchant to send information with the request to be saved in the API level and returned in response.
userPaymentOptionId ^String(45)	The first time a consumer uses a payment method, Nuvei assigns a unique ID to it and returns it. The next time the consumer uses a payment method that Nuvei has previously assigned an ID to, the ID is returned as the value of this parameter.
errCode ^String(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
paymentMethodErrorCode ^String(11)	If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason ^String(400)	If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode ^String(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^String(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 ^String(10)	The current version of the request. The current version is 1.
clientRequestId ^String(255)	The 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
safecharge.getPaymentStatus({
    "sessionToken": "3765655c-c333-47b7-aea6-07c54e59d1fb" // as returned from /getSessionToken result
}, function (pError, pRes){

})

1
2
3
4
5
//Initialize the SDK (see https://docs.safecharge.com/?p=29433)

{
    GetPaymentStatusResponse response = safecharge.getPaymentStatus();
}

1
2
3
4
5
6
7
//Initialize the SDK (see https://docs.safecharge.com/?p=53233)

<?php
$getPaymentStatusRequest = $SafeCharge->getPaymentService()->getPaymentStatus([
    'sessionToken'  =>  '<sessionToken>',
]);
?>

1
2
3
4
//Initialize the SDK (see https://docs.safecharge.com/?p=48413)

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

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "transactionType":"Sale",
    "transactionStatus":"APPROVED",
    "transactionId":"1110000000015619958",
    "paymentOption":{
        "alternativePaymentMethod":{
            "externalAccountID":"XULDPMBSWPJZU",
            "externalTransactionId":"5FH47158U3529041Y",
            "APMReferenceID":"3274FEAB2016D682D1D6919ED8A39F8C",
            "orderTransactionId":"1078647708",
            "apmPayerInfo":"Address:Confirmed;Payer:verified;Country:US;FirstName:John;LastName:Smith Coevorden",
            "paymentMethod":"apmgw_expresscheckout"
        }
    },
    "currency":"USD",
    "amount":"200",
    "sessionToken":"da5d9646-faf0-449d-86e5-efc5b008ba82",
    "internalRequestId":291868078,
    "status":"SUCCESS",
    "errCode":0,
    "reason":"",
    "merchantSiteId":"204388",
    "version":"1.0"
}

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

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

Use Cases:

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

@Links URLs

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

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

Input Parameters

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

Output Parameters

Parameter	Description
sessionToken ^String(36)	Session identifier returned by /getSessionToken or generated by /openOrder.
version ^String(10)	The current version of the API method. The current version is 1.
status ^String(20)	The cashier status of merchant request. Possible values: SUCCESS, ERROR
transactionStatus ^String(20)	The Gateway transaction status.
amount ^String(12)	The transaction amount.
currency ^String(3)	The 3-letter ISO currency code.
userPaymentOption ^Class	userPaymentOptionId (String, 45) The first time a consumer uses a payment method, Nuvei assigns a unique ID to it. The next time the consumer uses a payment method that Nuvei has previously assigned an ID to, the ID is returned as the value of this parameter.
customData ^String(255)	This parameter can be used to pass any type of information. If sent in the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back-office tool for transaction reporting and is returned in the response.
clientUniqueId ^String(255)	The ID of the transaction in the merchant’s system.
gwExtendedErrorCode ^String(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 ^String(11)	The error code if error occurred. 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 ^String(11)	The error code if error occurred at the APM side.
paymentMethodErrorReason ^String(400)	The error reason if error occurred at the APM side.
authCode ^String(128)	Auth code.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
transactionType ^String(45)	The type of transaction: Sale or Auth. Sale – Performs a regular payment request. Auth – Performs an authorization only request. Press here for more details.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
transactionId ^String(20)	The Gateway transaction ID.
errCode ^String(11)	The error code if the error occurred at the cashier side.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if the error occurred at the cashier side.
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.

/getPayoutStatus

Definition

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

1
COMING SOON

1
COMING SOON

1
COMING SOON

1
COMING SOON

Example Response

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

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

@Links URLs

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

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

Input Parameters

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

Output Parameters

Parameter	Description
version ^String(10)	The current version of the API method. The current version is 1.
status ^String(20)	The cashier status of merchant request. Possible values: SUCCESS, ERROR
transactionStatus ^String(20)	The Gateway transaction status.
amount ^String(12)	The transaction amount.
currency ^String(3)	The 3-letter ISO currency code.
userPaymentOption ^Class	userPaymentOptionId (String, 45) The first time a consumer uses a payment method, Nuvei assigns a unique ID to it. The next time the consumer uses a payment method that Nuvei has previously assigned an ID to, the ID is returned as the value of this parameter.
gwExtendedErrorCode ^Sting(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 ^String(11)	The error code if error occurred. 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.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
transactionId ^String(20)	The Gateway transaction ID.
errCode ^String(11)	The error code if the error occurred at the cashier side.
reason ^String(400)	The error reason (such as “failure in checksum validation” and “timeout from processing engine”) if the error occurred at the cashier side.
clientRequestId ^String(20)	The ID of the API request in the merchant’s system.

/accountCapture (API)

Definition

1
2
3
4
5
6
7
8
9
10
11
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "paymentMethod":"apmgw_BankPayouts",
    "userTokenId":"230811147",
    "currencyCode":"USD",
    "countryCode":"US",
    "languageCode":"en",
    "notificationUrl":"<notificationURL>"
}

1
COMING SOON

1
COMING SOON

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

<?php
//accountCapture
$accountCaptureResponse = $safeCharge->getPaymentService()->accountCapture([
    'sessionToken'      => '9610a8f6-44cf-4c4f-976a-005da69a2a3b',
    'merchantId'        => '427583496191624621',
    'merchantSiteId'    => '142033',
    'paymentMethod'     => 'apmgw_FastBankTansfer',
    'userTokenId'       => '230811147',
    'currencyCode'      => 'USD',
    'countryCode'       => 'US',
    'languageCode'      => 'en',
    'notificationUrl'   => '<notificationURL>'
]);
?>

1
COMING SOON

Example Response

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

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

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	Session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255) ~Required	This ID uniquely identifies your consumer/user in your system. This must be sent when using the User Payment Management feature.
paymentMethod ^String(50) ~Required	Specifies the payment method name of the payment option to be charged. See: APM Input Fields and APIs.
currencyCode ^String(3) ~Required	The three-letter ISO currency code.
countryCode ^String(2) ~Required	The two-letter ISO country code.
languageCode ^String(2) ^Optional	The language in which the transaction is to be completed.
notificationUrl ^String(1000) ^Optional	The URL to which DMNs are sent.

Output Parameters

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

DCC Methods

/getCardDetails (API)

Definition

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

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

});

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

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

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

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

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

1
2
3
//Initialize the SDK (see https://docs.safecharge.com/?p=48413)

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

Example Response

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

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

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

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
cardNumber ^String(20) ~Required	The credit card number. cardNumber or bin must be populated.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this field is used to prevent idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
clientUniqueId ^String(45) ^Optional	The ID of the transaction in the merchant’s system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.

Output Parameters

Parameter	Description
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
clientRequestId ^String(20)	The ID of the API request in the merchant’s system.
clientUniqueId ^String(255)	The ID of the transaction in the merchant’s system.
brand ^String	The name of the card scheme; for example: Visa
cardType ^String	The type of card used in the transaction. Possible values: credit, debit
program ^String	The card program used in the transaction; for example: Visa Platinum
cardProduct ^String	The code of the card program used in the transaction; for example, “N” for Visa Platinum
visaDirectSupport ^String	Indicates whether Visa Direct is supported or not
dccAllowed ^String	Indicates whether DCC is allowed for this card.
issuerCountry ^String(2)	2-letter ISO code of the card issuer’s country.
currency ^String(3)	The 3-letter ISO currency code.
internalRequestId ^String(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
version ^String(10)	The current version of the API method. The current version is 1.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
errCode ^String(11)	If an error occurred on the request side, an error code is returned in this parameter.
status ^String(20)	The cashier status of merchant request. Possible values: SUCCESS, ERROR

/getMcpRates

Definition

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

1
COMING SOON

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

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

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

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

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

1
COMING SOON

Example Response

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

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

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36) ~Required	The session identifier returned by /getSessionToken.
merchantId ^String(20) ~Required	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The Merchant Site ID provided by Nuvei.
fromCurrency ^String(3) ~Required	The original merchant currency.
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this field is used to prevent idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
clientUniqueId ^String(45) ^Optional	The ID of the transaction in the merchant’s system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
toCurrency ^String(200) ^Optional	The list of target currencies separated by commas. If not supplied, all the Merchant Site related currencies are retrieved.
paymentMethod ^String(200) ^Optional	The list of payment methods separated by commas. If not supplied, all the Merchant related payment methods are retrieved.

Output Parameters

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

/getDccDetails

Definition

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

1
COMING SOON

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

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

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

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

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

1
COMING SOON

Example Response

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

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

The output of this method is the complete DCC information.

@Links URLs

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

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

Input Parameters

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

Output Parameters

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

MPI Methods

/authorize3d

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
safecharge.authorize3d({
    "sessionToken": "sessionToken", // as returned from /getSessionToken result
    "currency": "USD",
    "amount": "200",
    "paymentOption": {
        "card": {
            "expirationYear": "2026",
            "CVV": "217",
            "cardHolderName": "John Smith",
            "expirationMonth": "12",
            "cardNumber": "4000027891380961"
        }
    },
    "deviceDetails": {
        "ipAddress": "127.0.0.1"
    },
    "billingAddress": {
        "email": "john.smith@email.com",
        "county": "US"
    }
}, function(pError, pRes) {

});

1
2
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
//Initialize the SDK (see https://docs.safecharge.com/?p=29433)

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

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

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

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

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

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

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

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
//Initialize the SDK (see https://docs.safecharge.com/?p=48413)

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

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
    {  
    "orderId":"241494183",
    "paymentOption":{  
        "userPaymentOptionId":"8348263",
        "card":{  
            "ccCardNumber":"5****8464",
            "bin":"511580",
            "last4Digits":"8464",
            "ccExpMonth":"01",
            "ccExpYear":"20",
            "cvv2Reply":"",
            "avsCode":"",
            "threeD":{  
                "acsUrl":"https://qa1-tlv-acq1:4434/api/ThreeDSACSChallengeController/ChallengePage?eyJub3RpZmlj...",
                "eci":"7",
                "termUrl":"https://srv-bsf-devppptrunk.gw-4u.com/ppp/api/threeDSecure/completePayment.do?sessionToken\u003d04fcc8cf-3789-4936-b690-9801261f83a9",
                "whiteListStatus":"",
                "cavv":"",
                "acsChallengeMandated":"Y",
                "cReq":"eyJ0aHJlZURTU...",
                "authenticationType":"01",
                "cardHolderInfoText":"",
                "result":"C",
                "version":"2.1.0",
                "acsTransId":"541a88a9-f01f-4206-9137-ec1bed295955",
                "dsTransID":"f0ff3e24-cdf6-4561-900b-849a5054d776"
            }
        }
    },
    "transactionStatus":"DECLINED",
    "merchantDetails":{  
        "customField1":"merchantName"
    },
    "gwErrorCode":-1,
    "gwErrorReason":"Decline",
    "gwExtendedErrorCode":0,
    "transactionType":"Auth3D",
    "transactionId":"1110000000000347161",
    "externalTransactionId":"",
    "authCode":"",
    "customData":"",
    "sessionToken":"5bd76168-844c-4fb1-9cfb-f7812ca31950",
    "clientUniqueId":"uniqueIdCC",
    "internalRequestId":134148663,
    "status":"SUCCESS",
    "errCode":0,
    "reason":"",
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "version":"1.0"
    }

Call this method if you need to use the Nuvei MPI service to perform a 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 acsUrl under the threeD Output 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.
timeStamp ^String(14) ~Required	The local time when the method call is performed in the format: YYYYMMDDHHmmss. This is needed for the “checksum” hashing calculation.
checksum ^String(256) ~Required	The hashed values (SHA-256 encoded) of the input parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey Press here to see an example.
currency ^String(3) ~Required	The 3-letter ISO currency code.
amount ^String(12) ~Required	The transaction amount.
paymentOption ^Class ~Required	This class represents the details about the payment method. Can have either card or userPaymentOptionId: • card – Represents a credit/debit card     ▫ cardNumber String(20) – The card number.     ▫ cardHolderName String(70) – The card holder name.     ▫ expirationMonth String(2) – Card expiration month.     ▫ expirationYear string4() – Card expiration year.     ▫ CVV String(4) – The CVV/CVC security code.     ▫ threeD (class) – Contains the required 3D-Secure information. Refer to threeD Input Class 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 a previous use.
relatedTransactionId ^String(19) ~Required	Sets the transactionId returned from the preceding initPayment call.
subMerchant ^Class ^Optional	countryCode (String,2) – The payment facilitator’s sub-merchant’s 2-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 is forwarded to Mastercard as “SubMerchantId”.
deviceDetails ^Class ~ipAddress Required	ipAddress (String, 15, REQUIRED) deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255)
billingAddress ^Class ~country and email Required	The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters. country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30) lastName (String, 40) address (String, 60) address2 (String, 60) phone (String, 18) zip (String, 10) city (String, 30) state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). county (String, 255) These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.
userTokenId ^String(255) ~Conditional	This ID uniquely identifies your consumer/user in your system. It is REQUIRED if you wish to use the userPaymentOptionId field for future charging of this user without re-collecting the payment details (see User Payment Management for details).
clientRequestId ^String(255) ^Optional	Based on the merchant configuration, this field is used to prevent idempotency. It uniquely identifies the API request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it assumes idempotency.
clientUniqueId ^String(45) ^Optional	The ID of the transaction in the merchant’s system. This must be sent to facilitate future actions, such as reconciliation, identifying the transaction in the event of any issues, etc. It appears in DMN as the merchant_unique_id parameter.
userDetails ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100) county (String, 255) language (String, 2) – 2-letter ISO language code. dateOfBirth (String, 10) – Format is YYYY-MM-DD. identification (String, 15) – This currently represents the social security number (SSN) of United States citizens.
shippingAddress ^Class ^Optional	firstName (String, 30) lastName (String, 40) address (String, 60) phone (String, 18) zip (String, 10) city (String, 30) country (String, 2) – 2-letter ISO country code state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). email (String, 100) shippingCounty (String, 255)
merchantDetails ^Class ^Optional	customField1 (String, 255) … customField15 This allows the merchant to send information with the request to be saved in the API level and returned in response.
urlDetails ^Class ^Optional	Although DMN responses can be configured per merchant site, it allows dynamically returning the DMN to the provided address per request. pendingUrl (String, 1000) – The URL the customer is directed to when the transaction response is pending.
items ^Class ^Optional	Describes the items in the purchase. name (String, 255) price (String, 10) quantity (String, 10)
customSiteName ^String(50) ^Optional	The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name. Risk rules and traffic management rules are usually built based on this 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 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 by Nuvei REST API SDKs to send the plugin/SDK name and version so that Support is able to identify from where the transaction arrived at the REST API Gateway.
orderId ^String(45) ^Optional	The order ID provided by Nuvei. This parameter is passed to define which merchant order to update.
addendums ^Class ^Optional	This class contains industry specific addendums. For /authorize3d, only localpayment is relevant.

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
clientUniqueId ^String(255)	The ID of the transaction in the merchant’s system.
internalRequestId ^String(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
status ^String(20)	The cashier status of merchant request. Possible values: SUCCESS, ERROR
transactionStatus ^String(20)	The Gateway transaction status.
paymentOption ^Class	This class represents the data retrieved from the processed payment method. It can be either card, or in case of an APM, it shows the redirectUrl. In addition, the userPaymentOptionId field is retrieved as detailed below: • redirectUrl (String) – The redirect URL to follow in case of an APM, 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) 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 address verification service (AVS) response.     Possible values:     ◦ A – The street address matches, the ZIP code does not.     ◦ W – Postal code matches, the street address does not.     ◦ Y – Postal code and the street address match.     ◦ X – An exact match of both the 9-digit ZIP code and the street address.     ◦ Z – Postal code matches, the street code does not.     ◦ U – Issuer is unavailable.     ◦ S – AVS not supported by issuer.     ◦ R – Retry.     ◦ B – Not authorized (declined).     ◦ N – Both the street address and postal code do not match.   ▫ acquirerId (String) – The acquirer ID of the acquirer that processed the transaction.   ▫ cardType (String) – The type of card used in the transaction.     Possible values: Credit, Debit   ▫ cardBrand (String) – The card brand used in the transaction.     Possible values: VISA, MASTERCARD, AMEX   ▫ threeD (class) – Contains the required 3D-Secure information. Refer to threeD Output Class for details. OR • userPaymentOptionId – In addition to the above, this field represents the ID for the newly created payment option, which can be referenced in future requests. For full details, refer to Card-on-File.
merchantDetails ^Class	customField1 (String, 255) … customField15 This allows the merchant to send information with the request to be saved in the API level and returned in response.
errCode ^String(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwErrorCode ^String(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^String(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 ^String(10)	The current version of the request. The current version is 1.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
transactionId ^String(20)	The Gateway transaction ID.
authCode ^String(128)	The authorization code of the transaction.
partialApprovalDetails ^Class	This determines whether or not the transaction is a partial approval, plus other information regarding the amount. These following parameters are returned only if the partial approval feature was in use, as per the relevant input parameter sent value. isPartialApproval (String – True or False) amountInfo: requestedAmount (String) requestedCurrency (String) processedAmount (String) processedCurrency (String)
transactionType ^String(45)	The type of transaction: Sale or Auth. Sale – Performs a regular payment request. Auth – Performs an authorization only request. Press here for more details.
customData ^String(255)	This parameter can be used to pass any type of information. If sent in the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back-office tool for transaction reporting and is returned in the response.
fraudDetails ^Class	finalDecision (String) score (decimal) recommendations (String) system (Array) [systemId (String), systemName (String), decision (String)] rules (Array) [ruleId (String), ruleDescription (String)] score refers to a number between 0 and 1 that indicates the probability of a transaction becoming fraudulent, which is calculated using a risk machine learning model. system refers to which risk management system provided the fraud information. The provider can be Nuvei (systemId=1) or an external provider. rules refers to the risk management system rules triggered by the transaction. decision refers to the risk management system decisions regarding the rules that were triggered by the transaction. There are five possible values for the decision parameter: Accept – The risk management system accepts the transactions. Reject – The risk management system rejects the transaction. The transaction is not passed to bank for authorization. The reasons are returned in ruleDescription parameter. Review – The risk management system flags a transaction for review, but still accepts the transaction. Error – An error occurred during the risk management system operation. The Gateway continues to process the transaction through the bank. None – No risk analysis was performed. The Gateway continues to process the transaction through the bank. finalDecision refers to when deciding whether to accept or reject a transaction. The risk management system bases its finalDecision on individual decisions made regarding rules triggered. If none of the rules leads to a Reject decision, the finalDecision accepts the transaction. If at least one of the rules leads to a Reject decision, the finalDecision rejects the transaction. To receive this information in response special configurations are required. For more information, please contact Nuvei’s Integration Support Team.
orderId ^String(20)	The ID returned from the merchantOrderID input parameter in update and payment methods. This parameter is returned to define which merchant order to update.
clientRequestId ^String(20)	The ID of the API request in the merchant’s system.

/verify3d

Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "merchantSiteId":"142033",
    "merchantId":"427583496191624621",
    "sessionToken":" 9e07802d-5126-4b02-b4b3-ef09dfb94219",
    "relatedTransactionId":"2110000000001208909",
    "currency":"USD",
    "amount":"200",
    "paymentOption":{
        "card":{
            "cardNumber":"4000027891380961",
            "cardHolderName":"john Smith",
            "expirationMonth":"12",
            "expirationYear":"2026",
            "CVV":"217"
        }
    },
    "deviceDetails":{
        "ipAddress":"127.0.0.1"
    },
    "billingAddress":{
        "email":"john.smith@email.com",
        "country":"US"
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
safecharge.verify3d({
    "sessionToken": "sessionToken", // as returned from /getSessionToken result
    "relatedTransactionId": "transactionId", // as returned from /authorize3d result
    "currency":"USD",
    "amount":"200",
    "paymentOption":{
      "card": {
        "expirationYear" : "2026",
        "CVV"            : "217",
        "cardHolderName" : "John Smith",
        "expirationMonth": "12",
        "cardNumber"     : "4000027891380961"
      }
    },
    "deviceDetails": {
        "ipAddress": "127.0.0.1"
    },
    "billingAddress": {
      "email": "john.smith@email.com",
      "county": "US"
    }
}, function (pError, pRes){

});

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

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

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

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

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

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

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

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

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

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

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

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

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
    "orderId": "29264489",
    "transactionStatus": "APPROVED",
    "transactionType": "VerifyAuth3D",
    "transactionId": "2110000000000644999",
    "customData": "customData",
    "merchantDetails": {
        "customField1": "merchantName"
    },
    "paymentOption": {
        "card": {
            "ccCardNumber": "5****3511",
            "bin": "541333",
            "last4Digits": "3511",
            "ccExpMonth": "12",
            "ccExpYear": "25",
            "threeD": {
                "threeDFlow": "0",
                "eci": "2",
                "version": "2.1.0",
                "serverTransId": "34cfeb35-5ba6-4df3-a5f1-bf4b93e14476",
                "whiteListStatus": "",
                "cavv": "ZkhQRHd3Mzd6Z2t2MlFLQmRMbW8=",
                "sdk": {},
                "result": "Y",
                "acsTransId": "",
                "dsTransID": "9bd98ea9-035e-4ec3-a863-831fc547473f"
            }
        }
    },
    "sessionToken": "9e07802d-5126-4b02-b4b3-ef09dfb94219",
    "clientUniqueId": "clientUniqueId",
    "internalRequestId": 3329188,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0"
}

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

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

@Links URLs

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

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

Input Parameters

PARAMETER	DESCRIPTION
merchantId ^String(20) ~Required	The merchant ID provided by Nuvei.
merchantSiteId ^String(20) ~Required	The merchant site ID provided by Nuvei.
sessionToken ^String(36) ~Required	Session identifier returned by /getSessionToken.
currency ^String(3) ~Required	The 3-letter ISO currency code.
amount ^String(12) ~Required	The transaction amount.
paymentOption ^Class ~Required	This class represents the details about the payment method. Can have either card or userPaymentOptionId: • card – Represents a credit/debit card.     ▫ cardNumber String(20) – The card number.     ▫ cardHolderName (String, 70) – The card holder name.     ▫ expirationMonth (String, 2) – Card expiration month.     ▫ expirationYear – String(4)– Card expiration year.     ▫ CVV (String, 4) – The CVV/CVC security code     ▫ threeD.paResponse (class) – Only relevant if 3D-Secure is v1. To verify, you need to provide the paResponse retrieved from the termUrl. See the 3D-Secure Guide for a full explanation. For 3D-Secure v2, no threeD field needs to be submitted. OR • userPaymentOptionId – This is a field identifying a payment option that has already been used by the customer and now it is requested for re-use. Nuvei keeps payment option details from a previous use.
relatedTransactionId ^String(19) ~Required	The transaction ID of the of the call to /authorize3d.
subMerchant ^Class ^Optional	countryCode (String,2) – The payment facilitator’s sub-merchant’s 2-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 is forwarded to Mastercard as “SubMerchantId”.
deviceDetails ^Class ~ipAddress Required	ipAddress (String, 15, REQUIRED) deviceType (String, 10) – Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized). deviceName (String, 255) deviceOS (String, 255) browser (String, 255)
billingAddress ^Class ~country and email Required	The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters. country (String, 2, REQUIRED) – 2-letter ISO country code. Must be entered in uppercase. email (String, 100, REQUIRED) firstName (String, 30) lastName (String, 40) address (String, 60) address2 (String, 60) phone (String, 18) zip (String, 10) city (String, 30) state (String, 2) – 2-letter ISO state code (for customers based in the US, Canada, and India only). county (String, 255) These parameters can be defined as required or non-required as needed by Nuvei’s Integration Support Team.
userTokenId ^String(255) ~Conditional	This ID uniquely identifies your consumer/user in your system. It is REQUIRED if you wish to use the userPaymentOptionId field for future charging of this user without re-collecting the payment details (see User Payment Management for details).

Output Parameters

PARAMETER	DESCRIPTION
sessionToken ^String(36)	The session identifier returned by /getSessionToken.
merchantId ^String(20)	The Merchant ID provided by Nuvei.
merchantSiteId ^String(20)	The Merchant Site ID provided by Nuvei.
userTokenId ^String(255)	This ID uniquely identifies your consumer/user in your system.
clientUniqueId ^String(255)	The ID of the transaction in the merchant’s system.
internalRequestId ^String(20)	Nuvei’s internal unique Request ID (used for reconciliation purposes).
status ^String(20)	The cashier status of merchant request. Possible values: SUCCESS, ERROR
transactionStatus ^String(20)	The Gateway transaction status.
paymentOption ^Class	This class represents the details of the payment method. • 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.   ▫ cardBrand (String) – The card brand used in the transaction.     Possible values: VISA, MASTERCARD, AMEX   ▫ threeD (class) – Contains the required 3D-Secure information. Refer to threeD Output Class for details. • 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 a previous use.
merchantDetails ^Class	customField1 (String, 255) … customField15 This allows the merchant to send information with the request to be saved in the API level and returned in response.
errCode ^String(11)	If an error occurred on the request side, an error code is returned in this parameter.
reason ^String(400)	If an error occurred on the request side, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwErrorCode ^String(11)	If an error occurred in the Gateway, then an error code is returned in this parameter.
gwErrorReason ^String(400)	If an error occurred in the Gateway, then an error reason (such as “failure in checksum validation” and “timeout from processing engine”) is returned in this parameter.
gwExtendedErrorCode ^String(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 ^String(10)	The current version of the request. The current version is 1.
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
transactionId ^String(20)	The Gateway transaction ID.
authCode ^String(128)	The authorization code of the transaction.
transactionType ^String(45)	The type of transaction: Sale or Auth. Sale – Performs a regular payment request. Auth – Performs an authorization only request. Press here for more details.
customData ^String(255)	This parameter can be used to pass any type of information. If sent in the request, then it is passed on to the payment Gateway; it is then visible in Nuvei’s back-office tool for transaction reporting and is returned in the response.
fraudDetails ^Class	finalDecision (String) score (decimal) recommendations (String) system (Array) [systemId (String), systemName (String), decision (String)] rules (Array) [ruleId (String), ruleDescription (String)] score refers to a number between 0 and 1 that indicates the probability of a transaction becoming fraudulent, which is calculated using a risk machine learning model. system refers to which risk management system provided the fraud information. The provider can be Nuvei (systemId=1) or an external provider. rules refers to the risk management system rules triggered by the transaction. decision refers to the risk management system decisions regarding the rules that were triggered by the transaction. There are five possible values for the decision parameter: Accept – The risk management system accepts the transactions. Reject – The risk management system rejects the transaction. The transaction is not passed to bank for authorization. The reasons are returned in ruleDescription parameter. Review – The risk management system flags a transaction for review, but still accepts the transaction. Error – An error occurred during the risk management system operation. The Gateway continues to process the transaction through the bank. None – No risk analysis was performed. The Gateway continues to process the transaction through the bank. finalDecision refers to when deciding whether to accept or reject a transaction. The risk management system bases its finalDecision on individual decisions made regarding rules triggered. If none of the rules leads to a Reject decision, the finalDecision accepts the transaction. If at least one of the rules leads to a Reject decision, the finalDecision rejects the transaction. To receive this information in 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-Secure authorization request (the first /payment call) as defined in 3DS Authentication Flows.

Most of the fields specified below are required for 3D-Secure only for the first call to /payment (or /authorize3d), which performs the 3D-Secure authorization before proceeding for payment.

The following are exceptions to this:

• The paResponse field – Press here for details.
• External MPI – If you use an external MPI provider to perform the 3D-Secure authentication independently from Nuvei, use the set of parameters here.

Additional Class Parameters

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

v2AdditionalParams

Parameter	Description
challengeWindowSize ^String(2) ~Required for 3DS v2	The dimensions of the challenge window. 01 – 250 x 400 02 – 390 x 400 03 – 500 x 600 04 – 600 x 400 05 – Full screen
rebillExpiry ^String(8) ~Conditional	Recurring Expiry in format YYYYMMDD. REQUIRED if isRebilling = 0 We recommend setting rebillExpiry to a value of no more than 5 years from the date of the initial transaction processing date.
rebillFrequency ^String(4) ~Conditional	Recurring Frequency in days. REQUIRED if isRebilling = 0
challengePreference ^String(2) ^Optional	Determines the preference of the merchant. This can be used either during an Authentication request when Nuvei is the 3D-Secure v2 MPI or during an Authorization request without any prior authentication when the transaction amount allows it. Please contact our Risk Team to set this threshold amount. Possible values: 01 – Challenge requested 02 – Exemption requested 03 – No preference
deliveryEmail ^String(254) ^Optional	For electronic delivery, the email address to which the merchandise was delivered.
deliveryTimeFrame ^String(2) ^Optional	Indicates the merchandise delivery timeframe. 01 – Electronic Delivery 02 – Same day shipping 03 – Overnight shipping 04 – Two-day or more shipping
giftCardAmount ^String(15) ^Optional	For prepaid or gift card purchase, the total purchase amount of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).
giftCardCount ^String(2) ^Optional	For prepaid or gift card purchase, the total number of individual prepaid or gift cards/codes purchased.
giftCardCurrency ^String(3) ^Optional	For prepaid or gift card purchase, the ISO 4217 3-letter currency code of the gift card.
preOrderDate ^String(8) ^Optional	For a pre-ordered purchase, the expected date that the merchandise is available (YYYYMMDD).
preOrderPurchaseInd ^String(2) ^Optional	Indicates whether cardholder is placing an order for merchandise with a future availability or release date. 01 – Merchandise available 02 – Future availability
reorderItemsInd ^String(2) ^Optional	Indicates whether the cardholder is reordering previously purchased merchandise. 01 – First time ordered 02 – Reordered
shipIndicator ^String(2) ^Optional	Indicates the selected shipping method for the transaction. 01 – Ship to cardholder’s billing address 02 – Ship to another verified address on file with merchant 03 – Ship to address that is different than the cardholder’s billing address 04 – “Ship to Store”/Pickup at local store (store address shall be populated in shipping address fields) 05 – Digital goods (includes online services, electronic gift cards and redemption codes) 06 – Travel and event tickets, not shipped 07 – Other (for example, gaming, digital services not shipped, e-media subscriptions, etc.)

browserDetails

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

account

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

threeD Output Class

This class contains the 3D-Secure information returned from the call to the /payment or /authorize3d methods after performing the 3D-Secure authorization request (the first /payment call) as defined in the 3D-Secure Guide.

The output parameters are separated into two parts:

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

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

PARAMETER	DESCRIPTION
acsUrl ^String	URL or endpoint used to redirect the consumer to the card issuer/bank’s 3D-Secure verification page.
acsChallengeMandate ^String(1)	The 3D-Secure v2 challenge required indication. Possible values: N – Not required Y – Required (only in case of 3D-Secure v2)
cReq ^String	The Base64 encoded cReq relevant for the 3D-Secure v2. acsUrl is also sent as a separate field (only in case of 3D-Secure v2)
paRequest ^String	The 3D-Secure request data for the card issuer/bank (only in case of 3D-Secure v1)
threeDFlow ^String	Indicates which 3D-Secure flow is taking place: If the Gateway response parameter for threeDFlow = 1, the transaction is converted from Sale3D to Auth3D after passing the Gateway rule engine. (paRequest and acsUrl are returned and the merchant needs to redirect to issuer and call payment3D method afterwards). If the Gateway response parameter for threeDFlow= 0, the transaction converted from Sale3D to Sale or Auth depending on the configured merchant mode of operation after passing the Gateway rule engine. (paRequest and acsUrl are NOT returned and the merchant does NOT need to redirect to issuer or call payment3Dmethod later on).
externalTransactionId ^String(20)	The transaction ID of the transaction in the event that an external service is used.
transactionId ^String(20)	The Gateway transaction ID.
threeDReasonId ^String	Reason ID for a failed 3D-Secure authorization as received from the issuer. Press here for more information.
threeDReason ^String	Reason description for a failed 3D-Secure authorization as received from the issuer. Press here for more information.
challengeCancelReasonId ^String	Reason ID for a canceled 3D-Secure authorization as received from the issuer.
challengeCancelReason ^String	Reason description for a canceled 3D-Secure authorization as received from the issuer.
isLiabilityOnIssuer ^String	Indicates if there is 3D-Secure liability shift. If equal to “1” – Liability shift is present. If equal to “0”, empty or null – No liability shift has occurred.
isExemptionRequestInAuthentication ^String	Indicates if an exemption was requested during authorization.
challengePreferenceReason ^String	This value is returned following a 3D-Secure v2 challenge and describes the reason for challenge (press here for more details).
cascadedTo3Dv1 ^String(5)	Indicates if a transaction failed for a technical reason and was downgraded from 3Dv2 to 3Dv1 after /payment or /authorize3d was invoked. Possible values: TRUE – The transaction was downgraded. FALSE or Null – No downgrade was performed. This parameter is included in the response only if its value is TRUE.

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

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

externalMpi Class

If you use an external MPI provider to perform the 3D-Secure authorization 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.

PARAMETER	DESCRIPTION
cavv ^String(50) ~Required	The card authentication verification value as received from the MPI.
eci ^String(2) ~Conditional	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. This parameter is REQUIRED for credit/debit cards, and optional for GooglePay and Apple Pay.
xid ^String(50) ~Conditional	The transaction ID received from the MPI for 3D-Secure v1.
dsTransID ^String(36) ~Conditional	The transaction ID received from the MPI for 3D-Secure v2. REQUIRED for 3D-Secure v2; do not send for 3D-Secure v1.
exemptionRequestReason ^String(25) ~Conditional	If challengePreference is populated with a value of “ExemptionRequest”, then this field becomes REQUIRED and displays the reason for the request. Possible values: AddCard, AccountVerification, LowValuePayment, TransactionRiskAnalysis
externalTokenProvider ^String(45) ~Conditional	The name of the external token provider (Apple Pay, GooglePay, VisaCheckout). The merchant uses this parameter ONLY when they perform self-decryption of the external token. For an example, see Payments with externalMPI.
challengePreference ^String(25) ^Optional	If your MPI has already requested an exemption in the authentication and the issuer has approved the exemption request, you should provide Nuvei with this field value to allow us to adjust our exemption flag accordingly so it is synchronized according to EMVCO and schemes guidelines. Possible values: ExemptionRequest, NoPreference

externalToken Class

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) ~Required	The name of the external token provider (Apple Pay, GooglePay, Visa Checkout).
mobileToken ^String(5000) ~Conditional	This encrypted token represents a customer payment method (REQUIRED for ApplePay and GooglePay). It is generated by the external token provider, as described in the Payments with externalToken topic. To work with these tokens, contact Nuvei’s Integration Support Team for them to configure your merchant account accordingly.
externalTokenData ^String(255) ~Conditional	The token (callId) received by the merchant from the external token provider (REQUIRED for Visa Checkout).
cardType ^String(45) ~Conditional	Indicates the type of information received (REQUIRED for Visa Checkout). Possible values: PAN, CardToken

storedCredentials Class

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

PARAMETER

DESCRIPTION

storedCredentials ^Class ^Optional

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

addendums Class

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

• airlines
• cardPresentPointOfSale
• localpayment

airlines

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

reservationDetails

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

reservationDetails.passengerDetails

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

reservationDetails.flightLegDetails

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

cardPresentPointOfSale

PARAMETER	DESCRIPTION
terminalId ^Integer(8) ^Optional
trackData ^LLVAR ^Optional
trackType ^Integer
icc ^LLLVAR ^Optional
pinData ^String ^Optional
entryMode ^Integer ^Optional
terminalCapability ^String ^Optional
terminalAttendance ^Boolean ^Optional
cardSequenceNum ^Integer(3) ^Optional
offlineResCode ^String ^Optional
localTime ^String ^Optional
localDate ^String ^Optional
cvMethod ^Integer ^Optional
cvEntity ^Integer ^Optional
outputCapability ^Integer ^Optional
autoReversal ^Boolean ^Optional
autoReversalAmount ^Integer ^Optional
autoReversalCurrency ^String ^Optional
suppressAuth ^Integer ^Optional
terminalCity ^String(13) ^Optional
terminalAddress ^String(20) ^Optional
terminalCountry ^String(2) ^Optional
terminalZip ^String(5) ^Optional
terminalState ^String(3) ^Optional
terminalModel ^String ^Optional
terminalManufacturer ^String ^Optional
terminalMacAddress ^String ^Optional
terminalKernel ^String ^Optional
terminalImei ^String ^Optional
mobileTerminal ^Integer ^Optional

localpayment

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

 

Payment Page

Payment Page

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

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

For more details, please refer to Payment Page.

 

Callbacks (DMNs)

Callbacks (DMNs)

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 callback, also known as a Direct Merchant Notification (DMN).

For more details, please refer to our Callbacks (DMNs) guide.

Additional Services

Additional Services

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

• Payment Options API
• Advanced APM Integration Overview
• Rebilling
• Withdrawals API
• KYC API