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:
| TYPE | URL |
|---|---|
| Request URL | https://testpayments.worldnettps.com/merchant/xmlpaylink |
| XML XSD descriptor | https://testpayments.worldnettps.com/merchant/paylink.xsd |
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.
| 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. |
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 |
<?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.
The response body fields will be:
| 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. |
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 |
<?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.
| 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. |
| 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. |
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 |
<?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.
The response body fields will be:
| 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. |
| 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. |
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 |
<?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.
| 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. |
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.
<?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.
If the cancellation is succesful 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 | 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. |
| 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. |
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 |
<?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.