eInvoice Features


In this feature you can find different subfeatures which are design to allow integrations to manage payment links. They are useful in a scenario where merchants have applications with payments receiving flows (invoices, service bills, etc.) instead of a platform where their clients go to buy goods and does not want to insert manual steps to contact each customer and perform the payment.

HOSTED PAYMENT PAGE INTEGRATION

This features uses the HPP mechanisms and features available and configured for your terminals during a payment - Hosted Page Payment (HPP) Features -

Once a link is created and sent to a customer it's possible to click on the link to be redirected to a Hosted Payment Page. There, the customer is able to perform the payment.

Depending on the HPP Feature's Settings, you might be able to perform a background validation on each transaction - HPP Background Validation - and at the end of the transaction you are going to receive a response at the Receipt Page URL, also configured at your terminal, containing all the details on the transaction's result.

For more details on the response to be received using the Receipt Page URL, refer to the Response Body Fields section on Hosted Page Payment Features page. Also, don't forget that this URL (Receipt Page URL) works as a webhook where you need to implement a mechanism to treat the information received, if you want to use it somehow.

DEFAULT RECEIPT PAGE

In case a terminal being used with HPP does not have a Receipt Page URL, the gateway is not going to send back the details regarding the transaction's result, but it's going to present a default receipt page providing feedback to the customer with a simpler receipt version.

The following resources are the same for all the requests and responses you find on this page:

Use the Request URL and the Request Body Fields to perform a request for this feature, then prepare your integration to receive the response, as defined by the Response Body Fields.

This feature allows you to create payment links.

  • Main Request body Tag: <CREATE_PAYMENT_LINK>
  • Main Response body Tag: <CREATE_PAYMENT_LINK_RESPONSE>

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
TERMINALID Y A Terminal ID provided by Nuvei, in which the payment is going to be processed.
Take a look at ND003 - Fields' Constraints.
ORDERID N A unique identifier for the order created by the merchant.
Maximun of 24 characters.
CURRENCY Y Currency of the transaction. A 3 character code following the ISO 4217 Currency Code.
Take a look at ND003 - Fields' Constraints.
SUBTOTAL N The value of the purchase before applied tax. A 2 digit decimal or an Integer value for JPY amounts. If not informed on request, the gateway is going to calculate the correct value based on AMOUNT and TAX.
TAX N The percentage tax to be applied to the purchase's SUBTOTAL. A 2 digit decimal up to 13 digits. If not informed on request, the gateway is going to consider 0, unless the TAX_AMOUNT of LEVEL_2_DATA is informed, and in this case, it's going to be calculated. Take a look at ND005 - Fields' Constraints.
AMOUNT Y The amount of the transaction.
A 2 digit decimal or an Integer value for JPY amounts.
It should be calculated based on the subtotal and tax informed. Take a look at ND005 - Fields' Constraints.
DESCRIPTION N Description of the payment request to which the payment link refers too.
MERCHANTREF Y This field represents the merchant reference that is going to be considered for the payment link generated.
Take a look at ND005 - Fields' Constraints.
CREATION_DATE N Date for the actual creation of the payment request for the customer. Format: DD-MM-YYYY.
EXPIRATION_DATE Y Date in which the link must expire. Format: DD-MM-YYYY.
Take a look at ND005 - Fields' Constraints.
AUTH_TYPE N This field allows the integration to define what should be created: a Payment, sending the integer 1, or a Pre-Authorization, sending the integer 2.
It's necessary to notice that a pre-authorization is going to require the transaction's completion by the merchant, even after the customer's payment. For more details, see the Virtual Terminal section. If not informed, the gateway is going to consider 1 as default.
LEVEL_DATA N This field points out if the transaction is going to receive or not enhanced data. Accepted values: 1 - for STANDARD; 2 - LEVEL 2.
It's only allowed for terminal which hold such configuration.
If not informed, the gateway is going to consider 1 as default.
LEVEL_2_DATA N This field is going to receive the level II enhanced data for the transaction to be created.
Take a look at ND003 - Level II data .
ITEMS N This field allows the information of items that compose the pruchase. It accepts a list of the ITEM component.
Take a look at ND004 - Item Composition.
DATETIME Y Request date and time. Format: YYYY-MM-DDTHH:MM:SS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following format:

TERMINALID:ORDERID:CURRENCY:SUBTOTAL:TAX:AMOUNT:DESCRIPTION:MERCHANTREF:CREATION_DATE:EXPIRATION_DATE:AUTH_TYPE:LEVEL_DATA:CUSTOMER_REF_NUMBER:TAX_AMOUNT:FULL_NAME:ADDRESS1:ADDRESS2:CITY:REGION:POSTCODE:COUNTRY:DATETIME:TERMINAL SECRET

The optional fields (REQUIRED as “N”) should only be added to the hash if used on request.


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Level II Data Validation

This field is associated with the feature “Level II Data”, and to be used it is necessary to set the “Allow Level II Data” option on the Processing Terminal “Features” section.

A few things to consider when using this field:

  • All the fields associated with the feature “Level II Data”, except for SHIPPING_ADDRESS, are mandatory when the “Level II Data Compulsory” is checked in the Processing Terminal “Features” section.
  • This feature is only available for specific acquirers. Contact our support team to know more.

The request component LEVEL_2_DATA is composed by the following nested elements:

FIELD REQUIRED DESCRIPTION
CUSTOMER_REF_NUMBER Y Subfield of LEVEL_2_DATA. Value is text, type with max length of 48 characters. This number is defined by the cardmember. It is entered by the merchant at the point of sale.
TAX_AMOUNT Y Subfield of LEVEL_2_DATA. Value is integer type, with max length of 13 numbers. A value of zero is required in order to indicate tax exempt transactions.
If this field is not informed on request it's going to be considered 0.
SHIPPING_ADDRESS N Subfield of LEVEL_2_DATA. Subcomponent with all the data related to the shipping address of a purchase.
FULL_NAME N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS1 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS2 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Always optional regardless compulsory setting.
CITY N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
REGION N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
POSTCODE N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 50 characters.
COUNTRY N Subfield of SHIPPING_ADDRESS. Value is text type, with 2 characters. ISO ALPHA-2 Country Code.


ND004 - Item Composition

the fields below represent the ITEM elements present on the creation request. Althought no ITEM is necessary on your request, when informing one of the , all the fields are mandatory. If informed, ITEMs can be used by the gateway to build the e-mail body to be sent to the customer in case the integration does not want to define a body when sending the e-mail.

FIELD REQUIRED DESCRIPTION
CODE Y Item code, used to identify it's nature. Text between 1 and 45 characters.
DESCRIPTION Y Description of the item, used to provide more details on what's was purchased. Text between 1 and 250 characters.
QUANTITY Y Decimal number to express the quantity pruchased of an item. Values accepted between 0.01 and 999999999.99.
PRICE Y Unit price for the purchased item. minimum accepted value of 0.001 and value up to 13 numbers, or 99999999999.99 , with 2 decimal points.
AMOUNT Y Total amount calculated for the item, calculated as Quantity X Price. Minimum accepted value of 0.001 and value up to 13 numbers, or 99999999999.99 , with 2 decimal points. The gateway verifies the


ND005 - Fields' Constraints

CONSTRAINT DESCRIPTION
C001 The terminal (TERMINALID) should support Internet (HPP) to use this feature.
C002 The terminal (TERMINALID) should be completely configured and active to use this feature.
C003 The currency (CURRENCY) should be supported by the Terminal.
C004 The Expiration Date (EXPIRATION_DATE) cannot be placed in the past
C005 The Expiration Date (EXPIRATION_DATE) cannot be before Creation Date
C006 The Merchant Ref (MERCHANTREF) should be unique for the Terminal
C007 Only terminals which support Pre-Auth allow integrations to choose the AUTH_TYPE.
C008 Only terminals which support Level II Enhanced Data allow integrations to inform the LEVEL_2_DATA.
C009 If a terminal defines Level II as compulsory, the Tax Amount is mandatory and other level2 fields might be present or not.
C010 The gateway ig always going to validate the consitency among the value fields of the request, meaning that SUBTOTAL, TAX (and TAX_AMOUNT from LEVEL_2_DATA, when informed) and AMOUNT will be validate among themselves.
C011 If a request is submitted without the TAX, the terminal allows the Level 2 Enhanced Data and the TAX_AMOUNT was informed, the gateway is going to calculate the TAX percentage to keep consistency.
C012 If a request is submitted with the TAX, the terminal allows the Level 2 Enhanced Data and the TAX_AMOUNT was informed, the gateway is going to validate them considering the transaction's SUBTOTAL and AMOUNT.
C013 If a request is submitted with at least one ITEM in ITEMS, the SUBTOTAL field becomes mandatory.
C014 If a request is submitted with at least one ITEM in ITEMS, the SUBTOTAL field is going to be validate against the sum of all the ITEM's ITEM-AMOUNT.
C015 All the values present on the request are going to be validated against the informed CURRENCY for format.


Examples for a Request

  • Scenario: Create payment link, informing all the fields.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<CREATE_PAYMENT_LINK>
    <TERMINALID>6491002</TERMINALID>
    <ORDERID>XMLPL0001</ORDERID>
    <CURRENCY>EUR</CURRENCY>
    <AMOUNT>30.00</AMOUNT>
    <DESCRIPTION>Test</DESCRIPTION>
    <MERCHANTREF>XMLPL018</MERCHANTREF>
    <CREATION_DATE>09-05-2018</CREATION_DATE>
    <EXPIRATION_DATE>18-04-2018</EXPIRATION_DATE>
    <DATETIME>06-03-2018:17:41:08:273</DATETIME>
    <HASH>4DFD8C75BD198951A33357A374F6C6120A67BA7AF608BB56A89339DDE91F81A89F2AF9945ADB29CCD0CD83A0D1880AE484FE03968A161CD4A8C404BBC39BA010</HASH>
</CREATE_PAYMENT_LINK>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

The response body fields will be:

Filter:

FIELD DESCRIPTION
TERMINALID The Terminal ID informed on request.
MERCHANTREF The Merchant Ref informed on request.
PAY_NOW_BUTTON An HTML ready to use component, containing the link to the pre-configured hosted payment page which can be used by the customer to execute the payment. In case the merchant wants to send the e-mail by itself, this component can be added, by the merchant's solution, to an e-mail or a SMS before sending it to a customer.
PAY_NOW_URL The URL link to the pre-configured hosted payment page which can be used by the customer to execute the payment. Also can be used to send directly to the merchant's customer.
DATETIME Response date and time. Format: YYYY-MM-DDTHH:MM:SS.
HASH A HASH code formed by the response fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following format:

TERMINALID:MERCHANTREF:PAY_NOW_URL:DATETIME:SECRET


ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

Possible errors for this subfeature:

ERROR MESSAGE
Can not find terminal or terminal is deactivated Invalid TERMINALID field
Datetime is invalid Invalid DATETIME field
Hash is invalid Invalid HASH field
Terminal is not configured Terminal is not configured
Currency is invalid or is not supported by the Terminal Invalid Terminal Currency
Terminal does not support HPP (Internet transactions) Terminal does not support Internet transactions
Amount is invalid Invalid AMOUNT field
Creation date is invalid Invalid CREATION_DATE field
Expiration Date is invalid Invalid EXPIRATION_DATE field
Expiration Date is before Creation Date Invalid EXPIRATION_DATE field
Expiration Date placed in the past EXPIRATION_DATE field can not be a past date
Already exists a payment link using the Merchant Ref for the terminal Payment Link with this MERCHANTREF already exists


Examples for the Response

  • Scenario: Response for a simple creation request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<CREATE_PAYMENT_LINK_RESPONSE>
    <TERMINALID>3614006</TERMINALID>
    <MERCHANTREF>XMLPL019</MERCHANTREF>
    <PAY_NOW_BUTTON>
        <![CDATA[
           <table width="100%" border="0" cellspacing="0" cellpadding="0">
           <tr><td>
           <table border="0" cellspacing="0" cellpadding="0" align="center">
           <tr><td>
           <a href="https://tmedeiros.localhost/merchant/paymentpageservlet?09ce05ba1fbb64d9a7cf59e5ff738818" 
           target="_blank" style="font-size: 18px; font-family: Helvetica, Arial, sans-serif; color: #ffffff; 
           text-decoration: none; border-radius: 30px; background-color: #6C7A89; border-top: 14px solid #6C7A89; 
           border-bottom: 14px solid #6C7A89; border-right: 32px solid #6C7A89; border-left: 32px solid #6C7A89; 
           display: inline-block;">Pay Now &rarr;</a></td> </tr> </table> </td> </tr> </table>
        ]]>
    </PAY_NOW_BUTTON>
    <PAY_NOW_URL>https://tmedeiros.localhost/merchant/paymentpageservlet?09ce05ba1fbb64d9a7cf59e5ff738818</PAY_NOW_URL>
    <DATETIME>18-04-2018:10:22:22:617</DATETIME>
    <HASH>C523EA36923DDCBC0FE3941295188DACEA4CD35F65AC0AAEDC4B8C263484E33182015A032B19622AD49CA1EF30FC16A25388226A37A2D4B9BB1852809BB3A76A</HASH>
</CREATE_PAYMENT_LINK_RESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


This feature allows you to create payment links.

  • Main Request body Tag: <SEND_PAYMENT_LINK_EMAIL>
  • Main Response body Tag: <SEND_PAYMENT_LINK_EMAIL_RESPONSE>

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
TERMINALID Y A Terminal ID provided by Nuvei, in which the payment is going to be processed.
Take a look at ND003 - Fields' Constraints.
MERCHANTREF Y This is the identifier of the payment link to be sent.
Take a look at ND003 - Fields' Constraints.
CUSTOMER_NAME Y The name of the customer who is going to receive the payment link.
CUSTOMER_EMAIL Y The customer's e-mail address to which the payment link should be sent to.
EMAIL_BODY Y The information which should be sent in the customer's e-mail body. This element can be manipulated and formatted as the merchant sees fit. The Payment Gateway is going to send the body, as informed, to the customer's e-mail informed, adding the the “PAY NOW” button to it.
Take a look at ND004 - The PAYNOWBUTTON Tag.
DATETIME Y Request date and time. Format: YYYY-MM-DDTHH:MM:SS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following format:

TERMINALID:MERCHANTREF:CUSTOMER_NAME:CUSTOMER_EMAIL:DATETIME:TERMINAL SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Fields' Constraints

CONSTRAINT DESCRIPTION
C001 The terminal (TERMINALID) should support Internet (HPP) to use this feature.
C002 The payment link informed (MERCHANTREF) can not be one with a past expired date.
C003 The payment link informed (MERCHANTREF) can not be one already paid.


ND004 - The PAYNOWBUTTON Tag

The {PAYNOWBUTTON} tag is a component which can be added to the e-mail body to let the Payment Gateway know where the merchant would like the button to appear in its e-mail to the customer. If not informed, the default behavior is to add the button right after the e-mail body.


Examples for a Request

  • Scenario: Send payment link.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<SEND_PAYMENT_LINK_EMAIL>
    <TERMINALID>6491002</TERMINALID>
    <MERCHANTREF>XMLPL032</MERCHANTREF>
    <CUSTOMER_NAME>Customer X</CUSTOMER_NAME>
    <CUSTOMER_EMAIL>customerx@gmail.com</CUSTOMER_EMAIL>
    <EMAIL_BODY><![CDATA[
        <!DOCTYPE html>
        <html>
          <body bgcolor="#f9f9f9" style="margin: 0; padding: 0; background:#f9f9f9">
            <table style="width: 100%;">
              <tbody>
                <tr>
                  <td height="20"></td>
                </tr>
              </tbody>
            </table>
            <table style="line-height: 135%; border-radius: 3px 3px 0 0; max-width: 580px; width: 100%; margin: 0 auto;" bgcolor="#ffffff">
              <tbody>
                <tr>
                  <td>
                    <table border="0" cellpadding="0" cellspacing="10" style="width: 100%;">
                      <tbody>
                        <tr>
                          <td align="right">
                            <div style="color: #042029; font-size: 1.3em; font-weight:100; margin: 0;">
                              <img src="https://www.freelogodesign.org/img/logo-ex-7.png" alt="Logo">
                            </div>
                          </td>
                        </tr>
                      </tbody>
                    </table>
                    <table border="0" cellpadding="0" cellspacing="10" style="width: 100%;">
                      <tbody>
                        <tr>
                          <td>Order XXXXXX</td>
                        </tr>
                        <tr>
                          <td>Reference:</td>
                        </tr>
                        <tr>
                          <td>Garden Services</td>
                        </tr>
                      </tbody>
                    </table>
                  </td>
                </tr>
              </tbody>
            </table>
          </body>
        </html>
    ]]></EMAIL_BODY>
    <DATETIME>06-03-2018:17:41:08:273</DATETIME>
    <HASH>AE460F454FC3681FF63F8E49CDB60852ED71A8088BB05DBB84B31071591742C053A4C965482CDAAD6A517769DDD3AFA95275F2B41B213E9456D089EEDBD1E6C6</HASH>
</SEND_PAYMENT_LINK_EMAIL>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

The response body fields will be:

Filter:

FIELD DESCRIPTION
TERMINALID The Terminal ID informed on request.
MERCHANTREF The Merchant Ref informed on request.
DATETIME Response date and time. Format: YYYY-MM-DDTHH:MM:SS.
HASH A HASH code formed by the response fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following format:

TERMINALID:MERCHANTREF:DATETIME:SECRET


ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

Possible errors for this subfeature:

ERROR MESSAGE
Can not find terminal or terminal is deactivated Invalid TERMINALID field
Datetime is invalid Invalid DATETIME field
Hash is invalid Invalid HASH field
Terminal is not configured Terminal is not configured
Payment Link not found Payment Link does not exist
Payment Link is expired Payment Link is expired
Payment Link already paid Payment Link already paid
Customer email invalid Invalid CUSTOMER_EMAIL field


Examples for the Response

  • Scenario: Response for a simple creation request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<SEND_PAYMENT_LINK_EMAIL_RESPONSE>
    <TERMINALID>6491002</TERMINALID>
    <MERCHANTREF>XMLPL032</MERCHANTREF>
    <DATETIME>08-05-2018:14:22:44:650</DATETIME>
    <HASH>DF865EB64A3E65B6A4912BB168C368AD58AED58E6048C8D2999D67286CE3B7FE467A3A418C863F62A4626731C4387AFFED25F90159269B569E871A2D18E57871</HASH>
</SEND_PAYMENT_LINK_EMAIL_RESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


This feature allows you to retrieve the details of an existing payment link.

  • Main Request body Tag: <GET_PAYMENT_LINK>
  • Main Response body Tag: GET_PAYMENT_LINK_RESPONSE>

Request Body Fields

FIELD REQUIRED DESCRIPTION
TERMINALID Y A Terminal ID provided by Nuvei in which the payment was created.
MERCHANTREF YThis is the identifier used to create the payment link.
DATETIME Y Request date and time. Format: YYYY-MM-DDTHH:MM:SS
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following format.

TERMINALID:MERCHANTREF:DATETIME:TERMINALSECRET

ND002 - Data Encoding for Request

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

Examples for a Request

  • Scenario: Retrieve a payment link to check its status.
  • *Terminal: 6491002 * *Terminal Secret: x4n35c32RT
<?xml version="1.0" encoding="UTF-8"?>
<GET_PAYMENT_LINK>
    <TERMINALID>6491002</TERMINALID>
    <MERCHANTREF>USD</MERCHANTREF>
    <DATETIME>06-03-2018:17:41:08:273</DATETIME>
    <HASH>69c10527f4c5f0cb3ce0e6bcf0957503c6e0f9dbdccd01bf4e7a685c2ffb272057f6e5831a2e3d1a298abd137b891db31a6a69ff443d8b01ee37d0d789c04ecf</HASH>
</GET_PAYMENT_LINK>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.

Response Body Fields

If the cancellation is successful, you are going to receive a response with the following fields:

FIELD DESCRIPTION
TERMINALID The Terminal ID informed on request.
MERCHANTREF The Merchant Ref informed on request.
ORDERID Order ID which is going to be used for the payment attempts.
AUTH_TYPE Authorization type (1-auth or 2-pre-auth) defined on creation.
CURRENCY Currency provided on creation to be used in each payment attempt.
AMOUNT Payment value.
DESCRIPTION Description about the payment requested and sent to the customer.
CREATION_DATE Creation date of the payment link.
EXPIRATION_DATE Due date of the payment link.
PAYMENT_LINK_STATUS Current status of the payment link. OPEN, CANCELLED, EXPIRED or COMPLETE.
PAY_NOW_URL URL/Link which can be sent (or was sent) to a customer, so the payment can be performed.
DATETIME Response date and time. Format: YYYY-MM-DDTHH:MM:SS.
HASH A HASH code formed by the response fields. The formation rule is given at the ND001 - Hash Formation, the next section.

Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following format:

TERMINALID:MERCHANTREF:ORDERID:AUTH_TYPE:CURRENCY:AMOUNT:DESCRIPTION:CREATION_DATE:EXPIRATION_DATE:PAYMENT_LINK_STATUS:PAY_NOW_URL:DATETIME:TERMINAL SECRET

ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

Possible error for this subfeature:

ERROR MESSAGE
Cannot find terminal or terminal is deactivated Invalid TERMINALID field
Datetime is invalid Invalid DATETIME field
Hash is invalid Invalid HASH field
Terminal is not configured Terminal is not configured
Terminal informed does not have feature erminal does not support Invoice Payment Request
Payment Link not found Invoice Payment Request does not exist

Examples for the Response

  • Scenario: Response for a successful cancellation.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT
<?xml version="1.0" encoding="UTF-8"?>
<GET_PAYMENT_LINK_RESPONSE>
       <TERMINALID>6491002</TERMINALID>
       <MERCHANTREF>A1B2C3</MERCHANTREF>
       <ORDERID>PBL_JJW45945AEVSRG</ORDERID>
       <AUTH_TYPE>1</AUTH_TYPE>
       <CURRENCY>USD</CURRENCY>
       <AMOUNT>13.95</AMOUNT>
       <DESCRIPTION>miscellaneous goods and services</DESCRIPTION>
       <CREATION_DATE>31/01/2019</CREATION_DATE>
       <EXPIRATION_DATE>31/01/2019</EXPIRATION_DATE>
       <PAYMENT_LINK_STATUS>CANCELLED</PAYMENT_LINK_STATUS>
       <PAY_NOW_URL>https://gatewayhost/merchant/paymentlink?token=a04c2fb6-a341-4c22-829b-5ee6e56b8f90</PAY_NOW_URL>
       <DATETIME>06-03-2018:17:41:08:273</DATETIME>
       <HASH>69c10527f4c5f0cb3ce0e6bcf0957503c6e0f9dbdccd01bf4e7a685c2ffb272057f6e5831a2e3d1a298abd137b891db31a6a69ff443d8b01ee37d0d789c04ecf</HASH>
</GET_PAYMENT_LINK_RESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret to valid values. Consult the Integration Docs for examples or contact our support team.

This feature allows you to cancel an existing payment link.

  • Main Request body Tag: <CANCEL_PAYMENT_LINK>
  • Main Response body Tag: <CANCEL_PAYMENT_LINK_RESPONSE>

Request Body Fields

FIELD REQUIRED DESCRIPTION
TERMINALID Y A Terminal ID provided by Nuvei, in which the payment was created.
MERCHANTREF Y This is the identifier used to create the payment link.
DATETIME Y Request date and time. Format: YYYY-MM-DDTHH:MM:SS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under Special Fields and Parameters section. For this specific feature, you should use the following format.

TERMINALID:MERCHANTREF:DATETIME:TERMINALSECRET

ND002 - Data Encoding for Requests

All data sent to us shold be correctly encoded using UTF-8 as the character encoding.

ND003 - General Constraints

CONTRAINT DESCRIPTION
C001 You can only cancel payment links that are still OPEN (status). If they are already cancelled, expired or complete, you are not going to be able to cancel them and an error will be returned.

Examples for a Request

  • Scenario: Cancel a payment link you don't want to be paid anymore.
  • Terminal: 6491002.
  • Terminal Secret:x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<CANCEL_PAYMENT_LINK>
    <TERMINALID>3614043</TERMINALID>
    <MERCHANTREF>XML_JAN22002</MERCHANTREF>
    <DATETIME>06-03-2018:17:41:08:273</DATETIME>
    <HASH>7777552e7a847fd7e42c979dc42180a3772e5685b9e117589048595af9a7f872f5b7e6ce9d6213622889a7cfc1fbeb50f39a64bf4bdf32db3aae64f775c679d9</HASH>
</CANCEL_PAYMENT_LINK>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.

Response Body Fields

If the cancellation is successful, you are going to receive a response with the following fields:

FIELD DESCRIPTION
TERMINALID The Terminal ID informed on request.
MERCHANTREF The Merchant Ref informed on request.
DATETIME Request date and time. Format: YYYY-MM-DDTHH:MM:SS
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following format.

TERMINALID:MERCHANTREF:DATETIME:TERMINAL SECRET

ND002 - Error Handling

*ERROR ^ MESSAGE
Cannot find terminal or terminal is deactivated Invalid TERMINALID field
Datetime is invalid Invalid DATETIME field
Hash is invalid Invalid HASH field
Terminal is not configured Terminal is not configured
Terminal informed does not have feature Terminal does not support Invoice Payment Request
Payment Link not found Invoice Payment Request does not exist
Payment Link status is not OPEN Cannot cancel an Invoice Payment Request with status different from Open

Examples for the Response

  • Scenario: Response for a successful cancellation.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<CANCEL_PAYMENT_LINK_RESPONSE>
    <TERMINALID>3614043</TERMINALID>
    <MERCHANTREF>XML_JAN22002</MERCHANTREF>
    <DATETIME>22-01-2019:14:57:23:770</DATETIME>
    <HASH>8b304d77a9b621a99de4e97f8bf8d8b72ae2787315a13688ea8a2acbb02956401e6d3099d866e54dd4fdac8a0b31e481385fffaf75ad53ec1885b9beef780df6</HASH>
</CANCEL_PAYMENT_LINK_RESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Intregration Docs for examples or contact our support team.

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International