Chapter 4 - Payment Page

The redirecting to Nuvei is accomplished by means of a simple HTML form post with a number of defned form felds (below). The following is the Nuvei test payment page URL:

https://testpayments.nuvei.com/merchant/paymentpage

The live URL will be provided once merchant testing is complete.

The following table describes the form felds to be posted:

Field Name

Required

Description

TERMINALID

Y

A Terminal ID provided by Nuvei. NB – Please contact Nuvei to be issued with a test terminal ID.

ORDERID

Y

A unique identifer for the order created by the merchant. (Max 12 Characters).

CURRENCY

Y

Must be “USD”.

AMOUNT

Y

The amount of the transaction as a 2 digit decimal or an Integer value for JPY amounts.

DATETIME

Y

Format: DD-MM-YYYY:HH:MM:SS:SSS.

RECEIPTPAGEURL

N

This is the URL of the page on your site that will display the result of the transaction. If sent this will override the terminal setting in the SelfCare System.

CARDHOLDERNAME

N

This will pre-populate the Account Name feld on the payment page. This will be editable on the payment page. It should be as displayed on the front of the account.

DESCRIPTION

N

A description of the transaction.

EMAIL

N

An email address to send a confrmation email to. Normally this is account owner email address.

RECEIPTPAGEURL

N

This is the URL of the page on your site that will display the result of the transaction. If sent this will override the terminal setting in the SelfCare System.

VALIDATIONURL

N

This will overwrite the default Background Validation URL and will display an error if this feature is not enabled and sent. Highly recommended. See section 3.2.

TERMINALTYPE

N

1 or 2 (default). Defnes whether the transaction is to be processed as Mail Order/Telephone Order (1) or eCommerce (2 or not sent). Mail Order transactions can have a separate Payment Page Layout.

ADDRESS1

N

Will pre-populate the ADDRESS1 feld on the Hosted Payment Page

ADDRESS2

N

The same handling as ADDRESS1.

POSTCODE

N

Zip/Postal Code associated with this account, characters 0-10

CITY

N

The same handling as ADDRESS1.

STATE

N

State/Region associated with this account .

PHONE

N

Customer phone number, to be stored against transaction. International format and numeric.

AnyOtherCustomField

N

Any other felds sent in the request will be treated as a custom feld. It will be returned to the Receipt and Validation URLs also. Note that this is subject to the max length of a HTTP GET request which we would conservatively recommend considering to be 2000 characters.

Any other felds that are sent to the HPP are considered to be 'extra felds'. These will be returned in the response to the Receipt Page URL, but will not be stored in the system or sent to the Validation URL.

The following HTML shows the minimum required to initiate a transaction.

The URL where Nuvei will send transaction processing results is set on the Terminal Setup screen (Receipt Page URL feld) or is sent dynamically with the transaction as the RECEIPTPAGEURL parameter (see above).

The following felds are returned in the response:

Field Name

Description

TERMINALID

The Terminal ID that the trans was processed under.

ORDERID

The original order ID of the transaction.

UNIQUEREF

Generated reference that should be stored for tracking and remote XML refunding.

AMOUNT

Transaction amount.

RESPONSECODE

E:Initial Approval or D:Declined. If E is received then fnal approval will be provided by background notifcation.

RESPONSETEXT

The text of the authorization.

DATETIME

The time of the transaction created by the bank. Format: YYYY-MM- DDTHH:MM:SS.

ACCOUNT_TYPE

CHECKING orSAVINGS

ROUTING_NUMBER

The ACH routing number

APPROVALCODE

Approval code of the operation

HASH

An SHA-512 HASH. See Note1 below.

Any other feld

Any other felds sent in the request will be treated as a custom feld. It will be returned to the Receipt Page URL also. Note that this is subject to the max length of a HTTP GET request which we would conservatively recommend considering to be 2000 characters.

Notes:

1. The SHA-512 HASH is generated using the following as an input string:

Many code examples on how to generate an SHA-512 HASH can be found on the Internet. For assistance, please contact Nuvei.

2. Depending on your customer's browser defnitions and if there's a language template defned for his/ her language priority, the Payment Gateway is going to send the payment receipt translated. If the language is not supported by the gateway, the receipt is going to be sent using the gateway's language.

Background notifcation is a method of providing the fnal results of transactions using a server side post. The Notifcation URL must be set for the terminal or sent in the payment request to the Payment Page, and Nuvei will use this URL to send an HTTP POST request with transaction processing result and will expect to receive “OK” in the HTTP response body ( 2 characters only, no HTML). Any other response or connection issue will be considered as not-notifed and a subsequent attempt to reach the notifcation URL will be made later, this process will repeat until our maximum allowed time for notifcation has passed. If the maximum allowed time has passed and the transaction was not successfully notifed, the transaction will be marked as expired and the notifcation email address will be notifed.

Send ACH JH background notifcation using the Background Validation process, result of sending notifcation does not impact on farther ACH JH transaction processing.

Notifcation sent in two cases:

ACH JH transaction made from HPP (general fow)

During Settlement process when transaction moving from open to closed transactions

Use the same 'Validation URL' from Terminal Settings->iIntegration to notify merchant about ACH JH transactions result processing. Note: Validation must be enabled ('Enable Validation' checkbox on Terminal Settings->iIntegration page).

The following parameters are sent in the validation request:

FieldName

Description

TERMINALID

A Terminal ID provided by Nuvei. NB – Please contact Nuvei to be issued with a test terminal ID.

AMOUNT

Transaction amount.

ORDERID

Order ID supplied by merchant in request.

RESPONSETEXT

Text describing transaction state. This will be populated with an error message if there was an issue during processing.

RESPONSECODE

A:Approved or D:Declined.

DATETIME

Format: YYYY-MM-DDTHH:MM:SS.

UNIQUEREF

Generated reference that should be stored for tracking and remote XML
refunding.

DESCRIPTION

PAYMENT or REVERSAL.

ACCOUNTNUMBER

Masked ACH account number, shows ~60% of characters.

HASH

An SHA-512 HASH. See Note 1 below.

Notes:

1. The SHA-512 HASH is generated using the following as an input string:

It is also possible to process transactions using an iFrame rather than a full redirect. All the same felds are required as the standard full redirect integration, but the implementation for the iFrame is slightly diferent. There are two methods of doing this:

Build and submit the form as with the standard integration, but within the iFrame.

Build the POST query string within the main page and then create an iFrame with that string as it's SRC value.

In either case you should also include this extra parameter:

Field Name

Required

Description

INIFRAME

Y

Ensures that all the redirects that our system performs don’t break out of the iFrame.

Need Help?

How can we help you today? Our team is standing by and just a click away.