Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
developer:api_specification:xml_payment_features_payment_link [2018/08/10 12:33]
thiago123 [Request Body Fields] [Quick Fix] QA pointed out the error and asked to repair
— (current)
Line 1: Line 1:
-====== Payment Link 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. 
- 
-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 Payment Link ===== 
- 
-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 ==== 
- 
-<​searchtable>​ 
-^ **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**.| 
-| 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**. | 
-| AMOUNT ​         | Y | The amount of the transaction.\\ A 2 digit decimal or an Integer value for JPY amounts. | 
-| 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 **ND003 - 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 **ND003 - Fields'​ Constraints**. | 
-| 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. | 
-</​searchtable>​ 
- 
-\\ 
-==== 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: 
- 
-<WRAP center box 100%> 
-TERMINALID:​ORDERID:​CURRENCY:​AMOUNT:​DESCRIPTION:​MERCHANTREF:​CREATION_DATE:​EXPIRATION_DATE:​DATETIME:​TERMINAL SECRET 
-</​WRAP>​ 
- 
-<WRAP center important 100%> 
-The not mandatory fields - Description and Creation Date - should only be added to the hash if used on request. 
-</​WRAP>​ 
- 
-\\ 
- 
-**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 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 | 
- 
-\\ 
- 
-==== Examples for a Request ==== 
- 
-  * **Scenario**:​ Create payment link, informing all the fields. 
-  * **Terminal**:​ 6491002. 
-  * **Terminal Secret**: x4n35c32RT. 
- 
-<code xml> 
-<?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>​ 
-</​code>​ 
- 
-<WRAP center important 100%> 
-**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. 
-</​WRAP>​ 
- 
-\\ 
- 
-==== Response Body Fields ==== 
- 
-The response body fields will be: 
- 
-<​searchtable>​ 
-^ **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. | 
-</​searchtable>​ 
-\\ 
- 
-==== 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: 
- 
-<WRAP center box 100%> 
-TERMINALID:​MERCHANTREF:​PAY_NOW_URL:​DATETIME:​SECRET 
-</​WRAP>​ 
- 
-\\ 
- 
-**ND002 - Error Handling** 
- 
-If there is an error processing the transaction,​ the error string is returned in an XML message with the simple tags: 
- 
-<code xml> 
-<​ERROR>​ 
-    <​ERRORSTRING>​This is the error generated!</​ERRORSTRING>​ 
-</​ERROR>​ 
-</​code>​ 
- 
-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. 
- 
-<code xml> 
-<?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>​ 
-</​code>​ 
- 
-<WRAP center important 100%> 
-**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. 
-</​WRAP>​ 
- 
-\\ 
- 
-===== Send Payment Link by E-mail ===== 
- 
-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 ==== 
- 
-<​searchtable>​ 
-^ **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. | 
-</​searchtable>​ 
- 
-\\ 
-==== 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: 
- 
-<WRAP center box 100%> 
-TERMINALID:​MERCHANTREF:​CUSTOMER_NAME:​CUSTOMER_EMAIL:​DATETIME:​TERMINAL SECRET 
-</​WRAP>​ 
- 
-\\ 
- 
-**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. 
- 
-<code xml> 
-<?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>​ 
-</​code>​ 
- 
-<WRAP center important 100%> 
-**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. 
-</​WRAP>​ 
- 
-\\ 
- 
-==== Response Body Fields ==== 
- 
-The response body fields will be: 
- 
-<​searchtable>​ 
-^ **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. | 
-</​searchtable>​ 
-\\ 
- 
-==== 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: 
- 
-<WRAP center box 100%> 
-TERMINALID:​MERCHANTREF:​DATETIME:​SECRET 
-</​WRAP>​ 
- 
-\\ 
- 
-**ND002 - Error Handling** 
- 
-If there is an error processing the transaction,​ the error string is returned in an XML message with the simple tags: 
- 
-<code xml> 
-<​ERROR>​ 
-    <​ERRORSTRING>​This is the error generated!</​ERRORSTRING>​ 
-</​ERROR>​ 
-</​code>​ 
- 
-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. 
- 
-<code xml> 
-<?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>​ 
-</​code>​ 
- 
-<WRAP center important 100%> 
-**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. 
-</​WRAP>​ 
- 
-\\ 
  
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International