title

API P2P-счетов 1.0.0

true

metatitle

API P2P-счетов 1.0.0

P2P-счета

Последнее обновление: 06-06-2022

Условия использования {#terms}

Чтобы подключить на свой сайт сервис приема p2p-переводов для физических лиц, вам необходим QIWI Кошелек со статусом идентификации Основной или Профессиональный. Если у вашего кошелька статус Анонимный, пройдите идентификацию удобным для вас способом:

Для получения статуса Основной достаточно указать паспортные данные.
Для получения статуса Профессиональный необходимо пройти очную идентификацию.

Рекомендуем сразу получить статус Профессиональный. Такой статус имеет повышенные лимиты на остаток на балансе, сумму платежей и переводов в месяц, максимальную сумму одной операции. Подробнее про лимиты.

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

Активация доступа к сервису {#p2p-activate}

Авторизуйтесь на p2p.qiwi.com
Убедитесь, что вам доступно выставление счетов – в форме Выставить счет заполните поле Сумма и нажмите кнопку. Ниже должна появиться ссылка на счет и кнопка Скопировать ссылку

Поздравляем! Вы можете приступить к интеграции.

Как работать с сервисом {#how-to-start}

Создайте публичный и секретный ключи. Подробнее см. в разделе Методы авторизации.
Реализуйте взаимодействие через API или через вызов формы оплаты счета. Вы можете воспользоваться SDK или готовыми решениями для CMS.
Для получения уведомлений после перевода по счету активируйте их отправку.
Начните принимать платежи с банковских карт или c QIWI Кошельков.

Сценарий платежа {#payment-scenario}

sequenceDiagram participant user as Пользователь participant rec as Получатель participant p2p as QIWI P2P API opt Основной сценарий user->>rec:Оформление заказа activate user activate rec alt Использование API rec->>p2p:Выставление счета p2p->>rec:Ссылка на платежную форму rec->>user:Перенаправление на платежную форму
oplata.qiwi.com end alt Использование платежной формы rec->>user:Выставление счета через форму
oplata.qiwi.com end deactivate rec user->>p2p:Выбор способа оплаты и подтверждение платежа p2p->>p2p:Оплата счета opt Возврат на страницу партнера p2p->>user:Возврат на страницу партнера end deactivate user end opt Дополнительный сценарий opt Уведомления (callback) activate p2p activate rec p2p->>rec:Уведомление об успешной оплате rec->>p2p:Уведомление принято deactivate rec deactivate p2p end opt Проверка статуса activate p2p activate rec rec->>p2p:Проверка статуса счета p2p->>rec:Информация о счете deactivate rec deactivate p2p end end

Пользователь формирует счет на вашей стороне.
Вы перенаправляете пользователя на платежную форму для выставления и оплаты счета в сервисе. Или выставляете счет по API и также перенаправляете пользователя на созданную платежную форму (ссылка на форму придет в ответе).
Пользователь выбирает способ перевода и подтверждает перевод. По умолчанию на форме отображается оптимальный для пользователя способ перевода.
После перевода по счету вы получите уведомление, если активировали отправку уведомлений. Уведомления о переводе по счету содержат цифровую подпись, которую необходимо проверять на вашем сервере.

Также через API вы можете:

запросить текущий статус перевода по счету,
отменить неиспользуемый счет.

SDK и библиотеки {#sdk}

NODE JS SDK — Готовое решение для разработки server2server интеграции c помощью Node.js.
PHP SDK — Готовое решение для разработки server2server интеграции c помощью PHP.
Java SDK — Готовое решение для разработки server2server интеграции c помощью Java.
.Net SDK — Готовое решение для разработки server2server интеграции c помощью C# .NET.

С руководством по работе с SDK можно ознакомиться здесь.

Решения для CMS {#cms}

Онлайн Лейка — Wordpress расширение для благотворительности.
1С-Битрикс — решение для работы с заказами.
Opencart — решение для работы с заказами.
PrestaShop — решение для работы с заказами.

Методы авторизации в сервисе {#auth}

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

const QiwiBillPaymentsAPI = require('@qiwi/bill-payments-node-js-sdk');

const SECRET_KEY = 'eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjUyNjgxMiwiYXBpX3VzZXJfaWQiOjcxNjI2MTk3LCJzZWNyZXQiOiJmZjBiZmJiM2UxYzc0MjY3YjIyZDIzOGYzMDBkNDhlYjhiNTnONPININONPN090MTg5Z**********************';

const qiwiApi = new QiwiBillPaymentsAPI(SECRET_KEY);

--header "Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******"

<?php

const SECRET_KEY = 'eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjUyNjgxMiwiYXBpX3VzZXJfaWQiOjcxNjI2MTk3LCJzZWNyZXQiOiJmZjBiZmJiM2UxYzc0MjY3YjIyZDIzOGYzMDBkNDhlYjhiNTnONPININONPN090MTg5Z**********************';

/** @var \Qiwi\Api\BillPayments $billPayments */
$billPayments = new Qiwi\Api\BillPayments(SECRET_KEY);

?>

String secretKey = "eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjUyNjgxMiwiYXBpX3VzZXJfaWQiOjcxNjI2MTk3LCJzZWNyZXQiOiJmZjBiZmJiM2UxYzc0MjY3YjIyZDIzOGYzMDBkNDhlYjhiNTnONPININONPN090MTg5Z**********************";
 BillPaymentClient client = BillPaymentClientFactory.createDefault(secretKey);

var secretKey = "eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjUyNjgxMiwiYXBpX3VzZXJfaWQiOjcxNjI2MTk3LCJzZWNyZXQiOiJmZjBiZmJiM2UxYzc0MjY3YjIyZDIzOGYzMDBkNDhlYjhiNTnONPININONPN090MTg5Z**********************";

var client = BillPaymentClientFactory.createDefault(secretKey);

Для авторизации запросов вам понадобятся ключи:

Секретный ключ <SECRET_KEY> — для авторизации запросов к API P2P-счетов по стандарту OAuth 2.0. Ключ указывается в заголовке HTTP-запроса Authorization: Bearer <SECRET_KEY>.
Публичный ключ <PUBLIC_KEY> — для авторизации при выставлении счетов через форму.

Чтобы выпустить пару ключей <SECRET_KEY> и <PUBLIC_KEY>:

Авторизуйтесь в личном кабинете https://p2p.qiwi.com/.
Перейдите на вкладку API и нажмите кнопку Создать пару ключей и настроить. Если вы создаете пару ключей впервые, то нажмите кнопку Настроить.
Укажите название для пары ключей и нажмите кнопку Создать.
Сохраните секретный ключ в безопасном месте — в дальнейшем он не будет отображаться в интерфейсе. Публичный ключ вы всегда можете скопировать из Личного кабинета.
Нажмите кнопку Дальше. Пара ключей будет активирована.

Не передавайте секретный ключ третьим лицам!

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

Вы можете использовать секретный ключ также для автоматизации платежных операций по QIWI Кошельку:

Подробнее см. в документации API QIWI Кошелька.

Выставление счета через форму {#http-invoice}

Этим способом доступно выставление счетов только в рублях. Для выставления счетов в тенге используйте API, SDK или решения для CMS. При открытии формы в webview на android обязательно включать settings.setDomStorageEnabled(true)

Простой способ для интеграции. При переходе на форму клиенту автоматически выставляется счет. Параметры счета передаются в открытом виде в ссылке. Далее клиенту отображается форма с выбором способа перевода.

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

GET →

URL https://oplata.qiwi.com/create

const publicKey = 'Fnzr1yTebUiQaBLDnebLMMxL8nc6FF5zfmGQnypc*******';

const params = {
    publicKey,
    amount: 42.24,
    billId: 'cc961e8d-d4d6-4f02-b737-2297e51fb48e',
    successUrl: 'http://example.com/success/',
    email: 'mail@example.com'
};

const link = qiwiApi.createPaymentForm(params);

curl https://oplata.qiwi.com/create?publicKey=Fnzr1yTebUiQaBLDnebLMMxL8nc6FF5zfmGQnypc*******&amount=100&successUrl=http%3A%2F%2Fexample.com%3Fsuccess%3F&email=mail@example.com&customFields[paySourcesFilter]=qw,card&lifetime=2020-12-01T0509

<?php

$publicKey = '2tbp1WQvsgQeziGY9vTLe9vDZNg7tmCymb4Lh6STQokqKrpCC6qrUUKEDZAJ7mvFnzr1yTebUiQaBLDnebLMMxL8nc6FF5zf******';
$params = [
  'publicKey' => $publicKey,
  'amount' => 200,
  'billId' => 'cc961e8d-d4d6-4f02-b737-2297e51fb48e'
];

/** @var \Qiwi\Api\BillPayments $billPayments */
$link = $billPayments->createPaymentForm($params);

echo $link;

?>

String publicKey = "2tbp1WQvsgQeziGY9vTLe9vDZNg7tmCymb4Lh6STQokqKrpCC6qrUUKEDZAJ7mvFnzr1yTebUiQaBLDnebLMMxL8nc6FF5zfmGQnypdXCbQJqHEJW5RJmKfj8nvgc";
 MoneyAmount amount = new MoneyAmount(
        BigDecimal.valueOf(499.90),
        Currency.getInstance("RUB")
);
String billId = UUID.randomUUID().toString();
String successUrl = "https://example.com/payment/success?billId=cc961e8d-d4d6-4f02-b737-2297e51fb48e";
 String paymentUrl = client.createPaymentForm(new PaymentInfo(key, amount, billId, successUrl));

var publicKey = "2tbp1WQvsgQeziGY9vTLe9vDZNg7tmCymb4Lh6STQokqKrpCC6qrUUKEDZAJ7mvFnzr1yTebUiQaBLDnebLMMxL8nc6FF5zfmGQnypdXCbQJqHEJW5RJmKfj8nvgc";

var amount = new MoneyAmount
{
    ValueDecimal = 499.9m,
    CurrencyEnum = CurrencyEnum.Rub
};
var billId = Guid.NewGuid().ToString();
var successUrl = "https://example.com/payment/success?billId=cc961e8d-d4d6-4f02-b737-2297e51fb48e";

var paymentUrl = client.createPaymentForm(new PaymentInfo(key, amount, billId, successUrl));

Параметры
В ссылке на веб-форму указываются параметры счета.

Параметр	Описание	Тип
publicKey	Обязательный параметр. Ваш публичный ключ для формы переводов, полученный на сайте p2p.qiwi.com	String
billId	Идентификатор выставляемого счета в вашей системе. Он должен быть уникальным и генерироваться на вашей стороне любым способом. Идентификатором может быть любая уникальная последовательность букв или цифр. Также разрешено использование символа подчеркивания (`_`) и дефиса (`-`).	String(200)
amount	Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков	Number(6.2)
phone	Номер телефона пользователя (в международном формате)	URL-Encoded String
email	E-mail пользователя	URL-Encoded String
account	Идентификатор пользователя в вашей системе	URL-Encoded String
comment	Комментарий к счету	URL-Encoded String(255)
customFields[]	Дополнительные данные счета	URL-Encoded String(255)
customFields[paySourcesFilter]	При открытии формы будут отображаться только указанные способы перевода, если они доступны. Возможные значения (можно указать все, через `,`): `qw` - QIWI Кошелек, `card` - банковская карта, `mobile` - баланс телефона (телефон получателя будет виден отправителю).	URL-Encoded String
customFields[themeCode]	Код персонализации вашей формы	String(255)
lifetime	Дата, до которой счет будет доступен для перевода. Если перевод по счету не будет произведен до этой даты, ему присваивается финальный статус `EXPIRED` и последующий перевод станет невозможен. Внимание! По истечении 45 суток от даты выставления счет автоматически будет переведен в финальный статус	URL-Encoded String `ГГГГ-ММ-ДДTччмм`
successUrl	URL для переадресации на ваш сайт в случае успешного перевода	URL-Encoded String

API P2P-счетов. Выставление счета {#create}

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

Доступно выставление счетов в рублях и тенге.

Надежный способ для интеграции. Параметры передаются server2server с использованием авторизации.

При успешном выполнении запроса в ответе вернется параметр payUrl — ссылка для перенаправления пользователя на форму оплаты. К ней вы можете добавить дополнительные параметры. Подробнее см. в разделе Форма для оплаты счета.

Рекомендуем воспользоваться SDK для интеграции.

Также существует более простой способ выставления счета — непосредственно через вызов платежной формы.

Для тестирования и отладки сервиса рекомендуем выставлять и оплачивать счета суммой 1 рубль.

Ознакомьтесь со статьями Кошелек заблокирован. Что делать? и Как избежать блокировки кошелька.

Запрос → PUT

const billId = 'cc961e8d-d4d6-4f02-b737-2297e51fb48e';

const fields = {
    amount: 1.00,
    currency: 'RUB',
    comment: 'Hello world',
    expirationDateTime: '2018-03-02T08:44:07+03:00'
};

qiwiApi.createBill( billId, fields ).then( data => {
    //do with data
});

curl --location \
  --request PUT \
  'https://api.qiwi.com/partner/bill/v1/bills/cc961e8d-d4d6-4f02-b737-2297e51fb48e' \
  --header 'content-type: application/json' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer <SECRET_KEY>' \
  --data-raw '{  
     "amount": {   
       "currency": "RUB",   
       "value": "1.00" 
     },  
     "comment": "Text comment",  
     "expirationDateTime": "2025-12-10T09:02:00+03:00",  
     "customer": {
       "phone": "78710009999",
       "email": "test@example.com",
       "account": "454678"
     }, 
     "customFields" : {
       "paySourcesFilter":"qw",
       "themeCode": "Yvan-YKaSh",
       "yourParam1": "64728940",
       "yourParam2": "order 678"
     }
  }'

<?php

$billId = 'cc961e8d-d4d6-4f02-b737-2297e51fb48e';
$fields = [
  'amount' => 1.00,
  'currency' => 'RUB',
  'comment' => 'test',
  'expirationDateTime' => '2018-03-02T08:44:07+03:00',
  'email' => 'mail@example.org',
  'account' => 'client4563'
];

/** @var \Qiwi\Api\BillPayments $billPayments */
$response = $billPayments->createBill($billId, $fields);

print_r($response);

?>

CreateBillInfo billInfo = new CreateBillInfo(
                UUID.randomUUID().toString(),
                new MoneyAmount(
                        BigDecimal.valueOf(199.90),
                        Currency.getInstance("RUB")
                ),
                "comment",
                ZonedDateTime.now().plusDays(45),
                new Customer(
                        "mail@example.org",
                        UUID.randomUUID().toString(),
                        "79123456789"
                ),
                "http://example.com/success"
        );
BillResponse response = client.createBill(billInfo);

client.CreateBill(
    info: new CreateBillInfo
    {
        BillId = Guid.NewGuid().ToString(),
        Amount = new MoneyAmount
        {
            ValueDecimal = 199.9m,
            CurrencyEnum = CurrencyEnum.Rub
        },
        Comment = "comment",
        ExpirationDateTime = DateTime.Now.AddDays(45),
        Customer = new Customer
        {
            Email = "mail@example.org",
            Account = Guid.NewGuid().ToString(),
            Phone = "79123456789"
        },
        SuccessUrl = new Uri("http://example.com/success"),
        CustomFields: new CustomFields
        {
            ThemeCode = "кодСтиля"
        }
    }
);

URL https://api.qiwi.com/partner/bill/v1/bills/{billid}
- billId - сгенерированный на вашей стороне любым способом идентификатор счета. Идентификатором может быть любая уникальная последовательность букв или цифр. Также разрешено использование символа подчеркивания (_) и дефиса (-).

HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json
- Accept: application/json

Параметр тела запроса	Описание	Тип
amount	Обязательный параметр. Информация о сумме счета	Object
amount. value	Обязательный параметр. Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков	Number(6.2)
amount. currency	Обязательный параметр. Валюта суммы счета. Возможные значения: `RUB` - рубли, `KZT` - тенге.	Alpha-3 ISO 4217 код
expirationDateTime	Обязательный параметр. Дата, до которой счет будет доступен для оплаты. Если перевод не будет совершен до этой даты, ему присваивается финальный статус `EXPIRED` и последующий перевод станет невозможен.	`ГГГГ-ММ-ДДTчч:мм:сс±чч:мм`
customer	Идентификаторы пользователя	Object
customer. phone	Номер телефона пользователя (в международном формате)	String
customer. email	E-mail пользователя	String
customer. account	Идентификатор пользователя в вашей системе	String
comment	Комментарий к счету	String(255)
customFields	Дополнительная информация о счете. Вы можете здесь передавать свои дополнительные поля с данными, например, `SteamId`	Object
customFields. paySourcesFilter	Строка с разделителями-запятыми. При открытии формы будут отображаться только указанные способы перевода (один или несколько), если они доступны. Возможные значения: `qw` - QIWI Кошелек, `card` - банковская карта, `mobile` - баланс телефона (телефон получателя будет виден отправителю).	String
customFields. themeCode	Код персонализации вашей формы	String(255)

Ответ ←

Пример тела ответа

{
    "siteId": "9hh4jb-00",
    "billId": "cc961e8d-d4d6-4f02-b737-2297e51fb48e",
    "amount": {
        "currency": "RUB",
        "value": "1.00"
    },
    "status": {
        "value": "WAITING",
        "changedDateTime": "2021-01-18T14:22:56.672+03:00"
    },
    "customer": {
        "phone": "78710009999",
        "email": "test@example.com",
        "account": "454678"
    },
    "customFields": {
        "paySourcesFilter": "qw",
        "themeCode": "Yvan-YKaSh",
        "yourParam1": "64728940",
        "yourParam2": "order 678"
    },
    "comment": "Text comment",
    "creationDateTime": "2021-01-18T14:22:56.672+03:00",
    "expirationDateTime": "2025-12-10T09:02:00+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=aa0fa2bb-5452-47ca-9190-cd9c1a73718f"
}

Пример тела ответа при ошибке

{
    "serviceName": "invoicing-api",
    "errorCode": "http.message.conversion.failed",
    "description": "Bad request",
    "userMessage": "Bad request",
    "dateTime": "2021-01-18T14:29:51.984+03:00",
    "traceId": "8fa9cfe10c7f83d1"
}

HEADERS
- Content-Type: application/json

Поле	Тип	Описание
siteId	String	Ваш идентификатор в сервисе приема платежей для физических лиц p2p.qiwi.com
billId	String	Уникальный идентификатор счета в вашей системе, указанный при выставлении
amount	Object	Информация о сумме счета
amount. value	Number	Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
amount. currency	String	Валюта суммы счета (Alpha-3 ISO 4217 код)
status	Object	Информация о статусе счета
status. value	String	Текущий статус счета
status. changedDateTime	String	Дата обновления статуса. Формат даты: `ГГГГ-ММ-ДДTчч:мм:сс±чч:мм`
customFields	Object	Объект строковых дополнительных параметров. Возможные элементы: `paySourcesFilter`, `themeCode`
customer	Object	Идентификаторы пользователя. Возможные элементы: `email`, `phone`, `account`
comment	String	Комментарий к счету
creationDateTime	String	Системная дата создания счета. Формат даты: `ГГГГ-ММ-ДДTчч:мм:сс±чч:мм`
expirationDateTime	String	Срок действия созданной формы для перевода. Формат даты: `ГГГГ-ММ-ДДTчч:мм:сс±чч:мм`
payUrl	String	Ссылка на созданную форму. Перенаправьте пользователя по этой ссылке для оплаты счета или используйте библиотеку Popup, чтобы открыть форму во всплывающем окне.

API P2P-счетов. Проверка статуса перевода по счету {#invoice-status}

Рекомендуется использовать этот метод после получения уведомления о переводе.

Запрос → GET

const billId = 'cc961e8d-d4d6-4f02-b737-2297e51fb48e';

qiwiApi.getBillInfo(billId).then( data => {
    //do smth with data
});

curl --location \
  --request GET \
  'https://api.qiwi.com/partner/bill/v1/bills/cc961e8d-d4d6-4f02-b737-2297e51fb48e' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer <SECRET_KEY>'

<?php

$billId = 'cc961e8d-d4d6-4f02-b737-2297e51fb48e';

/** @var \Qiwi\Api\BillPayments $billPayments */
$response = $billPayments->getBillInfo($billId);

print_r($response);

?>

String billId = "cc961e8d-d4d6-4f02-b737-2297e51fb48e";
 BillResponse response = client.getBillInfo(billId);

var billId = "cc961e8d-d4d6-4f02-b737-2297e51fb48e";

var response = client.getBillInfo(billId);

URL https://api.qiwi.com/partner/bill/v1/bills/{billid}
- billId — уникальный идентификатор счета в вашей системе.

HEADERS
- Authorization: Bearer SECRET_KEY
- Accept: application/json

Ответ ←

Пример тела ответа

{
    "siteId": "9hh4jb-00",
    "billId": "cc961e8d-d4d6-4f02-b737-2297e51fb48e",
    "amount": {
        "currency": "RUB",
        "value": "1.00"
    },
    "status": {
        "value": "WAITING",
        "changedDateTime": "2021-01-18T14:22:56.672+03:00"
    },
    "customer": {
        "email": "test@example.com",
        "phone": "78710009999",
        "account": "454678"
    },
    "customFields": {
        "paySourcesFilter": "qw",
        "themeCode": "Yvan-YKaSh",
        "yourParam1": "64728940",
        "yourParam2": "order 678"
    },
    "comment": "Text comment",
    "creationDateTime": "2021-01-18T14:22:56.672+03:00",
    "expirationDateTime": "2025-12-10T09:02:00+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=aa0fa2bb-5452-47ca-9190-cd9c1a73718f"
}

Пример тела ответа при ошибке

{
    "serviceName": "invoicing-api",
    "errorCode": "api.invoice.not.found",
    "description": "Invoice not found",
    "userMessage": "Invoice not found",
    "dateTime": "2021-01-18T14:34:40.865+03:00",
    "traceId": "b3d41cafa0c6d088"
}

HEADERS
- Content-Type: application/json

Поле	Тип	Описание
billId	String	Уникальный идентификатор счета в вашей системе, указанный при выставлении
siteId	String	Ваш идентификатор в сервисе приема платежей для физических лиц p2p.qiwi.com
amount	Object	Информация о сумме счета
amount. value	Number	Сумма счета, округленная до 2 знаков после запятой в меньшую сторону.
amount. currency	String	Идентификатор валюты суммы счета (Alpha-3 ISO 4217 код)
status	Object	Информация о статусе счета
status. value	String	Текущий статус счета
status. changedDateTime	String	Дата обновления статуса
customFields	Object	Объект строковых дополнительных параметров, переданных вами
customer	Object	Идентификаторы пользователя
customer. phone	String	Номер телефона (если был указан при выставлении счета)
customer. email	String	E-mail пользователя (если был указан при выставлении счета)
customer. account	String	Идентификатор пользователя в вашей системе (если был указан при выставлении счета)
comment	String	Комментарий к счету
creationDateTime	String	Системная дата создания счета. Формат даты: `ГГГГ-ММ-ДДTчч:мм:сс`
payUrl	String	Ссылка для переадресации пользователя на созданную форму
expirationDateTime	String	Срок действия созданной формы для перевода. Формат даты: `ГГГГ-ММ-ДДTчч:мм:сс±чч:мм`

API P2P-счетов. Отмена неоплаченного счета {#cancel}

Вы можете отменить счет, по которому не был выполнен перевод.

Запрос → POST

const bill_id = 'cc961e8d-d4d6-4f02-b737-2297e51fb48e';

qiwiApi.cancelBill(billId).then( data => {
    //do with data
});

curl --location \
  --request POST \
  'https://api.qiwi.com/partner/bill/v1/bills/cc961e8d-d4d6-4f02-b737-2297e51fb48e/reject' \
  --header 'content-type: application/json' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer <SECRET_KEY>' \
  --data-raw ''

<?php

$billId = 'cc961e8d-d4d6-4f02-b737-2297e51fb48e';

/** @var \Qiwi\Api\BillPayments $billPayments */
$response = $billPayments->cancelBill($billId);

print_r($response);

?>

String billId = "cc961e8d-d4d6-4f02-b737-2297e51fb48e";
 BillResponse response = client.cancelBill(billId);

var billId = "cc961e8d-d4d6-4f02-b737-2297e51fb48e";

var response = client.cancelBill(billId);

URL https://api.qiwi.com/partner/bill/v1/bills/{billId}/reject
- billId — уникальный идентификатор счета в вашей системе.

HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json
- Accept: application/json

Ответ ←

Пример тела ответа

{
    "siteId": "9hh4jb-00",
    "billId": "cc961e8d-d4d6-4f02-b737-2297e51fb48e",
    "amount": {
        "currency": "RUB",
        "value": "1.00"
    },
    "status": {
        "value": "REJECTED",
        "changedDateTime": "2021-01-18T14:36:17.65+03:00"
    },
    "customer": {
        "email": "test@example.com",
        "phone": "78710009999",
        "account": "454678"
    },
    "customFields": {
        "paySourcesFilter": "qw",
        "themeCode": "Yvan-YKaSh",
        "yourParam1": "64728940",
        "yourParam2": "order 678"
    },
    "comment": "Text comment",
    "creationDateTime": "2021-01-18T14:22:56.672+03:00",
    "expirationDateTime": "2025-12-10T09:02:00+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=aa0fa2bb-5452-47ca-9190-cd9c1a73718f"
}

Пример тела ответа при ошибке

{
    "serviceName": "invoicing-api",
    "errorCode": "api.invoice.not.found",
    "description": "Invoice not found",
    "userMessage": "Invoice not found",
    "dateTime": "2021-01-18T14:39:54.265+03:00",
    "traceId": "bc6bb6e7c5cf5beb"
}

HEADERS
- Content-Type: application/json

Поле	Тип	Описание
billId	String	Уникальный идентификатор счета в вашей системе, указанный при выставлении
siteId	String	Ваш идентификатор в сервисе приема платежей для физических лиц p2p.qiwi.com
amount	Object	Информация о сумме счета
amount. value	Number	Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
amount. currency	String	Идентификатор валюты суммы счета (Alpha-3 ISO 4217 код)
status	Object	Информация о статусе счета
status. value	String	Текущий статус счета
status. changedDateTime	String	Дата обновления статуса. Формат даты: `ГГГГ-ММ-ДДTчч:мм:сс±чч:мм`
customFields	Object	Объект строковых дополнительных параметров. Возможные элементы: `paySourcesFilter`, `themeCode`
customer	Object	Идентификаторы пользователя. Возможные элементы: `email`, `phone`, `account`
comment	String	Комментарий к счету
creationDateTime	String	Системная дата создания счета. Формат даты: `ГГГГ-ММ-ДДTчч:мм:сс`
payUrl	String	Ссылка на созданную платежную форму
expirationDateTime	String	Срок действия созданной формы для перевода. Формат даты: `ГГГГ-ММ-ДДTчч:мм:сс±чч:мм`

API P2P-счетов. Статусы оплаты счетов {#status}

Статус	Описание	Финальный
WAITING	Счет выставлен, ожидает оплаты	-
PAID	Счет оплачен	+
REJECTED	Счет отклонен	+
EXPIRED	Время жизни счета истекло. Счет не оплачен	+

Уведомления о переводе по счету {#notification}

Сервис не является обязательным для интеграции, вы можете реализовать более простой вариант с опросом статуса счета.

Перед началом работы с сервисом уведомлений прочитайте условия по интеграции API уведомлений.

Пулы IP-адресов, с которых сервисы QIWI отправляют уведомления:

79.142.16.0/20
195.189.100.0/22
91.232.230.0/23
91.213.51.0/24

Если ваш сервер обработки уведомлений работает за брандмауэром, необходимо добавить эти IP-адреса в список разрешенных адресов входящих TCP-пакетов.

Уведомление о переводе (callback) отправляется только по протоколу HTTPS и только на 443 порт.

Сертификат должен быть выдан доверенным центром сертификации (например, Comodo, Verisign, Thawte и т.п.).

Уведомление представляет собой входящий HTTP POST-запрос.

Запрос ← POST

Пример уведомления

POST /qiwi-notify.php HTTP/1.1
Accept: application/json
Content-type: application/json
X-Api-Signature-SHA256: J4WNfNZd***V5mv2w=
Host: example.com

{
  "bill": {
    "siteId": "9hh4jb-00",
    "billId": "cc961e8d-d4d6-4f02-b737-2297e51fb48e",
    "amount": {
      "value": "1.00",
      "currency": "RUB"
    },
    "status": {
      "value": "PAID",
      "changedDateTime": "2021-01-18T15:25:18+03"
    },
    "customer": {
      "phone": "78710009999",
      "email": "test@example.com",
      "account": "454678"
    },
    "customFields": {
      "paySourcesFilter": "qw",
      "themeCode": "Yvan-YKaSh",
      "yourParam1": "64728940",
      "yourParam2": "order 678"
    },
    "comment": "Text comment",
    "creationDateTime": "2021-01-18T15:24:53+03",
    "expirationDateTime": "2025-12-10T09:02:00+03"
  },
  "version": "1"
}

Тело запроса содержит JSON-сериализованные данные счета (кодировка UTF-8).

HEADERS
- X-Api-Signature-SHA256: XXX
- Accept: application/json
- Content-type: application/json

Заголовки по стандарту регистронезависимы и ваш клиент может их изменить — смотрите документацию вашего клиента. Если в ответе код состояния HTTP отличается от 200 (OK), это интерпретируется как временная ошибка в вашей системе. Сервер QIWI будет повторять запрос с нарастающим интервалом в течение суток. Уведомление может быть отправлено несколько раз даже в случае успешного ответа от вашего сервиса. Учитывайте это при разработке бизнес-логики на вашей стороне.

Регистрация сервера уведомлений {#notification-server}

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

Адрес сервера для уведомлений настраивается в Личном кабинете P2P. При этом выпускается новая пара ключей для авторизации.

Вы можете выполнить настройку сервера уведомлений только для одной пары ключей.

Авторизуйтесь в Личном кабинете P2P.
Перейдите на вкладку API и нажмите кнопку Создать пару ключей и настроить. Если вы настраиваете адрес сервера вместе с первичным созданием пары ключей впервые, то нажмите кнопку Настроить.
Укажите название для новой пары ключей.
Выделите поле Использовать эту пару ключей для серверных уведомлений об изменении статусов счетов.
В поле URL сервера для уведомлений укажите адрес вашего сервера для обработки уведомлений об оплате. Внимание! Сервер должен быть доступен из интернета.
Нажмите кнопку Создать.
Замените в настройках ваших приложений ключи для сервиса QIWI P2P на вновь созданные.

Проверка подлинности уведомлений {#notification-auth}

После получения входящего уведомления необходимо проверить его подлинность. Для этого используется механизм цифровой подписи. Подпись уведомления отправляется в HTTP–заголовке X-Api-Signature-SHA256. Для формирования подписи используется механизм проверки целостности HMAC с хеш-функцией SHA256.

Алгоритм проверки подписи:

Объединить значения следующих параметров уведомления в одну строку с разделителем |:

invoice_parameters = {amount.currency}|{amount.value}|{billId}|{siteId}|{status.value}

где {*} – значение параметра. Все значения при проверке подписи должны трактоваться как строки.
Вычислить HMAC-хеш c алгоритмом хеширования SHA256:

hash = HMAС(SHA256, invoice_parameters, <SECRET_KEY>)

Где:
- <SECRET_KEY> – секретный ключ, при помощи которого был выставлен счёт;
- invoice_parameters – строка из п.1.
Сравнить значение заголовка X-Api-Signature-SHA256 с результатом из п.2.

const validSignatureFromNotificationServer =
      '07e0ebb10916d97760c196034105d010607a6c6b7d72bfa1c3451448ac484a3b';

const notificationData = {
    bill: {
        siteId: 'test',
        billId: 'test_bill',
        amount: { value: 1, currency: 'RUB' },
        status: { value: 'PAID', datetime: '2018-03-01T11:16:12+03' },
        customer: {},
        customFields: {},
        creationDateTime: '2018-03-01T11:15:39+03:',
        expirationDateTime: '2018-04-15T11:15:39+03'
    },
    version: '1'
};

const secretKey = 'eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjUyNjgxMiwiYXBpX3VzZXJfaWQiOjcxNjI2MTk3LCJzZWNyZXQiOiJmZjBiZmJiM2UxYzc0MjY3YjIyZDIzOGYzMDBkNDhlYjhiNTnONPININONPN090MTg5Z**********************';

qiwiApi.checkNotificationSignature(
    validSignatureFromNotificationServer, notificationData, secretKey
); // true

<?php

$validSignatureFromNotificationServer = '07e0ebb10916d97760c196034105d010607a6c6b7d72bfa1c3451448ac484a3b';
$notificationData = [
  'bill' => [
    'siteId' => 'test',
    'billId' => 'test_bill',
    'amount' => ['value' => 1, 'currency' => 'RUB'],
    'status' => ['value' => 'PAID']
  ],
  'version' => '3'
];
$secretKey = 'eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjUyNjgxMiwiYXBpX3VzZXJfaWQiOjcxNjI2MTk3LCJzZWNyZXQiOiJmZjBiZmJiM2UxYzc0MjY3YjIyZDIzOGYzMDBkNDhlYjhiNTnONPININONPN090MTg5Z**********************';

/** @var \Qiwi\Api\BillPayments $billPayments */
$billPayments->checkNotificationSignature(
  $validSignatureFromNotificationServer, $notificationData, $secretKey
); // true

?>

String secretKey = "eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjUyNjgxMiwiYXBpX3VzZXJfaWQiOjcxNjI2MTk3LCJzZWNyZXQiOiJmZjBiZmJiM2UxYzc0MjY3YjIyZDIzOGYzMDBkNDhlYjhiNTnONPININONPN090MTg5Z**********************";
Notification notification = new Notification(
        new Bill(
                "test",
                "test_bill",
                new MoneyAmount(
                        BigDecimal.ONE,
                        Currency.getInstance("RUB")
                ),
                BillStatus.PAID
        ),
        "3"
);
String validSignature = "07e0ebb10916d97760c196034105d010607a6c6b7d72bfa1c3451448ac484a3b";
 BillPaymentsUtils.checkNotificationSignature(validSignature, notification, secretKey); //true

Строка и ключ подписи кодируются в UTF-8.

Параметры
В уведомлении содержится информация о счете.

Поле	Описание	Тип
bill	Информация о счете	Object
billId	Уникальный идентификатор счета в вашей системе, указанный при выставлении	String(200)
siteId	Ваш идентификатор в сервисе приема платежей для физических лиц p2p.qiwi.com	String
amount	Информация о сумме счета	Object
amount. value	Сумма счета, округленная до двух десятичных знаков в меньшую сторону	Number(6.2)
amount. currency	Идентификатор валюты суммы счета (Alpha-3 ISO 4217 код)	String(3)
status	Информация о статусе счета	Object
status. value	Строковое значение статуса	String
status. changedDateTime	Дата обновления статуса. Формат даты `ГГГГ-ММ-ДДTЧЧ:ММ:СС+Z`	String
customer	Информация о пользователе	Object
customer. phone	Номер телефона (если был указан при выставлении счета)	String
customer. email	E-mail пользователя (если был указан при выставлении счета)	String
customer. account	Идентификатор пользователя в вашей системе (если был указан при выставлении счета)	String
creationDateTime	Дата создания счета. Формат даты `ГГГГ-ММ-ДДTЧЧ:ММ:СС+Z`	String
expirationDateTime	Срок оплаты счета. Формат даты `ГГГГ-ММ-ДДTЧЧ:ММ:СС+Z`	String
comment	Комментарий к счету	String(255)
customFields	Дополнительные данные счета (если были указаны при выставлении счета)	Object
version	Версия уведомлений	String

Ответ →

HTTP/1.1 200 OK
Content-Type: application/json

{
 "error":"0"
}

HEADERS
- Content-type: application/json

После того, как был получен входящий запрос-уведомление, необходимо проверить подлинность цифровой подписи и отправить ответ.

Форма для оплаты счета {#payurl}

При открытии формы в webview на android обязательно включать settings.setDomStorageEnabled(true)

При выставлении счета через API в ответе присутствует поле payUrl со ссылкой на платежную форму. При перенаправлении по ссылке для оплаты счета к ней можно добавить параметры:

Пример ссылки

https://oplata.qiwi.com/form?invoiceUid=a8437e7e-dc48-44f7-9bdb-4d46ca8ef2e4&paySource=qw&successUrl=google.com

Параметр	Описание	Тип
paySource	При открытии формы сразу будет выбран указанный способ перевода. Возможные значения: `qw` - QIWI Кошелек, `card` - банковская карта, `mobile` - баланс телефона. Если способ перевода недоступен, выбирается рекомендуемый для пользователя способ	String
successUrl	URL для переадресации на ваш сайт в случае успешного перевода	URL-Encoded String

Добавьте реферальные ссылки для платежей с сайта. Полная ссылка подтвердит реальность сайта и позволит избежать проблем с блокировкой кошелька. Платежи, проходящие со страницы без заголовка запроса Refer будут приводить к блокировке кошелька. Подробнее см. в статье Как передавать реферальные ссылки.

Пример передачи реферальной ссылки

<?php 
  header("Referrer-Policy: no-referrer-when-downgrade"); 
?>

Для того, чтобы в новых версиях браузеров передавался полный referer при переходе, укажите в ответе сервера заголовок Referrer-Policy со значением no-referrer-when-downgrade. Это можно сделать для всего сайта или только для страницы со ссылкой на форму оплаты.

Персонализация {#custom}

Вы можете настроить персонализированную форму оплаты: изменить свое имя на название магазина и настроить цвет фона и кнопок.

Пример персонализированной формы оплаты:

Чтобы настроить внешний вид формы оплаты:

Авторизуйтесь в Личном кабинете P2P.
Перейдите в раздел Форма приема переводов. Код вашего стиля для переменной themeCode (указывается в запросах API и вызовах SDK, см. далее) выделен жирным шрифтом в блоке серого цвета. Значение themeCode индивидуально для разных QIWI кошельков.
Нажмите кнопку Настроить и выполните настройку формы.
Нажмите кнопку Сохранить.

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

curl https://oplata.qiwi.com/create?publicKey=Fnzr1yTebUiQaBLDnebLMMxL8nc6FF5zfmGQnypc*******&amount=100&billId=cc961e8d-d4d6-4f02-b737-2297e51fb48e&successUrl=http%3A%2F%2Fexample.com%3Fsuccess%3F&customFields%5BthemeCode%5D=кодСтиля

Пример передачи параметра в запросе к API

curl --location \
  --request PUT \
  'https://api.qiwi.com/partner/bill/v1/bills/cc961e8d-d4d6-4f02-b737-2297e51fb48e' \
  --header 'content-type: application/json' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer <SECRET_KEY>' \
  --data-raw '{
     "amount": {
       "currency": "RUB",
       "value": 100.00
     },
     "comment": "Text comment",
     "expirationDateTime": "2025-04-13T14:30:00+03:00",
     "customer": {},
     "customFields": {"themeCode":"кодСтиля"}
  }'

const billId = 'cc961e8d-d4d6-4f02-b737-2297e51fb48e';

const fields = {
    amount: 1.00,
    currency: 'RUB',
    comment: 'Hello world',
    customFields: {themeCode: 'кодСтиля'},
    expirationDateTime: '2018-03-02T08:44:07+03:00'
};

qiwiApi.createBill( billId, fields ).then( data => {
    //do with data
});

<?php

$billId = 'cc961e8d-d4d6-4f02-b737-2297e51fb48e';
$customFields = ['themeCode' => 'кодСтиля'];
$fields = [
  'amount' => 1.00,
  'currency' => 'RUB',
  'comment' => 'test',
  'expirationDateTime' => '2018-03-02T08:44:07+03:00',
  'email' => 'mail@example.org',
  'account' => 'client4563',
  'customFields' => $customFields
];

/** @var \Qiwi\Api\BillPayments $billPayments */
$response = $billPayments->createBill($billId, $fields);

print_r($response);

?>

client.CreateBill(
    info: new CreateBillInfo
    {
        BillId = Guid.NewGuid().ToString(),
        Amount = new MoneyAmount
        {
            ValueDecimal = 199.9m,
            CurrencyEnum = CurrencyEnum.Rub
        },
        Comment = "comment",
        ExpirationDateTime = DateTime.Now.AddDays(45),
        Customer = new Customer
        {
            Email = "mail@example.org",
            Account = Guid.NewGuid().ToString(),
            Phone = "79123456789"
        },
        SuccessUrl = new Uri("http://example.com/success"),
        CustomFields: new CustomFields
        {
            ThemeCode = "кодСтиля"
        }
    }
);

Для применения стиля к платежной форме:

В запросе создания счета или при вызове метода создания счета в нужном модуле SDK добавьте в тело запроса объект customFields c полем themeCode и укажите в нем код вашего стиля.

Например, "customFields": { "themeCode":"кодСтиля"}.
При вызове платежной формы добавьте в запрос параметр customFields c полем themeCode и укажите в нем код вашего стиля.

Например, customFields[themeCode]=кодСтиля.

Библиотека Checkout Popup {#popup}

Пример работы popup

Методы библиотеки позволяют открыть форму перевода как всплывающее окно (popup) поверх вашего сайта.

Скачать библиотеку QIWI Checkout Popup

Установка и подключение библиотеки:

<script src='https://oplata.qiwi.com/popup/v1.js'></script>

В библиотеке доступно два метода:

Открытие существующего счета.
Открытие вашей формы приема переводов.

Открытие существующего счета {#openpopup}

Метод QiwiCheckout.openInvoice.

Пример открытия уже созданного счета в popup

params = {
    payUrl: 'https://oplata.qiwi.com/form?invoiceUid=06df838c-0f86-4be3-aced-a950c244b5b1'
}

QiwiCheckout.openInvoice(params)
    .then(data => {
        // ...
    })
    .catch(error => {
        // ...
    })

Параметр	Описание	Тип
payUrl	Обязательный параметр. URL счета	String

Открытие персонализированной формы {#openpopupcustom}

Метод QiwiCheckout.openPreorder.

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

params = {
    widgetAlias: 'https://my.qiwi.com/form/User-ABCDE1234-56'
}

QiwiCheckout.openPreorder(params)
    .then(data => {
        // ...
    })
    .catch(error => {
        // ...
    })

Параметр	Описание	Тип
widgetAlias	Обязательный параметр. Ссылка на форму приема переводов	String

Uh oh!

FilesExpand file tree

p2p-payments_ru.html.md

Latest commit

History

p2p-payments_ru.html.md

File metadata and controls

P2P-счета

Последнее обновление: 06-06-2022

Условия использования {#terms}

Активация доступа к сервису {#p2p-activate}

Как работать с сервисом {#how-to-start}

Сценарий платежа {#payment-scenario}

SDK и библиотеки {#sdk}

Решения для CMS {#cms}

Методы авторизации в сервисе {#auth}

Выставление счета через форму {#http-invoice}

GET →

URL https://oplata.qiwi.com/create

Параметры

API P2P-счетов. Выставление счета {#create}

Запрос → PUT

URL https://api.qiwi.com/partner/bill/v1/bills/{billid}

HEADERS

Ответ ←

HEADERS

API P2P-счетов. Проверка статуса перевода по счету {#invoice-status}

Запрос → GET

URL https://api.qiwi.com/partner/bill/v1/bills/{billid}

HEADERS

Ответ ←

HEADERS

API P2P-счетов. Отмена неоплаченного счета {#cancel}

Запрос → POST

URL https://api.qiwi.com/partner/bill/v1/bills/{billId}/reject

HEADERS

Ответ ←

HEADERS

API P2P-счетов. Статусы оплаты счетов {#status}

Уведомления о переводе по счету {#notification}

Запрос ← POST

HEADERS

Регистрация сервера уведомлений {#notification-server}

Проверка подлинности уведомлений {#notification-auth}

Параметры

Ответ →

HEADERS

Форма для оплаты счета {#payurl}

Персонализация {#custom}

Библиотека Checkout Popup {#popup}

Открытие существующего счета {#openpopup}

Открытие персонализированной формы {#openpopupcustom}