Подготовка к интеграции

Регистрация и создание магазина через pikassa.io

​ Для подготовки к интеграции необходимо:

1. Зарегистрировать личный кабинет Pikassa по кнопке Подключиться на странице pikassa.io;
2. В личном кабинете создать магазин в разделе Магазины, перейти в настройки магазина и заполнить раздел Общие настройки;
3. Перейти в раздел настроек магазина Технические настройки и сгенерировать новый секретный ключ (secretPhrase) для формирования подписи;
4. Если требуется передача уведомлений об изменении статусов счета в одну из ваших систем (Callback), заполнить поле ResultURL адресом для получения уведомлений;
5. Активировать созданный магазин, связавшись с персональным менеджером.

HTTP-заголовки

Взаимодействие с сервисом происходит посредством передачи HTTP-запросов.

Запросы могут включать следующие заголовки:

• Content-Type: application/json; charset=utf-8
• x-api-key: <API Key>
• x-sign: <электронно-цифровая подпись> (кроме получения данных счета и данных магазина)

Алгоритм формирования ЭЦП

ЭЦП формируется следующим образом:

1. К сформированному телу запроса (body) добавляется secretPhrase магазина (операция конкатенации)
2. Вычисляется контрольная сумма по алгоритму md5, кодировка UTF-8
3. Контрольная сумма переводится в base64

Примеры реализации алгоритма формирования x-sign

Пример на языке C#

Пример на языке PHP

Пример на языке Python

Схема проведения запроса

1. Магазин отправляет в Pikassa запрос на создание счета;
2. Pikassa обрабатывает запрос и, если счет создан корректно, возвращает данные, содержащие ссылку для перехода на оплату;
3. Плательщик переходит по ссылке, выбирает способ оплаты и вводит платежные данные;
4. Pikassa отправляет запрос на списание денежных средств эквайеру;
5. Pikassa получает ответ об успешной/неуспешной оплате счета от эквайера; происходит переадресация плательщика на страницу магазина
   1. В случае успешной оплаты счета плательщик перенаправляется на страницу, указанную при создании счета в параметре successUrl;
   2. В случае неуспешной оплаты происходит перенаправление на страницу, указанную при создании счета в параметре failUrl;
6. Pikassa отправляет магазину уведомление об успешной/неуспешной оплате счета; Магазин возвращает ответ-подтверждение о проведенной операции.

Создание счета

Метод позволяет создать счет на оплату и отправить его плательщику.

Пример запроса на создание счета

curl https://pikassa.io/merchant-api/api/v2/invoices \
  -X POST \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
    "amount": 105.05,
    "currency": "RUB",
    "description": "Оплата заказа №12080",
    "customerPhone": "+74994550185",
    "customerEmail": "support@pikassa.io",
    "customerIp": "127.0.0.1",
    "customData": {
            "key1": "value1",
            "key2": 5
    },
    "successUrl": "https://empty.com/successUrl",
    "failUrl": "https://empty.com/failUrl",
    "deliveryMethod": "URL",
    "expirationDate": "2021-03-14 11:08:24.909150+03:00",
    "ofdData": null,
    "preAuth": false,
    "locale": "ru",
    "createToken": false,
    "paymentSplits": [
        {
            "shopId": 197,
            "amount": 20,
            "currency": "RUB"
        },
        {
            "shopId": 198,
            "amount": 85.05,
            "currency": "RUB"
        }
    ]
}'

Описание параметров запроса на создание счета

Описание параметров коллекции paymentSplits

Пример успешного ответа на запрос на создание счета

{
    "success": true,
    "data": {
        "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
        "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
        "paymentLink": "https://pikassa.io/portal2/pay/i/cd422358-56dd-4039-9559-c1fb766dbbbd"
    }
}

Описание параметров успешного ответа при создании счета

Описание параметров объекта data

Пример ответа с ошибкой на запрос на создание счета

{
    "success": false,
    "error": {
        "code": "1",
        "message": "Ошибка создания счета"
    }
}

Описание параметров ответа с ошибкой создания счета

Описание параметров объекта error

Авторизация захолдированного счета

Метод позволяет списать захолдированную сумму с карты плательщика. Используется при двухстадийном платеже.

Пример запроса на авторизацию счета

curl https://pikassa.io/merchant-api/api/v2/invoices/<uuid>/auth \
  -X PUT \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
    "amount": 123.12
}'

uuid - идентификатор счета, полученный в успешном ответе при создании захолдированного счета.

Описание параметров запроса на авторизацию счета

Пример успешного ответа на запрос на авторизацию счета

{
    "success": true,
    "data": {
        "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
        "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
    }
}

Описание параметров успешного ответа на запрос на авторизацию счета

Описание параметров объекта data

Пример ответа с ошибкой на запрос на авторизацию счета

{
    "success": false,
    "error": {
        "code": "2",
        "message": "Ошибка авторизации платежа"
    }
}

Описание параметров ответа с ошибкой на запрос на авторизацию счета

Описание параметров объекта error

Отмена счета

Метод позволяет отменить возможность оплаты счета. Доступен только для тех счетов, по которым еще не было переходов на платежную страницу, в обратном случае запрос будет отклонен.

Также метод используется при двухстадийном платеже и позволяет разблокировать ранее захолдированную сумму на карте плательщика.

Пример запроса на отмену счета

curl https://pikassa.io/merchant-api/api/v2/invoices/<uuid>/cancel \
  -X PUT \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
    "reason": "Отменен"
}'

uuid - идентификатор счета, полученный в успешном ответе при создании счета.

Описание параметров запроса на отмену счета

Пример успешного ответа на запрос на отмену счета

{
    "success": true,
    "data": {
        "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
        "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
    }
}

Описание параметров успешного ответа на запрос на отмену счета

Описание параметров объекта data

Пример ответа с ошибкой на запрос на отмену счета

{
    "success": false,
    "error": {
        "code": "3",
        "message": "error"
    }
}

Описание параметров ответа с ошибкой на запрос на отмену счета

Описание параметров объекта error

Возврат

Используется для возврата денежных средств. Срок возврата зависит от банка, выпустившего карту плательщика.

Пример запроса на возврат

curl https://pikassa.io/merchant-api/api/v2/invoices/<uuid>/refund \
  -X PUT \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
    "amount": 123.12,
    "reason": "Возврат по счету №22530",
    "refundSplits": [
        {
            "shopId": 197,
            "amount": 100,
            "currency": "RUB"
        },
        {
            "shopId": 198,
            "amount": 23.12,
            "currency": "RUB"
        }
    ],
    "ofdData": null
}'

uuid - идентификатор счета, полученный в успешном ответе при создании счета.

Описание параметров запроса на возврат

Описание параметров коллекции refundSplits

Пример успешного ответа на запрос на возврат

{
    "success": true,
    "data": {
        "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
        "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
    }
}

Описание параметров успешного ответа на запрос на возврат

Описание параметров объекта data

Пример ответа с ошибкой на запрос на возврат

{
    "success": false,
    "error": {
        "code": "6",
        "message": "error"
    }
}

Описание параметров ответа с ошибкой на запрос на возврат

Описание параметров объекта error

Получение данных счета

Метод позволяет запросить данные счета: статус счета, итоговая сумма счета, метод оплаты и др.

Пример запроса на получение данных

curl https://pikassa.io/merchant-api/api/v2/invoices/<uuid> \
  -X GET \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'Content-Type: application/json; charset=utf-8' \

uuid - идентификатор счета, полученный в успешном ответе при создании счета.

Описание параметров запроса на получение данных

Пример успешного ответа на запрос на получение данных

{
    "id": 132345,
    "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "amount": 105.05,
    "finalAmount": 123.12,
    "currency": "RUB",
    "description": "Счет на оплату заказа №12080",
    "customerPhone": "+74994550185",
    "customerEmail": "support@pikassa.io",
    "customData": {
        "key1": "value1",
        "key2": 5
    },
    "successUrl": "http://empty.com/successUrl",
    "failUrl": "http://empty.com/failUrl",
    "deliveryMethod": "URL",
    "subscriptionUuid": "945c06b4-b791-4f2c-89b1-a45f78cb1568",
    "expirationDate": "2021-03-14 11:08:24.0909150+03:00",
    "locale": "ru",
    "ofdData": null,
    "preAuth": false,
    "status": {
        "name": "InvoicePaid",
        "time": "2020-03-14 11:08:24.0909150+03:00",
        "message": "message"
    },
    "payments": [
        {
            "paymentMethod": "BankCard",
            "paymentDetails": {
                "account": "411111******1111",
                "paymentToken": "837c06b4-b791-4f2c-89b1-a45f78cb1568",
                "cardBrand": "Visa",
                "rrn": "002949319187"
            },
            "status": {
                "name": "PaymentPaid",
                "message": null
            }
        }
    ]
}

Описание параметров успешного ответа на запрос на получение данных

Описание параметров объекта status

Описание параметров объекта payments

Описание параметров объекта details

Описание параметров объекта status

Пример ответа с ошибкой на запрос на получение данных

{
    "success": false,
    "error": {
        "code": "5",
        "message": "error"
    }
}

Описание параметров ответа с ошибкой на запрос на получение данных

Описание параметров объекта error

Получение данных счетов

Метод позволяет запросить данные нескольких счетов по фильтрам.

Передаваемые параметры не должны дублироваться.

Пример запроса на получение данных счетов

curl https://pikassa.io/merchant-api/api/v2/invoices?status=InvoicePaid&customerEmail=support@pikassa.io&dateFrom=2022-09-14 11:08:24 \
  -X GET \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'X-Sign: <Подпись>' \
  -H 'Content-Type: application/json; charset=utf-8' \

Правила формирования подписи при запросе данных счетов

Подпись формируется следующим образом:

1. Значения передаваемых query-параметров сортируются по именам query-параметров, по алфавиту в нижнем регистре в прямом порядке
2. Значения параметров склеиваются (конкатенация) в строку через точку с запятой
3. К полученной строке приклеивается (конкатенация) секретный ключ магазина
4. Вычисляется контрольная сумма полученной строки по алгоритму md5, кодировка UTF-8
5. Контрольная сумма кодируется в base64
6. Полученная подпись передается в заголовке запроса : X-Sign

Описание параметров запроса на получение данных

Пример успешного ответа на запрос на получение данных счетов

    {
        "success": true,
        "meta": {
            "totalRow": 2,
            "paging": {
                "skip": 0,
                "take": 100
            }
        },
        "data": [{
                "id": 123345,
                "externalId": "3cebaddf-d806-ebad-9f96-ebad5d2d3827",
                "uuid": "1fdebad-a8e7-ebad-a799-f0cfa3ebebad",
                "amount": 105.05,
                "finalAmount": 105.05,
                "currency": "RUB",
                "description": "Счет на оплату заказа №1223080",
                "customerPhone": "+74999999999",
                "customerEmail": "support@pikassa.io",
                "customData": {
                    "key1": "value1",
                    "key2": 5
                },
                "successUrl": "http://empty.com/successUrl",
                "failUrl": "http://empty.com/failUrl",
                "deliveryMethod": "URL",
                "subscriptionUuid": "945c06b4-b791-4f2c-89b1-a45f78cb1568",
                "expirationDate": "2021-03-14 12:08:24.0909150+03:00",
                "locale": "ru",
                "ofdData": null,
                "preAuth": false,
                "status": {
                    "name": "InvoicePaid",
                    "time": "2022-09-14 13:08:24.0908110+03:00",
                    "message": "message"
                },
                "payments": [{
                        "paymentMethod": "BankCard",
                        "paymentDetails": {
                            "account": "411111******1111",
                            "paymentToken": "837c06b4-b791-4f2c-89b1-a45f78cb1568",
                            "cardBrand": "Visa",
                            "rrn": "004567375490"
                        },
                        "status": {
                            "name": "PaymentPaid",
                            "message": null
                        }
                    }
                ]
            }, {
                "id": 123467,
                "externalId": "4ddfaddf-d806-ebad-9f96-ebad5d2d3827",
                "uuid": "ddfebad-a8e7-ebad-a799-f0cfa3ebeddf",
                "amount": 105,
                "finalAmount": 100,
                "currency": "RUB",
                "description": "Счет на оплату заказа №122",
                "customerPhone": "+74999999999",
                "customerEmail": "support@pikassa.io",
                "customData": {
                    "key1": "value1",
                    "key2": 6
                },
                "successUrl": "http://empty.com/successUrl",
                "failUrl": "http://empty.com/failUrl",
                "deliveryMethod": "URL",
                "subscriptionUuid": null,
                "expirationDate": "2021-03-14 11:08:24.0909150+03:00",
                "locale": "ru",
                "ofdData": null,
                "preAuth": false,
                "status": {
                    "name": "InvoicePaid",
                    "time": "2020-03-14 11:08:24.0909150+03:00",
                    "message": "message"
                },
                "payments": [{
                        "paymentMethod": "BankCard",
                        "paymentDetails": {
                            "account": "411111******1111",
                            "paymentToken": null,
                            "cardBrand": "Visa",
                            "rrn": "002949319187"
                        },
                        "status": {
                            "name": "PaymentPaid",
                            "message": null
                        }
                    }
                ]
            }

        ]
    }

Описание параметров успешного ответа на получение данных

Описание параметров объекта из коллекции data

Описание параметров объекта status

Описание параметров объекта payments

Описание параметров объекта details

Описание параметров объекта status

Описание параметров объекта meta

Описание параметров объекта paging

Пример ответа с ошибкой на запрос на получение данных счетов

{
    "success": false,
    "error": {
        "code": "5",
        "message": "error"
    }
}

Описание параметров ответа с ошибкой на запрос на получение данных

Описание параметров объекта error

Оплата счета

Метод позволяет передать детали платежа для осуществления оплаты. Оплата возможна по реквизитам банковской карты, либо по ранее созданному платежному токену.

Пример запроса оплаты счета

curl https://pikassa.io/merchant-api/api/v2/invoices/<uuid>/pay \
  -X PUT \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
    "paymentMethod": "BankCard",
    "details": {
        "key1": "value1",
        "key2": "value2"
        }
    }
}'

Описание параметров запроса оплаты счета

Оплата счета по реквизитам банковской карты

Алгоритм работы

1. Магазин отправляет в Pikassa запрос на создание счета (см. "Создание счета");
2. Pikassa обрабатывает запрос и, если счет создан корректно, то возвращает успешный ответ с его идентификатором (uuid);
3. Магазин отображает пользователю форму ввода карточных данных для данного счета;
4. Пользователь вводит банковские реквизиты на форме магазина;
5. Магазин отправляет в Pikassa запрос на оплату счета с реквизитами банковской карты в объекте details;
6. Pikassa обрабатывает запрос и, если от пользователя требуется ввод 3DS, то в ответе возвращается ссылка для перенаправления пользователя, в противном случае переходим к пункту 9;
7. Магазин перенаправляет пользователя на страницу ввода 3DS по полученным от Pikassa данным;
8. Пользователь вводит 3DS и перенаправляется на successUrl/failUrl (в зависимости от результата), который был указан в запросе на создание счета;
9. Pikassa отправляет магазину уведомление об успешной/неуспешной оплате счета;
10. Магазин возвращает ответ-подтверждение о проведенной операции.

Пример запроса для оплаты счета по реквизитам банковской карты

curl https://pikassa.io/merchant-api/api/v2/invoices/<uuid>/pay \
  -X PUT \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
    "paymentMethod": "BankCard",
    "details": {
        "pan": "4111111111111111",
        "cardHolder": "ivan ivanov",
        "expYear": "24",
        "expMonth": "12",
        "cvc": "123"
        }
    }
}'

Описание параметров details для оплаты счета по реквизитам банковской карты

Оплата счета с помощью платежного токена

Алгоритм работы

1. Магазин отправляет в Pikassa запрос на создание счета, где указывает параметр createToken=true для создания платежного токена (см. "Создание счета"). Предварительно данную возможность необходимо согласовать с менеджером;
2. Pikassa обрабатывает запрос и, если счет создан корректно, то возвращает успешный ответ с его идентификатором (uuid) и ссылкой для оплаты счета. Счет может быть оплачен любым удобным способом - либо по платежной ссылке, либо с помощью метода оплаты счета по реквизитам банковской карты;
3. Магазин получает платежный токен в уведомлении от Pikassa об успешной оплате счета, либо в ответе на запрос данных счета.
4. Для оплаты счета по токену, Магазин отправляет в Pikassa запрос на создание счета (см. "Создание счета");
5. Pikassa обрабатывает запрос и, если счет создан корректно, то возвращает успешный ответ с его идентификатором (uuid);
6. Магазин отправляет в Pikassa запрос на оплату счета по полученному в предыдущем пункте идентификатору с платежным токеном в объекте details;
7. Pikassa отправляет магазину уведомление об успешной/неуспешной оплате счета;
8. Магазин возвращает ответ-подтверждение о проведенной операции.

Пример запроса для оплаты счета по токену

curl https://pikassa.io/merchant-api/api/v2/invoices/<uuid>/pay \
  -X PUT \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
    "paymentMethod": "BankCard",
    "details": {
        "token": "5fc6aaf6-f3e6-42f5-8b30-984f82ca8527"
        }
    }
}'

Описание параметров details для оплаты счета по токену

Пример успешного ответа на запрос оплаты счета

{
    "success": true,
    "data": {
        "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
        "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad",
        "redirect": {
            "url": "http://example.com",
            "method": "POST",
            "params": [
                {
                    "name": "name1",
                    "value": "value1"
                }
            ]
        }
    }
}

В случае необходимости ввода кода 3DS может потребоваться перенаправление пользователя.

Описание параметров успешного ответа на запрос оплаты счета

Описание параметров объекта data

Описание параметров объекта redirect

Пример ответа с ошибкой на запрос оплаты счета

{
    "success": false,
    "error": {
        "code": "4",
        "message": "error"
    }
}

Описание параметров ответа с ошибкой на запрос оплаты счета

Описание параметров объекта error

Создание подписки

Метод позволяет создать подписку для проведения регулярных платежей, совершаемых без подтверждения клиентом.

Алгоритм работы с подпиской

1. Магазин отправляет в Pikassa запрос на создание счета, где указывает параметр createToken=true для создания платежного токена. Предварительно данную возможность необходимо согласовать с менеджером;
2. Логика оплаты счета описана в "Схеме проведения запроса";
3. В случае если счет был успешно оплачен, то Pikassa отправляет магазину уведомление об успешной оплате, которое содержит идентификатор платежного токена; Магазин возвращает ответ-подтверждение о проведенной операции.
4. Магазин отправляет в Pikassa запрос на создание подписки, где указывает идентификатор платежного токена первого счета и данные подписки;
5. Pikassa обрабатывает запрос и если подписка создана корректно, возвращает ответ, содержащий идентификатор подписки;
6. В случае если наступил момент следующей оплаты счета Pikassa создает счет и проводит его аналогично первому платежу, но списание средств осуществляется уже без подтверждения клиентом;
7. Pikassa отправляет магазину уведомление об успешной/неуспешной оплате счета, которое содержит идентификатор подписки, на основе которой создан счет; Магазин возвращает ответ-подтверждение о проведенной операции.

Пример запроса на создание подписки

curl https://pikassa.io/merchant-api/api/v2/subscriptions \
  -X POST \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
    "paymentToken": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad",
    "customerEmail": "support@pikassa.io",
    "name": "Подписка на сервис",
    "amount": 444.44,
    "startDate": "2020-07-01 00:00:00.000000+03:00",
    "interval": "MONTH",
    "period": 1,
    "maxPeriods": 12,
    "currency": "RUB"
}'

paymentToken - идентификатор платежного токена, полученный в нотификации (callback), после оплаты счета.

Описание параметров запроса на создание подписки

Пример успешного ответа на запрос на создание подписки

{
    "success": true,
    "data": {
        "uuid": "5c91a9f9-984b-4ed5-818b-8136fdd551e2",
        "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a"
    }
}

Описание параметров успешного ответа на запрос на создания подписки

Описание параметров объекта data

Пример ответа с ошибкой на запрос на создание подписки

{
    "success": false,
    "error": {
        "code": "7",
        "message": "Ошибка создания подписки"
    }
}

Описание параметров ответа с ошибкой на запрос на создание подписки

Описание параметров объекта error

Получение баланса магазина

Пример запроса на получение данных

Метод позволяет по ключу доступа получить баланс данного магазина. Если магазин работает с несколькими валютами, то баланс будет получен по каждой из валют.

curl https://pikassa.io/merchant-api/api/v2/balance \
  -X GET \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'Content-Type: application/json; charset=utf-8' \

Пример успешного ответа на запрос на получение данных

{
    "success": true,
    "data": [
        {
            "currency": "RUB",
            "balance": 890.12,
            "freeze": 23.44
        },
        {
            "currency": "USD",
            "balance": 562.43,
            "freeze": 0
        },
    ]
}

Описание параметров успешного ответа на запрос на получение данных

Описание параметров элемента коллекции data

Пример ответа с ошибкой на запрос на получение данных

{
    "success": false,
    "error": {
        "code": "8",
        "message": "error"
    }
}

Описание параметров ответа с ошибкой на запрос на получение данных

Описание параметров объекта error

Создание выплаты

Метод позволяет осуществлять вывод средств на платежные средства. Pikassa предлагает следующие способы вывода: на банковскую карту, кошелек WebMoney (P, Z), кошелек ЮMoney, кошелек QIWI, мобильный телефон. Для активации возможности создавать выплаты необходимо связаться с менеджером Pikassa.

Пример запроса на создание выплаты

curl https://pikassa.io/merchant-api/api/v2/payouts \
  -X POST \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
    "amount": 10005.05,
    "currency": "RUB",
    "description": "Вывод себе на карту",
    "destination": {
        "pan": "41233543544386", 
        "cardholder": "Ivan Pupkin"
    },
    "payoutMethod": "BankCard",
    "customData": {
        "key1": "value1",
        "key2": 5
    }
}'

Описание параметров запроса на создание выплаты

Описание параметров объекта destination для способа вывода на банковскую карту

{
    ...
    "destination": {
        "pan": "41233543544386", 
        "cardholder": "Ivan Pupkin"
    },
    "payoutMethod": "BankCard"
}

Описание параметров объекта destination для способа вывода на кошелек WebMoney

{
    ...
    "destination": {
        "wallet": "P123456789123"
    },
    "payoutMethod": "WMR"
}

Описание параметров объекта destination для способа вывода на кошелек ЮMoney

{
    ...
    "destination": {
        "wallet": "41234567891234567812"
    },
    "payoutMethod": "YandexMoney"
}

Описание параметров объекта destination для способа вывода на мобильный телефон

{
    ...
    "destination": {
        "phone": "+79851111111"
    },
    "payoutMethod": "Mobile"
}

Описание параметров объекта destination для способа вывода на кошелек QIWI

{
    ...
    "destination": {
        "phone": "+79851111111"
    },
    "payoutMethod": "Qiwi"
}

Пример успешного ответа на запрос на создание выплаты

{
    "success": true,
    "data": {
        "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
        "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827"
    }
}

Описание параметров успешного ответа при создании выплаты

Описание параметров объекта data

Примеры ответа с ошибкой на запрос на создание выплаты

{
    "success": false,
    "error": {
        "code": "9",
        "message": "Ошибка создания выплаты"
    }
}

При получении ответа на запрос создания выплаты с http кодом 408, требуется дождаться оповещения об изменении статуса выплаты (Callback).

Описание параметров ответа с ошибкой создания выплаты

Описание параметров объекта error

Получение данных выплаты

Метод позволяет запросить данные выплаты: статус выплаты, сумму, метод вывода и др.

Пример запроса на получение данных

curl https://pikassa.io/merchant-api/api/v2/payouts/<uuid> \
  -X GET \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'Content-Type: application/json; charset=utf-8' \

uuid - идентификатор выплаты, полученный в успешном ответе при создании выплаты.

Описание параметров запроса на получение данных

Пример успешного ответа на запрос на получение данных

{
    "success": true,
    "data": {
        "externalId": "12_530539_wm927548",
        "uuid": "63947ef9-fb75-4b8a-b126-e6f53441e24a",
        "payoutMethod": "BankCard",
        "amount": 813.03,
        "currency": "RUB",
        "description": "Вывод на карту",
        "destination": {
            "cardholder": "Ivan Pupkin",
            "masked_pan": "489049******0514"
        },
        "status": {
            "name": "PayoutSucceeded",
            "time": "2022-04-13 08:42:22.501903+00:00",
            "message": "Получено событие о удачном проведении транзакции на выплату"
        },
        "commission": {
            "amount": -150.16,
            "currency": "RUB"
        },
        "customData": {
            "key1": "value1",
            "key2": 5
        },
        "rrn": "004567375490"
    }
}

Описание параметров успешного ответа при получении данных выплаты

Описание параметров объекта data

Описание параметров объекта commission

Описание параметров объекта status

Описание параметров объекта destination для способа вывода на банковскую карту

Описание параметров объекта destination для способа вывода на кошелек WebMoney

Описание параметров объекта destination для способа вывода на кошелек ЮMoney

Описание параметров объекта destination для способа вывода на мобильный телефон или Qiwi

Пример ответа с ошибкой на запрос на получение данных

{
    "success": false,
    "error": {
        "code": "10",
        "message": "Ошибка при получении данных выплаты"
    }
}

Описание параметров ответа с ошибкой на запрос на получение данных

Описание параметров объекта error

Google Pay^TM

Google Pay^TM — это способ оплаты заказов, позволяющий в один клик совершать платежи без ввода банковских реквизитов. GPay доступен с любых устройств, имеющих Google аккаунт. Pikassa принимает платежи через Google Pay^TM двумя методами:

• Через платежный портал Pikassa — для подключения данного способа оплаты свяжитесь с вашим менеджером;
• Путем прямой интеграции с Google Pay API.

Требования к сайту магазина для прямой интеграции с Google Pay API

1. При реализации подключения руководствоваться документацией.
2. Необходимо соблюсти требования по брендированию при размещении кнопки GPay на форме оплаты.
3. Убедиться, что товары или услуги не входят в перечень запрещенных.
4. Сверить реализацию с контрольным списком.
5. Пройти процедуру проверки.

Сценарий оплаты

1. Клиент в интернет-магазине оформляет заказ и для оплаты выбирает способ GPay.
2. Магазин отправляет запрос на создание счета в Pikassa.
3. Pikassa обрабатывает запрос и, если счет создан корректно, возвращает его уникальный идентификатор uuid.
4. Магазин отправляет запрос на оплату в Google Pay API.
5. Система Google Pay^TM по полученным платежным данным формирует токен.
6. Магазин в ответ на запрос получает сформированный токен.
7. Магазин формирует запрос на передачу деталей платежа в систему Pikassa, где в адресе запроса указывает uuid полученный при создании счета, а в параметре details - токен полученный от Google Pay API.
8. Pikassa обрабатывает запрос и для транзакций PAN_ONLY возвращает ссылку для перенаправления клиента на форму ввода 3DS.
9. Магазин для завершения аутентификации 3DS перенаправляет клиента на адрес, указанный в параметре data.redirect.url в ответе Pikassa.
10. Pikassa отправляет магазину уведомление об успешной/неуспешной оплате счета.
11. Магазин возвращает ответ-подтверждение о проведенной операции.

Примеры запросов в Google Pay API

//Проверка на доступность GPay для данного устройства
const readyToPayRequest = {
    "apiVersion": 2,
    "apiVersionMinor": 0,
    "allowedPaymentMethods": [
        {
            "type": "CARD",
            "parameters": {
                "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
                "allowedCardNetworks": ["MASTERCARD", "VISA"]
            }
        }
    ]
}

//Запрос на оплату в Google Pay API
const paymentDataRequest = {
    "apiVersion": 2,
    "apiVersionMinor": 0,
    "allowedPaymentMethods": [
        {
            "type": "CARD",
            "parameters": {
                "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
                "allowedCardNetworks": ["MASTERCARD", "VISA"]
            },
            "tokenizationSpecification": {
                "type": "PAYMENT_GATEWAY",
                "parameters": {
                    "gateway": "pikassa",
                    "gatewayMerchantId": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
                }
            }
        }
    ],
    "transactionInfo": {
        "countryCode": "RU",
        "currencyCode": "RUB",
        "totalPriceStatus": "FINAL",
        "totalPrice": "123.12"
    }
}

В примере продемонстрированы 2 запроса:

• isReadyToPay() - проверка на доступность GPay для данного устройства. В примере показано, как настроить поддержку платежных карт и токенов для устройств Android для платежных систем VISA и MASTERCARD.
• paymentDataRequest() - запрос на оплату в Google Pay API. В этом примере показано, как настроить поддержку платежных карт и токенов для устройств Android для платежных систем VISA и MASTERCARD. Токенизация карт выполняется через шлюз pikassa. Запрос способа платежа осуществляется для выставления окончательного счета на сумму 123,12 рублей.

Описание параметров

Объект allowedPaymentMethods

Объект allowedPaymentMethods.parameters

Параметр запроса платежного адреса BillingAddressParameters - не используется.

Объект allowedPaymentMethods.tokenizationSpecification

Объект allowedPaymentMethods.tokenizationSpecification.parameters

Объект transactionInfo

Перечень возможных значений статусов счета

Перечень возможных значений статусов платежа

Перечень возможных значений статусов выплаты

Перечень возможных значений методов оплаты

Перечень возможных значений методов вывода

Перечень возможных значений валюты

Оповещение об изменении статуса счета

Оповещение об изменении статуса (Callback) происходит путем отправки POST-запроса по адресу, указанному в настройках магазина (раздел Технические настройки , параметр Result url)

Если на оповещение получен невалидный ответ/валидный ответ с ошибкой, или же ответ не получен, система отправляет повторное оповещение позднее. Оповещение отправляется повторно конечное число раз.

Пример оповещения от Pikassa

curl https://pikassa.io/resultUrl \
  -X POST \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "id": 12356,
    "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "amount": 105.05,
    "finalAmount": 123.12,
    "currency": "RUB",
    "description": "Счет на оплату заказа №12080",
    "customerPhone": "+74994550185",
    "customerEmail": "support@pikassa.io",
    "customData": {
        "key1": "value1",
        "key2": 5
    },
    "successUrl": "http://empty.com/successUrl",
    "failUrl": "http://empty.com/failUrl",
    "deliveryMethod": "URL",
    "subscriptionUuid": "945c06b4-b791-4f2c-89b1-a45f78cb1568",
    "expirationDate": "2021-03-14 11:08:24.909150+03:00",
    "locale": "ru",
    "ofdData": null,
    "preAuth": false,
    "status": {
        "name": "InvoicePaid",
        "time": "2019 -03-14 11:08:24.0909150+03:00",
        "message": "message"
    },
    "payments": [
        {
            "paymentMethod": "BankCard",
            "paymentDetails": {
                "account": "411111******1111",
                "paymentToken": "837c06b4-b791-4f2c-89b1-a45f78cb1568",
                "cardBrand": "Visa",
                "rrn": "002949319187"
            },
            "status": {
                "name": "PaymentPaid",
                "message": null
            }
        }
    ]
}

Описание параметров оповещения от Pikassa

Описание параметров объекта status

Описание параметров объекта payments

Описание параметров объекта details

Описание параметров объекта status

Пример ожидаемого успешного ответа от системы мерчанта на оповещение от Pikassa

{
    "success": true,
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}

Пример ожидаемого ответа с ошибкой от системы мерчанта на оповещение от Pikassa

{
    "success": false,
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}

Описание параметров ожидаемых ответов от системы мерчанта на оповещение от Pikassa

Оповещение об изменении статуса выплаты

Оповещение об изменении статуса (Callback) происходит путем отправки POST-запроса по адресу, указанному в настройках магазина (раздел Технические настройки , параметр Payout Result URL)

Если на оповещение получен невалидный ответ/валидный ответ с ошибкой, или же ответ не получен, система отправляет повторное оповещение позднее. Оповещение отправляется повторно конечное число раз.

Пример оповещения от Pikassa

curl https://pikassa.io/PayoutResultURL \
  -X POST \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
  "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
  "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
  "payoutMethod": "BankCard",
  "amount": 10005.05,
  "currency": "RUB",
  "description": "Вывод себе на карту",
  "destination": {
    "cardholder": "Ivan Pupkin",
    "masked_pan": "412335******4386"
  },
  "status": {
    "name": "PayoutSucceeded",
    "time": "2020-08-01 11:08:24.0909150+03:00",
    "message": "message"
  },
  "commission": {
    "amount": -29.80,
    "currency": "RUB"
  },
  "customData": {
    "key1": "value1",
    "key2": 5
  },
  "rrn": "004567375490"
}

Описание параметров оповещения от Pikassa

Описание параметров объекта commission

Описание параметров объекта status

Описание параметров объекта destination для способа вывода на банковскую карту

Описание параметров объекта destination для способа вывода на кошелек WebMoney

Описание параметров объекта destination для способа вывода на кошелек ЮMoney

Описание параметров объекта destination для способа вывода на мобильный телефон

Пример ожидаемого успешного ответа от системы мерчанта на оповещение от Pikassa

{
    "success": true,
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}

Пример ожидаемого ответа с ошибкой от системы мерчанта на оповещение от Pikassa

{
    "success": false,
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}

Описание параметров ожидаемых ответов от системы мерчанта на оповещение от Pikassa

Описание кодов ошибок

Тестирование

Тестовые карты для проведения платежей и осуществления выплат (для тестовых магазинов Pikassa)

Отправка данных в соответствии с ФЗ-54

Для отправки фискальных данных используется протокол, совместимый с протоколом АТОЛ; поддерживаемый провайдер данных — АТОЛ. Для подключения возможности передавать фискальные данные необходимо сообщить данные аккаунта АТОЛ менеджеру Pikassa. Важно: Параметры, которые не должны быть указаны в JSON схеме: timestamp, external_id, service.

Схема и пример данных ОФД

Схема запроса JSON , пример 1 и пример 2.

Описание параметров запроса

Структура параметров запроса

receipt

1.client

1.1. email

1.2.phone

2.company

2.1. email

2.2. sno

2.3. inn

2.4. payment_address

1. agent_info

   3.1. type

   3.2. paying_agent

   3.2.1.operation

   3.2.2.phones

   3.3. receive_payments_operator

   3.3.1.phones

   3.4. money_transfer_operator

   3.4.1.phones

   3.4.2.name

   3.4.3.address

   3.4.4.inn

2. supplier_info

   4.1. phones

3. items

   5.1. name

   5.2. price

   5.3. quantity

   5.4. sum

   5.5. measurement_unit

   5.6. payment_method

   5.7. payment_object

   5.8. vat

   5.8.1.type

   5.8.2.sum

   5.9. agent_info

   5.9.1.type

   5.9.2.paying_agent

   5.9.2.1.operation

   5.9.2.2.phones

   5.9.3.receive_payments_operator

   5.9.3.1.phones

   5.9.4.money_transfer_operator

   5.9.4.1.name

   5.9.4.2.address

   5.9.4.3.inn

   5.10. supplier_info

   5.10.1.phones

   5.10.2.name

   5.10.3.inn

   5.11. user_data

4. payments

   6.1.type

   6.2.sum

5. vats

   7.1.type

   7.2.sum

6. total

7. additional_check_props

8. cashier

9. additional_user_props

   11.1.name

   11.2.value

Описание полей параметров запроса

Описание подпараметра client

Описание подпараметра company

Описание подпараметра agent_info

Возможные значения type

«bank_paying_agent» — банковский платежный агент. Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным агентом.

«bank_paying_subagent» — банковский платежный субагент. Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным субагентом.

«paying_agent» — платежный агент. Оказание услуг покупателю (клиенту) пользователем, являющимся платежным агентом.

«paying_subagent» — платежный субагент. Оказание услуг покупателю (клиенту) пользователем, являющимся платежным субагентом.

«attorney» — поверенный. Осуществление расчета с покупателем (клиентом) пользователем, являющимся поверенным.

«commission_agent» — комиссионер. Осуществление расчета с покупателем (клиентом) пользователем, являющимся комиссионером.

«another» — другой тип агента. Осуществление расчета с покупателем (клиентом) пользователем, являющимся агентом и не являющимся банковским платежным агентом (субагентом), платежным агентом (субагентом), поверенным, комиссионером.

Описание подпараметра supplier_info

Описание подпараметра items

Возможные значения items.payment_method:

«full_prepayment» — предоплата 100%. Полная предварительная оплата до момента передачи предмета расчета.

«prepayment» — предоплата. Частичная предварительная оплата до момента передачи предмета расчета.

«advance» — аванс.

«full_payment» — полный расчет. Полная оплата, в том числе с учетом аванса (предварительной оплаты) в момент передачи предмета расчета.

«partial_payment» — частичный расчет и кредит. Частичная оплата предмета расчета в момент его передачи с последующей оплатой в кредит.

«credit» — передача в кредит. Передача предмета расчета без его оплаты в момент его передачи с последующей оплатой в кредит.

«credit_payment» — оплата кредита. Оплата предмета расчета после его передачи с оплатой в кредит (оплата кредита).

Возможные значения agent_info.type:

«bank_paying_agent» — банковский платежный агент. Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным агентом.

«bank_paying_subagent» — банковский платежный субагент. Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным субагентом.

«paying_agent» — платежный агент. Оказание услуг покупателю (клиенту) пользователем, являющимся платежным агентом.

«paying_subagent» — платежный субагент. Оказание услуг покупателю (клиенту) пользователем, являющимся платежным субагентом.

«attorney» — поверенный. Осуществление расчета с покупателем (клиентом) пользователем, являющимся поверенным.

«commission_agent» — комиссионер. Осуществление расчета с покупателем (клиентом) пользователем, являющимся комиссионером.

«another» — другой тип агента. Осуществление расчета с покупателем (клиентом) пользователем, являющимся агентом и не являющимся банковским платежным агентом (субагентом), платежным агентом (субагентом), поверенным, комиссионером.

Возможные значения items.payment_object:

«commodity» – товар. О реализуемом товаре, за исключением подакцизного товара (наименование и иные сведения, описывающие товар).

«excise» – подакцизный товар. О реализуемом подакцизном товаре (наименование и иные сведения, описывающие товар).

«job» – работа. О выполняемой работе (наименование и иные сведения, описывающие работу).

«service» – услуга. Об оказываемой услуге (наименование и иные сведения, описывающие услугу).

«gambling_bet» – ставка азартной игры. О приеме ставок при осуществлении деятельности по проведению азартных игр.

«gambling_prize» – выигрыш азартной игры. О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению азартных игр.

«lottery» – лотерейный билет. О приеме денежных средств при реализации лотерейных билетов, электронных лотерейных билетов, приеме лотерейных ставок при осуществлении деятельности по проведению лотерей.

«lottery_prize» – выигрыш лотереи. О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению лотерей.

«intellectual_activity» – предоставление результатов интеллектуальной деятельности. О предоставлении прав на использование результатов интеллектуальной деятельности или средств индивидуализации.

«payment» – платеж. Об авансе, задатке, предоплате, кредите, взносе в счет оплаты,пени, штрафе, вознаграждении, бонусе и ином аналогичном предмете расчета.

«agent_commission» – агентское вознаграждение. О вознаграждении пользователя, являющегося платежным агентом (субагентом), банковским платежным агентом (субагентом), комиссионером, поверенным или иным агентом.

«award» – о взносе в счет оплаты пени, штрафе, вознаграждении, бонусе и ином аналогичном предмете расчета.

«another» – иной предмет расчета. О предмете расчета, не относящемуся к выше перечисленным предметам расчета.

«property_right» – имущественное право. О передаче имущественных прав.

«non-operating_gain» – внереализационный доход. О внереализационном доходе.

«insurance_premium» – страховые взносы. О суммах расходов, уменьшающих сумму налога (авансовых платежей) в соответствии с пунктом 3.1 статьи 346.21 Налогового кодекса Российской Федерации.

«sales_tax» – торговый сбор. О суммах уплаченного торгового сбора.

«deposit» – залог. О залоге.

«expense» – расход. О суммах произведенных расходов в соответствии со статьей 346.16 Налогового кодекса Российской Федерации, уменьшающих доход.

«pension_insurance_ip» – взносы на ОПС ИП. О страховых взносах на обязательное пенсионное страхование, уплачиваемых ИП, не производящими выплаты и иные вознаграждения физическим лицам.

«pension_insurance» – взносы на ОПС. О страховых взносах на обязательное пенсионное страхование, уплачиваемых организациями и ИП, производящими выплаты и иные вознаграждения физическим лицам.

«medical_insurance_ip» – взносы на ОМС ИП. О страховых взносах на обязательное медицинское страхование, уплачиваемых ИП, не производящими выплаты и иные вознаграждения физическим лицам.

«medical_insurance» – взносы на ОМС. О страховых взносах на обязательное медицинское страхование, уплачиваемые организациями и ИП, производящими выплаты и иные вознаграждения физическим лицам.

«social_insurance» – взносы на ОСС. О страховых взносах на обязательное социальное страхование на случай временной нетрудоспособности и в связи с материнством, на обязательное социальное страхование от несчастных случаев на производстве и профессиональных заболеваний.

«casino_payment» – платеж казино. О приеме и выплате денежных средств при осуществлении деятельности казино с использованием обменных знаков казино, в зале игровых автоматов.

Признак предмета расчета «composite» более не используется согласно ФФД 1.05.

Возможные значения items.vat.type:

Устанавливает номер налога в ККТ. Перечисление со значениями:

«none» – без НДС;

«vat0» – НДС по ставке 0%;

«vat10» – НДС чека по ставке 10%;

«vat18» – НДС чека по ставке 18%;

«vat110» – НДС чека по расчетной ставке 10/110;

«vat118» – НДС чека по расчетной ставке 18/118;

«vat20» – НДС чека по ставке 20%;

«vat120» – НДС чека по расчетной ставке 20/120.

С 01.04.2019 00:00 при отправке ставки vat18 или vat118 в чеках приход и расход сервис будет возвращать ошибку IncomingValidationException с текстом: "Передана некорректная ставка налога. С 01.04.2019 ставки НДС 18 и 18/118 не могут использоваться в чеках sell(приход) и buy(расход)".

Описание подпараметра payments

Описание подпараметра vats

Возможные значения type:

«none» – без НДС;

«vat0» – НДС по ставке 0%;

«vat10» – НДС чека по ставке 10%;

«vat18» – НДС чека по ставке 18%;

«vat110» – НДС чека по расчетной ставке 10/110;

«vat118» – НДС чека по расчетной ставке 18/118;

«vat20» – НДС чека по ставке 20%;

«vat120» – НДС чека по расчетной ставке 20/120.

С 01.02.2019 00:00 при отправке ставки vat18 или vat118 в чеках приход и расход сервис возвращает ошибку IncomingValidationException с текстом «Передана некорректная ставка налога. С 01.02.2019 ставки НДС 18 и 18/118 не могут использоваться в чеках sell (приход) и buy (расход)».

Описание подпараметра additional_user_props

С 01.04.2024 вступила в силу новая версия АТОЛ на более современной "Платформе v.5". С последней версией протокола АТОЛ можно ознакомиться на официальном сайте АТОЛ.