NAV Navbar
Přejít na partner.givery.cz

Introduction to documentation

The Givery platform has a very simple REST API based on the standard HTTPS protocol. Thanks to it, you can connect your existing system with ours and thus tailor the sale and delivery of products to end customers.

If you have any questions regarding the implementation, please contact:

Vojtěch Zikmund
vojtech.zikmund@egit.cz

British English is used throughout the documentation (for example CANCELLED).

Environment

Development environment - sandbox

Requests for this sandbox will not result in any change in production and the products issued will not be reflected in the invoicing. The sandbox is therefore fully used for testing the written code.

Production

All requests are processed and issued products are reflected in invoicing. Production methods only need to be accessed from allowed IP addresses.

In case of a request for a VPN tunnel or other above-standard security, contact us.

Transaction life cycle

Terms used in the documentation:

Authentication and signing

Requests verification consists of two levels. API-Key parameter in the HTTP header, which is mandatory for all merchants and requests signing by HMAC, which is optional and subject to individual agreement.

1: API-Key parameter (mandatory)

cURL Request

curl https://api.sandbox.givery.cz/v1/ping/20124 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'API-Key: ak_sandbox_VGyXs0T6G8JkPuaX6C8C3Xwda'

The HTTP request header is extended with the API-Key parameter, the value of which isAPI_KEY (Merchant's API key). The API key is provided to the merchant during the implementation process.

The HTTP request header must also contain parameters
Content-Type: application/json
Accept: application/json

The response also contains the API-Key parameter in the HTTP header.

2. Signature and Timestamp (optional)

JSON Request

{
  "type": "PIN",
  "order_id": "moje_objednavka123",
  "product_id": 237,
  "account_id": null,
  "activation_id": null,
  "pos_id": 1234,
  "value": null,
  "terminal_id": 116796190,
  "retailer_id": 11679,
  "chit_card_taken": null
}

Creating a signature in PHP

<?php

# secret key of a merchant for signing a request
const SECRET_KEY = "sk_sandbox_CAsI4fcX0PJC8XVMH4AgIahwL";
const HTTP_METHOD = "POST"; # POST | GET | PUT - uppercase
const ENDPOINT = "/order";

$ts = time(); # UNIX in seconds (UTC)
$json_request = '{"type":"PIN","order_id":"moje_objednavka123","product_id":237,"account_id":null,"activation_id":null,"pos_id":1234,"value":null,"terminal_id":116796190,"retailer_id":11679,"chit_card_taken":null}';

$s = HTTP_METHOD . "\n" . ENDPOINT . "\n" . $ts . "\n" . $json_request;

# created signature === '95101184222b9f91e229cce2bec4d30ef1ce3d56b9a6280d15115d499aa4fce8'
$signature = hash_hmac("sha256", $s, SECRET_KEY);
?>

cURL Request

curl --request POST 'https://api.sandbox.givery.cz/v1/order' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'API-Key: ak_sandbox_VGyXs0T6G8JkPuaX6C8C3Xwda' \
-H 'Signature: 95101184222b9f91e229cce2bec4d30ef1ce3d56b9a6280d15115d499aa4fce8' \
-H 'Timestamp: 1612174498'

-d '{"type":"PIN","order_id":"moje_objednavka123","product_id":237,"account_id":null,"activation_id":null,"pos_id":1234,"value":null,"terminal_id":116796190,"retailer_id":11679,"chit_card_taken":null}'

HMAC Authentication is used for signing. The signature is a cryptographically strong hash based on the SHA-256 function, which is included in every request and response. The hash is based on a secret key (SECRET_KEY), which is known only to the recipient and sender of the request. Before sending the request, its signature is calculated, which is then added as an HTTP header parameter named Signature. Upon receipt of the request, the other party's signature is counted again and compliance is verified.

The request header must also contain the Timestamp parameter. The value is a UNIX timestamp in UTC timezone that cannot be older than 5 minutes. It serves to prevent possible repeated attacks.

The hash string is created from the HTTP method of the request, endpoint without domain and API version, timestamp and unformatted JSON request. Values are separated by the \n character.

signature = HTTP_METHOD + \n + ENDPOINT + \n + TIMESTAMP + \n + JSON_REQUEST

For GET methods, JSON is also created in key-value format. The keys are the parameter names in the request URL.

The HTTP header parameters Timestamp andSignature are set in the response. The value of the Signature parameter is created in the same way.

Examples for creating a request

HTTP method Endpoint Timestamp JSON for signature
POST /order 1612282826 {"type":"PIN","order_id":"moje_objednavka123","product_id":237,"account_id":null,"activation_id":null,"pos_id":1234,"value":null,"terminal_id":116796190,"retailer_id":11679,"chit_card_taken":null}
GET /order/78912/moje_objednavka123 1612282826 {"retailer_id":78912,"order_id":"moje_objednavka123"}
GET /transaction/78912/1234567890 1612282826 {"retailer_id":78912,"transaction_id":1234567890}
GET /ping/78912 1612282826 {"retailer_id":78912}

Available methods

New order

/order

JSON Request

{
    "type": "PIN",
    "order_id": "moje_objednavka123",
    "product_id": 246537,
    "account_id": null,
    "activation_id": null,
    "pos_id": 1234,
    "value": null,
    "terminal_id": 789120555,
    "retailer_id": 78912,
    "chit_card_taken": true
}

JSON Response

{
    "error": null,
    "error_code": 0,
    "type": "PIN",
    "order_id": "moje_objednavka123",
    "transaction_id": 1234567890,
    "product_id": 246537,
    "vat": 0,
    "cost": {
        "currency": "CZK",
        "cost": 9850,
        "cost_vat": 0
    },
    "recommended_retail_price": {
        "CZK": 10000,
        "EUR": null
    },
    "terminal_id": 789120555,
    "retailer_id": 78912,
    "account_id": null,
    "activation_id": null,
    "pos_id": 1234,
    "value": null,
    "pin": "9999818580216628",
    "barcode": null,
    "serial_number": "1416965707",
    "ean": null,
    "valid_to": null,
    "text": "PIN = hotovost! \nPIN nikdy nesdělujte cizím osobám!\n\nPoužití: Vyberte si internetový obchod a výrobek, zvolte způsob platby paysafecard a zadejte PIN.\n\nV případě dotazů navštivte www.paysafecard.com/help. Tipy pro bezpečné platby na internetu naleznete na www.paysafecard.com/security.\n\nPaysafecard je forma platebního prostředku vydaná společností Paysafe Prepaid Services Ltd. Všeobecné obchodní podmínky naleznete na www.paysafecard.com.",
    "created_at": "2020-06-10T09:49:50+00:00",
    "changed_at": "2020-06-10T09:49:51+00:00",
    "status": "DELIVERED",
    "order_error_code": 0,
    "order_error_desc": null
}

The method for creating a new order request. After calling it, a new product will be issued. We distinguish 3 types of requirements:

The choice of these three types to implement depends on mutually agreed products. Therefore, it may not always be necessary to implement all types.

All requirement parameters described below are mandatory.

Request

Parameter Data type Description
type enum A request type that contains one of the values PIN, ACCOUNT or ACTIVATION
order_id string (max 50) Order ID. You choose this value yourself. Use only alphanumeric characters (underscores are possible). Each new order must have a unique ID.
product_id int The ID of the ordered product or its EAN. The value must match the ID/EAN of the available product. Available products can be obtained by the method /products or in the merchant's administration.
account_id int|null Required only for request type ACCOUNT. ID of topped-up account.
activation_id int|null Required only for request type ACTIVATION. ID of the topped-up account/activated voucher.
pos_id int (max 9 999 999) Your identification of the physical location (branch/cash desk, ...) from which the request is sent. Needed for reporting to some providers.
value int|null NULL if it is a fixed price product. If it is a top-up product, the parameter is required and the top-up amount is in hundredths of a currency is entered.
terminal_id int The ID of the terminal from which the method is called. You will be assigned a terminal ID during the implementation process.
retailer_id int Merchant ID. The value is constant for all your orders. Your Merchant ID will be assigned to you during the implementation process.
chit_card_taken bool|null Information on whether the end customer has taken a physical chitcard with him from the point of sale.

Response

The response is an object of type ResponseReceipt.

Query for one order

  /order/78912/moje_objednavka123
  /transaction/78912/1234567890

Response

{
    "error": null,
    "error_code": 0,
    "type": "PIN",
    "order_id": "moje_objednavka123",
    "transaction_id": 1234567890,
    "product_id": 246537,
    "vat": 0,
    "cost": {
        "currency": "CZK",
        "cost": 9850,
        "cost_vat": 0
    },
    "recommended_retail_price": {
        "CZK": 10000,
        "EUR": null
    },
    "terminal_id": 789120555,
    "retailer_id": 78912,
    "account_id": null,
    "activation_id": null,
    "pos_id": 1234,
    "value": null,
    "pin": null,
    "barcode": null,
    "serial_number": "1416965707",
    "ean": null,
    "valid_to": null,
    "text": "PIN = hotovost! \nPIN nikdy nesdělujte cizím osobám!\n\nPoužití: Vyberte si internetový obchod a výrobek, zvolte způsob platby paysafecard a zadejte PIN.\n\nV případě dotazů navštivte www.paysafecard.com/help. Tipy pro bezpečné platby na internetu naleznete na www.paysafecard.com/security.\n\nPaysafecard je forma platebního prostředku vydaná společností Paysafe Prepaid Services Ltd. Všeobecné obchodní podmínky naleznete na www.paysafecard.com.",
    "created_at": "2020-06-10T09:49:50+00:00",
    "changed_at": "2020-06-10T09:49:51+00:00",
    "status": "DELIVERED",
    "order_error_code": 0,
    "order_error_desc": null
}

Get information about a single order by the ID you assigned to it by calling the /order method.

Get information about a single order based on the transaction_id assigned to it by calling the /order method.

Sample request values for /order

Parameter Data type Description Example
retailer_id int Merchant ID. Your Merchant ID will be assigned to you during the implementation process. 78912
order_id string The order ID that you assigned to the order by creating an order using the method /order moje_objednavka123

Sample request values for /transaction

Parameter Data type Description Example
retailer_id int Merchant ID. Your Merchant ID will be assigned to you during the implementation process. 78912
transaction_id int (10 chars, does not start with zero) The transaction ID which was automatically assigned when the order was created by the method /order 1234567890

Response

The response is an object of type ResponseReceipt.

Query for more orders in the last days

/orders-list/78912/7

Response

{
    "error": null,
    "error_code": 0,
    "retailer_id": 78912,
    "date_start": "2020-06-03",
    "date_end": "2020-06-10",
    "days": 7,
    "orders_count": 6,
    "orders": [
        {
            "type": "PIN",
            "order_id": "2211863191",
            "transaction_id": 1234567890,
            "product_id": 640993,
            "vat": 21,
            "cost": {
                "currency": "CZK",
                "cost": 115000,
                "cost_vat": 24150
            },
            "recommended_retail_price": {
                "CZK": null,
                "EUR": null
            },
            "terminal_id": 789120444,
            "account_id": null,
            "activation_id": null,
            "value": null,
            "pin": "abcd-efgh-1234",
            "barcode": "QR",
            "serial_number": null,
            "ean": "8595149006324",
            "valid_to": null,
            "status": "DELIVERED"
        },
        { ... },
        {
            "type": "PIN",
            "order_id": "moje_objednavka123",
            "transaction_id": 9876543120,
            "product_id": 246537,
            "vat": 0,
            "cost": {
                "currency": "CZK",
                "cost": 9850,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "terminal_id": 789120555,
            "account_id": null,
            "activation_id": null,
            "value": null,
            "pin": null,
            "barcode": null,
            "serial_number": "1416965707",
            "ean": null,
            "valid_to": null,
            "status": "DELIVERED"
        }
    ]
}

The method allows you to get more orders in the last few days. Acquired orders are sorted from oldest to newest. The first parameter in the query is the merchant ID, the second parameter is definitely how many days in the past to search for orders, and the third parameter is the signature.

For full detail of the order, it is necessary to call a new query for a specific order according to its ID.

Sample request values

Parameter Data type Description Example
retailer_id int Merchant ID. Your Merchant ID will be assigned to you during the implementation process. 78912
last_days int Specifies how many full days in the past to search for orders (for example, if today is 08. 01. 2020 and we enter the value 7, orders from 01. 01. 2020 to 08. 01. 2020 inclusive will be searched). 7

Response

The response is an object of type ResponseReceiptsList.

Query for multiple orders in an interval

/orders-interval/78912/2020-01-01/2020-01-31

Response

{
    "error": null,
    "error_code": 0,
    "retailer_id": 78912,
    "date_start": "2020-01-01",
    "date_end": "2020-01-31",
    "days": 30,
    "orders_count": 2,
    "orders": [
        {
            "type": "PIN",
            "order_id": "5215889594",
            "transaction_id": 1234567890,
            "product_id": 246537,
            "vat": 0,
            "cost": {
                "currency": "CZK",
                "cost": 9900,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "terminal_id": 789120444,
            "account_id": null,
            "activation_id": null,
            "value": null,
            "pin": null,
            "barcode": null,
            "serial_number": "1416966337",
            "ean": null,
            "valid_to": null,
            "status": "CANCELLED"
        },
        {
            "type": "PIN",
            "order_id": "test1",
            "transaction_id": 8527413698,
            "product_id": 246537,
            "vat": 0,
            "cost": {
                "currency": "CZK",
                "cost": 9900,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "terminal_id": 789120151,
            "account_id": null,
            "activation_id": null,
            "value": null,
            "pin": null,
            "barcode": null,
            "serial_number": "1416966338",
            "ean": null,
            "valid_to": null,
            "status": "DELIVERED"
        }
    ]
}

The method allows you to get orders made in a certain time interval. Acquired orders are sorted from oldest to newest.

For full detail of the order, it is necessary to call a new query for a specific order according to its ID.

Sample request values

Parameter Data type Description Example
retailer_id int Merchant ID. Your Merchant ID will be assigned to you during the implementation process. 78912
date_start date Y-m-d 2020-01-01
date_end date Y-m-d 2020-01-31

Response

The response is an object of type ResponseReceiptsList.

Cancellations

/order/cancel

JSON Request

{
  "retailer_id": 78912,
  "order_id": "moje_dalsi_objednavka"
}

Response HTTP code 200

{
    "error": null,
    "error_code": 0,
    "type": "PIN",
    "order_id": "moje_dalsi_objednavka",
    "transaction_id": 1234567890,
    "product_id": 978147,
    "vat": 0,
    "cost": {
        "currency": "CZK",
        "cost": 9850,
        "cost_vat": 0
    },
    "recommended_retail_price": {
        "CZK": 10000,
        "EUR": null
    },
    "terminal_id": 789120555,
    "retailer_id": 78912,
    "account_id": null,
    "activation_id": null,
    "pos_id": 1234,
    "value": null,
    "pin": null,
    "barcode": null,
    "serial_number": "1416965710",
    "ean": null,
    "valid_to": null,
    "text": "PIN = hotovost! \nPIN nikdy nesdělujte cizím osobám!\n\nPoužití: Vyberte si internetový obchod a výrobek, zvolte způsob platby paysafecard a zadejte PIN.\n\nV případě dotazů navštivte www.paysafecard.com/help. Tipy pro bezpečné platby na internetu naleznete na www.paysafecard.com/security.\n\nPaysafecard je forma platebního prostředku vydaná společností Paysafe Prepaid Services Ltd. Všeobecné obchodní podmínky naleznete na www.paysafecard.com.",
    "created_at": "2020-06-10T10:35:37+00:00",
    "changed_at": "2020-06-10T10:35:43+00:00",
    "status": "CANCELLED",
    "order_error_code": 0,
    "order_error_desc": null
}

Response HTTP code 400

{
    "error": "Order id 'moje_dalsi_objednavka' is already cancelled",
    "error_code": 5
}

Method for order cancellation. If the order can be canceled, it returns an object of type ResponseReceipt. If it is not possible to cancel the order, it returns an error status. The error status is returned even if the order is already canceled.

All requirement parameters described below are mandatory.

Sample request values

Parameter Data type Description Example
retailer_id int Merchant ID. Your Merchant ID will be assigned to you during the implementation process. 78912
order_id string The ID of the order you wish to cancel. moje_dalsi_objednavka

Response

The response is an object of type ResponseReceipt.

Ping

/ping/78912

Response - OK

{
    "status": "ok",
    "ip": "127.0.0.1",
    "timestamp": "2020-06-19T13:40:37+00:00"
}

Response - ERROR

{
    "error": "Internal error",
    "error_code": 1
}

For purposes of testing whether an API is ready to accept requests. You can always call this method before the initial call to verify the functionality of the connection as well as the functionality of both systems. However, this is not a check on the availability of the product provider's system. Use the check method to do this.

Response

If a connection is established, the response includes key status with the value ok, your IP address and time stamp (UTC timezone +00:00 in RFC 3339 format). If the connection has not been established, one of the error states is returned.

Sample request values

Parameter Data type Description Example
retailer_id int Merchant ID. Merchant ID will be assigned to you during the implementation process. 78912

Check

/check/78912/978147

Response - OK

{
    "status": "ok",
    "ip": "127.0.0.1",
    "timestamp": "2020-06-19T13:40:37+00:00"
}

Response - ERROR

{
    "error": "Service provider error",
    "error_code": 9
}

A means of testing whether a provider's system is available and capable of releasing a new product. We recommend that you always call this method before the initial POST call to verify that the connection with us and the provider is working.

Response

If a connection is established, the response includes key status with the value ok, your IP address and time stamp (UTC timezone +00:00 in RFC 3339 format). If the connection has not been established, one of the error states is returned.

If an error is returned, we do not recommend calling the /order method on the product being queried. Please try calling later.

Sample request values

Parameter Data type Description Example
retailer_id int Merchant ID. Merchant ID will be assigned to you during the implementation process. 78912
product_id int The ID of the product that will be the subject of the order. 2001003

Available products

One product

 /products/78912/978147

All products

  /products/78912/ALL

Response

{
    "error": null,
    "error_code": 0,
    "products_count": 9,
    "products": [
        {
            "id": 978147,
            "name": "Paysafecard 100 Kč",
            "text": "PIN = hotovost! \nPIN nikdy nesdělujte cizím osobám!\n\nPoužití: Vyberte si internetový obchod a výrobek, zvolte způsob platby paysafecard a zadejte PIN.\n\nV případě dotazů navštivte www.paysafecard.com/help. Tipy pro bezpečné platby na internetu naleznete na www.paysafecard.com/security.\n\nPaysafecard je forma platebního prostředku vydaná společností Paysafe Prepaid Services Ltd. Všeobecné obchodní podmínky naleznete na www.paysafecard.com.",
            "image_url": "https://media.egit.cz/givery/loga/paysafecard.png",
            "vat": 0,
            "cost": {
                "currency": "CZK",
                "cost": 9850,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "status": "ENABLED",
            "can_be_cancelled": true,
            "is_top_up": false
        },
        { ... },
        {
            "id": 246537,
            "name": "PlayStation Plus 1 měsíc",
            "text": null,
            "image_url": null,
            "vat": 21,
            "cost": {
                "currency": "CZK",
                "cost": 16000,
                "cost_vat": 3360
            },
            "recommended_retail_price": {
                "CZK": 19000,
                "EUR": null
            },
            "status": "ENABLED",
            "can_be_cancelled": true,
            "is_top_up": false
        },
        {
            "id": 794765,
            "name": "Blizzard Battle.net Digital Code 20 EUR",
            "text": "Kód zadejte na stránce account.blizzard.com. Tím dojde k jeho aktivaci a okamžitému uplatnění.",
            "image_url": "https://media.egit.cz/givery/loga/blizzard.png",
            "vat": 0,
            "cost": {
                "currency": "EUR",
                "cost": 1900,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 51900,
                "EUR": 2000
            },
            "status": "ENABLED",
            "can_be_cancelled": false,
            "is_top_up": false
        }
    ]
}

The method returns an object of type ResponseProductsList containing the individual products that are available for sale to the merchant. Individual products are an object of type ResponseProduct. You can get information about one product or all products by parameterizing the API url.

Sample request values

Parameter Data type Description Example
retailer_id int Merchant ID. Your Merchant ID will be assigned to you during the implementation process. 78912
product_id int | string The ID of the product you want to get information about. The product ID can be obtained by querying all available products first. Enter a keyword ALL instead of a product ID. 2001003 | ALL

Response

The response is an object of type ResponseProductsList.

Response objects

ResponseReceipt

{
    "error": null,
    "error_code": 0,
    "type": "PIN",
    "order_id": "2211863191",
    "transaction_id": 1234567890,
    "product_id": 794765,
    "vat": 21,
    "cost": {
        "currency": "CZK",
        "cost": 115000,
        "cost_vat": 24150
    },
    "recommended_retail_price": {
        "CZK": null,
        "EUR": null
    },
    "terminal_id": 789120444,
    "retailer_id": 78912,
    "account_id": null,
    "activation_id": null,
    "pos_id": 1234,
    "value": null,
    "pin": "abcd-efgh-1234",
    "barcode": "QR",
    "serial_number": null,
    "ean": "8595149006324",
    "valid_to": null,
    "text": null,
    "created_at": "2020-06-04T09:54:55+00:00",
    "changed_at": "2020-06-05T00:18:48+00:00",
    "status": "DELIVERED",
    "order_error_code": 0,
    "order_error_desc": null
}

The most common type of answer. This object is returned both when creating a new order, its cancellation, and when querying the detail of one order.

Parameter Data type Value format Description
error string|null Description of if an error occurred during the request.
error_code int Zero or a number greater than zero if an error occurred during the request.
type enum PIN | ACCOUNT | ACTIVATION A request type.
order_id string The order ID that you specify when creating a new order.
transaction_id int (10 chars, does not start with zero) The transaction ID is a unique number that is assigned to the order when it is created.
product_id int ID of the ordered product. Product detail can be obtained by calling the method /products.
vat int VAT rate as a percentage of the invoiced amount.
cost object Cost Object type Cost.
recommended_retail_price object RecommandedRetailPrice Object type RecommandedRetailPrice.
terminal_id int The ID of the terminal from which the request was sent.
retailer_id int Your Merchant ID that will be assigned to you during the implementation process.
account_id int|null ID of topped-up account. Filled for request type ACCOUNT only.
activation_id int|null ID of the topped-up account/activated voucher. Filled for request type ACTIVATION only.
pos_id int Identification of the physical location (branch/cash desk, ...) that you specify when creating a new order.
value int|null NULL if it is a fixed price product. If it is a top-up product, the top-up amount in hundredths of a currency is entered.
pin string|null NULL value (if it is not possible to retrieve the value again - eg for Paysafecard) or PIN.
barcode enum Barcode Optional representation of the value pin. Contains one of the values described in Barcode.
serial_number string|null NULL (unless the value is provided by the vendor) or serial number.
ean string|null NULL (if the value is not known) or EAN of the product.
valid_to date|null Y-m-d NULL (if the vendor does not indicate the expiration date) or the expiration date of the PIN.
text string|null Product description/application instructions. Plain text. New line separated by a character \n.
created_at dateTime RFC 3339 Order creation timestamp. The time zone is set to UTC timezone +00:00.
changed_at dateTime RFC 3339 Time stamp when the status of the order was changed. The time zone is set to UTC timezone +00:00.
status enum OrderStatus Order status. It contains one of the values ​​described in OrderStatus.
order_error_code int Zero or error number if the order was not completed successfully.
order_error_desc string|null Error description if the order was not completed successfully.

By default, the customer is given the data pin, serial_number, valid_to, text, transaction_id and the date and time of the sale (approximately created_at).

ResponseReceiptSimplified

{
    "type": "PIN",
    "order_id": "2211863191",
    "transaction_id": 1234567890,
    "product_id": 794765,
    "vat": 21,
    "cost": {
        "currency": "CZK",
        "cost": 115000,
        "cost_vat": 24150
    },
    "recommended_retail_price": {
        "CZK": null,
        "EUR": null
    },
    "terminal_id": 789120444,
    "account_id": null,
    "activation_id": null,
    "value": null,
    "pin": "abcd-efgh-1234",
    "barcode": null,
    "serial_number": null,
    "ean": "8595149006324",
    "valid_to": null,
    "status": "DELIVERED"
}

This is a simplified variant of the object ResponseReceipt. This object is missing some less important information. The object is inserted as the value of the parameter orders in response object ResponseReceiptsList when querying multiple orders.

Parameter Data type Value format Description
type enum PIN | ACCOUNT | ACTIVATION A request type.
order_id string The order ID that you specify when creating a new order.
transaction_id int (10 chars, does not start with zero) The transaction ID is a unique number that is assigned to the order when it is created.
product_id int ID of the ordered product. Product detail can be obtained by calling the method /products.
vat int VAT rate as a percentage of the invoiced amount.
cost object Cost Object type Cost.
recommended_retail_price object RecommandedRetailPrice Object type RecommandedRetailPrice.
terminal_id int The ID of the terminal from which the request was sent.
account_id int|null ID of topped-up account. Filled for request type ACCOUNT only.
activation_id int|null ID of the topped-up account/activated voucher. Filled for request type ACTIVATION only.
value int|null NULL if it is a fixed price product. If it is a top-up product, the top-up amount in hundredths of a currency is entered.
pin string|null NULL value (if it is not possible to retrieve the value again - eg for Paysafecard) or PIN.
serial_number string|null NULL (unless the value is provided by the vendor) or serial number.
ean string|null NULL (if the value is not known) or EAN of the product.
valid_to date|null Y-m-d NULL (if the vendor does not indicate the expiration date) or the expiration date of the PIN.
status enum OrderStatus Order status. It contains one of the values ​​described in OrderStatus.

 ResponseReceiptsList

{
    "error": null,
    "error_code": 0,
    "retailer_id": 78912,
    "date_start": "2020-06-03",
    "date_end": "2020-06-10",
    "days": 7,
    "orders_count": 6,
    "orders": [
        {
            "type": "PIN",
            "order_id": "2211863191",
            "transaction_id": 1234567890,
            "product_id": 640993,
            "vat": 21,
            "cost": {
                "currency": "CZK",
                "cost": 115000,
                "cost_vat": 24150
            },
            "recommended_retail_price": {
                "CZK": null,
                "EUR": null
            },
            "terminal_id": 789120444,
            "account_id": null,
            "activation_id": null,
            "value": null,
            "pin": "abcd-efgh-1234",
            "barcode": "QR",
            "serial_number": null,
            "ean": "8595149006324",
            "valid_to": null,
            "status": "DELIVERED"
        },
        { ... },
        {
            "type": "PIN",
            "order_id": "moje_objednavka123",
            "transaction_id": 9876543120,
            "product_id": 246537,
            "vat": 0,
            "cost": {
                "currency": "CZK",
                "cost": 9850,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "terminal_id": 789120555,
            "account_id": null,
            "activation_id": null,
            "value": null,
            "pin": null,
            "barcode": null,
            "serial_number": "1416965707",
            "ean": null,
            "valid_to": null,
            "status": "DELIVERED"
        }
    ]
}

The object is returned when querying multiple orders. It contains all orders from a certain period according to the passed parameters. It can be used to consolidate with your system.

Parameter Data type Value format Description
error string|null Description of if an error occurred during the request.
error_code int Zero or a number greater than zero if an error occurred during the request.
retailer_id int Your Merchant ID that will be assigned to you during the implementation process.
date_start date Y-m-d The beginning of the time interval for which orders are displayed.
date_end date Y-m-d The end of the time interval for which orders are displayed.
days int The number of days in the past for which you want to list completed orders. The method selects orders that have a creation date >= (today - n).
orders_count int Number of orders found.
orders pole ResponseReceiptSimplified An array item is an object of type ResponseReceiptSimplified. If no order is found, the field is empty. The items are sorted by creation date from oldest to newest.

 ResponseProduct

{
    "id": 794765,
    "name": "PlayStation Plus 1 měsíc",
    "text": null,
    "image_url": null,
    "ean": "8595149006324",
    "vat": 21,
    "cost": {
        "currency": "CZK",
        "cost": 16000,
        "cost_vat": 3360
    },
    "recommended_retail_price": {
        "CZK": 19000,
        "EUR": null
    },
    "status": "ENABLED",
    "can_be_cancelled": true,
    "is_top_up": false
}

Various product information can be read from the object. It can be used to automate the listing of products into your system and regularly update purchase prices. The object is inserted into the parameter products in object ResponseProductsList, which is the answer when querying all products of the merchant.

Parameter Data type Value format Description
id int The product ID, which is inserted as a value of parameter product_id when creating a new order using the method /order.
name string Full name of the product.
text string|null Product description/application instructions. Plain text. New line separated by a character \n.
image_url string|null URL address - link to PNG logo/image with transparent background.
ean string|null NULL (if the value is not known) or EAN of the product.
vat int VAT rate as a percentage of the invoiced amount.
cost object Cost Object type Cost.
recommended_retail_price object RecommandedRetailPrice Object type RecommandedRetailPrice.
status enum ProductStatus Product availability. It contains one of the values ​​described in ProductStatus.
can_be_cancelled boolean Product cancellation after ordering.
is_top_up boolean Contains false for product with fixed price. For top-up product contains true. When creating new order (POST request) the parameter value is required for top-up product.

 ResponseProductsList

{
    "error": null,
    "error_code": 0,
    "products_count": 9,
    "products": [
        {
            "id": 246537,
            "name": "Paysafecard 100 Kč",
            "text": "PIN = hotovost! \nPIN nikdy nesdělujte cizím osobám!\n\nPoužití: Vyberte si internetový obchod a výrobek, zvolte způsob platby paysafecard a zadejte PIN.\n\nV případě dotazů navštivte www.paysafecard.com/help. Tipy pro bezpečné platby na internetu naleznete na www.paysafecard.com/security.\n\nPaysafecard je forma platebního prostředku vydaná společností Paysafe Prepaid Services Ltd. Všeobecné obchodní podmínky naleznete na www.paysafecard.com.",
            "image_url": "https://media.egit.cz/givery/loga/paysafecard.png",
            "ean": "8595180006324",
            "vat": 0,
            "cost": {
                "currency": "CZK",
                "cost": 9850,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "status": "ENABLED",
            "can_be_cancelled": true,
            "is_top_up": false
        },
        { ... },
        {
            "id": 640993,
            "name": "PlayStation Plus 1 měsíc",
            "text": null,
            "image_url": null,
            "ean": "8595149006324",
            "vat": 21,
            "cost": {
                "currency": "CZK",
                "cost": 16000,
                "cost_vat": 3360
            },
            "recommended_retail_price": {
                "CZK": 19000,
                "EUR": null
            },
            "status": "ENABLED",
            "can_be_cancelled": true,
            "is_top_up": false
        },
        {
            "id": 978147,
            "name": "Blizzard Battle.net Digital Code 20 EUR",
            "text": "Kód zadejte na stránce account.blizzard.com. Tím dojde k jeho aktivaci a okamžitému uplatnění.",
            "image_url": "https://media.egit.cz/givery/loga/blizzard.png",
            "ean": null,
            "vat": 0,
            "cost": {
                "currency": "EUR",
                "cost": 1900,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 51900,
                "EUR": 2000
            },
            "status": "ENABLED",
            "can_be_cancelled": false,
            "is_top_up": false
        }
    ]
}

The object lists the products of the merchant, incl. their sales prices, full names, etc. This object is returned when calling the method to find out all the merchant's products.

Parameter Data type Value format Description
error string|null Description of if an error occurred during the request.
error_code int Zero or a number greater than zero if an error occurred during the request.
products_count int Number of products found.
products array ResponseProduct An array item is an object of type ResponseProduct. If no product is found, the array is empty.

Cost

"cost": {
    "currency": "CZK",
    "cost": 9900,
    "cost_vat": 0
}

The object contains information about the purchase price of the sold product. Some values are filled in for top-up products only after topping-up.

Parameter Data type Value format Description
currency string ISO 4217 Linguistic designation of the currency according to ISO 4217 (CZK, EUR), in which the order product will be invoiced.
cost int|null cena v setinách měny Price without VAT, which will be invoiced. NULL for top-up product for which the top-up amount is not yet known.
cost_vat int|null cena v setinách měny Calculated VAT that will be invoiced. NULL for top-up product for which the top-up amount is not yet known.

RecommandedRetailPrice

Recommended retail prices for both currencies are filled

"recommended_retail_price": {
    "CZK": 51900,
    "EUR": 2000
}

Recommended retail price for one currency only

"recommended_retail_price": {
    "CZK": 51900,
    "EUR": null
}

The object contains recommended retail prices of the sold product in currencies CZK i EUR. If the product has no recommended retail price, a null is entered instead of the number.

The object may acquire new values in the future, especially for products that will not be regionally limited. However, all products will always have the same keys.

Parameter Data type Value format Description
CZK int|null price with VAT in hundredths of a currency Recommended retail price in CZK.
EUR int|null price with VAT in hundredths of a currency Recommended retail price in EUR.

Barcode

Optional representation of the pin value by a QR/barcode. It can take the values QR, CODE128, CODE11, etc. In other cases, the value NULL is returned. It will be specified during implementation depending on the individual products.

The barcode parameter may acquire new values in the future according to the requirements of new publishers.

OrderStatus

Each order has one of the following statuses:

Hodnota Popis
CREATED Initialization status of the order. It then goes into one of the following states.
DELIVERED Status indicating successful delivery of the product. Products in this state are included in the invoicing and are operated in the mechanisms controlling the order limits of the terminals and the merchant.
REJECTED The order was not completed successfully. More information is displayed when obtaining a specific order in parameter order_error_code and order_error_desc.
CANCELLED The order was canceled using the method /order/cancel

ProductStatus

If any product is no longer available, its availability status will change.

Value Description
ENABLED The product is available for sale.
DISABLED The product is not available for sale.

Return HTTP codes

The following HTTP status codes are used in responses to our API calls:

Code Description
200 Successful call.
400 Failed request.
403 Authorization failed.
404 Non-existent source / method / endpoint.
500 The call ended in error.

Error states

Error states are returned with an error number error_code an error description error. The HTTP code differs depending on the type of error. Error descriptions are not intended for the end customer. Contact us for a more detailed description of the error in unclear individual cases.

Order not found

{
    "error": "Order id 504187 was not found",
    "error_code": 4
}

Order of a non-exist product

{
    "error": "Invalid parameters supplied. Check retailer_id, terminal_id and product_id.",
    "error_code": 3
}

The order cannot be canceled again

{
    "error": "Order id '5599715725' is already cancelled",
    "error_code": 5
}
Error code HTTP code Value Description
1 500 Internal error Internal application error.
2 400
Invalid request (*)
Product ID '{product_id}' is not valid
Error validating request.
3 400
Invalid request (*)
Product is no longer available for orders
API has to use virtual terminal
Web app cannot use virtual terminal
Error validating new order request.
4 404 Order id 'order_id' was not found Source not found.
5 400 Invalid request (*) The resource already exists or the method cannot be applied to the resource.
6 403
Invalid request (*)
Not authorized (*)
Retailer is not allowed to process orders.
Unauthorized access. Merchant by ID not found, signature is incorrect, IP address is not allowed, ...
7 403
Terminal weekly limit has been exceeded
Terminal daily limit has been exceeded
Retailer postpaid limit has been exceeded
Retailer prepaid limit has been exceeded
Merchant / terminal orders limit exceeded.
8 500 Service provider unavailable Error on the part of the provider.
9 500
Service provider error
Order of this product cannot be cancelled.
Error on the part of the provider. The error is displayed if the product can no longer be canceled.
10 404 Service endpoint not found Endpoint or method not found.

(*) content can be in a general format on production instance for security reasons, but in the test environment is always more specific.

Consolidation

Lost responses

Implementing a process that captures and works with unfinished orders and lost responses is important to maintain the mutual state integrity of orders in our and your systems and to ensure the expected billing.

The lost request or response can occur for many reasons, but especially for problems at the network connection level. These circumstances can lead to inconsistencies of states, where in some cases the actual (final) state may not be reflected in your application. If such a situation occurs, we recommend repeating the POST call with the same order_id in the first unsuccessful attempt, or calling the GET method directly on the established order to obtain a PIN.

Lost requests, or unfinished calls due to technical problems on the part of the product publisher, can be prevented by calling the ping , resp. check before each request.

Reconsolidation process

We recommend performing the reconsolidation process on a minimum basis on a daily basis in order to maintain the mutual state integrity of orders in both systems in the long term. To find out the status of orders placed in the past days, use the Query for multiple orders method. In case of any inconsistencies found, call Order Cancellation (if possible) or assign the lost PIN to the relevant order.

If the PIN code can no longer be assigned to the order and the voucher issuer does not allow cancellation, save the entire request, including the detailed log, and contact us to resolve the situation individually. It is always necessary to carefully log whether the PIN was handed over to the customer or not.

Properties of individual products

Provider PIN re-obtain Product cancellation The period for which
products can be canceled
paysafecard no yes 20 days
Blizzard yes yes unlimited
Steam yes yes unlimited
Microsoft yes no -
Sony yes no -
Amazon yes yes 15 minutes
Wargaming yes yes unlimited
Adidas yes yes only on the day of ordering
Zalando yes yes neomezeno
Netflix yes yes only on the day of ordering
Twitch yes yes only on the day of ordering
Ostatní yes no -