# ING Księgowość

This option is available when the ING Księgowość service is **enabled**. An `invoice` object must be attached to the basic request creating the transaction as described in the section [Creating a payment](#topic-creating-a-payment). This object consists of a `buyer` object and a `positions` array with the following parameters:

`buyer` object:

| Parameter | Type | Parameter required | Description |
|-------------------|-----------------------------------------------|-|-|
| `type`    | string | `YES` | It takes the value `PERSON` *individual buyer* or `COMPANY` *company* |
| `email`   | string(200) | `YES` | E-mail address in the format compliant with RFC 5322 and RFC 6531 |
| `fullName`| string(200) | `YES` | Buyer's name/company name |
| `street`  | string(200) | `YES` | Street |
| `city`    | string(100) | `YES` | City
| `postalCode` | string(30) | `YES` | Postal code |
| `countryCodeAlpha2` | string(2) | `YES` | Country code `Alpha2` |
| `idCountryCodeAlpha2` | string(2) | `NO` | `Alpha2` country code identifier. Required for the `VAT_ID` value of the `idType` parameter |
| `idType`  | string | `NO` | Identification number type. Required for the `COMPANY` value of the `type` parameter. Takes the value of ID *TIN* or VAT_ID *CRN*. |
| `idNumber`| string(30) | `NO` | CRN or TIN number. Required for the `COMPANY` value of the `type` parameter. |

`positions` array:

| Parameter | Type | Parameter required | Description |
|-------------------|-----------------------------------------------|-|-|
| `name` | string | `YES` | Product name |
| `code` | string | `YES` | Product code |
| `quantity` | number | `YES` | Quantity. **The minimum value is 0** |
| `unit` | string | `YES` | Unit |
| `grossAmount` | integer | `YES` | Gross unit value |
| `taxStake` | string | `YES` | Tax rate. **Available values:** <br> `TAX_23` <br> `TAX_22` <br> `TAX_8` <br> `TAX_7` <br> `TAX_5` <br> `TAX_3` <br> `TAX_0` <br> `TAX_EXEMPT` <br> `TAX_NOT_LIABLE` <br> `TAX_REVERSE_CHARGE` <br> `TAX_EXCLUDING` |
| `discountAmount` | integer | `NO` | Discount value |

In the case of tax exemption, the relevant data should be provided in the request using the `basisForVatExemption` object with the following parameters:

| Parameter | Type   | Parameter required | Description |
|-----------|--------|--------------------|-------------|
| `type`    | string | `NO`               | **Available values:** <br> `DENTAL_TECHNICAN_SERVICES`, <br> `DOCTOR_DENTIST_SERVICES`, <br> `PHYSIOTHERAPY_SERVICES`, <br> `NURSING_SERVICES`, <br> `PSYCHOLOGICAL_SERVICES`, <br> `MEDICAL_TRANSPORT_SERVICES`, <br> `CARE_SERVICES`, <br> `TUTORING`, <br> `TEACHING_FOREIGN_LANGUAGES`, <br> `ARTISTS`, <br> `RENTING_PROPERTY`, <br> `INSURANCE_SERVICES`, <br> `CREDITS_AND_LOANS_SERVICES`, <br> `GUARANTIEES`, <br> `SPECIAL_CONDITIONS_FOR_EXEMPTION`, <br> `UE_TRANSACTIONS`, <br> `SUBJECTIVE_EXEMPTIONS`, <br> `OTHER`, <br> `OTHER_OBJECTIVE_EXEMPTIONS` |
| `text`    | string | `NO`               | Description. This parameter is required when the value `OTHER` is specified in the `type` parameter. |


Additionally, it is possible to specify whether the invoice should be sent automatically using the parameter:

| Parameter      | Type    | Parameter required | Description                  |
|----------------|---------|--------------------|------------------------------|
| `issueInvoice` | boolean | `NO`               | Automatic invoice sending |

## Example data structure

```php
$invoiceData = [
    "buyer"     => [
        "type"              => "PERSON",
        "email"             => "jan.kowalski@example.com",
        "fullName"          => "Jan Kowalski",
        "street"            => "Street",
        "city"              => "City",
        "postalCode"        => "12-345",
        "countryCodeAlpha2" => "PL",
    ],
    "positions" => [
        [
            "name"        => "Produkt",
            "code"        => "produkt-01",
            "quantity"    => 1,
            "unit"        => "Sztuki",
            "taxStake"    => "TAX_23",
            "grossAmount" => 12300,
        ],
    ],
];
```

The above parameters should be taken into account when calculating the signature in accordance with the section [Authorisation](#topic-authorisation).

## Preparing the invoice object

### Using PHP functions
The data collected from the above parameters should be encoded using the following functions:

```
base64_encode(gzencode(json_encode($invoiceData), 5));
```

where:

`$invoiceData` - previously prepared parameters

```php
$invoiceData = [
    "buyer"     => [
        "type"              => "PERSON",
        "email"             => "jan.kowalski@example.com",
        "fullName"          => "Jan Kowalski",
        "street"            => "Street",
        "city"              => "City",
        "postalCode"        => "12-345",
        "countryCodeAlpha2" => "PL",
    ],
    "positions" => [
        [
            "name"        => "Produkt",
            "code"        => "produkt-01",
            "quantity"    => 1,
            "unit"        => "Sztuki",
            "taxStake"    => "TAX_23",
            "grossAmount" => 12300,
        ],
    ],
];
$invoice = base64_encode(gzencode(json_encode($invoiceData), 5));

$fields = [
    'serviceId' => '63f574ed-d90d-4abe-9cs1-39117584a7b7',
    'merchantId' => '6yt3gjtm9p1odfgx8491',
    'amount' => '12300',
    'currency' => 'PLN',
    'orderId' => '123',
    'orderDescription' => '#Example transaction',
    'customerFirstName' => 'Jan',
    'customerLastName' => 'Kowalski',
    'customerEmail' => 'jan.kowalski@example.com',
    'customerPhone' => '515515515',
    'urlSuccess' => 'https://your-shop.com/success',
    'urlFailure' => 'https://your-shop.com/failure',
    'urlReturn' => 'https://your-shop.com/return',
    'invoice' => $invoice,
];
$serviceKey = 'eAyhFLuHgwl5hu-32GM8QVlCVMWRU0dGjH1c';
$hashMethod = 'sha256';
$signature= createSignature(
    $fields,
    $serviceKey,
    $hashMethod
) . ';' . $hashMethod;
```
## Example of an encoded invoice object

```php
H4sIAAAAAAAAA0WOQQvCNAyF/4rkPGWbenAnh3gTFedBEJGqVcu6dq4pOMf+u8MYeAnJl/fy0sDF17KCpAGsSwkJbJe7bLOGAGQhlCaA0uGcy6jUhO9e67UoZL8zcCHssJISfzAiclVY9zNNpXUo9MLe2BjFw/KkyhrrDVY141SXTxHzAytoO71CZY2D5NiA+QfGna07M6P25YXBLikKwBvFL2Qf9LmiJYp3hiJn7T49nENCj8o6lxacS5ZpGLan9gsKdX5sBQEAAA==
```
## Example HTML form content

```html
<input type="hidden" value="63f574ed-d90d-4abe-9cs1-39117584a7b7" name="serviceId">
<input type="hidden" value="6yt3gjtm9p1odfgx8491" name="merchantId">
<input type="hidden" value="300" name="amount">
<input type="hidden" value="PLN" name="currency">
<input type="hidden" value="123" name="orderId">
<input type="hidden" value="Example transaction" name="orderDescription">
<input type="hidden" value="John" name="customerFirstName">
<input type="hidden" value="Doe" name="customerLastName">
<input type="hidden" value="johndoe@domain.com" name="customerEmail">
<input type="hidden" value="501501501" name="customerPhone">
<input type="hidden" value="https://your-shop.com/success" name="urlSuccess">
<input type="hidden" value="https://your-shop.com/failure" name="urlFailure">
<input type="hidden" value="https://your-shop.com/return" name="urlReturn">
<input type="hidden" value="<?= $invoice ?>" name="invoice">
```