Table of Contents

Pay Link Features


This feature allows merchants to create links which can be paid by customers, without any additional iteraction for the customer.

Whenever merchants have applications with payments receiving flows (invoices, service bills, etc.), instead of making their clients come to them to provide payment details, they can just create a link and send to an e-mail account so the customer can pay, using our secure and PCI compliant Hosted Payment Page solution.

HOSTED PAYMENT PAGE INTEGRATION

This features uses the HPP secure PCI compliant feature available in our platform. It needs to be enabled and configured in your terminal account before you can use Pay Links - Hosted Page Payment (HPP) Features -

Once a link is created and sent to a customer, it's possible to click on the link sent to be redirected to a Hosted Payment Page. There, the customer is able to provide the card details and confirm 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.

To close the flow of your pay links, you can consult the situation of a Pay Link, getting a pay link created to be sure if customer already paid it.

GETTING THE TRANSACTION DETAILS FOR A PAID PAY LINK

When getting a pay link, you are going to receive the most recent payment attempts on it. That's by design, once the pay link can only be paid once, so if the pay link status is paid, the first payment attempt returned is going to be the transaction which achieved that. In case you want to have more details on that final transaction, you can use the Get Transaction Details service and retrieve the available details on that transaction.

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 pay links.

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
TERMINALID Y A Terminal ID provided by Worldnet, in which the payment is going to be processed.
Take a look at ND003 - Fields' Constraints.
MERCHANTREF Y Unique reference for the pay link you are creating. It's a merchant reference, so you can choose. Max of 48 characters.
ORDERID N Order ir related to the payment that is going to result from the pay link. If not provided, the platform is going to generated one for you. Max of 24 characters.
EXPIRATION_DATE N Date in which the pay link expires and can not be paid anymore. If not informed, the pay link won't ever expire.
AUTH_TYPE N Indicates which type of authorization you to be submitted when the payment is performed by the customer. A simple PAYMENT or a PRE-AUTH - remember the pre-auths required later completion to be ready for closed batch. The default value is PAYMENT.
DESCRIPTION N A description for your pay link. Useful contextual information. In case it's informed and the pay link is sent using our platform, the description is going to be added to the e-mail sent to the customer. Between 1 and 1024 characters.
CURRENCY Y Currency to be applied to the authorization.
A 3 character code following the ISO 4217 Currency Code.
TOTAL_AMOUNT Y Total amount to be charged when submitting the authorization. Minimum of 0.001 (depending on the currency selected) with a maximum of 13 digits value.
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:ORDERID:EXPIRATION_DATE:AUTH_TYPE:DESCRIPTION:CURRENCY:TOTAL_AMOUNT:DATETIME: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 - Fields' Constraints

CONSTRAINT DESCRIPTION
C01 The host must be a valid one for the terminal > merchant > gateway used
C02 Terminal must have have the pay link feature enabled
C03 Merchantref must be unique within the terminal
C04 Currency provided must be supported by the terminal
C05 Expiration date must be in the future
C06 If AUTH_TYPE is PRE_AUTH, the terminal must have pre-auth feature enabled
C07 if ORDERID is not provided, the platform auto generates it for the pay link


Examples for a Request

<?xml version="1.0" encoding="UTF-8"?>
<CREATE>
    <TERMINALID>3614008</TERMINALID>
    <MERCHANTREF>APR30002</MERCHANTREF>
    <EXPIRATION_DATE>10-06-2019</EXPIRATION_DATE>
    <AUTH_TYPE>PAYMENT</AUTH_TYPE>
    <DESCRIPTION>This is a first pay link</DESCRIPTION>
    <CURRENCY>USD</CURRENCY>
    <TOTAL_AMOUNT>52.03</TOTAL_AMOUNT>
    <DATETIME>06-03-2018:17:41:08:273</DATETIME>
    <HASH>52ca153676bb4e70f8004ce4773a87fe673852d5acab1f614e5f4ba79691303a845ec68a4b10c56c4e26c6e2e71d051c5342299a1b3da7cd7e7a0960430233b0</HASH>
</CREATE>

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 Same as the one provided on request.
MERCHANTREF Same as the one provided on request.
ORDERID Same as the one provided on request or the one auto-generated if none provided on request.
EXPIRATION_DATE Same as the one provided on request, or none, if not provided on request.
AUTH_TYPE Same as the one provided on request, or PAYMENT, if none provided.
DESCRIPTION Same as the one provided on request, or none, if not provided on request.
CURRENCY Same as the one provided on request.
TOTAL_AMOUNT Same as the one provided on request.
CREATION_DATE Date and time of creation.
URL Link to redirect a customer for the pre-configured Hosted Payment Page. It can be used by the merchants' solutions to send their own e-mails for their customers.
STATUS Current status of the pay link. One of: OPEN, COMPLETED, CANCELLED, EXPIRED. After a pay link is created, the status is OPEN.
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:ORDERID:EXPIRATION_DATE:AUTH_TYPE:DESCRIPTION:CURRENCY:TOTAL_AMOUNT:CREATION_DATE:URL:STATUS: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
Host used to request service is not registered within the gateway used or is inconsistent with the Merchant/ Terminal account used Invalid HOST
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 have the pay link feature enabled Pay Link is not enabled for this terminal
Field breaking related constraints or format Invalid TOTAL_AMOUNT field
Field breaking related constraints or format Invalid EXPIRATION_DATE field
A previous pay link was already registered with the same MERCHANTREF Pay link with this MERCHANTREF already exists
Currency provided is not supported by the terminal used Invalid terminal currency
Expiration date is today or previous to the current day Expiration Date can not be a past date
Terminal does not have the pre-auth feature enabled Terminal does not support PRE AUTH


Examples for the Response

<?xml version="1.0" encoding="UTF-8"?>
<CREATE_RESPONSE>
    <TERMINALID>3614008</TERMINALID>
    <MERCHANTREF>APR30002</MERCHANTREF>
    <ORDERID>PL_1556621357137XV</ORDERID>
    <EXPIRATION_DATE>10-06-2019</EXPIRATION_DATE>
    <AUTH_TYPE>PAYMENT</AUTH_TYPE>
    <DESCRIPTION>This is a first pay link</DESCRIPTION>
    <CURRENCY>USD</CURRENCY>
    <TOTAL_AMOUNT>52.03</TOTAL_AMOUNT>
    <CREATION_DATE>30-04-2019</CREATION_DATE>
    <URL>https://host.foo.com/merchant/paylink?token=427676be-13ed-40cf-8fb3-15d834f97dfb</URL>
    <STATUS>OPEN</STATUS>
    <DATETIME>30-04-2019:11:49:17:147</DATETIME>
    <HASH>441f372265654b6a339ba399f1a4523a33ee88e24a34ef663162e49eadf8b31a4ad278cef56dc2fba30181edb7cdc010d76fe1e13dc1b3137d74197d23d0fa0c</HASH>
</CREATE_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 send pay links by e-mail.

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
TERMINALID Y A Terminal ID provided by Worldnet, in which the payment is going to be processed.
Take a look at ND003 - Fields' Constraints.
MERCHANTREF Y Unique reference used when creating the pay link.
ADDITIONAL_MESSAGE N Any additional information you desire to add to the e-mail. It can be any claim or notification (it's up to you). 500 characters.
CUSTOMER_MERCHANTREF N* Should be used when you desire to send the link to a customer you already registered in the past, using the reference you provided on creation. Can not be used at the same time as (below) CUSTOMER.
CUSTOMER N* Should be used when you desire to create a new customer, along with sending the pay link. Can not be used at the same time as the (previous/ external) CUSTOMER_MERCHANTREF. 48 characters.
CUSTOMER_MERCHANTREF Y Subfield of CUSTOMER. Identification of the cutomer (unique reference). 48 characters.
NAME Y Subfield of CUSTOMER. Name of the customer. 255 characters.
EMAIL Y Subfield of CUSTOMER. Email of the customer. It's going to be used to send the e-mail with the link, plus any additional message you might have added. The e-mail uses the configuration at your terminal (logo and footer messages), and if they are not configured, the e-mail is sent without those fields. 128 characters.
PHONE N Subfield of CUSTOMER. Customer's phone number. 20 characters.
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:ADDITIONAL_MESSAGE:CUSTOMER_MERCHANTREF[1]:CUSTOMER[2]:DATETIME: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
C01 The host must be a valid one for the terminal > merchant > gateway used
C02 Terminal must have have pa link feature enabled
C03 Can't use the external CUSTOMER_MERCHANTREF (existing one) and CUSTOMER (new) together
C04 If providing a customer and the pay link already has one associated, it can't be different
C05 If an exiting customer (external CUSTOMER_MERCHANTREF) is provided, it must exist
C06 If a new customer (CUSTOMER) is informed, it must not exist (CUSTOMER_MERCHANTREF must be unique)
C07 The MERCHANTREF provide must be of an existing Pay Link
C08 Can only send pay links which are still with OPEN status


Examples for a Request

<?xml version="1.0" encoding="UTF-8"?>
<SEND>
    <TERMINALID>3614008</TERMINALID>
    <MERCHANTREF>APR30002</MERCHANTREF>
    <ADDITIONAL_MESSAGE>Please, pay by the date. It might generate additional fees otherwise.</ADDITIONAL_MESSAGE>
    <CUSTOMER>
        <CUSTOMER_MERCHANTREF>CUSTOMRE0006</CUSTOMER_MERCHANTREF>
        <NAME>CUSTOMER NAME</NAME>
        <EMAIL>weverthon@gmail.com</EMAIL>
        <PHONE>123456</PHONE>
    </CUSTOMER>
    <DATETIME>06-03-2018:17:41:08:273</DATETIME>
    <HASH>5325b759cd74b8336bb141bb829e25dc1d93b6c685fbf889141941217bf01959cd6a478c74c216768368947d1c7ce6913e45a2b318216663c748e6052b4692b1</HASH>
</SEND>
<?xml version="1.0" encoding="UTF-8"?>
<SEND>
    <TERMINALID>3614008</TERMINALID>
    <MERCHANTREF>APR30002</MERCHANTREF>
    <ADDITIONAL_MESSAGE>Please, pay by the date. It might generate additional fees otherwise.</ADDITIONAL_MESSAGE>
    <CUSTOMER_MERCHANTREF>CUSTOMRE0006</CUSTOMER_MERCHANTREF>
    <DATETIME>06-03-2018:17:41:08:273</DATETIME>
    <HASH>5c86ccf1fef0b32a5f217f819def48b4398324e86e2a6bf92f3a915656f946ab7145c896033a1c82c25e7cc244d2fe9a937fe6741e70cc3823ec3ba4c9b5eac9</HASH>
</SEND>

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 Same as the one provided on request.
MERCHANTREF Same as the one provided on request.
ADDITIONAL_MESSAGE Same as the one provided on request, or none, if none provided.
CUSTOMER If used external CUSTOMER_MERCHANTREF, retrieves the details of the customer previously registered with the CUSTOMER_MERCHANTREF. If used the CUSTOMER and its sub-elements, it's going to return the details provided on request.
CUSTOMER_MERCHANTREF Reference for the customer.
NAME Customer's name.
EMAIL Customer's email.
PHONE Customer's phone.
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:ADDITIONAL_MESSAGE:CUSTOMER[1]: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
Host used to request service is not registered within the gateway used or is inconsistent with the Merchant/ Terminal account used Invalid HOST
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
A customer is provided (CUSTOMER_MERCHANTREF or CUSTOMER), the pay link already has an associated customer, and it's different from the one provided Pay link already has a customer
Customer's e-mail provided does not match the expected format for e-mails Invalid email field
A customer is provided (CUSTOMER), but another customer with the same CUSTOMER_MERCHANTREF already exists Customer {merchant ref informed} already exists
A customer is provided (CUSTOMER_MERCHANTREF), but it does not exist Customer {merchant ref informed} does not exists
The MERCHANTREF provided refers an existing pay link, but its status is not OPEN Cannot send a pay link which is not open
The MERCHANTREF provided does not refer an existing pay link Pay link does not exist


Examples for the Response

<?xml version="1.0" encoding="UTF-8"?>
<SEND_RESPONSE>
    <TERMINALID>3614008</TERMINALID>
    <MERCHANTREF>APR30002</MERCHANTREF>
    <ADDITIONAL_MESSAGE>Please, pay by the date. It might generate additional fees otherwise.</ADDITIONAL_MESSAGE>
    <CUSTOMER>
        <CUSTOMER_MERCHANTREF>CUSTOMRE0006</CUSTOMER_MERCHANTREF>
        <NAME>CUSTOMER NAME</NAME>
        <EMAIL>weverthon@gmail.com</EMAIL>
        <PHONE>123456</PHONE>
    </CUSTOMER>
    <DATETIME>30-04-2019:11:50:27:413</DATETIME>
    <HASH>4a73968466633cb7acc910d4549a5ba8e70205064af810a9124ad03401213dd71e0ec722a728ddf65e21f4036cb3c85c1df75c223180276eba98a5008b89c8a2</HASH>
</SEND_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 pay link.

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
TERMINALID Y A Terminal ID provided by Worldnet, used to create the link.
MERCHANTREF Y This is the identifier used to create the pay 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:SECRET


ND002 - Data Encoding for Requests

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


Examples for a Request

<?xml version="1.0" encoding="UTF-8"?>
<GET>
    <TERMINALID>3614008</TERMINALID>
    <MERCHANTREF>APR26001</MERCHANTREF>
    <DATETIME>06-04-2019:17:41:08:273</DATETIME>
    <HASH>3a0760c4fd4e155fa3a7c26ae245a493417548d42ea124072d79fb347fce3add8f933b1428e42e310cb236a8c5904a8400ae7e8a7ffc8438f1e2189c808bf9f7</HASH>
</GET>

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 succesful you are going to receive a response with the following fields:

Filter:

FIELD DESCRIPTION
TERMINALID The Terminal ID informed on request.
MERCHANTREF The Merchant Ref informed on request.
ORDERID Same as the one provided on creation or the one auto-generated if none provided on creation.
EXPIRATION_DATE Same as the one provided on creation, or none, if not provided on creation.
AUTH_TYPE Same as the one provided on creation, or PAYMENT, if none provided.
DESCRIPTION Same as the one provided on creation, or none, if not provided on creation.
CURRENCY Same as the one provided on creation.
TOTAL_AMOUNT Same as the one provided on creation.
CREATION_DATE Date and time of creation.
URL Link to redirect a customer for the pre-configured Hosted Payment Page. It can be used by the merchants' solutions to send their own e-mails for their customers.
STATUS Current status of the pay link. One of: OPEN, COMPLETED, CANCELLED, EXPIRED.
ADDITIONAL_MESSAGE Same as the one provided on sending request, if provided.
CUSTOMER Same as provided on sending request.
CUSTOMER_MERCHANTREF Same as provided on sending request.
NAME Customer's name. Same as provided on sending request.
EMAIL Customer's email. Same as provided on sending request.
PHONE Customer's phone. Same as provided on sending request.
PAYMENT_ATTEMPTS_TOTAL Total quantity of payment attempts for this particular pay link. If you want to know all of them, you must used the ORDERID in Selfcare system, but the relevant ones are listed here.
PAYMENTS_ATTEMPTS List of PAYMENT_ATTEMPT, if already attempted any.
UNIQUEREF Transaction's unique reference.
DATE Transaction creation date.
STATUS Current status of the transaction.
AMOUNT Transaction's amount.
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:ORDERID:EXPIRATION_DATE:AUTH_TYPE:DESCRIPTION:CURRENCY:TOTAL_AMOUNT:CREATION_DATE:URL:STATUS:ADDITIONAL_MESSAGE:CUSTOMER[1]:PAYMENT_ATTEMPTS_TOTAL


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
Host used to request service is not registered within the gateway used or is inconsistent with the Merchant/ Terminal account used Invalid HOST
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
The MERCHANTREF provided does not refer an existing pay link Pay link does not exist


Examples for the Response

<?xml version="1.0" encoding="UTF-8"?>
<GET_RESPONSE>
    <TERMINALID>3614008</TERMINALID>
    <MERCHANTREF>APR26001</MERCHANTREF>
    <ORDERID>PL_1556273138749QB</ORDERID>
    <EXPIRATION_DATE>10-06-2019</EXPIRATION_DATE>
    <AUTH_TYPE>PAYMENT</AUTH_TYPE>
    <DESCRIPTION>This is a first pay link</DESCRIPTION>
    <CURRENCY>USD</CURRENCY>
    <TOTAL_AMOUNT>52.03</TOTAL_AMOUNT>
    <CREATION_DATE>26-04-2019</CREATION_DATE>
    <URL>https://testpayments.worldnettps.com/merchant/paylink?token=57f45805-638a-4d41-88a4-a7d21c855982</URL>
    <STATUS>COMPLETE</STATUS>
    <PAYMENT_ATTEMPTS_TOTAL>1</PAYMENT_ATTEMPTS_TOTAL>
    <PAYMENT_ATTEMPTS>
        <PAYMENT_ATTEMPT>
            <UNIQUEREF>E4RGZYVCME</UNIQUEREF>
            <DATE>26-04-2019</DATE>
            <STATUS>REVIEW</STATUS>
            <AMOUNT>52.03</AMOUNT>
        </PAYMENT_ATTEMPT>
    </PAYMENT_ATTEMPTS>
    <DATETIME>30-04-2019:14:32:59:194</DATETIME>
    <HASH>a0cd84b78b726b96f3e6d79c731358bdef2632cdfb6d4e871b00491eca8164f91ee14bd09f7b66f039cbf0a11629d73b2e09d4ca536989ba418ab4221bca35f6</HASH>
</GET_RESPONSE>

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