Руководство по интеграции платежного шлюза Billdesk | Документация для разработчиков
Руководство по интеграции платежного шлюза Billdesk
Обновлено: 14 ноября 2025 г
Цель данного документа — описать интеграцию платежных систем с Billdesk, необходимую для продавца или партнера по решениям, внедрившего чат-бота с использованием API WhatsApp Business и нуждающегося в приеме платежей от пользователей WhatsApp.
В этом документе описаны необходимые API, которые должны быть интегрированы, и то, как интеграция работает совместно с API WhatsApp Business. Хотя это не исчерпывающее руководство, оно служит общим обзором, помогающим понять процесс интеграции платежного шлюза. Любые конкретные или уникальные детали, касающиеся платежного шлюза, должны быть определены продавцом или партнером по решениям.
Что касается интеграции с продуктом WA P2M, в этом документе описаны запросы и ответы, выделенные красным цветом на блок-схеме.
Интеграция платежных систем Billdesk
Настраивать
Для аутентификации в API Billdesk необходимо создать клиент и выбрать метод аутентификации: HMAC или Javascript Object Signing and Encryption (JOSE), при этом JOSE является предпочтительным методом. Эти методы используются для шифрования/дешифрования запросов/ответов от API Billdesk.
Для упрощения объяснения, следующие примеры будут касаться только той части итоговой полезной нагрузки, которая в конечном итоге будет включена в конечный объект, необходимый для успешной аутентификации с их API. Важно обратиться к документации Billdesk за рекомендациями относительно структуры этого конечного объекта.
Для продолжения вам потребуется следующая информация:
API для инициирования платежей
Пример POST к https://pguat.billdesk.io/payments/ve1_2/transactions/create
{ "mercid": "BDMERCHANTID", "orderid": "UPIODR00000004", "amount": "2.00", "currency": "356", "bankid": "ICW", "txn_process_type": "intent", "itemcode": "DIRECT", "payment_method_type": "upi", "wa_mc": "0743", "wa_vpa": "billdesk@hdfcbank", "wa_txnid": "H477676443", "wa_mercname": "SIDDHIVINK", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2" }, "device": { "init_channel": "app", "ip": "124.124.1.1", "user_agent": "App/22.6.74 Платформа/19.5.0" } }| Параметры | Описание |
|---|---|
Идентификатор заказа (обязательно) | нить Уникальный идентификатор заказа, генерируемый продавцом для идентификации транзакции |
милосердие (Обязательно) | нить Уникальный идентификатор, определенный BillDesk для каждого продавца |
сумма (обязательно) | нить Сумма транзакции в двух знаках после запятой |
Валюта (обязательно) | нить Валюта ISO суммы транзакции |
txn_process_type (Необязательно) | нить Значение должно соответствовать намерению. |
bankid (Необязательно) | нить BillDesk определил уникальный идентификатор для банка или эквайера |
ru (Необязательно) | нить URL возврата продавца |
itemcode (Обязательно) | нить Значение Itemcode, предоставленное BillDesk, со значением по умолчанию DIRECT. |
устройство (Обязательно) | объект Объект устройства. Для получения более подробной информации обратитесь к документации BillDesk. |
Тип_метода_оплаты (Обязательно) | нить Необходимо установить значение upi. |
wa_mc (Обязательно) | нить Категория продавца |
wa_vpa (Обязательно) | нить Получатель платежа VPA |
wa_txnid (Обязательно) | нить Уникальный идентификатор транзакции (txnid), сгенерированный банком для данной транзакции |
wa_mercname (Обязательно) | нить Название продавца |
Пример ответа
{ "objectid": "transaction", "transactionid": "X7890477676443", "orderid": "UPIODR00000004", "mercid": "BDMERCID", "transaction_date": "2022-03-18T11:50:27+05:30", "amount": "2.00", "surcharge": "0.00", "discount": "0.00", "charge_amount": "2.00", "currency": "356", "additional_info": { "additional_info1": "Details1", "additional_info2": "Details2" }, "txn_process_type": "intent", "bankid": "ICW", "itemcode": "DIRECT", "auth_status": "0002", "transaction_error_code": "TRP0000", "transaction_error_desc": "Транзакция в ожидании", "transaction_error_type": "pending", "payment_method_type": "upi", "wa_mc": "7399", "wa_vpa": "billdesk@hdfcbank", "wa_txnid": "H477676443", "wa_mercname": "SIDDHIVINK", "intent": "dXBpOi8vcGF5P3BhPWJpbGxkZXNrQGhkZmNiYW5rJnBuPVNJRERISVZJTksmbWM9NjMwMCZ0cj1YSEQ1MDQ3NzY3NjQ0MyZ0bj1QYXkmYW09Mi4wMCZtYWwMCZjdT1JTlI=" }Проанализируйте ответ
Используйте значение
wa_txnid из ответа и передайте его в качестве reference_id при настройке параметров для отправки сообщения с подробной информацией о заказе через API.Обязательно проверьте значения в полученном вами намерении:
Intent содержит закодированное в Base64 значение Intent.Расшифровка намерения должна дать значение, похожее на следующее: upi://pay?pa=billdesk@hdfcbank&pn=SIDDHIVINKamp;mc=6300&tr=XHD50477676443&tn=Pay&am=2.00&malORSЗначение параметра pa VPA продавца . Это значение должно совпадать с VPA в файле payment_configuration, который вы указываете в объекте параметров Веб-перехватчик статуса
Billdesk отправит объект транзакции на указанный вами URL-адрес возврата (
ru ) в API инициирования платежа.| Ключ | Тип данных | Описание |
|---|---|---|
objectid (Обязательный) | нить | Строка, представляющая тип объекта. Это значение будет зафиксировано в ходе транзакции |
идентификатор транзакции | нить | Система BillDesk генерирует уникальный идентификатор транзакции для данной операции |
orderid | нить | Уникальный идентификатор заказа (orderid), генерируемый продавцом для данной транзакции |
мерсид | нить | Уникальный идентификатор, определенный BillDesk для каждого продавца |
дата транзакции | метка времени | Дата и время транзакции BillDesk в формате ГГГГ-ММ ДДЧЧ:мм:ссТЗД |
количество | нить | Сумма транзакции в двух знаках после запятой |
надбавка | нить | Если таковая имеется, к сумме транзакции применяется дополнительная плата, указываемая в двух знаках после запятой |
скидка | нить | Если таковая имеется, к сумме покупки применяется скидка для клиента, выраженная двумя знаками после запятой |
сумма_заряда | нить | Общая сумма к оплате клиентом |
валюта | целое число | Валюта ISO суммы транзакции |
txn_process_type | нить | Указывает тип обработки транзакции. Intent для payment_method_type имеет значение upi, а метод оплаты — UPI |
банкид | нить | BillDesk определил уникальный идентификатор для банка или эквайера |
txn_process_type | нить | Указывает тип обработки транзакции. В параметре payment_method_type указано upi, а в параметре method of payment — UPI. |
ру | нить | URL возврата продавца |
дополнительная_информация | объект | Массив из 10 additional_info , которые можно прикрепить к транзакции. Примечание: Продавцу рекомендуется не передавать персональные данные клиентов в полях additional_info. |
код товара | нить | Значение Itemcode предоставляется системой BillDesk, значение по умолчанию — DIRECT. |
номер_банка | нить | Номер транзакции, сгенерированный банком или эквайером |
auth_status | нить | Представляет статус авторизации транзакции с возможными значениями: 0300 - транзакция успешно завершена0002 - транзакция ожидает авторизации0399 - транзакция не удалась |
settlement_lob | нить | Функция расчетов, предварительно настроенная BillDesk для перечисления средств на торговый счет |
клиент | объект | Объект клиента |
устройство | объект | Объект устройства |
transaction_error_code | нить | Представляет собой код ошибки для транзакции со статусом 0399. |
transaction_error_type | нить | Представляет собой категорию стандартной ошибки для транзакции со статусом 0399. |
transaction_error_desc | нить | Представляет собой описание кода ошибки для транзакции со статусом 0399. |
код авторизации | нить | Код авторизации, полученный от эквайера за успешно авторизованную транзакцию по карте |
эци | нить | Значение ECI для аутентификации, используемой при карточной транзакции |
payment_method_type | нить | Представляет собой способ оплаты, например, UPI |
карта | Объект | Объект способа оплаты (применяется, если способ оплаты — карта) |
customer_refid | нить | Уникальный идентификатор клиента в соответствии с данными продавца |
ссылки | объект | Связанные ссылки с объектом |
Анализ ответа
Используйте значение
auth_status , полученное из ответа выше, и передайте соответствующее сообщение о статусе через API WhatsApp.
Комментарии отсутствуют
Комментарии отсутствуют