4.1 Hosted Payment Page link
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. |
|
|
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. |
|
HASH |
Y |
An SHA-512 HASH. See Note 1 below. |
Notes:
-
The SHA-512 HASH is generated using the following as an input string:
TERMINALID:ORDERID:AMOUNT:DATETIME:RECEIPTPAGEURL:VALIDATIONURL:secret
-
For multi-currency Terminal Ids (see section 2.2 above) this should be:
TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:RECEIPTPAGEURL:VALIDATIONURL: secret
-
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.
<html>
<body>
<form action="https://testpayments.nuvei.com/merchant/paymentpage" method="post">
<input type="hidden" name="TERMINALID" value="6491002" />
<input type="hidden" name="ORDERID" value="3281" />
<input type="hidden" name="CURRENCY" value="USD" />
<input type="hidden" name="AMOUNT" value="10.00" />
<input type="hidden" name="DATETIME" value="15-3-2015:10:43:01:673" />
<input type="hidden" name="HASH" value="3b41c01e592b396c91d70dead081c183" />
<input type="submit" value="Pay Now" />
</form>
</body>
<html>
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:
TERMINALID:ORDERID:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:secret
For multi-currency Terminal Ids (see section 2.2 above) this should be:
TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:RESPONSECODE: RESPONSETEXT:secret
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.
4.2 Background Notification link
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
To distinguish notifcation types on merchant side use response code, where 'E' means that transaction initially approved, 'A' transaction approved fnally.
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:
|
Field Name |
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:
TERMINALID:ORDERID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:secret
2. For multi-currency Terminal Ids (see section 2.2 above) this should be:
TERMINALID:ORDERID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:
RESPONSETEXT:secret
4.3 Hosted Pages in an iFrame link
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. |