====== %feature_title Features ====== ~~TOC~~ \\ 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 - **[[developer:api_specification:hpp_payment_features|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 - **[[developer:api_specification:hpp_background_validation|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 **[[developer:api_specification:hpp_payment_features|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: ^ **TYPE** ^ **URL** ^ | Request URL | %URLXMLPayments | | XML XSD descriptor | %URLGateway | 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. ===== Create Link ===== This feature allows you to create links. * **Main Request body Tag**: * **Main Response body Tag**: ==== Request Body Fields ==== ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ | TERMINALID | Y | A Terminal ID provided by %CompanyName, in which the transaction is going to be processed.\\ Take a look at **ND005 - Fields' Constraints**.| | ORDERID | N | A unique identifier for the order created by the merchant. Maximum of 24 characters.\\ Take a look at **ND005 - Fields' Constraints**.| | CURRENCY | Y | Currency of the transaction. A 3 character code following the ISO 4217 Currency Code.\\ Take a look at **ND005 - Fields' Constraints**. | | SUBTOTAL | N | The value of the purchase. A up to 3 decimal points value, limited to 13 digits.\\ Take a look at **ND005 - Fields' Constraints**. | | DISCOUNT | N | Total discount rate applied to the purchase. A positive decimal between 0 and 100 (%) up to 3 decimal points value, limited to 13 digits.\\ Take a look at **ND005 - Fields' Constraints**. | | TAX | N | Total tax rate applied to the purchase. A positive decimal between 0 and 100 (%) up to 3 decimal points value, limited to 13 digits.\\ Take a look at **ND005 - Fields' Constraints**. | | TOTAL_DUTY_AMOUNT | N | This is a field used mainly for enhanced data (level 3) and it's not necessary in any other scenario. Represents the duty amount applied to the sale. Decimal value, allowing max of 13 digits with min value of 0. | | TOTAL_FREIGHT_AMOUNT | N | This is a field used mainly for enhanced data (level 3) and it's not necessary in any other scenario. Represents the freight amount applied to the sale. Decimal value, allowing max of 13 digits with min value of 0. | | 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 **[[merchant:existing_merchant:selfcare_system:virtual_terminal|Virtual Terminal]]** section. 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 purchase. 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 **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following format: TERMINALID:ORDERID:CURRENCY:SUBTOTAL:DISCOUNT:TAX:TOTAL_DUTY_AMOUNT:TOTAL_FREIGHT_AMOUNT:AMOUNT:DESCRIPTION:MERCHANTREF:CREATION_DATE:EXPIRATION_DATE:AUTH_TYPE: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** 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. 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. | | COMMODITY_CODE | N | This is a field used mainly for enhanced data (level 3) and it's not necessary in any other scenario. Item's commodidy code, defined for trade tariff. Widely used by corporate purchasing organizations to segment and manage their total spend across diverse product lines. Defined at government or commercial aggrements level. Consult your Acquirer for more details. | | 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. | | UNIT_OF_MEASURE | N | This is a field used mainly for enhanced data (level 3) and it's not necessary in any other scenario. Measure unit used for this specific item type to sell it in parts, units or sets. | | 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. | | DISCOUNT_RATE | N | This is a field used mainly for enhanced data (level 3) and it's not necessary in any other scenario. A % of discount applied to the item total (quantity x unit price) before taxes. | | TAX_RATE | N | This is a field used mainly for enhanced data (level 3) and it's not necessary in any other scenario. A % of tax applied to the item total (quantity x unit price) after discounts. | | 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 is 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.




    6491002
    XMLPL0001
    EUR
    30.00
    Test
    XMLPL018
    09-05-2018
    18-04-2018
    06-03-2018:17:41:08:273
    4DFD8C75BD198951A33357A374F6C6120A67BA7AF608BB56A89339DDE91F81A89F2AF9945ADB29CCD0CD83A0D1880AE484FE03968A161CD4A8C404BBC39BA010

**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team. \\ ==== Response Body Fields ==== The response body fields will be: ^ **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 **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|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:



    This is the error generated!




    3614006
    XMLPL019
    
        
           
           
           
           Pay Now →  
    
        ]]>
    
    https://tmedeiros.localhost/merchant/paymentpageservlet?09ce05ba1fbb64d9a7cf59e5ff738818
    18-04-2018:10:22:22:617
    C523EA36923DDCBC0FE3941295188DACEA4CD35F65AC0AAEDC4B8C263484E33182015A032B19622AD49CA1EF30FC16A25388226A37A2D4B9BB1852809BB3A76A

**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team. \\ ===== Send Payment Link by E-mail ===== This feature allows you to create payment links. * **Main Request body Tag**: * **Main Response body Tag**: ==== Request Body Fields ==== ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ | TERMINALID | Y | A Terminal ID provided by %CompanyName, 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 **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|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 (complete). | \\ **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.




    6491002
    XMLPL032
    Customer X
    customerx@gmail.com
    
        
          
            
              
                
                  
                
              
            
            
              
                
                  
                    
                      
                        
                          
                            
                              
                            
                          
                        
                      
                    
                    
                      
                        
                          Order XXXXXX
                        
                        
                          Reference:
                        
                        
                          Garden Services
                        
                      
                    
                  
                
              
            
          
        
    ]]>
    06-03-2018:17:41:08:273
    AE460F454FC3681FF63F8E49CDB60852ED71A8088BB05DBB84B31071591742C053A4C965482CDAAD6A517769DDD3AFA95275F2B41B213E9456D089EEDBD1E6C6

**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team. \\ ==== Response Body Fields ==== The response body fields will be: ^ **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 **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|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:



    This is the error generated!




    6491002
    XMLPL032
    08-05-2018:14:22:44:650
    DF865EB64A3E65B6A4912BB168C368AD58AED58E6048C8D2999D67286CE3B7FE467A3A418C863F62A4626731C4387AFFED25F90159269B569E871A2D18E57871




    6491002
    USD
    06-03-2018:17:41:08:273
    69c10527f4c5f0cb3ce0e6bcf0957503c6e0f9dbdccd01bf4e7a685c2ffb272057f6e5831a2e3d1a298abd137b891db31a6a69ff443d8b01ee37d0d789c04ecf

**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|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: ^ **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 send (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**, 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 **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|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:



    This is the error generated!




       6491002
       A1B2C3
       PBL_JJW45945AEVSRG
       1
       USD
       13.95
       miscellaneous goods and services
       31/01/2019
       31/01/2019
       CANCELLED
       https://gatewayhost/merchant/paymentlink?token=a04c2fb6-a341-4c22-829b-5ee6e56b8f90
       06-03-2018:17:41:08:273
       69c10527f4c5f0cb3ce0e6bcf0957503c6e0f9dbdccd01bf4e7a685c2ffb272057f6e5831a2e3d1a298abd137b891db31a6a69ff443d8b01ee37d0d789c04ecf




    3614043
    XML_JAN22002
    06-03-2018:17:41:08:273
    7777552e7a847fd7e42c979dc42180a3772e5685b9e117589048595af9a7f872f5b7e6ce9d6213622889a7cfc1fbeb50f39a64bf4bdf32db3aae64f775c679d9

**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|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: ^ **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 **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following format: TERMINALID:MERCHANTREF: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:



    This is the error generated!




    3614043
    XML_JAN22002
    22-01-2019:14:57:23:770
    8b304d77a9b621a99de4e97f8bf8d8b72ae2787315a13688ea8a2acbb02956401e6d3099d866e54dd4fdac8a0b31e481385fffaf75ad53ec1885b9beef780df6

**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team. \\