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. 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:
TAX_23
TAX_22
TAX_8
TAX_7
TAX_5
TAX_3
TAX_0
TAX_EXEMPT
TAX_NOT_LIABLE
TAX_REVERSE_CHARGE
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:
DENTAL_TECHNICAN_SERVICES,
DOCTOR_DENTIST_SERVICES,
PHYSIOTHERAPY_SERVICES,
NURSING_SERVICES,
PSYCHOLOGICAL_SERVICES,
MEDICAL_TRANSPORT_SERVICES,
CARE_SERVICES,
TUTORING,
TEACHING_FOREIGN_LANGUAGES,
ARTISTS,
RENTING_PROPERTY,
INSURANCE_SERVICES,
CREDITS_AND_LOANS_SERVICES,
GUARANTIEES,
SPECIAL_CONDITIONS_FOR_EXEMPTION,
UE_TRANSACTIONS,
SUBJECTIVE_EXEMPTIONS,
OTHER,
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 

$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.

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

$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 

H4sIAAAAAAAAA0WOQQvCNAyF/4rkPGWbenAnh3gTFedBEJGqVcu6dq4pOMf+u8MYeAnJl/fy0sDF17KCpAGsSwkJbJe7bLOGAGQhlCaA0uGcy6jUhO9e67UoZL8zcCHssJISfzAiclVY9zNNpXUo9MLe2BjFw/KkyhrrDVY141SXTxHzAytoO71CZY2D5NiA+QfGna07M6P25YXBLikKwBvFL2Qf9LmiJYp3hiJn7T49nENCj8o6lxacS5ZpGLan9gsKdX5sBQEAAA==

Example HTML form content 

<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">