Create a country specific VAT Report extension

Dokumentation •
In diesem Artikel

Following, we will explain what needs to be considered when creating a Banana Accounting Extension for VAT reporting suitable for a specific country.

  • Creating the Vat code for the specific country.
  • Creating the country specific reports or export files, using the functionalities offered by the Banana API .


Banana Accounting manage all kinds of VAT, thanks to the use of customizable VAT Code. For more information on how it managed and recorded VAT see:

Vat Table

Countries require to fill a form with the VAT grouped by different percentages and criterias. In order to achieve this goals it is necessary to create a specific VAT code for each type of VAT that need to be reported.

There are two main groups:

  • Vat due to the tax authority.
  • Vat recoverable


Creating the VatCode for a specific country

When you use Banana Accounting in a new country, you need to adapt the VatCode table to your country needs. Basically you should procede as described here:

  • The starting point is the Vat reporting form of the country.
  • You need to create a VAT Code in the VAT Code Table.
  • The user, for each transaction that is related to the VAT,  will specify the VAT code so that similar transactions can be grouped and summed together, based on the form requirements. 
  • For each case there should be a specific VAT Codes.  The parameters will vary base on:
    • VAT recoverable and payable
    • Percentage of VAT.
    • Tax reporting requirements.
      There should be a different VAT Code for export of goods and goods that are exempt.
      Tax authorities requires the amounts to be reported sepately even if the percentage applicable is always zero.

Example, for a country that has a VAT percentage of 0% and 5%.

  • For the 0% you need to report both the sales exempt and the export:
    • Create a Vat code S0 for Vat Exempt (Vat due Yes even if percentage is 0)
    • Create a Vat code SE for Vat Export. (Vat due Yes even if percentage is 0)
  • For the 5%
    • Create a Vat code S5 for sales at 5% (Vat due Yes)
    • Create a Vat code P5 for purchase. (Vat due void, means recoverable)
    • If you need to show separatly on the tax form the discounts, create a Vat code SD5 for discount on sales at 5%.
      If it is not necessary to show separatly the discounts, when entering the transactions for discounts we precede the VAT code with the "-S5" so the  amount will be reversed.

There are countries where the are many VAT percentages and a complex tax reporting form. In this case, you will end up having a VAT table with many codes.

Use the Gr1 to groups VAT Code together

If the VAT amounts for different VAT code need to be grouped together, you can use the Gr1 to enter to witch field the VAT code belong.

  • When creating a Banana Extension to groups the amounts together, you can use this groups to report the amounts.
  • In case the user need to add a new VatCode that fit in a form, he can do it and get it correctly summed in the tax form.

Specify in the Gr1 the field number of the VAT form, separating the number with ";" if the same goes in more than one group. For example:

  • The field 100 of the tax form require to declare all sales amounts.
  • The different sales need also to be indicated in the specific tax field, so we specify also the other tax field.
  • Discount need to be indicate separately so we specify for a discount the specific field. The same for purchases.

Give the full VAT code table

It is possible that you will end up with a very complex VAT table.
Some user will probably use only few VAT code, the one that are necessary for their actitivity. 
It is better not to give to the user a stripped down Vat table, for the fact that it may need one specific Vat code.

In this case enter the 1 in the Disable columns. The user will be able to use the code but this will not appear in the list of available VatCode when entering it in the Transactions table.

Assigning vat code to the accounts table

For each account you can assign a default Vat Code (column Vat code).
When you enter or import transactions the Vat code will be retrieved, but you can change it.

Vat Transactions

When entering transactions you also specify the VAT code, so that:

  • The VAT code parameters are retrieved.
  • The VAT Amounts are calculated.
  • The VAT is recorded on the appropriate accounts.
  • You will have all the information necessary to prepare a summary report.

We see above different examples of VAT transactions.

  • Doc 10-11.
    We record cash sale using different Amount type.
    We see that the transaction amount is different but the Taxable amount and VAT amount are always the same.
    VAT amount is in negative for the fact that the VAT amount is registered in credit, and therefore the amount must be payed to the tax authority.
  • Doc 20.
    Return of goods from customer.
    We use the same VAT code, but preceeded by the minus sing. The taxable amount and VAT amout sign is inverted. 
    Vat Amount is positive (debit), meaning we recover the VAT from the tax authoriy.
  • Doc 100-102.
    Purchase the VAT amount is positive (debit) meaning we recover the VAT from the tax authortity.
  • Doc 130.
    Return of good to suppliers the VAT code is inverted, and we owe the taxt to the authority.

VAT documentation

For each country there should be a documentation that explain the VAT theme with:

  • Page for the VAT codes.
    Explaining the single VAT code and grouping.
  • Page for the transactions with examples and explanations
    In one or more pages all possible transactions case should be explained. The page is a reference that allows user to understand how a specific case should be recorded.
    • Create a file with transactions examples.
    • Create header and sub header for the different cases, user should be able to find the case by going through the page or an index. Typical:
      • VAT Due
        • Normal
        • Credit notes
        • Reverse charge
      • VAT Recoverable
        • Normal
        • Credit note
        • VAT not fully deductible.
      • VAT Exempt
      • VAT 0 %
      • Adjustments
      • Corrections
      • End of period transactions.
    • Create images of the Transaction's table.
    • Use the column Doc to number each transaction group.
      • When you write explanations you will precede the explanation with the doc number of the tranasaction. 
      • Use bullet paragraph when explaining single transactions.
  • End of period
    Explain what procedure do to at the and of period.
    • Check accounting.
    • Account1 -> VAT report
    • Country specific report
    • Transaction to move the automatic VAT amount to  the VAT due or recoverable.
    • Transaction to pay the VAT

Banana Extension for VAT country summary report 

Before creating a country specific VAT report you should have created a file containing:

  • Account plan for the country.
  • VAT code table with all the necessary VAT codes for the country, with the GR1 set with the group.
  • Test Transactions for all the cases and VAT codes. Including also che reversal transactions (like discounts or credit notes).
    This transactions will allow the programmer to immediately test the results.

Examples files

Javascipt API to use for VAT Calculation

The API to retrieve the values above would be:

//get the description of the vat code
// use the vatCurrent Balance to retrieve the different values
  • vatTaxable is the net amount, the one that usually must figure on the vat report as the amount of revenue to declare.
  • vatAmount is the VAT amount.
  • vatTaxable + vatAmount is the gross amount or inclusive Vat..
  • vatNotDeductible is the amount of vat that cannot be fiscally deducted. In case you have an expense where the VAT cannot be totally deducted.
  • vatPosted (vatAmount - vatNotDeductible) is the amount that has been posted on tha VAT account.
  • count is the number of row that have been found to use the vatCode.

Grouping VAT Codes

The VAT call can only be made for one or more VAT Codes.
If more VAT code need to be grouped together, you should have a Javascript function that take as parameter the GR1.
The function should iterate the VAT table and return the VAT code that have the the corresponding GR1.

The sign of the vatAmount

The sign of the vatAmount follows the accounting convention.

  • If the sign of the vatAmount is negative (debit), it means that the vat is due.
  • If the sign of the vatAmount is positive, it means that the vat is recoverable.

The sign of the vatTaxable follow the sign of the vatAmount. In case the vatAmount is zero the vatTaxable sign is negative if the isDue of the vatCode is true.

If you use the vatAmount to create a tax form you should take care to invert the amount.

vatAmount sign and isDue flag:

  • Vat code that have the isDue to true (1)  normally have the vatAmount in negative, but the vatAmount could also be positive in case the user has used the vatCode with the minus sign "-S10".
    The minus sign before the vatCode is used in case of reversal transaction (correction of an incorrect transactions). In this case, the vatAmount would be recorded in the positive.
  • Vat code that have the isDue to false (void)  normally have the vatAmount in positive, but the vatAmount could also be negative in case the user has used the vatCode with the minus sign "-P10".
    In this case the vatAmount would be recorded in negative.

Amount used in the vat report for the tax authorities

Vat due

The amounts are usually in negative,so they must be inverted.

Banana.document.vatCurrentBalance("S10").vatTaxable * (-1);
Banana.document.vatCurrentBalance("S10").vatAmount * (-1);

They could be positive in the case that there have been a good returned from clients that exceeds the amount of sales.

Vat recoverable

The amounts are usually in negative,so they must be inverted.


They could be negative in the case that there have been a good returned to suppliers that exceed the amount of sales.

Combination of sign and typology (VAT Class)

Combining sign and typology we have the different case that come up in the VAT reporting:

  • "1" Recoverable VAT Taxable (VAT netto)
  • "2" Due  VAT Taxable (VAT netto)
  • "3" Recoverable VAT posted (VAT Amount)
  • "4" Due  VAT posted  (VAT Amount)
  • "5" Recoverable VAT gross amount (VAT taxable + VAT amount)
  • "6" Due VAT gross amount (VAT taxable + VAT amount)

The VAT class is used in a function to automate the calculation and reporting with the correct sign.


VAT report are usually done for a period (month, quarter or semester).
You should use the vatCurrentBalance with tha startDate and endDate

//vat report for January 2018
var startDate = "2018-01-01";
var endDate = "2018-01-31
Banana.document.vatCurrentBalance("S10", startDate, endDate).vatTaxable;
Banana.document.vatCurrentBalance("P10", startDate, endDate).vatTaxable;

Summing many VAT codes

You can have the total of different code by separating the VAT code with the sign "|"

//vat report for January 2018
var startDate = "2018-01-01";
var endDate = "2018-01-31
// The taxable amount
Banana.document.vatCurrentBalance("S0|S5|S10|SD5|SD10", startDate, endDate).vatTaxable * (-1);
// The vat due 
Banana.document.vatCurrentBalance("S0|S5|S10|SD5|SD10", startDate, endDate).vatAmount * (-1);
// The vat taxable vat recoverable 
Banana.document.vatCurrentBalance("P0|P5|P10|PD5|PD10", startDate, endDate).vatTaxable;
// The vat vat recoverable 
Banana.document.vatCurrentBalance("P0|P5|P10|PD5|PD10", startDate, endDate).vatAmount;

VAT Extra Info

There are some case where for appropriate reporting the VAT code alone is not sufficient. The VAT Extra info allows to define an extra code and enter in the Transactions to further specify  the case. The VAT Extra code allows to limit the number of VAT codes needed, but also to track exceptions.

Printing the VAT transactions list

To print the transactions with VAT or doing VAT calculations, use the function Banana.document.journal().

// use the data from the transactions and only normal accounts (exclude cost centers)
var journal = Banana.document.journal(Banana.document.ORIGINTYPE_CURRENT, Banana.document.ACCOUNTTYPE_NORMAL);
for (i = 0; i < journal.rowCount; i++) {
  var tRow = journal.row(i);
  // we get the vat values 
  var vatTaxable = tRow.value('JVatTaxable');
  var vatAmount = tRow.value('VatAmount');
  var vatPosted = tRow.value('VatPosted');

Within the samples apps repository you find two examples of transactions list:





Wie können wir Ihnen besser helfen?
Wenn die Informationen auf dieser Seite nicht das sind, was Sie suchen, nicht klar genug sind oder nicht aktuell sind, lassen Sie es uns wissen.

Diesen Artikel teilen: Twitter | Facebook | LinkedIn | Email