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_paybylink [2018/08/10 12:33]
thiago123 [Request Body Fields] [Quick Fix] QA pointed out the error and asked to repair
developer:api_specification:xml_payment_features_paybylink [2018/11/13 10:58] (current)
thiago123 Fix
Line 5: Line 5:
 \\ \\
 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. 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.
 +
 +<WRAP center important 100%>
 +
 +**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]]** - 
 +
 +</​WRAP>​
 +
 +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.
 +
 +<WRAP center important 100%>
 +
 +**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.
 +
 +</​WRAP>​
  
 The following resources are the same for all the requests and responses you find on this page: The following resources are the same for all the requests and responses you find on this page:
Line 28: Line 50:
 | ORDERID ​        | N | A unique identifier for the order created by the merchant.\\ Maximun of 24 characters. | ​ | 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**. | | 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. |+| SUBTOTAL ​       | N | The value of the purchase before applied tax. A 2 digit decimal or an Integer value for JPY amounts. If not informed on request, the gateway is going to calculate the correct value based on AMOUNT and TAX. | 
 +| TAX             | N | The percentage tax to be applied to the purchase'​s SUBTOTAL. A 2 digit decimal up to 13 digits. If not informed on request, the gateway is going to consider 0, unless the TAX_AMOUNT of LEVEL_2_DATA is informed, and in this case, it's going to be calculated. Take a look at **ND005 - Fields'​ Constraints**. | 
 +| 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. | | 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**. |+| 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. | | 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**. |+| 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_DATA ​     | N | This field points out if the transaction is going to receive or not enhanced data. Accepted values: 1 - for STANDARD; 2 - LEVEL 2. \\ It's only allowed for terminal which hold such configuration. \\ 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 pruchase. 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. | | 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. | | 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. |
Line 45: Line 73:
  
 <WRAP center box 100%> <WRAP center box 100%>
-TERMINALID:​ORDERID:​CURRENCY:​AMOUNT:​DESCRIPTION:​MERCHANTREF:​CREATION_DATE:​EXPIRATION_DATE:​DATETIME:​TERMINAL SECRET+TERMINALID:​ORDERID:​CURRENCY:​SUBTOTAL:​TAX:​AMOUNT:​DESCRIPTION:​MERCHANTREF:​CREATION_DATE:​EXPIRATION_DATE:​AUTH_TYPE:​LEVEL_DATA:​CUSTOMER_REF_NUMBER:​TAX_AMOUNT:​FULL_NAME:​ADDRESS1:​ADDRESS2:​CITY:​REGION:​POSTCODE:​COUNTRY:​DATETIME:​TERMINAL SECRET
 </​WRAP>​ </​WRAP>​
  
 <WRAP center important 100%> <WRAP center important 100%>
-The not mandatory ​fields ​- Description and Creation Date - should only be added to the hash if used on request.+The optional ​fields ​(REQUIRED as "​N"​) ​should only be added to the hash if used on request.
 </​WRAP>​ </​WRAP>​
  
Line 60: Line 88:
 \\ \\
  
-**ND003 - Fields'​ Constraints**+**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: 
 + 
 +^ **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. | 
 +| 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. | 
 +| 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. | 
 +| 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** ^ ^ **CONSTRAINT** ^ **DESCRIPTION** ^
Line 69: Line 135:
 | C005 | The Expiration Date (EXPIRATION_DATE) cannot be before Creation Date | | C005 | The Expiration Date (EXPIRATION_DATE) cannot be before Creation Date |
 | C006 | The Merchant Ref (MERCHANTREF) should be unique for the Terminal | | 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 ig 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. |
  
 \\ \\
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International