Create an API call and use encryption

How to create an API call

Building an API call to NEXI always follows the same sequence:

https://ing-developer.atlassian.net/wiki/download/attachments/76317736/Creating%20API%20request.png?api=v2

Libraries for HMAC and Blowfish

Here are some libraries supporting you with HMAC calculation and Blowfish-Encryption: Implementation Sources

Merchant credentials

You will receive your merchant credentials after signing up the contract.

The merchant credentials consist of:

MerchantId: Your MerchantId on NEXI
HMAC-password: A password to calculate the MAC-value to protect specific values in the request (e.g. amount, currency) or response (e.g. status, code)
Blowfish/AES-password: A password to encrypt your request to NEXI and its response.

info You may receive a multiple set of MerchantId's and password's as a MerchantId is used to unite a set of configurations (e.g. paymethods, currencies, services).

Example

We would like to create a payment for 12,34 EUR with english language for the hosted payment page with additional template parameters.

3-D Secure 2.x shall be used in case that the customer selects credit cards (e.g. Mastercard, VISA, American Express), but also other paymethods like PayPal, Direct Debit, Sofort, ... can be selected.

Therefore we need:

MAC calculation to secure amount and currency
put API parameters together - unencrypted
encrypt all API parameters → by this we will get "Data" + "Len" for the API request
add plain parameters to customize Hosted Payment Page using (HPP) with a template, e.g. language="en" for using the HPP with preselected english language
send the API request to the desired endpoint.

MAC calculation

The MAC is calculated always like this: HmacSHA256("PayId*TransID*MerchantID*Amount*Currency", "YourHmacPassword") where:

Key	Value	Comments
PayId	Referenced PayId	May be empty, e.g. for creating an initial payment process or risk management request; is used with subsequent requests like capture/refund.
TransId	Your transactionId to reference / identify your request	Your own reference to identify each request / payment process.
MerchantId	Your MerchantId	Your MerchantId assigned to you by NEXI identifiying this request.
Amount	Amount in smallest unit of currency, e.g. 123=1,23 (EUR)	Amount of this request; may be empty if not used, e.g. for status inquiries.
Currency	Currency of payment process in ISO 4217, e.g. EUR, USD, GBP	Currency of this request; may be empty if not used, e.g. for status inquiries.
YourHmacPasswort	Your HMAC-password assigned to you by NEXI	Your HMAC-password assigned to a specific MID; if you have different MIDs you will have different HMAC passwords, too.

Notes:

in case that a value is not present just leave it empty, e.g.:
- with amount/currency, without PayId to initiate a new payment - like in this example: HmacSHA256("*TID-4453732122167114558*yourMerchantId*1234*EUR", "mySecret")
- with amount/currency, without PayId, without TransId: HmacSHA256("**yourMerchantId*1234*EUR", "mySecret")
- with PayId, without amount/currency: HmacSHA256("fe3f002e19814eea8aa733ec4fdacafe*TID-4453732122167114558*yourMerchantId**", "mySecret")
you will find more details for HMAC-calculation
- for requests: HMAC Authentication (Request)
- for responses/notify: HMAC Authentication (Notify)

Raw parameters before encryption

The raw parameters define basic settings for this payment call, e.g. your MerchantId, amount, currency, your reference and URLs for success, failure and notify:

Key-Value	Comments
MerchantID=yourMerchantId	Your MerchantId to identify your request at NEXI
MsgVer=2.0	Indicate that 3-D Secure 2.x shall be used; Specially for 3-D Secure 2.x it is useful to provide additional data (like billing- and shipping-address) to improve frictionless processing (i.e.: payment is authenticated without challenge).
TransID=TID-18724420542167170812	Your request identifier
RefNr=RG123-2021	Your payment process reference
Amount=1234	The desired amount in smallest currency unit, e.g. 1234 + EUR → 12,34 EUR
Currency=EUR	and currency
URLSuccess, URLFailure, URLBack	URLs for forwarding the customer in case of success, failure, cancel
URLNotify	URL to receive NEXI notifies
Response=encrypt	NEXI shall respond with encrypted data
Language=en	Customer wants english language

Parameters before encryption

MerchantID=yourMerchantId&MsgVer=2.0&TransID=TID-18724420542167170812&RefNr=RG123-2023&Amount=1234&Currency=EUR&URLSuccess=https://www.yourshop.info/success.php&URLFailure=https://www.yourshop.info/failure.php&URLNotify=https://www.yourshop.info/notify.php&Response=encrypt&MAC=ca3c75eaf2120dfd15de77af2398b1561d8473f647b72aa7270fde94df7756d6&Language=en

As "=" and "&" are used for building key-value-pairs these characters must not be part of any value.

Do not send empty values, but only keys which are required and really having values.

For credit card processing with 3-D Secure 2.x (EMV 3DS) you must add "MsgVers=2.0"

Hosted Payment Page works like a proxy for the other payment forms (i.e. Credit Card Form (PaySSL), Direct Debit Form (PaySDD), paymethod specific forms (e.g. PayPal))

so you have to add "MsgVers=2.0" to enable 3-D Secure 2.x for Credit Card Form (PaySSL)
you may supply other key-values for other paymethods (e.g. PayPal)

Encryt parameters into Data/Len (Blowfish)

The raw parameters are encrypted via Blowfish ECB and then hex-encoded. We provide you predefined functions in our toolkits for a quick start.

Notes

The value for "Len" is the string length of the unencrypted parameter string built in the step before.
Blowfish is standard encryption mode of NEXI

To ease your integration we provide predefined functions to help you with Blowfish ECB:

Your language	Where to find
ASP	txmsCrypto.dll // txmsCrypto.BlowFish
http://ASP.NET	NEXI.Core.Crypto.dll // NEXI.Core.Crypto.BlowFish
Java	Blowfish.java
PHP	function.inc.php ctHMAC ctEncrypt ctDecrypt

Here a sample

Element	Value
MerchantID	yourMerchantId
Password	TestTestTestTest
Unencrypted request	MerchantID=yourMerchantId&MsgVer=2.0&TransID=TID-18724420542167170812&RefNr=RG123-2023&Amount=1234&Currency=EUR&URLSuccess=https://www.yourshop.info/success.php&URLFailure=https://www.yourshop.info/failure.php&URLNotify=https://www.yourshop.info/notify.php&Response=encrypt&MAC=ca3c75eaf2120dfd15de77af2398b1561d8473f647b72aa7270fde94df7756d6&Language=en
Len	354
Data	397fb1b3eadb19c4c4610422e3426cecbc9e5f3c83ff04be4d78a63827839703847465e7118da27f8e186b7053923d5189c321d6bb04dbe1f147561184fc3c4c999861c69b79a94a1a44494219adaec1688765fa72282e04eca73b5725996acddfb874a615610df41c4eb8ae12bc62eece8c44dc50726afcf4d249d8a4d5af7ee93f9ea95839bf6ffcaa94eaa70e46f002b5954c3bbe9ae2a69ee1b451cf8d96387c09c4c7300ab95e5850df082d778a31f84e7c3722760d5f71927869a1ab3139154673d908a96ab2f5be4493b10112a4fa825b257310b79834027703224aa831f84e7c3722760d5f71927869a1ab314f78b3f489b9b6e165163bbdbb086ca49072acdfbb9fa317d847056fc38d6e0ec7a19685cfc7eaf733c965596e2a2df611686b5078cbf4f3f73338a8769334d88b674fa0ef1a03ffa518668a6f12e6fd0a4ab5fdfb093354f551c52de3a75c0a113dd8837ba810ae8926051ed6edbfcc3c1aef6417699fb6

Encryt parameters into Data/Len (AES)

The raw parameters are encrypted via AES/CBC/PKCS7 and then hex-encoded.

Notes

AES 128 / AES 192 / AES 256 are supported and depend on password-length with 16, 24 or 32 Byte
AES can be setup by NEXI on request
AES does not require LEN-parameter by technology, but it's still required for NEXI-compatibility
AES is used with Initialization Vector (IV) of 16 Bytes. IV is Bin2Hex-encoded and sent plain as part of Data: Data=concat(Bin2Hex(IV), "-", Bin2Hex(encryptedData))
The Initialization Vector (IV) is created randomly with each encryption process, is sent in plain text (Bin2Hex-encoded) and required for decryption

To ease your integration here some links to ancryption with AES CBC:

Your language	Links
ASP	https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.aescryptoserviceprovider.iv?view=net-6.0
Java	https://docs.oracle.com/javase/7/docs/api/javax/crypto/Cipher.html
PHP	https://www.php.net/manual/en/function.openssl-encrypt.php

Here a sample

Element	Value
MerchantID	yourMerchantId
Password	TestTestTestTest
Unencrypted request	MerchantID=yourMerchantId&MsgVer=2.0&TransID=TID-18724420542167170812&RefNr=RG123-2023&Amount=1234&Currency=EUR&URLSuccess=https://www.yourshop.info/success.php&URLFailure=https://www.yourshop.info/failure.php&URLNotify=https://www.yourshop.info/notify.php&Response=encrypt&MAC=ca3c75eaf2120dfd15de77af2398b1561d8473f647b72aa7270fde94df7756d6&Language=en
Len	354
Data	5b447021b775137d2a4249f271200071-634f5b121cf01f3bcc060f00827fb55affe364be050a36a9e97e9571ea1c2c150731300051cb2618f4e6809f72ecdf284e81ef465e0db2b808f5104f79d92cb4055dd60a5227cc82b82d240d502e51a60606c82c69bed317e117cdbb110cdd2cc8a7712a18c398990cc47a532cdf8caef6a32f048b51576de4d2575c9cf61ce08c3f6a441ea8e553028b6b7f908ebe0c34e3ed064b17b32f0a2afc7873ec16d10eaa7780ec89c1c6b1a0d68508cf9dbb916e27adcb08aeb774880c61001e66a10c841f0742fca82882260c511ab2a9ee9252ac88c6833b265fb70bb0f99af65b15434d052106dee38d2262ab72973aa28940da8c99c35f57f6fe5c065005b1c1e726b60eaeaba8fd3ed32edfdcbae52af9c92c0ba7c1a7edf88888a1f9af9055a105803beacbf5627d1d4a95b6aceebeb4f27b1fab6b47bfc8a2542b527b12514e80c959d038c177473363095b0aeff333962c4d5054bc293fea6402fac1fda8fab81b6d3c8127a709e3bbe1dfed19ae
Note	5b447021b775137d2a4249f271200071 is the Initialization Vector (IV) of 16 Bytes generated with AES encryption converted from Bin to Hex.

Notice: Please note that if you want to switch to AES encryption as a merchant, all requests for all actions must also be encrypted with AES. Please coordinate the changeover with all parties in advance. Batch submission is excluded here as no API encryption is used. In this case, PGP is used for security.

Now putting all together – the API request

The API request is then built like:

Value	Comments
Basic parameters
e.g. paymentPage.aspx	Selected desired endpoint of NEXI
MerchantID=yourMerchantId	Your MerchantId to identify your request at NEXI (here additionally as plain value)
Len=<Len>&Data=<Data>	Length of the uncrypted parameter string and Data returned by Encryption
Template parameter (plain)
Template=PaymentPageDropDown_v1	Template for Hosted Payment Page (HPP)
CCTemplate=Cards_v1	Template for Credit Card Form (called by HPP)
SDDTemplate=DirectDebit_v1	Template for Direct Debit Form (called by HPP)
Language=en	Starting laguage for the customer
CustomField1..16	Some CustomField-Data to display additional information on the HPP depending on the template

Building the API-call

https://www.NEXI-.com/paymentPage.aspx?MerchantID=yourMerchantId&Data=397fb1b3eadb19c4c4610422e3426cecbc9e5f3c83ff04be4d78a63827839703847465e7118da27f8e186b7053923d5189c321d6bb04dbe1f147561184fc3c4c999861c69b79a94a1a44494219adaec1688765fa72282e04eca73b5725996acddfb874a615610df41c4eb8ae12bc62eece8c44dc50726afcf4d249d8a4d5af7ee93f9ea95839bf6ffcaa94eaa70e46f002b5954c3bbe9ae2a69ee1b451cf8d96387c09c4c7300ab95e5850df082d778a31f84e7c3722760d5f71927869a1ab3139154673d908a96ab2f5be4493b10112a4fa825b257310b79834027703224aa831f84e7c3722760d5f71927869a1ab314f78b3f489b9b6e165163bbdbb086ca49072acdfbb9fa317d847056fc38d6e0ec7a19685cfc7eaf733c965596e2a2df611686b5078cbf4f3f73338a8769334d88b674fa0ef1a03ffa518668a6f12e6fd0a4ab5fdfb093354f551c52de3a75c0a113dd8837ba810ae8926051ed6edbfcc3c1aef6417699fb6&Len=354&Template=PaymentPageDropDown_v1&Language=en&CCTemplate=Cards_v1&SDDTemplate=DirectDebit_v1&URLBack=https%3A%2F%2Fwww.yourshop.info%2F&CustomField1=12%2C34+EUR&CustomField2=Order+Text&CustomField3=https%3A%2F%2Fwww.paytest.info%2Fphantasy-logo.png&CustomField4=Shopping+Cart&CustomField5=Company+Name&CustomField6=First+Name&CustomField7=Stra%C3%9Fe+4&CustomField8=12345+City&CustomField9=Shipping+Company&CustomField10=Shipping+Name&CustomField11=Shipping+Street&CustomField12=23456+Shipping+City&CustomField13=RG-Inv+123%2F2021&CustomField14=Some+Label&CustomField15=Some+Text&PayType=0

info This URL doesn't work and will result in "Unexpected exception", because MerchantId "yourMerchantId" doesn't exist. You will find some working URLs below.

Putting API-call together

The API-call consists of:

Category	Description
NEXI endpoint	e.g. https://www.NEXI-.com/paymentPage.aspx
MerchantID=<>	MerchantID=YourMerchantID
Len & Data	Encrypted data containing request data
additional params	Additional key/values in plain, not encrypted

Sending the API request

A request can be sent either via GET or POST. We recommend to use POST for two reasons:

with GET the parameter length is restricted to 2048 bytes depending on the browser, while with POST the request length is limited to 5120 bytes; If you require longer strings please contact NEXI
via GET the parameters are attached to the URL which can be easily manipulated by a customer - therefore NEXI prevents manipulation using Blowfish/AES encryption

Checking the NEXI response

Server-2-server response

With server-2-server requests a request will respond with a direct response containing

a status indicating success or failure of transaction
a code (response code) explaining details of transaction along with a description
other data like PayId for each payment process
and other data depending on the type transaction

Payment page / ansynchronous notification

In case of a redirect payment an ansynchronous notification is sent to your system indicated by a URLnotification.

The response can be either encrypted or in plain text - we recommend an encrypted response.

Common

Please check:

just checking whether "URLFailed" or "URLSuccess" has been called is not sufficient and can easily misused
- Response code: only "code=00000000" indicates a successful and completed action
HMAC in NEXI response is valid - to ensure that the message is not manipulated

Some tips on NEXI responses

Some tips on responses

Result	Description
Unexpected exception	NEXI response not containing "code" and "status" a very likely reason is that you simply used a wrong template name or wrong MerchantId. See more details in our documentation for Payment Pages
PayId=0000....0000 code=8 digit	NEXI detected some error in request and a payment process has not been created. These payment processes can not be found in NEXI. An overview of response codes can be found here: Response codes
valid PayId code=8 digit	A payment process with PayId has been created but the subsequent systems detected an error. An overview of response codes can be found here: Response codes
code=xxxx0005	The amount is the first parameter which is checked. The amount must be given in numbers without decimals. But you may also simply have mixed up your MIDs and Encryption-keys - just doublecheck.
valid PayId code=00000000	Payment / process successful and completed
valid PayId code=0	Payment / process pending