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_subscription_features [2019/07/16 13:13]
thiago123 [Examples for a Request]
developer:api_specification:xml_subscription_features [2019/07/16 13:15] (current)
thiago123 [Notes and Details About the Request]
Line 504: Line 504:
 | 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. |
 | CUSTOMFIELD'​N'​ | N | Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. Their values are going to be stored and used by the Payment Gateway for the requests sent to the Receipt URL and the Validation URL. To understand more visit the section regarding **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]**. Limited to 30 custom fields in this request. | | CUSTOMFIELD'​N'​ | N | Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. Their values are going to be stored and used by the Payment Gateway for the requests sent to the Receipt URL and the Validation URL. To understand more visit the section regarding **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]**. Limited to 30 custom fields in this request. |
-|LEVEL_2_DATA | N |Component of the request that can be added in case the Level II Data feature is in use for the Terminal processing the Payment. See **ND005 - Level 2 Data Validation**. | +|LEVEL_2_DATA | N |Component of the request that can be added in case the Level II Data feature is in use for the Terminal processing the Payment. See **ND004 - Level 2 Data Validation**. | 
-|LEVEL_3_DATA | N |Component of the request that can be added in case the Level 3 Data feature is in use for the Terminal processing the Payment. See **ND006 - Level 3 Data Validation**. | +|LEVEL_3_DATA | N |Component of the request that can be added in case the Level 3 Data feature is in use for the Terminal processing the Payment. See **ND005 - Level 3 Data Validation**. | 
  
 </​searchtable>​ </​searchtable>​
Line 554: Line 554:
 \\ \\
  
 +**ND004 - Level 2 Data Validation**
 +
 +This field is associated with the Transaction Enhanced Data feature, and to be used it is necessary to have the "Allow Enhanced Data (Level II and Level III)" enabled with the "​Transaction Data Level" option set as "Level II" on the Processing Terminal “Features” section.
 +
 +To provide a transaction with LEVEL 2, your request needs to add the LEVEL_2_DATA component and its fields, as described below.
 +
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| CUSTOMER_REF_NUMBER ​ | N | 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 | N | Integer type, with max length of 13 numbers. A value of zero is required in order to indicate tax exempt transactions. |
 +| SHIPPING_ADDRESS | N | A 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. |
 +
 +\\
 +
 +Quick example:
 +
 +<code xml>
 +<​LEVEL_2_DATA>​
 +    <​CUSTOMER_REF_NUMBER>​SDGK-JSAAS-0235.00002314</​CUSTOMER_REF_NUMBER>​
 +    <​TAX_AMOUNT>​151.27</​TAX_AMOUNT>​
 +    <​SHIPPING_ADDRESS>​
 + <​FULL_NAME>​JOHN SMITH AND ASSOCIATES</​FULL_NAME>​
 + <​ADDRESS1>​Unit 001, Street X</​ADDRESS1>​
 + <​ADDRESS2>​Block "​A",​ Neighborhood "​A"</​ADDRESS2>​
 + <​CITY>​City "​Y"</​CITY>​
 + <​REGION>​Region 1</​REGION>​
 + <​POSTCODE>​A00B0001</​POSTCODE>​
 + <​COUNTRY>​Country "​Z"</​COUNTRY>​
 + </​SHIPPING_ADDRESS>​
 +</​LEVEL_2_DATA>​
 +</​code>​
 +
 +\\
 +
 +**ND005 - Level 3 Data Validation**
 +
 +This field is associated with the Transaction Enhanced Data feature, and to be used it is necessary to have the "Allow Enhanced Data (Level II and Level III)" enabled with the "​Transaction Data Level" option set as "Level III" on the Processing Terminal “Features” section.
 +
 +To provide a transaction with LEVEL 3, your request needs to add the LEVEL_2_DATA (described before) and the LEVEL_3_DATA components and their fields. The LEVEL_3_DATA component fields are described below.
 +
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| SUMMARY | N | Subcomponent of Level 3. Agregates the sums of different values within the transaction. |
 +| TOTAL_DISCOUNT_AMOUNT | N | Subfield of SUMMARY. Represents the total value assigned as discount to the sale. That considers the resulting sum from all items' discunts rates (unit price x quantity x discount rate) and any other additional discount applied after that. \\ Decimal value, allowing max of 13 digits with min value of 0. |
 +| TOTAL_FREIGHT_AMOUNT | N | Subfield of SUMMARY. Represents the freight amount applied to the sale. \\ Decimal value, allowing max of 13 digits with min value of 0. |
 +| TOTAL_DUTY_AMOUNT | N | Subfield of SUMMARY. Represents the duty amount applied to the sale. \\ Decimal value, allowing max of 13 digits with min value of 0. |
 +| LINE_ITEMS | N | Subcomponent of Level 3. List of all items in which the sale is broken down. |
 +| LINE_ITEM | N | Subfield of LINE_ITEMS. Holds all the details of a sale's item. You can add as much as necessary to express the breaking down of your sale. |
 +| COMMODITY_CODE | N | Subfield of LINE_ITEM. 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. |
 +| PRODUCT_CODE | N | Subfield of LINE_ITEM. This is the merchant’s identifier for the product, also known as Universal Product code (UPC). |
 +| DESCRIPTION | N | Subfield of LINE_ITEM. This is the merchant’s description for the product. |
 +| QUANTITY | N | Subfield of LINE_ITEM. Quantity of the specific item for the sale. |
 +| UNIT_OF_MEASURE | N | Subfield of LINE_ITEM. Measure unit used for this specific item type to sell it in parts, units or sets. |
 +| UNIT_PRICE | N | Subfield of LINE_ITEM. Unit price applied for that specific type of item and measure unit, within the sale. |
 +| DISCOUNT_RATE | N | Subfield of LINE_ITEM. A % of discount applied to the item total (quantity x unit price) before taxes. |
 +| TAX_RATE | N | Subfield of LINE_ITEM. A % of tax applied to the item total (quantity x unit price) after discounts. |
 +| TOTAL_AMOUNT | N | Subfield of LINE_ITEM. Final item value based on total (quantity x unit price), after discount and tax applied. |
 +
 +\\
 +
 +Quick example:
 +
 +<code xml>
 +<​LEVEL_2_DATA>​...</​LEVEL_2_DATA>​
 +<​LEVEL_3_DATA>​
 +    <​SUMMARY>​
 +        <​TOTAL_DISCOUNT_AMOUNT>​61.30</​TOTAL_DISCOUNT_AMOUNT>​
 +        <​TOTAL_FREIGHT_AMOUNT>​3.50</​TOTAL_FREIGHT_AMOUNT>​
 +        <​TOTAL_DUTY_AMOUNT>​11.50</​TOTAL_DUTY_AMOUNT>​
 +    </​SUMMARY>​
 +    <​LINE_ITEMS> ​
 +        <!-- As many as necessary -->
 +        <​LINE_ITEM>​
 +            <​COMMODITY_CODE>​PDX001</​COMMODITY_CODE>​
 +            <​PRODUCT_CODE>​DSV1303.090.00001</​PRODUCT_CODE>​
 +            <​DESCRIPTION>​General services</​DESCRIPTION>​
 +            <​QUANTITY>​10</​QUANTITY>​
 +            <​UNIT_OF_MEASURE>​Hour</​UNIT_OF_MEASURE>​
 +            <​UNIT_PRICE>​105.50</​UNIT_PRICE>​
 +            <​DISCOUNT_RATE>​5.00</​DISCOUNT_RATE>​
 +            <​TAX_RATE>​12.50</​TAX_RATE>​
 +            <​TOTAL_AMOUNT>​1127.53</​TOTAL_AMOUNT>​
 +        </​LINE_ITEM>​
 +        <​LINE_ITEM>​
 +            <​COMMODITY_CODE>​PDX002</​COMMODITY_CODE>​
 +            <​PRODUCT_CODE>​DSV1302.090.00001</​PRODUCT_CODE>​
 +            <​DESCRIPTION>​General services</​DESCRIPTION>​
 +            <​QUANTITY>​2</​QUANTITY>​
 +            <​UNIT_OF_MEASURE>​Hour</​UNIT_OF_MEASURE>​
 +            <​UNIT_PRICE>​85.50</​UNIT_PRICE>​
 +            <​DISCOUNT_RATE>​5.00</​DISCOUNT_RATE>​
 +            <​TAX_RATE>​16.00</​TAX_RATE>​
 +            <​TOTAL_AMOUNT>​188.44</​TOTAL_AMOUNT>​
 +        </​LINE_ITEM>​
 +    </​LINE_ITEMS>​
 +</​LEVEL_3_DATA>​
 +</​code>​
 +
 +<WRAP info round 100%>
 +**DON'​T FORGET**
 +
 +If you are using LEVEL_3_DATA component, also add to your request the LEVEL_2_DATA 2 component to attempt a fully qualification for enhanced data.
 +
 +</​WRAP>​
 +
 +\\
 ==== Examples for a Request ==== ==== Examples for a Request ====
  
Line 737: Line 848:
 | 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. |
 | CUSTOMFIELD'​N'​ | N | Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. Their values are going to be stored and used by the Payment Gateway for the requests sent to the Receipt URL and the Validation URL. To understand more visit the section regarding **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]**. Limited to 30 custom fields in this request. | | CUSTOMFIELD'​N'​ | N | Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. Their values are going to be stored and used by the Payment Gateway for the requests sent to the Receipt URL and the Validation URL. To understand more visit the section regarding **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]**. Limited to 30 custom fields in this request. |
-|LEVEL_2_DATA | N |Component of the request that can be added in case the Level II Data feature is in use for the Terminal processing the Payment. See **ND005 - Level 2 Data Validation**. | +|LEVEL_2_DATA | N |Component of the request that can be added in case the Level II Data feature is in use for the Terminal processing the Payment. See **ND003 - Level 2 Data Validation**. | 
-|LEVEL_3_DATA | N |Component of the request that can be added in case the Level 3 Data feature is in use for the Terminal processing the Payment. See **ND006 - Level 3 Data Validation**. | +|LEVEL_3_DATA | N |Component of the request that can be added in case the Level 3 Data feature is in use for the Terminal processing the Payment. See **ND004 - Level 3 Data Validation**. | 
 </​searchtable>​ </​searchtable>​
 \\ \\
Line 765: Line 876:
  
 All data sent to us should be correctly encoded using **UTF-8** as the character encoding. All data sent to us should be correctly encoded using **UTF-8** as the character encoding.
 +
 +\\
 +
 +**ND003 - Level 2 Data Validation**
 +
 +This field is associated with the Transaction Enhanced Data feature, and to be used it is necessary to have the "Allow Enhanced Data (Level II and Level III)" enabled with the "​Transaction Data Level" option set as "Level II" on the Processing Terminal “Features” section.
 +
 +To provide a transaction with LEVEL 2, your request needs to add the LEVEL_2_DATA component and its fields, as described below.
 +
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| CUSTOMER_REF_NUMBER ​ | N | 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 | N | Integer type, with max length of 13 numbers. A value of zero is required in order to indicate tax exempt transactions. |
 +| SHIPPING_ADDRESS | N | A 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. |
 +
 +\\
 +
 +Quick example:
 +
 +<code xml>
 +<​LEVEL_2_DATA>​
 +    <​CUSTOMER_REF_NUMBER>​SDGK-JSAAS-0235.00002314</​CUSTOMER_REF_NUMBER>​
 +    <​TAX_AMOUNT>​151.27</​TAX_AMOUNT>​
 +    <​SHIPPING_ADDRESS>​
 + <​FULL_NAME>​JOHN SMITH AND ASSOCIATES</​FULL_NAME>​
 + <​ADDRESS1>​Unit 001, Street X</​ADDRESS1>​
 + <​ADDRESS2>​Block "​A",​ Neighborhood "​A"</​ADDRESS2>​
 + <​CITY>​City "​Y"</​CITY>​
 + <​REGION>​Region 1</​REGION>​
 + <​POSTCODE>​A00B0001</​POSTCODE>​
 + <​COUNTRY>​Country "​Z"</​COUNTRY>​
 + </​SHIPPING_ADDRESS>​
 +</​LEVEL_2_DATA>​
 +</​code>​
 +
 +\\
 +
 +**ND004 - Level 3 Data Validation**
 +
 +This field is associated with the Transaction Enhanced Data feature, and to be used it is necessary to have the "Allow Enhanced Data (Level II and Level III)" enabled with the "​Transaction Data Level" option set as "Level III" on the Processing Terminal “Features” section.
 +
 +To provide a transaction with LEVEL 3, your request needs to add the LEVEL_2_DATA (described before) and the LEVEL_3_DATA components and their fields. The LEVEL_3_DATA component fields are described below.
 +
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| SUMMARY | N | Subcomponent of Level 3. Agregates the sums of different values within the transaction. |
 +| TOTAL_DISCOUNT_AMOUNT | N | Subfield of SUMMARY. Represents the total value assigned as discount to the sale. That considers the resulting sum from all items' discunts rates (unit price x quantity x discount rate) and any other additional discount applied after that. \\ Decimal value, allowing max of 13 digits with min value of 0. |
 +| TOTAL_FREIGHT_AMOUNT | N | Subfield of SUMMARY. Represents the freight amount applied to the sale. \\ Decimal value, allowing max of 13 digits with min value of 0. |
 +| TOTAL_DUTY_AMOUNT | N | Subfield of SUMMARY. Represents the duty amount applied to the sale. \\ Decimal value, allowing max of 13 digits with min value of 0. |
 +| LINE_ITEMS | N | Subcomponent of Level 3. List of all items in which the sale is broken down. |
 +| LINE_ITEM | N | Subfield of LINE_ITEMS. Holds all the details of a sale's item. You can add as much as necessary to express the breaking down of your sale. |
 +| COMMODITY_CODE | N | Subfield of LINE_ITEM. 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. |
 +| PRODUCT_CODE | N | Subfield of LINE_ITEM. This is the merchant’s identifier for the product, also known as Universal Product code (UPC). |
 +| DESCRIPTION | N | Subfield of LINE_ITEM. This is the merchant’s description for the product. |
 +| QUANTITY | N | Subfield of LINE_ITEM. Quantity of the specific item for the sale. |
 +| UNIT_OF_MEASURE | N | Subfield of LINE_ITEM. Measure unit used for this specific item type to sell it in parts, units or sets. |
 +| UNIT_PRICE | N | Subfield of LINE_ITEM. Unit price applied for that specific type of item and measure unit, within the sale. |
 +| DISCOUNT_RATE | N | Subfield of LINE_ITEM. A % of discount applied to the item total (quantity x unit price) before taxes. |
 +| TAX_RATE | N | Subfield of LINE_ITEM. A % of tax applied to the item total (quantity x unit price) after discounts. |
 +| TOTAL_AMOUNT | N | Subfield of LINE_ITEM. Final item value based on total (quantity x unit price), after discount and tax applied. |
 +
 +\\
 +
 +Quick example:
 +
 +<code xml>
 +<​LEVEL_2_DATA>​...</​LEVEL_2_DATA>​
 +<​LEVEL_3_DATA>​
 +    <​SUMMARY>​
 +        <​TOTAL_DISCOUNT_AMOUNT>​61.30</​TOTAL_DISCOUNT_AMOUNT>​
 +        <​TOTAL_FREIGHT_AMOUNT>​3.50</​TOTAL_FREIGHT_AMOUNT>​
 +        <​TOTAL_DUTY_AMOUNT>​11.50</​TOTAL_DUTY_AMOUNT>​
 +    </​SUMMARY>​
 +    <​LINE_ITEMS> ​
 +        <!-- As many as necessary -->
 +        <​LINE_ITEM>​
 +            <​COMMODITY_CODE>​PDX001</​COMMODITY_CODE>​
 +            <​PRODUCT_CODE>​DSV1303.090.00001</​PRODUCT_CODE>​
 +            <​DESCRIPTION>​General services</​DESCRIPTION>​
 +            <​QUANTITY>​10</​QUANTITY>​
 +            <​UNIT_OF_MEASURE>​Hour</​UNIT_OF_MEASURE>​
 +            <​UNIT_PRICE>​105.50</​UNIT_PRICE>​
 +            <​DISCOUNT_RATE>​5.00</​DISCOUNT_RATE>​
 +            <​TAX_RATE>​12.50</​TAX_RATE>​
 +            <​TOTAL_AMOUNT>​1127.53</​TOTAL_AMOUNT>​
 +        </​LINE_ITEM>​
 +        <​LINE_ITEM>​
 +            <​COMMODITY_CODE>​PDX002</​COMMODITY_CODE>​
 +            <​PRODUCT_CODE>​DSV1302.090.00001</​PRODUCT_CODE>​
 +            <​DESCRIPTION>​General services</​DESCRIPTION>​
 +            <​QUANTITY>​2</​QUANTITY>​
 +            <​UNIT_OF_MEASURE>​Hour</​UNIT_OF_MEASURE>​
 +            <​UNIT_PRICE>​85.50</​UNIT_PRICE>​
 +            <​DISCOUNT_RATE>​5.00</​DISCOUNT_RATE>​
 +            <​TAX_RATE>​16.00</​TAX_RATE>​
 +            <​TOTAL_AMOUNT>​188.44</​TOTAL_AMOUNT>​
 +        </​LINE_ITEM>​
 +    </​LINE_ITEMS>​
 +</​LEVEL_3_DATA>​
 +</​code>​
 +
 +<WRAP info round 100%>
 +**DON'​T FORGET**
 +
 +If you are using LEVEL_3_DATA component, also add to your request the LEVEL_2_DATA 2 component to attempt a fully qualification for enhanced data.
 +
 +</​WRAP>​
  
 \\ \\
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International