XML eInvoice

This feature allows browser-based software applications to manage payment links. Payment links are useful in scenarios where merchants wish to invoice or bill their customers.

Once a link is created and sent to a customer, clicking on the link will redirect the customer to a Hosted Payment Page (HPP). 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 Payment Page: Payment section. 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.

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>

ND001 - Hash Formation

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

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:

ND004 - Item Composition

The fields below represent the ITEM elements present on the request. Althought ITEMs are not required to submit a request, if you decide to use ITEMs, then all ITEM fields become mandatory. If used, ITEMs build the e-mail body to be sent to the customer (for example, when you do not want your software to define the body when sending the e-mail.)

ND005 - Fields' Constraints

• Scenario: Create payment link, providing 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>

The response body fields will be:

ND001 - Hash Formation

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

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:

• 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>

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>

ND001 - Hash Formation

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

ND002 - Data Encoding for Requests

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

ND003 - Fields' Constraints

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 provided, the default behavior is to add the button right after the e-mail body.

• 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>

The response body fields will be:

ND001 - Hash Formation

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

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:

• 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>

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>

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.

ND002 - Data Encoding for Request

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

• 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>

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

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:

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:

• 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>

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>

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.

ND002 - Data Encoding for Requests

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

ND003 - General Constraints

• 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>

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

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.

ND002 - Error Handling

• 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>