Overview
This topic describes all the parameters that can be sent to Cashier Deposit page via an HTTP request.
Basic Parameters
Mandatory column values:
- All: Mandatory for all transaction types (every request).
- No: The parameter is not mandatory.
- Risk: By default, the parameter is configured as mandatory for risk analysis, and should be included in every request made. Changes to the mandatory risk fields must be approved by the Nuvei Risk team.
Parameter | Type | Size | Mandatory | Description |
---|---|---|---|---|
merchant_id | Integer | 64bits | All | The merchant’s ID provided by Nuvei. |
merchant_site_id | Integer | 64bits | All | The merchant website’s ID provided by Nuvei. |
checksum | String | Char(102400) | All | A hashing of the request to secure and authenticate the request. |
time_stamp | String | Char(19) | All | Current GMT time in the following format: YYY-MM-DD.HH:MM:SS. |
currency | String | Char(3) | All | The currency used in the transaction. |
invoice_id | String | Char(100) | No | A unique invoice identifier provided by the merchant or randomly generated. |
payment_method | String | Char(256) | No | The type of payment method selected by the customer. Credit Card: cc_card Debit Card: dc_card Alternative PM: For the values of specific APMs, see alternativePaymentMethod Class. |
payment_method_mode=filter | This parameter filters out any payment method that is not the payment method sent in the Payment_method parameter. |
|||
merchantLocale | String | Char(5) | No | The language and country of the user in ISO code in the following format: [language ISO]_[country ISO] Unless specified, the default is English. The possible values of this parameter is provided below: English (US): en_US English (UK): en_UK German: de_DE Chinese: (PRC) zh_CN Hebrew: iw_IL French: fr_FR Dutch (Standard): nl_NL Indonesia: in_ID Italian: it_IT Japanese: ja_JP Korean: ko_KR Lithuanian: lt_LT Spanish: es_ES English (Canada): en_CA English (Australia): en_AU Russian: ru_RU Arabic: ar_AA Portuguese: pt_BR Swedish: sv_SE Turkish: tr_TR Slovenian: sl_SI Danish: da_DK Romanian: ro_RO Bulgarian: bg_BG Polish: pl_PL Hungarian: hu_HU Vietnamese: vi_VL |
userId | String | Char(50) | No | The customer’s ID as per the merchant’s UserId. |
theme_id | Integer | 64bits | No | Use this field overrides |
customData | String | Char(255) | No | General data about the customer provided by the merchant. |
merchant_unique_id | String | Char(64) | No | The unique ID (identifier) of the transaction in the merchant’s database. |
encoding | String | Char (20) | No* If encoding=UTF-8, then this fields is mandatory. |
The type of character encoding. Default value is ISO-8859-1. |
webMasterId | String | Char(255) | No | This is an affiliate parameter that the merchant can send to Cashier. |
allow_installments | Integer | 64 bits | No | This parameter indicates whether payment may be made in installments or not, if this feature is supported by the merchant. The possible value of this parameter is either ‘1’ (yes) or ‘0’ (no). |
max_num_installments | Integer | 64 bits | No | This parameter indicates the maximum amount of installments with which the payment can be made. |
processingChannel | String | Char (4) | No | Sends “MOTO” value whenever the processing channel is from MOTO type (mail or telephone order) |
Item Details
* N represents the item count number. The first item is item_name_1 up to item_name_n.
Parameter | Type | Size | Mandatory | Description |
---|---|---|---|---|
item_name_N* | String | Char(400) | Yes | The name of item number N. Currently, item names can only include ISO-8859-1 character set encoding. |
item_number_N | String | Char(400) | Yes | The first part of the items list, the serial number. Counted from item_number_1 to item_number_N. |
item_amount_N | Double | 64 bits | Yes | The cost of the item numbered in the item_number_N parameter. |
item_shipping_N | Double | 64 bits | No | Shipping costs of the item numbered in the item_number_N parameter. |
item_handling_N | Double | 64 bits | No | Handling costs of the item numbered in the item_number_N parameter. |
item_discount_N | Double | 64 bits | No | Discount rate of the item numbered in the item_number_N parameter. |
item_quantity_N | Integer | 64 bits | Yes | Number of pieces of the item numbered in the item_number_N parameter. Default value is 1. |
item_open_amount_1 |
String | Char(5) | No |
True : Allows the customer to change the default deposit amount.False (default): The customer cannot change the default amount. |
item_min_amount_1 | Integer | 64 bits | Conditional | The minimum amount that the customer can deposit. The format is a maximum of 7 digits before the decimal and 2 digits after. Mandatory if item_open_amount_1=True . |
item_max_amount_1 | Integer | 64 bits | Conditional | The maximum amount that the customer can deposit. The format is a maximum of 7 digits before the decimal and 2 digits after. Mandatory if item_open_amount_1=True . |
numberofitems | Double | 64 bits | Conditional | Number of items to process. Default is 1. Mandatory if numberofitems is greater than 1. |
discount | Double | 64 bits | No | The total discount out of the total amount. |
shipping | Double | 64 bits | No | Total shipping costs. |
handling | Double | 64 bits | No | Total handling costs. |
total_amount | Double | 64 bits | Yes | Total transaction charge. |
total_tax | Double | 64 bits | No | The tax percentage to be applied to the transaction. |
productId | String | Char(50) | No | Merchant’s product ID. If this parameter is left empty, Cashier inserts a concatenation of all item names. |
promoCode | String | Char(512) | No | This value is a promotional code you define that you can use to apply discounts to your products or services. To activate this field, contact Nuvei Technical Support. |
nettelerAccount | String | Neteller | The customer's Neteller account number. | |
nettelerSecureId | String | Neteller | The customer's Neteller SecureId. | |
qiwi_phonenumber | String | Qiwi | The customer's phone number registered with Qiwi. |
User Token
Parameter | Type | Size | Mandatory | Description |
---|---|---|---|---|
user_token | String | Char (8) | No | This parameter determines if the payment page requires existing customers to register for each transaction. register – Always register, even if registered alreadyauto – Register only new usersreadonly – Cannot register new payment option, only use existing one. registeronly – Always register. Does not show existing payment options previously added by the userreadonlyupo – User can select only existing specific UPO specified in userPaymentOptionId
|
user_token_id | String | Char (255) | Yes | ID for the user, based on which we manage the user’s payment methods. |
userPaymentOptionId | String | No | This ID specifies the user payment option to use for the transaction when user_token = readonlyupo |
Customer Details
- Indicates that this parameter must be sent as part of the HTTPS request for Nuvei’s risk checks.
Parameter | Type | Mandatory | Description |
---|---|---|---|
first_name* | String(30) | Yes | Customer’s first name. |
last_name* | String(40) | Yes | Customer’s last name. |
email* | String(100) | Yes | Customer’s email address. |
address1* | String(60) | Yes | Customer’s address. |
address2 | String(60) | No | Customer’s address. |
city* | String(30) | Yes | Customer’s city. |
country* | String(20) | Yes | Customer’s two-letter ISO country code (see Country Codes). |
state* | String(20) | Yes | Customer’s two-letter ISO state code (for customers based in the US, Canada and India only). |
zip* | String(10) | Yes | Customer’s ZIP code. |
phone1* | String(18) | Yes | Customer’s phone1. |
phone2 | String(18) | No | Customer’s phone2. |
phone3 | String(18) | No | Customer’s phone3. |
personal_id | String(11) | No | The personal ID is the customer’s ID number issued by his/her respective country. This is only required for South American customers. |
dateOfBirth | String(10) | No | The date of birth of the registering user. (YYYY-MM-DD) |
3D-Secure v2
The Nuvei payment page handles the SCA 3D-Secure v2 process for the merchant. The merchant only needs to add parameters to the call for the web cashier URL to assist in completing the SCA process. For further information about the 3D-Secure v2, please refer to our 3D-Secure Guide.
Even though most of the below parameters are optional, it is highly recommended passing as many details as possible in the call to increase the chances of a frictionless authentication rather than invoking a challenge of the end user.
The following table displays the parameters that need to be added to fully support the 3D-Secure v2 process.
Parameter | Type | Mandatory | Description |
---|---|---|---|
deliveryEmail | String (254) | No | For electronic delivery, the email address to which the merchandise is delivered. deliveryEmail@somedomain.com |
deliveryTimeFrame | String (2) | No | This parameter indicates the merchandise delivery timeframe. 01 = Electronic delivery 02 = Same day shipping 03 = Overnight shipping 04 = Two-day or more shipping |
giftCardAmount | String (15) | No | For prepaid or gift card purchase, this represents the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123). |
giftCardCount | String (2) | No | For prepaid or gift card purchase, this represents the total count of individual prepaid or gift cards/codes purchased. |
giftCardCurrency | String (3) | No | For prepaid or gift card purchase, this represents the ISO 4217 three-letter currency code of the gift card. |
preOrderDate | String (8) | No | For a pre-ordered purchase, this represents the expected date that the merchandise is available. Format: YYYMMDD |
preOrderInd | String (2) | No | This indicates whether the cardholder is placing an order for merchandise with a future availability or release date. 01 = Merchandise available 02 = Future availability |
reorderItemsInd | String (2) | No | This indicates whether the cardholder is reordering previously purchased merchandise. 01 = First time ordered 02 = Reordered |
shipIndicator | String (2) | No | Indicates shipping method chosen for the transaction. Merchants must choose the Shipping Indicator code that most accurately describes the cardholder’s specific transaction, not their general business. If one or more items are included in the sale, use the Shipping Indicator code for the physical goods, or if all digital goods, use the Shipping Indicator code that describes the most expensive item. 01 = Ship to cardholder’s billing address 02 = Ship to another verified address on file with merchant 03 = Ship to address that is different than the cardholder’s billing address 04 = “Ship to Store” / Pickup at local store (store address shall be populated in shipping address fields) 05 = Digital goods (includes online services, electronic gift cards and redemption codes) 06 = Travel and Event tickets, not shipped 07 = Other (for example, gaming, digital services not shipped, e-media subscriptions, etc.) |
threeDSChallengeWindowSize | String (2) | No | Challenge Window Size 01 = 250 x 400 02 = 390 x 400 03 = 500 x 600 04 = 600 x 400 05 = Full screen Note: If no value is sent, the default value is 03. |
accountAge | String (2) | No | Length of time that the cardholder has had the account with the 3DS Requestor. 01 = No account (guest checkout) 02 = Created during this transaction 03 = Less than 30 days 04 = 30–60 days 05 = More than 60 days |
accountLastChangeDate | String (8) | No | Date that the cardholder’s account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added. Format: YYYMMDD |
accountLastChangeInd | String (2) | No | Length of time since the cardholder’s account information with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added. 01 = Changed during this transaction 02 = Less than 30 days 03 = 30–60 days 04 = More than 60 days |
accountRegistrationDate | String (8) | No | Date that the cardholder opened the account with the 3DS Requestor. Format: YYYMMDD |
accountPasswordChangeDate | String (8) | No | Date that cardholder’s account with the 3DS Requestor had a password change or account reset. Format: YYYMMDD |
accountResetInd | String | No | Indicates the length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset. 01 = No change 02 = Changed during this transaction 03 = Less than 30 days 04 = 30–60 days 05 = More than 60 days |
accountPurchasesCount6M | String (4) | No | Number of purchases with this cardholder account during the previous six months. |
accountAddCardAttempts24H | String (3) | No | Number of Add Card attempts in the last 24 hours. |
accountTransactionsCount24H | String (3) | No | Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours. |
accountTransactionsCount1Y | String (3) | No | Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year. |
accountAddressFirstUseDate | String (8) | No | Date when the shipping address used for this transaction was first used with the 3DS Requestor. Format: YYYMMDD |
accountAddressFirstUseInd | String (2) | No | Indicates when the shipping address used for this transaction was first used with the 3DS Requestor. 01 = This transaction 02 = Less than 30 days 03 = 30–60 days 04 = More than 60 days |
accountNameInd | String (2) | No | Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction. 01 = Account Name identical to shipping Name 02 = Account Name different than shipping Name |
accountSuspiciousActivityInd | String (2) | No | Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account. 01 = No suspicious activity has been observed 02 = Suspicious activity has been observed |
Shipping Details
The following details are required whenever product shipping is involved.
Parameter | Type | Size | Mandatory | Description |
---|---|---|---|---|
shippingFirstName | String | 30 | No | Recipient’s first name. |
shippingLastName | String | 40 | No | Recipient’s last name. |
shippingAddress | String | 60 | No | Recipient’s address. |
shippingCity | String | 30 | No | Recipient’s city. |
shippingCountry | String | 20 | No | Recipient’s country in an ISO code (see Country Codes). |
shippingZip | String | 10 | No | Recipient’s ZIP code. |
Navigation Parameters
* If some of the page’s mandatory parameters are missing, the customer’s browser is redirected to the “Cancel Page” URL.
Parameter | Type | Size | Mandatory | Description |
---|---|---|---|---|
skip_review_tab | String | Char(5) | No | A switch (true/false) indicating whether or not to skip the Cashier’s review page. |
success_url | String | Char (2048) | No | The customer is redirected to this URL on successful transaction. |
error_url | String | Char (2048) | No | The customer is redirected to this URL on error. |
pending_url | String | Char (2048) | No | The customer is redirected to this URL when response is pending. |
back_url | String | Char (2048) | No | The customer is redirected to this URL when user presses the ‘Back’ button. |
notify_url | String | Char (2048) | No | The DMN URL. See DMNs |
isNative | Boolean | 1 | No | Possible values: 1 = Opens the redirect APM in the same window (IFrame). 0 = Opens a redirect-based APM in a new window. |
quick_deposit | Boolean | 1 | No | For more information, please contact Nuvei’s Integration Team. |
Merchant Custom Fields
Parameter | Type | Size | Mandatory | Description |
---|---|---|---|---|
descriptorMerchantName | String | Char(25) | No | Allows the merchant to define a dynamic descriptor for the merchant’s name. |
descriptorMerchantPhone | String | Char(13) | No | Allows the merchant to define a dynamic descriptor for the merchant’s phone number. |
customSiteName | String | Char(50) | No | The merchant’s site name that should replace the default MerchantSite name. This parameter is useful for merchants operating many websites that are distinguished only by name. |
customField1 customField2 customField3 ... customField15 |
String | Char(64) | No | Custom fields for the merchant to update miscellaneous data. This is sent to the Cashier in the HTTP request and returned in its response. |