PayKeeper

https://docs.paykeeper.ru
Admin
PayKeeper is a payment system offering internet acquiring, online cash registers, mobile terminals,...
Tokens:259,903
Snippets:1,331
Trust Score:9.9
Update:9 months ago
Show doc for...
Tokens:
Raw
### PHP Example: Get Payment Systems List with HTTP Basic Auth

Source: https://docs.paykeeper.ru/dokumentatsiya-json-api/token-bezopasnosti

A PHP script demonstrating how to make a GET request to the /info/systems/list/ endpoint using cURL and HTTP Basic Authentication. It requires the 'curl' extension to be enabled. The output is a JSON-decoded array of payment systems.

```php
<?php
$server_paykeeper="demo.paykeeper.ru"; // укажите адрес вашего сервера PayKeeper
$uri="/info/systems/list/"; // Запрос 1.1 JSON API
$user="json"; // Логин в личном кабинете PayKeeper
$password="json"; // Соответствующий логину пароль

$base64=base64_encode("$user:$password"); // Формируем base64 хэш

$curl=curl_init(); // curl должен быть установлен
$headers=Array();
array_push($headers,'Authorization: Basic '.$base64); // Подготавливаем заголовок для авторизации

curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_URL,$server_paykeeper.$uri);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'GET');
curl_setopt($curl,CURLOPT_HTTPHEADER,$headers);
curl_setopt($curl,CURLOPT_HEADER,false);

$out=curl_exec($curl); // Инициируем запрос к API
print_r(json_decode($out)); // Декодируем ответ и выводим
?>
```

--------------------------------

### Request Payments by Date Range (HTTP)

Source: https://docs.paykeeper.ru/dokumentatsiya-json-api/platezhi

This example demonstrates an HTTP GET request to retrieve payments within a date range. It includes parameters for filtering by start and end dates, payment system IDs, and payment statuses. The response will be a JSON array of payment objects.

```HTTP
GET /info/payments/bydate/?limit=100&from=0&start=2016-04-14&end=2017-03-14&status[]=success&status[]=canceled&status[]=failed&payment_system_id[]=9&payment_system_id[]=1
```

--------------------------------

### PayKeeper Installation Script

Source: https://docs.paykeeper.ru/cms/umi-cms/umi-cms-23

The `paykeeper_install.php` script is used to perform the initial setup and integration of the PayKeeper module within the UMI CMS. Accessing this file via a web browser after placing it in the CMS root directory executes the necessary installation procedures. It's crucial to remove this file after successful execution to maintain security.

```php
<?php
// This is a placeholder for the actual content of paykeeper_install.php
// The actual script would contain PHP code to perform installation tasks.
// Example:
// require_once('classes/PayKeeperGateway.php');
// PayKeeperGateway::install();
// echo 'Готово!';
?>
```

--------------------------------

### Receipt Object Example

Source: https://docs.paykeeper.ru/dokumentatsiya-json-api/rabota-s-chekami-54-fz

Provides an example of a receipt object as returned by the API, including detailed payment and fiscalization information.

```APIDOC
## Receipt Object Example

### Description
This is an example of a receipt object returned by the Paykeeper API, showcasing various fields related to the payment, status, and fiscalization details.

### Response Example
```json
{
  "id": "4201",
  "payment_id": "2098",
  "type": "sale",
  "is_post_sale": "1",
  "is_correction": "1",
  "refund_id": null,
  "status": "success",
  "contact": "client@mail.ru",
  "sum_cashless": "0.00",
  "sum_cash": "0.00",
  "sum_advance": "15529.10",
  "sum_credit": "0.00",
  "sum_counter_payment": "0.00",
  "cart": "[{"name":"TEST 3","quantity":1,"price":15529.10,"sum":15529.10,"tax":"none","payment_type":"full"}]",
  "receipt_properties": "null",
  "fpd": "2020473855",
  "fnd": "8930",
  "fn": "9999078900001341",
  "ts": "20190621T1638",
  "rnkkt": "0000000400054952",
  "shift_number": "7123",
  "receipt_number": "6162",
  "obtain_datetime": "2019-05-11 09:12:22",
  "request_datetime": "2019-05-11 09:12:01",
  "fop_receipt_key": "VhamK7kl",
  "fop_uuid": "6ee-cs-130",
  "fop_url": "t=20190511T0912&amp;s=15529.10&amp;fn=9999078900001341&amp;i=8930&amp;fp=2020473855&amp;n=1",
  "custom_params": "{\"correction_type\":\"self\",\"correction_operation_date\":\"2022-04-11\"}",
  "error": null
}
```
```

--------------------------------

### PHP Example: Get Token and Add Email to Report List

Source: https://docs.paykeeper.ru/dokumentatsiya-json-api/token-bezopasnosti

This PHP script demonstrates how to obtain a security token using Basic HTTP authentication and then use that token to add an email address to the user's report subscription list via a POST request. It utilizes the cURL library for making HTTP requests.

```php
<?php
$user="user"; // Логин в личном кабинете PayKeeper
$password="pass"; // Соответствующий логину пароль
$base64=base64_encode("$user:$password"); // Формируем base64 хэш
$headers=Array();
array_push($headers,'Content-Type: application/x-www-form-urlencoded');
array_push($headers,'Authorization: Basic '.$base64); // Подготавливаем заголовок для авторизации
$server_paykeeper="your.server.paykeeper.ru"; // укажите адрес вашего сервера PayKeeper
// адрес your.server.paykeeper.ru - пример!

// Готовим первый запрос на получение токена
$uri="/info/settings/token/"; // Запрос на получение токена
$curl=curl_init(); // curl должен быть установлен
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_URL,$server_paykeeper.$uri);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'GET');
curl_setopt($curl,CURLOPT_HTTPHEADER,$headers);
curl_setopt($curl,CURLOPT_HEADER,false);
$out=curl_exec($curl); // Инициируем запрос к API
$php_array=json_decode($out,true); // Сохраняем результат в массив
if (isset($php_array['token'])) $token=$php_array['token']; else die(); // Сохраняем полученный токен в $token

// Готовим к выполнению запрос на добавление email в список рассылки
$email="example@paykeeper.ru"; // Почта для добавления
$uri="/change/organization/addreportemail/"; // Запрос 5.3 JSON API
$curl=curl_init(); // curl должен быть установлен
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_URL,$server_paykeeper.$uri);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($curl,CURLOPT_HTTPHEADER,$headers);
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_POSTFIELDS,"token=$token&email=$email");
$out=curl_exec($curl); // Инициируем запрос к API
print_r(json_decode($out)); // Выводим результат запроса
?>

```

--------------------------------

### GetCourse Process Setup for PayKeeper Integration

Source: https://docs.paykeeper.ru/cms/getcourse

This section outlines the steps to create and configure a business process in GetCourse to facilitate data transfer to PayKeeper via API.

```APIDOC
## GetCourse Process Setup for PayKeeper Integration

### Description
This guide details the steps to create and configure a business process in GetCourse to enable data transfer to PayKeeper via API, allowing for order status updates after payment.

### Method
N/A (Configuration Steps)

### Endpoint
N/A (Configuration Steps within GetCourse)

### Parameters
N/A (Configuration Steps within GetCourse)

### Request Example
N/A (Configuration Steps within GetCourse)

### Response
N/A (Configuration Steps within GetCourse)

## Steps:
1. **Authorize** in your GetCourse account.
2. Navigate to **CRM -> Processes**.
3. Click **Create Process**.
4. **Fill in Process Details**:
   - **Name**: e.g., "Transfer data to PayKeeper"
   - **Description**: Optional. e.g., "To transfer order information to PayKeeper before payment."
   - **Object Type**: Select "Orders".
   - **Add performers and supervisors**: Optional, can leave unchecked.
   - **Process Template**: Select "- without template -".
5. Click **Create**.
6. On the process editing page, go to the **Process** tab.
7. Add the following blocks sequentially: **Operation** block, then two **Process Completion** blocks.
   - **Operation Block**:
     - Select "Order" and "Call URL".
     - Click **Save**.
     - In the next window, set **Method** to "POST".
     - In the **URL** field, paste the provided GetCourse webhook URL, including order and payment details as parameters:
       `https://getcourse.paykeeper.ru/api/pay/webhook/xxxx?orderid={object.number}&dealid={object.id}&client_email={object.user.email}&client_phone={object.user.phone}&clientid={object.user.name}&positions={object.positions}&offers={object.offers}&cost={object.cost_money_value}&left_cost={object.left_cost_money}&payed_cost={object.payed_money}&status={object.status}&payment_link={object.payment_link}`
       (Replace 'xxxx' with your specific value).
   - **Process Completion Blocks**:
     - Add one with the option "Positive".
     - Add another with the option "Negative".
8. **Connect the blocks** using the drag-and-drop interface.
9. Navigate to **Site -> Pages**.
10. Go to the page with the form you want to link to the process. If it doesn't exist, create one and add a form block.
11. In the form settings, configure two actions sequentially:
    - **Create application/order**:
      - Set "Payment page opening location" to "Transition to payment page in a new window".
    - **Run process for order**:
      - Select the process created in step 5.
      - Check "Run again if a task for this order has already been launched".
12. Click **Save and close**.
13. **Publish changes**.
```

--------------------------------

### Get Payment Parameters by ID using cURL

Source: https://docs.paykeeper.ru/dokumentatsiya-json-api/platezhi

Retrieves additional, optional parameters for a payment identified by its ID in PayKeeper. This example shows a cURL GET request. The response is an array of parameter objects, each with an ID, payment ID, field name, and value.

```bash
curl "https://paykeeper.ru/api/info/params/byid/?id=11186"
```

--------------------------------

### Forming a Shopping Cart (PHP)

Source: https://docs.paykeeper.ru/onlain-kassa-54-fz/tovary-v-cheke-54-fz-full

This example demonstrates how to format a shopping cart in PHP using JSON, suitable for passing to the PayKeeper API.

```APIDOC
## POST /api/cart

### Description
Formats a shopping cart with items, prices, quantities, and tax information for use with the PayKeeper API.

### Method
POST

### Endpoint
/api/cart

### Parameters
#### Request Body
- **cart** (string) - Required - A JSON-encoded string representing the shopping cart.
  - **name** (string) - Required - Name of the item.
  - **price** (float) - Required - Price of the item.
  - **quantity** (integer) - Required - Quantity of the item.
  - **sum** (float) - Required - Total sum for the item (price * quantity).
  - **tax** (string) - Optional - Tax rate (e.g., 'vat20', 'vat10', 'none').
  - **item_type** (string) - Optional - Type of item (e.g., 'goods').
  - **payment_type** (string) - Optional - Payment type (e.g., 'prepay').

### Request Example
```php
"cart" => json_encode( array (
    array (
        "name" => 'Стол обеденный 2x3',
        "price" => 10.01,
        "quantity" => 1,
        "sum" => 10.01,
        "tax" => 'vat20',
        "item_type" => 'goods',
        "payment_type" => 'prepay'
    ),
    array (
        "name" => 'Книга о вкусной и здоровой пище',
        "price" => 1.01,
        "quantity" => 3,
        "sum" => 3.03,
        "tax" => 'vat10'
    )
) )
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of cart creation.

#### Response Example
```json
{
  "message": "Cart created successfully"
}
```
```

--------------------------------

### Get Payment Options by ID using cURL

Source: https://docs.paykeeper.ru/dokumentatsiya-json-api/platezhi

Retrieves additional information about payment options using their ID in PayKeeper. This example demonstrates a cURL GET request. The response format can vary based on the payment system and status, and should be used for supplementary information.

```bash
curl "https://paykeeper.ru/api/info/options/byid/?id=11186"
```

--------------------------------

### PHP: Verify Payment Details and Acknowledge Success

Source: https://docs.paykeeper.ru/metody-integratsii/priyom-post-opoveshhenij

This comprehensive PHP example shows how to receive payment notification data via POST requests. It verifies the security key using an MD5 hash of the received parameters and a secret seed. If the key matches, it includes placeholder comments for order processing logic and then sends the success acknowledgment back to Paykeeper.

```php
<?php $secret_seed = "verysecretseed"; $id = $_POST['id']; $sum = $_POST['sum']; $clientid = $_POST['clientid']; $orderid = $_POST['orderid']; $key = $_POST['key']; if ($key != md5 ($id.number_format($sum, 2, ".", "") .$clientid.$orderid.$secret_seed)) { echo "Error! Hash mismatch"; exit; } # Рекомендуем проверять, существует ли заказ $orderid, # принадлежит ли он пользователю $clientid, # совпадает ли его сумма с переданной $sum ... # Заказ $orderid можно считать оплаченным, # нужно отметить, что он оплачен ... echo "OK ".md5($id.$secret_seed); ?>
```

--------------------------------

### Get Errors by Date (GET /info/errors/bydate/)

Source: https://docs.paykeeper.ru/dokumentatsiya-json-api/statistika

Retrieves the sum of accepted payments across all payment systems for a specified date range. Requires 'start' and 'end' date parameters in YYYY-MM-DD format. The response format is similar to the /info/errors/total/ endpoint.

```http
GET /info/errors/bydate/?start=2014-04-12&end=2014-05-12
```

```json
{ "total": "759", "totalWithGroup": [ { "error_code": "70", "total": "240", "user_description": "Сетевая ошибка при отправке запроса." }, ... ] }
```

--------------------------------

### POST /change/invoice/preview/

Source: https://docs.paykeeper.ru/vozmozhnosti-i-primery-ispolzovaniya/primer-koda-dlya-yazyka-ruby

Creates a payment invoice and returns a payment link. Requires authentication and specific order details.

```APIDOC
## POST /change/invoice/preview/

### Description
This endpoint creates a payment invoice with the provided details and returns a payment link for the customer to complete the transaction. It supports passing detailed order information, including items and delivery, and requires authentication.

### Method
POST

### Endpoint
`/change/invoice/preview/`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **token** (string) - Required - Authentication token obtained from the `/info/settings/token/` endpoint.
- **pay_amount** (number) - Required - The total amount to be paid.
- **orderid** (string) - Required - The unique identifier for the order.
- **service_name** (string) - Required - A string containing service details, typically including a JSON representation of the items and their details, prefixed with ';PKC|' and suffixed with '|'. Example: `;PKC|["name":"Item Name","price":10.00,"quantity":1,"sum":10.00,"tax":"none","item_type":"goods"}]|`
- **client_email** (string) - Optional - The email address of the client.
- **client_phone** (string) - Optional - The phone number of the client.

### Request Example
```json
{
  "token": "your_auth_token",
  "pay_amount": 3300.00,
  "orderid": "9999",
  "service_name": ";PKC|[{\"name\":\"Тортилья, 20 см, 756 г\",\"price\":381.00,\"quantity\":5,\"sum\":1905.00,\"tax\":\"none\",\"item_type\":\"goods\"},{\"name\":\"Доставка\",\"price\":300,\"quantity\":1,\"sum\":300,\"tax\":\"none\",\"item_type\":\"service\"}]|",
  "client_email": "",
  "client_phone": ""
}
```

### Response
#### Success Response (200)
- **invoice_id** (string) - The unique identifier for the created invoice.
- **link** (string) - The URL to the payment page for the created invoice.

#### Response Example
```json
{
  "invoice_id": "123456789",
  "link": "https://your_paykeeper_server.ru/bill/123456789/"
}
```

#### Error Response
- **error** (string) - A message describing the error if the invoice creation fails.

#### Error Example
```json
{
  "error": "Invalid token provided."
}
```
```

--------------------------------

### Get Receipt Counts by Date Range (GET)

Source: https://docs.paykeeper.ru/dokumentatsiya-json-api/rabota-s-chekami-54-fz

Retrieves the total number of receipts within a specified date range, categorized by status, type, and payment method. Requires 'start' and 'end' dates in YYYY-MM-DD format. Returns a JSON object with counts for each category and a total count.

```HTTP
GET /info/receipts/bydatecount/?start=2020-10-18&end=2021-10-18
```

--------------------------------

### Get Total Balance of All Payment Systems (GET /info/systems/allsum/)

Source: https://docs.paykeeper.ru/dokumentatsiya-json-api/statistika

Retrieves the aggregated balance across all payment systems for a specified period. It returns a single sum without detailing individual system balances. Requires 'start' and 'end' date parameters in YYYY-MM-DD format.

```http
GET /info/systems/allsum/?start=2016-04-12&end=2016-05-12
```

```json
[ { "success":"10932.00", "account":"10932.00", "stuck":"0.00" } ]
```

--------------------------------

### Creating an Invoice with Shopping Cart (PHP)

Source: https://docs.paykeeper.ru/onlain-kassa-54-fz/tovary-v-cheke-54-fz-full

This example shows how to create an invoice using the PayKeeper JSON API, including passing a shopping cart for 54-FZ compliance. It involves obtaining a token and then submitting payment details.

```APIDOC
## POST /change/invoice/preview

### Description
Creates a payment invoice using the PayKeeper API. This endpoint supports passing a detailed shopping cart for generating a fiscal receipt in compliance with 54-FZ. It requires authentication and a token obtained separately.

### Method
POST

### Endpoint
`http://<your-server.paykeeper.ru>/change/invoice/preview`

### Parameters
#### Request Body
- **pay_amount** (float) - Required - The total amount to be paid.
- **clientid** (string) - Optional - Client's identifier or name.
- **orderid** (string) - Optional - Your internal order ID.
- **client_email** (string) - Optional - Client's email address for receipt.
- **service_name** (string) - Required - Contains the shopping cart data, formatted as `;PKC|' + json_encode(cart_array) + '|`. The `cart_array` should follow the structure defined in the 'Forming a Shopping Cart' example.
- **client_phone** (string) - Optional - Client's phone number.
- **token** (string) - Required - Authentication token obtained from the `/info/settings/token` endpoint.

### Request Example
```php
<?php
// Authentication details
$user = "user";
$password = "password";
$server = "example.server.paykeeper.ru";

// Payment data including the service_name with cart details
$payment_data = array (
    "pay_amount" => 7.50,
    "clientid" => "Иванов Иван Иванович",
    "orderid" => "Заказ № 10",
    "client_email" => "test@example.com",
    // Cart data for 54-FZ compliance
    "service_name" => ";PKC|".json_encode( array (
        array (
            "name" => 'Стол обеденный 2x3',
            "price" => 1.50,
            "quantity" => 1,
            "sum" => 1.50,
            "tax" => 'none',
        ),
        array (
            "name" => 'Книга о вкусной и здоровой пище',
            "price" => 2,
            "quantity" => 3,
            "sum" => 6,
            "tax" => 'none',
        )
    ))."|",
    "client_phone" => "8 (910) 123-45-67"
);

// --- Step 1: Get Authentication Token ---
$auth_header = array (
    'Authorization: Basic '.base64_encode("$user:$password")
);
$context = stream_context_create(array (
    'http' => array (
        'header' => $auth_header
    )
));
$result = json_decode(file_get_contents("http://$server/info/settings/token", FALSE, $context), TRUE);
$token = $result['token'];

// --- Step 2: Create Invoice ---
$request = array_merge($payment_data, array ('token'=>$token));
$request_string = http_build_query($request);
$request_headers = array_merge($auth_header, array("Content-type: application/x-www-form-urlencoded"));
$context = stream_context_create(array (
    'http' => array (
        'method' => 'POST',
        'header' => $request_headers,
        'content' => $request_string
    )
));
$result = json_decode(file_get_contents("http://$server/change/invoice/preview", FALSE, $context), TRUE);
$invoice_id = $result['invoice_id'];

// Direct payment link
$link = "http://$server/bill/$invoice_id/";
echo $link;
?>
```

### Response
#### Success Response (200)
- **invoice_id** (string) - The unique identifier for the created invoice.

#### Response Example
```json
{
  "invoice_id": "123456789"
}
```
```

--------------------------------

### Get Payment Parameters by ID using JavaScript

Source: https://docs.paykeeper.ru/dokumentatsiya-json-api/platezhi

Fetches additional payment parameters from PayKeeper using the payment's unique identifier. This JavaScript example utilizes the `fetch` API to make a GET request. The result is an array detailing each parameter's ID, associated payment ID, field key, and its value.

```javascript
const paymentId = "11186";
const url = `https://paykeeper.ru/api/info/params/byid/?id=${paymentId}`;

fetch(url)
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error('Error:', error);
  });
```

--------------------------------

### GET /info/systems/sums/

Source: https://docs.paykeeper.ru/dokumentatsiya-json-api/statistika

Retrieves the total sum of payments received across all payment systems for a given period. It supports filtering by start and end dates.

```APIDOC
## GET /info/systems/sums/

### Description
Retrieves the total sum of payments received across all payment systems for a given period. It supports filtering by start and end dates.

### Method
GET

### Endpoint
/info/systems/sums/

### Parameters
#### Query Parameters
- **start** (string) - Required - The start date of the period in YYYY-MM-DD format.
- **end** (string) - Required - The end date of the period in YYYY-MM-DD format.

### Request Example
```json
{
  "example": "/info/systems/sums/?start=2014-04-12&end=2014-05-12"
}
```

### Response
#### Success Response (200)
- **id** (string) - The identifier of the payment system.
- **system_description** (string) - The system name of the payment system.
- **site_description** (string) - The site name of the payment system.
- **success** (string) - The sum of payments with status 'Completed'.
- **account** (string) - The sum of successful payments credited to the bank account.
- **stuck** (string) - The sum of payments with status 'Completed without notification'.
- **currency** (string) - The currency of the received payments.

#### Response Example
```json
{
  "example": [
    {
      "id": "6",
      "system_description": "RS",
      "site_description": "Русский Стандарт",
      "success": "304 755.00",
      "account": "304 755.00",
      "stuck": "0.00",
      "currency": "RUR"
    },
    {
      "id": "2",
      "system_description": "AlfaBank",
      "site_description": "Альфа-Банк",
      "success": "19 902.00",
      "account": "19 902.00",
      "stuck": "0.00",
      "currency": "RUR"
    }
  ]
}
```
```

--------------------------------

### Initiate Payment Reversal /change/payment/reverse/

Source: https://docs.paykeeper.ru/dokumentatsiya-json-api/platezhi

This method initiates a full or partial refund for a payment. It automatically determines the type of refund based on the payment status and acquirer capabilities. For 54-FZ fiscalization, itemized return information can be provided. The request requires the payment ID, amount, and a boolean flag for partial refunds. Security token is also mandatory. Returns a JSON object indicating success or failure with an error message.

```JSON
{
  "result": "success"
}
```

```JSON
{
  "result": "fail",
  "msg": "Нельзя сделать возврат по платежу, статус которого не \"совершён\", \"получен\" или \"превышено число повторов\""
}
```

--------------------------------

### Search Invoices by Query and Date Range (GET Request)

Source: https://docs.paykeeper.ru/dokumentatsiya-json-api/scheta

This example demonstrates how to construct a GET request to the /info/invoice/search/ endpoint. It utilizes the 'query' parameter for substring searching within invoice details and specifies a 'start_date' and 'end_date' to filter results within a date range. The 'query' parameter supports MySQL-like syntax, where '*' is replaced by '%'.

```http
GET /info/invoice/search/?query=4038*9682&start_date=2016-01-01&end_date=2017-04-04
```

--------------------------------

### Get Payment System Balances by Time Interval - HTTP

Source: https://docs.paykeeper.ru/dokumentatsiya-json-api/statistika

Fetches data for constructing payment reception graphs over time. For intervals less than 30 days, daily sums are returned. For intervals over 30 days, averaged data for 30 points is returned. Requires a GET request with 'start' and 'end' date parameters.

```HTTP
GET /info/systems/sums/details/?start=2014-04-12&end=2014-05-12
```
Tokens:
Raw