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

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

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

1. Зарегистрировать личный кабинет Payquity по кнопке Подключиться на странице payquity.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

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

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

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

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

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

curl https://payquity.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@payquity.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,
    "createToken": false
}'

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

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

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

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

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

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

{
    "success": false,
    "error": {
        "code": "1",
        "message": "Ошибка создания счета",
        "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
    }
}

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

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

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

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

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

curl https://payquity.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": "Ошибка авторизации платежа",
        "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
    }
}

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

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

Отмена счета

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

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

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

curl https://payquity.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",
        "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
    }
}

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

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

Возврат

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

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

curl https://payquity.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"
}'

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

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

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

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

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

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

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

{
    "success": false,
    "error": {
        "code": "6",
        "message": "error",
        "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
    }
}

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

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

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

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

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

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

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

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

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

{
    "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@payquity.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",
            "details": {
                "account": "411111******1111",
                "paymentToken": "837c06b4-b791-4f2c-89b1-a45f78cb1568"
            },
            "status": {
                "name": "PaymentPaid"
            }
        }
    ]
}

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

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

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

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

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

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

{
    "success": false,
    "error": {
        "code": "5",
        "message": "error",
        "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
    }
}

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

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

Оплата счета

Метод позволяет передать детали платежа для осуществления оплаты.

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

curl https://payquity.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"
        }
    }
}'

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

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

Описание параметров details для способа оплаты BankCard

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

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

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

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

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

{
    "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": "5",
        "message": "error",
        "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
    }
}

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

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

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

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

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

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

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

curl https://payquity.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@payquity.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": "Ошибка создания подписки",
        "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
    }
}

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

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

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

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

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

curl https://payquity.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",
        "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
    }
}

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

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

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

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

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

curl https://payquity.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"
}'

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

Описание параметров объекта 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"
}

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

{
    ...
    "destination": {
        "account": "45X2XTPWXUCJK2AJRRBMA"
    },
    "payoutMethod": "Qand"
}

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

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

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

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

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

{
    "success": false,
    "error": {
        "code": "9",
        "message": "Ошибка создания выплаты",
        "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
    }
}

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

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

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

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

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

curl https://payquity.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": "8041905d-c3cb-4c83-a232-1a98891023b8",
        "uuid": "8904c0ef-7667-4ec2-b63a-57c50faf0248",
        "commission": {
            "amount": "12.33",
            "currency": "RUB"  
        },
        "payoutMethod": "BankCard",
        "amount": 813.03,
        "currency": "RUB",
        "description": "some description",
        "destination": {
            "masked_pan": "411111******1111"
        },
        "status": {
            "name": "PayoutSucceeded",
            "time": "2022-04-13 08:42:22.501903+00:00",
            "message": "Получено событие о удачном проведении транзакции на выплату"
        }
    }
}

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

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

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

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

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

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

{
    "success": false,
    "error": {
        "code": "10",
        "message": "error",
        "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
    }
}

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

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

Подтверждение двухэтапной выплаты

Метод позволяет подтверждать двухэтапную выплату. Подтверждение выполняется для выплаты в статусе PayoutWaitingConfirmation. Для активации возможности создавать двухэтапные выплаты необходимо связаться с менеджером Payquity.

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

curl https://payquity.io/merchant-api/api/v2/payouts/<uuid>/confirm \
  -X POST \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{}'

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

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

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

{
    "success": true,
    "data": {
        "uuid": "8904c0ef-7667-4ec2-b63a-57c50faf0248"
}

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

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

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

{
    "success": false,
    "error": {
        "code": "13",
        "message": "Ошибка подтверждения выплаты",
        "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
    }
}

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

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

Отклонение двухэтапной выплаты

Метод позволяет отклонять двухэтапную выплату. Отклонение выполняется для выплаты в статусе PayoutWaitingConfirmation. Для активации возможности создавать двухэтапные выплаты необходимо связаться с менеджером Payquity.

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

curl https://payquity.io/merchant-api/api/v2/payouts/<uuid>/decline \
  -X POST \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{}'

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

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

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

{
    "success": true,
    "data": {
        "uuid": "8904c0ef-7667-4ec2-b63a-57c50faf0248"
}

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

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

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

{
    "success": false,
    "error": {
        "code": "14",
        "message": "Ошибка отклонения выплаты",
        "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
    }
}

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

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

Создание виртуальной банковской карты

Метод позволяет создать виртуальную банковскую карту для пользователя.

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

1. Магазин отправляет в Payquity запрос на создание виртуальной банковской карты, где указывает адрес электронной почты, имя и фамилию владельца карты;
2. В случае если карта создана успешно, то Payquity возвращает магазину ответ, который содержит уникальный идентификатор карты, а пользователю, на указанный в запросе email, отправляет ссылку для регистрации в системе Qand.

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

curl https://payquity.io/merchant-api/api/v2/bankCards \
  -X POST \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "email": "email@payquity.io",
    "firstName": "Ivan",
    "lastName": "Ivanov",
    "externalId": "bbf878ededda4b278265e08ee8a8c5c2"
}'

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

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

{
    "success": true,
    "data": {
        "externalId": "bbf878ededda4b278265e08ee8a8c5c2",
        "uuid": "45X2XTPWXUCJK2AJRRBMA"
    }
}

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

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

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

{
    "success": false,
    "error": {
        "code": "11",
        "message": "Ошибка создания банковской карты",
        "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
    }
}

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

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

Получение данных виртуальной банковской карты

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

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

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

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

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

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

{
    "success": true,
    "data": {
        "uuid": "8KQQS75060WAZGYR2L",
        "panStart": "556735",
        "panEnd": "4500",
        "expYear": "25",
        "expMonth": "10",
        "brand": "MasterCard",
        "balance": {
            "currency": "USD",
            "amount": 10
        },
        "status": "Active"
    }
}

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

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

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

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

{
    "success": false,
    "error": {
        "code": "12",
        "message": "error",
        "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
    }
}

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

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

Google Pay^TM

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

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

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

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

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

1. Клиент в интернет-магазине оформляет заказ и для оплаты выбирает способ GPay.
2. Магазин отправляет запрос на создание счета в Payquity.
3. Payquity обрабатывает запрос и, если счет создан корректно, возвращает его уникальный идентификатор uuid.
4. Магазин отправляет запрос на оплату в Google Pay API.
5. Система Google Pay^TM по полученным платежным данным формирует токен.
6. Магазин в ответ на запрос получает сформированный токен.
7. Магазин формирует запрос на передачу деталей платежа в систему Payquity, где в адресе запроса указывает uuid полученный при создании счета, а в параметре details - токен полученный от Google Pay API.
8. Payquity обрабатывает запрос и для транзакций PAN_ONLY возвращает ссылку для перенаправления клиента на форму ввода 3DS.
9. Магазин для завершения аутентификации 3DS перенаправляет клиента на адрес, указанный в параметре data.redirect.url в ответе Payquity.
10. Payquity отправляет магазину уведомление об успешной/неуспешной оплате счета.
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": "payquity",
                    "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. Токенизация карт выполняется через шлюз payquity. Запрос способа платежа осуществляется для выставления окончательного счета на сумму 123,12 рублей.

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

Объект allowedPaymentMethods

Объект allowedPaymentMethods.parameters

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

Объект allowedPaymentMethods.tokenizationSpecification

Объект allowedPaymentMethods.tokenizationSpecification.parameters

Объект transactionInfo

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

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

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

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

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

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

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

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

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

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

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

curl https://payquity.io/resultUrl \
  -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",
    "amount": 105.05,
    "finalAmount": 123.12,
    "currency": "RUB",
    "description": "Счет на оплату заказа №12080",
    "customerPhone": "+74994550185",
    "customerEmail": "support@payquity.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",
            "details": {
                "account": "411111******1111",
                "paymentToken": "837c06b4-b791-4f2c-89b1-a45f78cb1568"
            },
            "status": {
                "name": "PaymentPaid"
            }
        }
    ]
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

curl https://payquity.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",
    "commission": {
        "amount": "12.33",
        "currency": "RUB"  
    },
    "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"
    },
    "payoutMethod": "BankCard"
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для отправки фискальных данных используется протокол, совместимый с протоколом АТОЛ; поддерживаемый провайдер данных — АТОЛ. Для подключения возможности передавать фискальные данные необходимо сообщить данные аккаунта АТОЛ менеджеру Payquity. Важно: Параметры, которые не должны быть указаны в 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

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

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

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

«advance» — аванс.

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

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

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

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

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

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

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

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

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

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

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

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

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

«commodity» — товар.

«excise» — подакцизный товар.

«job» — работа.

«service» — услуга.

«gambling_bet» — ставка азартной игры.

«gambling_prize» — выигрыш азартной игры.

«lottery» — лотерейный билет.

«lottery_prize» — выигрыш лотереи.

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

«payment» — платеж.

«agent_commission» — агентское вознаграждение.

«composite» — составной предмет расчета.

«another» — иной предмет расчета.

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

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

«insurance_premium» — страховые взносы.

«sales_tax» — торговый сбор.

«resort_fee» — курортный сбор.

Описание подпараметра 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

С последней версией протокола АТОЛ можно ознакомиться на официальном сайте АТОЛ.