P2P-счета

Условия использования

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

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

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

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

Активация доступа к сервису

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

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

Как работать с сервисом

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

Сценарий платежа

1. Пользователь формирует счет на вашей стороне.

2. Вы перенаправляете пользователя на платежную форму для выставления и оплаты счета в сервисе. Или выставляете счет по API и также перенаправляете пользователя на созданную платежную форму (ссылка на форму придет в ответе).

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

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

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

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

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

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

Методы авторизации в сервисе

Выпуск новых ключей для авторизации прекращён. Простите за доставленные неудобства.

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>:

1. Авторизуйтесь в личном кабинете https://p2p.qiwi.com/.

2. Перейдите на вкладку API и нажмите кнопку Создать пару ключей и настроить. Если вы создаете пару ключей впервые, то нажмите кнопку Настроить.

   

3. Укажите название для пары ключей и нажмите кнопку Создать.

   

4. Сохраните секретный ключ в безопасном месте — в дальнейшем он не будет отображаться в интерфейсе. Публичный ключ вы всегда можете скопировать из Личного кабинета.

   

5. Нажмите кнопку Дальше. Пара ключей будет активирована.

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

• выполнить перевод на кошелек;
• выполнить перевод на карту.

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

Выставление счета через форму

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

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

GET →

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

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

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

const link = qiwiApi.createPaymentForm(params);

curl https://oplata.qiwi.com/create?publicKey=Fnzr1yTebUiQaBLDnebLMMxL8nc6FF5zfmGQnypc*******&amount=100&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 paymentUrl = client.createPaymentForm(new PaymentInfo(key, amount, billId, ""));

var publicKey = "2tbp1WQvsgQeziGY9vTLe9vDZNg7tmCymb4Lh6STQokqKrpCC6qrUUKEDZAJ7mvFnzr1yTebUiQaBLDnebLMMxL8nc6FF5zfmGQnypdXCbQJqHEJW5RJmKfj8nvgc";

var amount = new MoneyAmount
{
    ValueDecimal = 499.9m,
    CurrencyEnum = CurrencyEnum.Rub
};
var billId = Guid.NewGuid().ToString();

var paymentUrl = client.CreatePaymentForm(new PaymentInfo(key, amount, billId, ""));

• Параметры

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

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

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

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

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

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

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

Запрос → 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"
                ),
                ""
        );
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"
        },
        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

Ответ ←

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

{
    "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

API P2P-счетов. Проверка статуса перевода по счету

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

Запрос → 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

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

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

Запрос → 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

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

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

Перед началом работы с сервисом уведомлений прочитайте условия по интеграции 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-пакетов.

Уведомление представляет собой входящий 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

Регистрация сервера уведомлений

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

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

1. Авторизуйтесь в Личном кабинете P2P.

2. Перейдите на вкладку API и нажмите кнопку Создать пару ключей и настроить. Если вы настраиваете адрес сервера вместе с первичным созданием пары ключей впервые, то нажмите кнопку Настроить.

   

3. Укажите название для новой пары ключей.

   

4. Выделите поле Использовать эту пару ключей для серверных уведомлений об изменении статусов счетов.

   

5. В поле URL сервера для уведомлений укажите адрес вашего сервера для обработки уведомлений об оплате. Внимание! Сервер должен быть доступен из интернета.

6. Нажмите кнопку Создать.

   

7. Замените в настройках ваших приложений ключи для сервиса QIWI P2P на вновь созданные.

Проверка подлинности уведомлений

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

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

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

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

   где {*} – значение параметра. Все значения при проверке подписи должны трактоваться как строки.

2. Вычислить HMAC-хеш c алгоритмом хеширования SHA256:

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

   Где:

   • <SECRET_KEY> – секретный ключ, при помощи которого был выставлен счёт;
   • invoice_parameters – строка из п.1.

3. Сравнить значение заголовка 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.

• Параметры

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

Ответ →

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

{
 "error":"0"
}

• HEADERS

  • Content-type: application/json

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

Форма для оплаты счета

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

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

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

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

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

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

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

Персонализация

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

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

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

1. Авторизуйтесь в Личном кабинете P2P.

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

   

3. Нажмите кнопку Настроить и выполните настройку формы.
4. Нажмите кнопку Сохранить.

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

curl https://oplata.qiwi.com/create?publicKey=Fnzr1yTebUiQaBLDnebLMMxL8nc6FF5zfmGQnypc*******&amount=100&billId=cc961e8d-d4d6-4f02-b737-2297e51fb48e&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"
        },
        CustomFields: new CustomFields
        {
            ThemeCode = "кодСтиля"
        }
    }
);

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

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

  Например, "customFields": { "themeCode":"кодСтиля"}.

• При вызове платежной формы добавьте в запрос параметр customFields c полем themeCode и укажите в нем код вашего стиля.

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

Библиотека Checkout Popup

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

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

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

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

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

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

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

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

Метод QiwiCheckout.openInvoice.

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

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

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

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

Метод QiwiCheckout.openPreorder.

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

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

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