Skip to main content

Nuvei

Overview​

Gateway Website https://nuvei.com
Developer Documentation: https://docs.nuvei.com/api/main/indexMain_v1_0.html?json#PaymentAPIOverview
Default Currency: USD

Request Objects: BillingAddress, ShippingAddress, CreditCard, OrderInfo,SoftDescriptors, StoredCredentials, ThreeDSecure

Gateway Endpoints
This implementation of Nuvei forwards request to the below endpoints

ActionProductionSandbox
Card Authorize, Card Purchasehttps://secure.safecharge.com/ppp/api/v1/payment.dohttps://ppp-test.safecharge.com/ppp/api/v1/payment.do
Card Capturehttps://secure.safecharge.com/ppp/api/v1/settleTransaction.dohttps://ppp-test.safecharge.com/ppp/api/v1/settleTransaction.do
Card Refundhttps://secure.safecharge.com/ppp/api/v1/refundTransaction.dohttps://ppp-test.safecharge.com/ppp/api/v1/refundTransaction.do
Card Voidhttps://secure.safecharge.com/ppp/api/v1/voidTransaction.dohttps://ppp-test.safecharge.com/ppp/api/v1/voidTransaction.do

Supported Request Parameters​

* denotes a required field
Field NameTypeNuvei MappingNotes
gatewaystringN/ANuvei
merchantKey*stringMerchantKeyThe merchant key provided by Nuvei (part of the authentication credentials).
merchantId*string(20)MerchantIdThe merchant ID provided by Nuvei (part of the authentication credentials).
merchantSiteId*string(20)MerchantSiteIdThe merchant Site ID provided by Nuvei (part of the authentication credentials).
testModebooleanServerHostTrue = TEST, False = PRODUCTION
sessionTokenstringSessionTokenGenerating a session token
If a session token is not sent, one will be auto-generated and available from the gatewayResponse.rawResponse.
amountintAmountTransaction amount in whole units. Example: $10.00 USD should be sent as 1000
userPaymentOptionIdstringPaymentOption.​UserPaymentOptionIdThis is a field identifying a payment option that has already been used by the customer and now it is requested for re-use. Nuvei keeps payment option details from previous uses.
alternativePaymentMethod.​PaymentMethodstring(50)PaymentOption.​AlternativePaymentMethod.​PaymentMethodSpecifies the payment method name of the payment option to be charged.
relatedTransactionIdstring(19)RelatedTransactionIdRequired for 3D-Secure, recurring/rebilling, and MIT payments
authenticationTypeOnlystringAuthenticationTypeOnlyIf you are not using Nuvei User Payment Management (Nuvei tokenization) and would like to send Zero Amount Authorization, you need to set AuthenticationTypeOnly to either RECURRING or INSTALLMENTS
clientRequestIdstring(255)ClientRequestIdUse this advanced field to prevent idempotency. Use it to uniquely identify the request you are submitting. If Nuvei's system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
clientUniqueIdstring(45)ClientUniqueIdThis ID identifies the transaction in your system. Optionally, you can pass this value in and Nuvei will store it with the transaction record created in their system for your future reference.
isMotostringIsMotoSet this field to “1” to mark the transaction as MOTO (mail order/telephone order). Leave null or “0” for regular transaction.
isRebillingnumericIsRebillingWhen performing recurring/rebilling, use this field to indicate the recurring step with the following values: 0 – For the first transaction in a series of recurring transactions. 1 – For all subsequent recurring transactions.
isPartialApprovalstringIsPartialApprovalThis 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.
customSiteNamestringCustomSiteNameThe 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.
productIdstringProductIdA 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.
customDatastringCustomDataThis parameter can be used to pass any type of information. If sent in request, then it is passed on to the payments gateway, and is visible in Nuvei’s back-office tool transaction reporting and is returned in response.
creditCard.​NumberstringPaymentOption.​Card.​CardNumberCard number or TokenEx Token - Tokenex will replace the Token with the Detokenized number
creditCard.​BrandstringPaymentMethod.​Card.​Brand and ExternalSchemeDetails.​BrandIf a value is not sent, the brand is parsed from the card number.
creditCard.​FirstNamestringPaymentOption.​Card.​CardholderNameConcatenated with LastName in the Card.CardHolderName field
creditCard.​LastNamestringPaymentOption.​Card.​CardholderNameConcatenated with FirstName in the Card.CardHolderName field
creditCard.​ExpMonthstringPaymentOption.​Card.​ExpirationMonthThe two-digit expiration month of the card. Example: 01
creditCard.​ExpYearstringPaymentOption.​Card.​ExpirationYearThe four-digit expiration year of the card. Example: 2022
creditCard.​CVVstringPaymentOption.​Card.​CVVThe three- or four-digit number on the back of a credit card (on the front for American Express).

This field is required if the merchant would like to use the Card Code Verification (CCV) security feature.

Cardholder information must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard.
creditCard.​AcquirerIdstringPaymentOption.​Card.​AcquirerIdThe acquirer ID of the acquirer which processed the transaction.
creditCard.​CcTempTokenstringPaymentOption.​Card.​CcTempTokenA temporary card token that can be used instead of your card number in your call.
creditCard.​StoredCredentialsModestring(1)PaymentOption.​Card.​StoredCredentials.​StoredCredentialsModeThis parameter shows whether or not stored tokenized card data is sent to execute the transaction.
threeDSecure.​CAVVstringPaymentOption.Card.​ThreeD.​ExternalMpi.​CavvThe Cardholder Authentication Verification Value (CAVV) for a Visa transaction, or Accountholder Authentication Value (AVV)/ Universal Cardholder Authentication Field indicator (UCAF) for a Mastercard transaction as received from the external MPI (Message Passing Interface)
threeDSecure.​ECIstringPaymentOption.Card.​ThreeD.​ExternalMpi.​EciThe Electronic Commerce Indicator (ECI) value for a Visa transaction, or the Universal Cardholder Authentication Field indicator (UCAF) for a Mastercard transaction. The cardholder authentication process generates the ECI or UCAF value prior to submitting the transaction.
threeDSecure.​DSTransIdstring(36)PaymentOption.Card.​ThreeD.​ExternalMpi.​DsTransIdThe transaction ID received from the MPI for 3D-Secure v2. Required for 3D-Secure v2; do not send for 3D-Secure v1.
threeDSecure.​ThreeDSecureVersionstringPaymentOption.​Card.​ThreeD.​VersionString passthrough for the version of 3DS used to perform the authentication. Including a value in this field may improve authorization rates.
note: this field is not part of Nuvei's external MPI 3DS authentication flow.
orderInfo.​ShippingAmountnumericAmountDetails.​TotalShippingShipping amount in whole units. Example: $10.00 USD should be sent as 1000
orderInfo.​DiscountAmountnumericAmountDetails.​TotalDiscountDiscount amount in whole units.
orderInfo.​DutyAmountnumericAmountDetails.​TotalHandlingDuty amount in whole units.
orderInfo.​PurchaseOrderNumberstringOrderIdThe order ID provided by Nuvei. This parameter is passed to define which merchant order to update.
orderInfo.​CustomerIdstringUserTokenIdThis ID uniquely identifies your consumer/user in your system.
tax.​Exemptboolean[not mapped]True/false. Only used for determining whether to include tax amount in the Nuvei request.
tax.​AmountnumericAmountDetails.​TotalTaxTax amount in whole units. Only passed through if Tax.Exempt is false
subMerchant.​CountryCodestring(2)SubMerchant.​CountryCodeThe payment facilitator’s submerchant’s Alpha-3 ISO country code
subMerchant.​Citystring(10)SubMerchant.​CityThe payment facilitator’s submerchant’s city name.
subMerchant.​Idstring(15)SubMerchant.​IdThis field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
deviceDetails.​DeviceTypestring(10)DeviceDetails.​DeviceTypeSupported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized).
deviceDetails.​DeviceNamestring(255)DeviceDetails.​DeviceNameThe name of the device.
deviceDetails.​DeviceOsstring(255)DeviceDetails.​DeviceOSThe OS of the device.
deviceDetails.​Browserstring(255)DeviceDetails.​BrowserThe browser of the device.
customerIpAddress*stringDeviceDetails.​IpAddressThe IP address of the device generating the operation.
subMethodDetails.​SubMethodstringSubMethodDetails.​SubMethodThe sub-method parameter enables working with a specific payment method in a few different flows. See the Nuvei APM Submethods page for details.
subMethodDetails.​EmailstringSubMethodDetails.​SubMethodField1Only applicable if using sub method "Skrill1tap"
userDetails.​AddressstringUserDetails.​AddressThe user's address.
userDetails.​CitystringUserDetails.​CityThe user's city.
userDetails.​CountrystringUserDetails.​CountryThe user's Alpha-3 ISO country code
userDetails.​Countystring(255)UserDetails.​CountyThe user's county.
userDetails.​DateOfBirthstring(10)UserDetails.​DateOfBirthThe user's date of birth. Format is YYYY-MM-DD.
userDetails.​EmailstringUserDetails.​EmailThe user's email address.
userDetails.​FirstNamestringUserDetails.​FirstNameThe user's first name.
userDetails.​LastNamestringUserDetails.​LastNameThe user's last name.
userDetails.​Languagestring(2)UserDetails.​LanguageThe user's language. 2-letter ISO language code.
userDetails.​PhonestringUserDetails.​PhoneThe user's phone number.
userDetails.​ZipstringUserDetails.​ZipThe user's postal code.
shippingAddress.​Address1stringShippingAddress.​AddressCustomer’s shipping address.
shippingAddress.​Address2stringShippingAddress.​AddressLine2Customer’s shipping address, line 2.
shippingAddress.​CountrystringShippingAddress.​CountryCodeAlpha-3 ISO country code
shippingAddress.​EmailstringShippingAddress.​EmailEmail address associated with customer’s shipping address.
shippingAddress.​CitystringShippingAddress.​CityCity of customer’s shipping address.
shippingAddress.​StatestringShippingAddress.​StateState of customer’s shipping address.
shippingAddress.​ZipstringShippingAddress.​ZipPostal code of customer’s shipping address.
shippingAddress.​PhonestringShippingAddress.​CellCell phone number associated with customer’s shipping address.
shippingAddress.​FirstNamestringShippingAddress.​FirstNameFirst name associated with customer’s shipping address.
shippingAddress.​LastNamestringShippingAddress.​LastNameLast name associated with customer’s shipping address.
billingAddress.​Address1stringBillingAddress.​AddressCustomer’s billing address.
billingAddress.​Address2stringBillingAddress.​AddressLine2Customer’s billing address, line 2.
billingAddress.​CountrystringBillingAddress.​CountryCodeAlpha3Alpha-3 ISO country code
billingAddress.​EmailstringBillingAddress.​EmailEmail address associated with customer’s billing address.
billingAddress.​CitystringBillingAddress.​CityCity of customer’s billing address.
billingAddress.​StatestringBillingAddress.​StateState of customer’s billing address.
billingAddress.​ZipstringBillingAddress.​ZipPostal code of customer’s billing address.
billingAddress.​PhonestringBillingAddress.​CellCell phone number associated with customer’s billing address.
billingAddress.​FirstNamestringBillingAddress.​FirstNameFirst name associated with customer’s shipping address.
billingAddress.​LastNamestringBillingAddress.​LastNameLast name associated with customer’s shipping address.
dynamicDescriptor.​MerchantNamestring(25)DynamicDescriptor.​MerchantNameThe merchant name, as is displayed for the transaction on the consumer’s card statement.
dynamicDescriptor.​MerchantPhonestring(13)DynamicDescriptor.​MerchantPhoneThe merchant contact information, as is displayed for the transaction on the consumer’s card statement. It can also be an email address.
softDescriptors.​MerchantNamestring(25)DynamicDescriptor.​MerchantNameThe merchant name, as is displayed for the transaction on the consumer’s card statement. NOTE: Takes precedent over dynamicDescriptor.MerchantName if both are populated
softDescriptors.​MerchantPhonestring(13)DynamicDescriptor.​MerchantPhoneThe merchant contact information, as is displayed for the transaction on the consumer’s card statement. It can also be an email address. NOTE: Takes precedent over dynamicDescriptor.MerchantPhone if both are populated
merchantDetails.​CustomField1string(255)MerchantDetails.​CustomField1These fields allow the merchant to send information with the request to be saved in the API level and returned in response. It is not passed to the payment gateway and is not used for processing. Applies to all custom fields below.
merchantDetails.​CustomField2string(255)MerchantDetails.​CustomField2
merchantDetails.​CustomField3string(255)MerchantDetails.​CustomField3
merchantDetails.​CustomField4string(255)MerchantDetails.​CustomField4
merchantDetails.​CustomField5string(255)MerchantDetails.​CustomField5
merchantDetails.​CustomField6string(255)MerchantDetails.​CustomField6
merchantDetails.​CustomField7string(255)MerchantDetails.​CustomField7
merchantDetails.​CustomField8string(255)MerchantDetails.​CustomField8
merchantDetails.​CustomField9string(255)MerchantDetails.​CustomField9
merchantDetails.​CustomField10string(255)MerchantDetails.​CustomField10
merchantDetails.​CustomField11string(255)MerchantDetails.​CustomField11
merchantDetails.​CustomField12string(255)MerchantDetails.​CustomField12
merchantDetails.​CustomField13string(255)MerchantDetails.​CustomField13
merchantDetails.​CustomField14string(255)MerchantDetails.​CustomField14
merchantDetails.​CustomField15string(255)MerchantDetails.​CustomField15
urlDetails.​SuccessUrlstring(1000)UrlDetails.​SuccessUrlThe URL the customer is directed to after a successful transaction.
urlDetails.​FailureUrlstring(1000)UrlDetails.​FailureUrlThe URL the customer is directed to after an unsuccessful transaction.
urlDetails.​PendingUrlstring(1000)UrlDetails.​PendingUrlThe URL the customer is directed to when the transaction response is pending.
urlDetails.​NotificationUrlstring(1000)UrlDetails.​NotificationUrlThe URL to which DMNs (Direct Merchant Notifications) are sent.
currencyConversion.​Typestring(10)CurrencyConversion.​TypeThe DCC flag indicating the type of conversion. For more information, see the Dynamic Currency Conversion Compliance Guide and the Nuvei DCC guide
currencyConversion.​OriginalAmountnumericCurrencyConversion.​OriginalAmountThe original amount of the transaction in whole units of the original currency. Example: $10.00 USD should be sent as 1000
currencyConversion.​OriginalCurrencystring(3)CurrencyConversion.​OriginalCurrencyThe 3-letter ISO currency code of the merchant’s own currency.
storedCredentials.​InitiatorstringIsRebillingValid value mappings:
"cardholder" = "0"
"merchant" = "1". Can be overridden by the IsRebilling field above.
storedCredentials.​CredentialStoredbooleanPaymentOption.​Card.​StoredCredentials.​StoredCredentialsModeSee usage in The Basics - Stored Credentials. True = "1", False = "0"
storedCredentials.​PreviousNetworkTransactionIdstringrelatedTransactionId or
ExternalSchemeDetails.​TransactionId		See usage in The Basics - Stored Credentials. Obtained from Nuvei response field TransactionId. See storedCredentials.​OriginCITThroughDifferentProvider
storedCredentials.​OriginCITThroughDifferentProviderbooleanaffects ExternalSchemeDetails.​TransactionId and ExternalSchemeDetails.​BrandIf true, the value sent in storedCredentials.PreviousNetworkTransactionId is mapped to ExternalSchemeDetails rather than relatedTransactionId. Card brand is read from CreditCard.Brand.
storedCredentials.​TransactionTypestringunmappedAny value sent will be dropped.

Example Requests​

{
  "merchantKey": "<Your Nuvei Merchant Key>",
  "merchantId": "<Your Nuvei Merchant ID>",
  "merchantSiteId": "<Your Nuvei Merchant Site ID>",
  "customerIpAddress": "100.101.102.103",
  "subMerchant": {
    "countryCode": "USA",
    "city": "Chicago",
    "id": "sampleMerchant"
  },
  "deviceDetails": {
    "deviceType": "DESKTOP",
    "deviceName": "TestDevice",
    "deviceOs": "Windows 10",
    "browser": null
  },
  "creditCard": {
    "acquirerId": null,
    "ccTempToken": null,
    "storedCredentialsMode": null,
    "lastName": "Nader",
    "brand": "Visa",
    "number": "4000022756305864",
    "expMonth": 9,
    "expYear": 2024,
    "firstName": "Rochelle",
    "cvv": "123"
  },
  "billingAddress": {
    "phone": "555-555-5555",
    "fax": "555-555-6666",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "name": "John Doe",
    "company": "Test Co.",
    "address1": "123 Someplace Lane",
    "address2": null,
    "city": "Tulsa",
    "state": "OK",
    "zip": "74111",
    "country": "USA"
  },
  "orderInfo": {
    "customerId": "storedCredentials-CustomerId"
  },
  "storedCredentials": {
    "initiator": "merchant",
    "credentialStored": true,
    "previousNetworkTransactionId": "711000000014281841"
  },
  "amount": 1000,
  "gateway": "Nuvei",
  "testMode": true,
  "currencyCode": "USD"
}

Gateway Response Parameters​

Field NameTypeNuvei Result MappingNotes
approvedbooleanTransactionStatusTrue if TransactionStatus equals 2 or "APPROVED"
approvalCodestringAuthCodeThe authorization code of the transaction.
providerTransactionCodestringTransactionIdTransaction ID of the newly run transaction
tokenexTransactionCodestringTransactionId;AuthCodeBase64 encoded
networkTransactionIdstringexternalSchemeTransactionIdValue to reference transaction in subsequent transactions. Example usage: storedCredentials.PreviousNetworkTransactionId
paymentProfileIdstringpaymentOption.userPaymentOptionIdID for the newly created payment option, which can be referenced in future requests.
customerProfileIdstringuserTokenIdThis ID uniquely identifies your consumer/user in your system.
merchantReferenceIdstringclientUniqueIdThe ID of the transaction in the merchant’s system.
verificationResult.cvvRawstringpaymentOption.card.cvv2ReplyThe CVV2 (card verification value) response returned by issuer.
verificationResult.avsRawstringpaymentOption.card.avsCodeThe address verification service (AVS) response returned by issuer.

Example Responses​

{
  "gatewayResponse": {
    "rawResponse": "{\"internalRequestId\":850532838,\"status\":\"SUCCESS\",\"errCode\":0,\"reason\":\"\",\"merchantId\":\"3612317282928935212\",\"merchantSiteId\":\"212567\",\"version\":\"1.0\",\"sessionToken\":\"18c348b1-5ceb-4549-a952-5d95b018c633\",\"orderId\":\"407325938\",\"paymentOption\":{\"userPaymentOptionId\":\"\",\"card\":{\"ccCardNumber\":\"4****1390\",\"bin\":\"476134\",\"last4Digits\":\"1390\",\"ccExpMonth\":\"01\",\"ccExpYear\":\"25\",\"acquirerId\":\"19\",\"cvv2Reply\":\"\",\"avsCode\":\"\",\"cardType\":\"Credit\",\"cardBrand\":\"VISA\",\"issuerBankName\":\"\",\"issuerCountry\":\"SG\",\"isPrepaid\":\"false\",\"threeD\":{}},\"paymentAccountReference\":\"f4iK2pnudYKvTALGdcwEzqj9p4\"},\"transactionStatus\":\"APPROVED\",\"gwErrorCode\":0,\"gwExtendedErrorCode\":0,\"issuerDeclineCode\":\"\",\"issuerDeclineReason\":\"\",\"transactionType\":\"Auth\",\"transactionId\":\"711000000029469188\",\"externalTransactionId\":\"\",\"authCode\":\"111748\",\"customData\":\"\",\"fraudDetails\":{\"finalDecision\":\"Accept\"},\"externalSchemeTransactionId\":\"\",\"merchantAdviceCode\":\"\"}",
    "gatewayErrors": [],
    "tokenExTransactionCode": "NzExMDAwMDAwMDI5NDY5MTg4OzExMTc0OA==",
    "approvalCode": "111748",
    "providerTransactionCode": "711000000029469188",
    "approved": true,
    "verificationResult": {
      "avsRaw": "",
      "cvvRaw": ""
    },
    "networkTransactionId": "",
    "paymentProfileId": ""
  },
  "referenceNumber": "23120710552911748563",
  "success": true,
  "error": "",
  "message": "",
  "thirdPartyStatusCode": "200"
}
Last updated on