Differences

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

Link to this comparison view

Both sides previous revision Previous revision
developer:api_specification:xml_payment_features_einvoice [2019/04/03 10:21]
thiago123
developer:api_specification:xml_payment_features_einvoice [2019/05/16 12:57] (current)
thiago123 adjusted 5.9 release
Line 4: Line 4:
  
 \\ \\
-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%> <WRAP center important 100%>
Line 36: Line 37:
 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. 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 =====+===== Create Link =====
  
-This feature allows you to create ​payment ​links.+This feature allows you to create links.
  
   * **Main Request body Tag**: <​CREATE_PAYMENT_LINK> ​   * **Main Request body Tag**: <​CREATE_PAYMENT_LINK> ​
Line 47: Line 48:
 <​searchtable>​ <​searchtable>​
 ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ ^ **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**.| +| 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.\\ Maximun ​of 24 characters. |  +| 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 **ND003 - 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 ​before applied tax. A 2 digit decimal ​or an Integer ​value for JPY amounts. If not informed on requestthe gateway is going to calculate the correct value based on AMOUNT and TAX. | +| 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**. | 
-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 caseit's going to be calculated. 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 valuelimited ​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**. | | 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. |
Line 58: Line 62:
 | EXPIRATION_DATE | Y | Date in which the link must expire. Format: DD-MM-YYYY.\\ Take a look at **ND005 - 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. |  | 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 **. | | 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**. |+| 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. | | 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 73: Line 76:
  
 <WRAP center box 100%> <WRAP center box 100%>
-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+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
 </​WRAP>​ </​WRAP>​
  
Line 88: Line 91:
 \\ \\
  
-**ND003 - Level II Data Validation**+**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 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.
- +
-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: The request component LEVEL_2_DATA is composed by the following nested elements:
Line 101: Line 99:
 ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ ^ **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. | | 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. | +| 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. | +| 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. | +| 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. | +| 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. | +| 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. | +| 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. | +| 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. | +| 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. |+| COUNTRY ​             | N | Subfield of SHIPPING_ADDRESS. Value is text type, with 2 characters. ISO ALPHA-2 Country Code. |
  
 \\ \\
Line 118: Line 116:
  
 ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
-| CODE        | Y | Item code, used to identify it's nature. Text between 1 and 45 characters. | +| 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. | +| 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. | 
-| QUANTITY ​   | Y | Decimal number to express the quantity pruchased of an item. Values accepted between 0.01 and 999999999.99. | +| DESCRIPTION ​    ​| Y | Description of the item, used to provide more details on what's was purchased. Text between 1 and 250 characters. | 
-| 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. | +| QUANTITY ​       | Y | Decimal number to express the quantity pruchased of an item. Values accepted between 0.01 and 999999999.99. | 
-| 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 |+| 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 |
    
 \\ \\
Line 138: Line 140:
 | C008 | Only terminals which support Level II Enhanced Data allow integrations to inform the LEVEL_2_DATA. | | 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. | | 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. |+| 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. | | 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. | | 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. |
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International