Руководство по интеграции платежного шлюза Cashfree | Документация для разработчиков

Руководство по интеграции платежного шлюза Cashfree

Обновлено: 31 октября 2025 г

Цель

Цель данного документа — описать процесс интеграции платежных систем с Cashfree, необходимый для продавца или партнера по решениям, который настроил чат-бота с использованием API WhatsApp Business и нуждается в приеме платежей от пользователей WhatsApp.

В этом документе описан набор API, которые необходимо интегрировать, и принцип работы интеграции с API WhatsApp Business. Для получения дополнительной информации об интеграции платежной системы Cashfree, пожалуйста, обратитесь к документации Cashfree.

Где это вписывается в общий процесс интеграции с продуктом WA P2M: В следующем документе описаны запросы и ответы, выделенные красным цветом на приведенной ниже блок-схеме.

Интеграция безналичных платежей

Настраивать

После создания учетной записи получите учетные данные (идентификатор клиента и секретный ключ) на панели управления Cashfree.Получите VPA продавца, MCC и код назначения платежа от Cashfree. Они будут использоваться для настройки параметров оплаты в WhatsApp. Поддерживается несколько VPA, поэтому можно настроить несколько параметров оплаты. Каждый параметр оплаты должен содержать один VPA.

Создать заказ

Это формирует заказ на стороне Cashfree.

Справочный документ⁠

Запрос

curl --request POST \ --url https://sandbox.cashfree.com/pg/orders \ // Production URL : https://api.cashfree.com/pg/orders --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-api-version: 2022-09-01' \ --header 'x-client-id: 26268833355ef02b8ff299390c886262' \ --header 'x-client-secret: 1708cc38a3c1c3c2512d79b3530dc5cc65ad2fde' \ --data ' { "customer_details": { "customer_id": "7112AAA812234", "customer_email": " [email protected] ", "customer_phone": "9908734801", "customer_bank_account_number": "1518121112", "customer_bank_ifsc": "CITI0000001", "customer_bank_code": 3333 }, "order_meta": { "notify_url": "https://b8af79f41056.eu.ngrok.io/webhook.php", // URL уведомлений, куда отправляются уведомления о статусе - может отличаться для разных продавцов "payment_methods": "upi" }, "order_tags": { "channel": "WhatsApp" // Пользовательский тег }, "order_id": "order02", "order_amount": 200.5, "order_currency": "INR", "order_expiry_time": "2022-12-29T00:00:00Z", "order_note": "Тестовый заказ" }

Ответ

{ "cf_order_id": 3401407, "created_at": "2022-12-26T14:11:07+05:30", "customer_details": { "customer_id": "7112AAA812234", "customer_name": null, "customer_email": " [email protected] ", "customer_phone": "9908734801" }, "entity": "order", "order_amount": 200.5, "order_currency": "INR", "order_expiry_time": "2022-12-29T05:30:00+05:30", "order_id": "order02", "order_meta": { "return_url": null, "notify_url": "https://b8af79f41056.eu.ngrok.io/webhook.php", "payment_methods": "upi" }, "order_note": "Тестовый заказ", "order_splits": [], "order_status": "АКТИВНЫЙ", "order_tags": { "channel": "WhatsApp" // Пользовательский тег }, "payment_session_id": "session_364o8HjN0-gc6n_n4EBEPOXriJUJvCeVIdy9u8ihOhwvpNg9F1wMorWmkVxUR90kTe473bpbotNxyZ6Fze8M0w42_BpTxoEWsbBR21y7i0nh", "payments": { "url": "https://sandbox.cashfree.com/pg/orders/order02/payments" // URL-адреса для производственной среды отличаются }, "возвраты": { "url": "https://sandbox.cashfree.com/pg/orders/order02/refunds" }, "расчеты": { "url": "https://sandbox.cashfree.com/pg/orders/order02/settlements" }, "terminal_data": null }

Оплата заказа

Этот API возвращает URL-адрес UPI-интента, содержащий параметры, необходимые для работы с API WhatsApp. Справочная документация .

Запрос

curl --request POST \ --url https://sandbox.cashfree.com/pg/orders/sessions \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-api-version: 2022-09-01' \ --data ' { "payment_method": { "upi": { "channel": "link", "upi_id": "rajnandan1@okhdfcbak", "upi_expiry_minutes": 10 } }, "payment_session_id": "session_364o8HjN0-gc6n_n4EBEPOXriJUJvCeVIdy9u8ihOhwvpNg9F1wMorWmkVxUR90kTe473bpbotNxyZ6Fze8M0w42_BpTxoEWsbBR21y7i0nh" // это из ответа API создания заказа }

Ответ

{ "action": "custom", "cf_payment_id": 885899755, // это идентификатор транзакции, также присутствует в URL-адресе UPI "channel": "link", "data": { "url": null, "payload": { "bhim": "https://payments-test.cashfree.com/pgbillpayuiapi/simulator/885899755?txnId=885899755&amount=200.50&pa=cashfree@testbank&pn=Cashfree&tr=885899755&am=200.50&cu=INR&mode=00&purpose=00&mc=5732&tn=Cashfree%20Simulator%20Payment", "default": "https://payouts-test.cashfree.com/pgbillpayuiapi/simulator/885899755?txnId=885899755&amount=200.50&pa=cashfree@ testbank&pn=Cashfree&tr=885899755&am=200.50&cu=INR&mode=00&function=00&mc=5732&tn=Cashfree%20Simulator%20Payment", "гпэй": "https://payments-test.cashfree.com/pgbillpayuiapi/simulator/885899755?txnId=885899755&amount=200.50&pa=cashfree@testbank&pn=Cashfree&tr=885899755&am=200.50&cu=INR&mode=00&purpose=00&mc=5732&tn=Cashfree%20Simulator%20Payment", "paytm": "https://payouts-test.cashfree.com/pgbillpayuiapi/simulator/885899755?txnId=885899755&amount=200.50&pa=cashfree@ testbank&pn=Cashfree&tr=885899755&am=200.50&cu=INR&mode=00&function=00&mc=5732&tn=Cashfree%20Simulator%20Payment", "фонопе": "https://payments-test.cashfree.com/pgbillpayuiapi/simulator/885899755?txnId=885899755&amount=200.50&pa=cashfree@testbank&pn=Cashfree&tr=885899755&am=200.50&cu=INR&mode=00&purpose=00&mc=5732&tn=Cashfree%20Simulator%20Payment", "web": "https://sandbox.cashfree.com/pg/view/upi/qcrgfb.session_364o8HjN0-gc6n_n4EBEPOXriJUJvCeVIdy9u8ihOhwvpNg9F1wMorWmkVxUR90kTe473bpbotNxyZ6Fze8M0w42_BpTxoEWsbBR21y7i0nh.c252cd27-c877-4a51-8352-837d04a2f4c2" }, "content_type": null, "method": null }, "payment_amount": 200.5, "payment_method": "upi" }

Анализ ответа

Сохраните cf_payment_id в качестве уникального идентификатора платежа на стороне Cashfree. Поскольку Cashfree поддерживает несколько платежей для одного order_id (или cf_order_id), сохранение cf_payment_id важно для удаления дубликатов/повторяющихся платежей (если они возникают из-за ошибки или по другим причинам).

Извлеките пары ключ-значение из data.payload.default

Убедитесь, что значение "am" совпадает с установленной величиной.Используйте значение из "tr" в качестве reference_id при настройке объекта Parameters для отправки платежного сообщения с помощью API WhatsApp.Значение параметра «pa» — это VPA продавца, который будет использоваться для этой транзакции. Имя конфигурации платежа, соответствующее возвращенному VPA, следует использовать в качестве payment_configuration при настройке объекта Parameters для отправки платежного сообщения с использованием API WhatsApp.Если полученный выше VPA продавца не совпадает ни с одним из VPA, установленных в настройках платежей WhatsApp, платеж следует отменить. Пожалуйста, свяжитесь с Cashfree для подтверждения обновленного VPA и внесения соответствующих изменений в настройки платежей WhatsApp.Также проверьте, совпадают ли значения «режим» и «назначение» с теми, которые установлены в настройках платежа. В случае несоответствия зарегистрируйте это несоответствие, чтобы связаться с Cashfree и уточнить правильные/обновленные значения. Не блокируйте платеж из-за этого несоответствия.

"default": "upi://pay?pa=cfsukoona@yesbank&pn=Sukoon&tr=877376394&am=10.00&cu=INR&mode=00&member=00&mc=5399&tn=877376394"

Вебхук

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

На основе значения payment_status в веб-хуке обновите статус заказа для пользователя, используя API WhatsApp.

Справочное руководство⁠

Веб-хук успешной транзакции

{ "data": { "order": { "order_id": "1633615918", "order_amount": 1.00, "order_currency": "INR", "order_tags": null }, "payment": { "cf_payment_id": 1107253, "payment_status": "SUCCESS", "payment_amount": 1.00, "payment_currency": "INR", "payment_message": "Transaction pending", "payment_time": "2021-10-07T19:42:40+05:30", "bank_reference": "1903772466", "auth_id": null, "payment_method": { "upi": { "channel":null, "upi_id":"miglaniyogesh7@okhdfcbank" } }, "payment_group":"upi" "customer_details": { "customer_name": "Yogesh", "customer_id": "12121212", "customer_email": " [email protected] ", "customer_phone": "9666699999" } }, "event_time": "2021-10-07T19:42:44+05:30", "type": "PAYMENT_SUCCESS_WEBHOOK" }

Веб-перехватчик неудачной транзакции

{ "data": { "order": { "order_id": "order_01", "order_amount": 2, "order_currency": "INR", "order_tags": null }, "payment": { "cf_payment_id": 975677709, "payment_status": "FAILED", "payment_amount": 2, "payment_currency": "INR", "payment_message": "ZA::U19::Transaction fail", "payment_time": "2022-05-25T14:28:22+05:30", "bank_reference": "214568722700", "auth_id": null, "payment_method": { "upi": { "channel": null, "upi_id": "9611199227@paytm" } }, "payment_group": "upi" }, "customer_details": { "customer_name": null, "customer_id": "7112AAA812234", "customer_email": " [email protected] ", "customer_phone": "9611199227" }, "error_details": { "error_code": "TRANSACTION_DECLINED", "error_description": "банк-эмитент или поставщик платежных услуг отклонил транзакцию", "error_reason": "auth_declined", "error_source": "customer" } }, "event_time": "2022-05-25T14:28:38+05:30", "type": "PAYMENT_FAILED_WEBHOOK" }

Проверка статуса

В качестве альтернативы, если веб-хук не получен в течение определенного периода времени, можно использовать API статуса. На основе значения payment_status в ответе обновите статус заказа для пользователя с помощью API WhatsApp.

Справочный документ⁠

Запрос

curl --request GET \ --url https://sandbox.cashfree.com/pg/orders/order02/payments/885899755 \ --header 'accept: application/json' \ --header 'x-api-version: 2022-09-01' \ --header 'x-client-id: 26268833355ef02b8ff299390c886262' \ --header 'x-client-secret: 1708cc38a3c1c3c2512d79b3530dc5cc65ad2fde'

Ответ

{ "auth_id": null, "authorization": null, "bank_reference": null, "cf_payment_id": 885704957, "entity": "payment", "error_details": null, "is_captured": true, "order_amount": 10.15, "order_id": "12345", "payment_amount": 10.15, "payment_completion_time": "2022-10-27T08:43:05+05:30", "payment_currency": "INR", "payment_group": "upi", "payment_message": "Transaction Successful", "payment_method": { "upi": { "channel": "link" } }, "payment_status": "SUCCESS", "payment_time": "2022-10-27T08:42:07+05:30" } ИЛИ { "auth_id": null, "authorization": null, "bank_reference": null, "cf_payment_id": 885899755, "entity": "payment", "error_details": null, "is_captured": false, "order_amount": 200.5, "order_id": "order02", "payment_amount": 200.5, "payment_completion_time": "2022-12-26T14:24:56+05:30", "payment_currency": "INR", "payment_gateway_details": null, "payment_group": "upi", "payment_message": "Пользователь отказался от двухфакторной аутентификации и не завершил ее", "payment_method": { "upi": { "channel": "link", "upi_id": "987836150" } }, "payment_status": "USER_DROPPED", "payment_time": "2022-12-26T14:14:56+05:30" }

Возвращать деньги

API для возврата средств может использоваться для инициирования возврата денег пользователю.

Справочный документ⁠

Запрос

curl --request POST \ --url https://sandbox.cashfree.com/pg/orders/12345/refunds \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-api-version: 2022-01-01' \ --header 'x-client-id: xxxxxx' \ --header 'x-client-secret: xxxxxx' \ --data ' { "refund_amount": 5, "refund_id": "refund12345" }

Ответ

{ "cf_payment_id": 885704957, "cf_refund_id": "refund_49234", "created_at": "2022-10-27T14:35:22+05:30", "entity": "refund", "metadata": null, "order_id": "12345", "processed_at": null, "refund_amount": 5, "refund_arn": null, "refund_charge": 0, "refund_currency": "INR", "refund_id": "refund12345", "refund_mode": "STANDARD", "refund_note": null, "refund_splits": [], "refund_status": "PENDING", "refund_type": "MERCHANT_INITIATED", "status_description": "In Progress" }

Рассмотрение особых случаев

Срок действия заказа

В API создания заказа Cashfree можно установить время истечения срока действия заказа. Используйте эту функцию для установки желаемого времени истечения срока действия.После истечения срока действия заказа, если веб-хук не был получен, выполните проверку статуса, чтобы убедиться, что заказ истек, а затем отмените заказ в WhatsApp, чтобы уведомить пользователя.

Обработка неудачных платежей

Сообщение об оплате, отправленное пользователю через WhatsApp, допускает несколько повторных попыток в случае неудачи (то есть кнопка «Оплатить» доступна до успешной оплаты). Однако Cashfree требует, чтобы идентификатор ссылки («tr» в URL-адресе, полученном в ответе на запрос об оплате заказа) был уникальным для каждой оплаты.Таким образом, если от Cashfree получено сообщение об ошибке платежа, обновите статус заказа в WhatsApp на «отменен». После этого пользователю будет отправлено новое сообщение с просьбой повторить платеж.В случае задержки отмены, если пользователь в итоге успешно совершил платеж, Cashfree не будет отправлять веб-хук продавцу, а автоматически произведет возврат средств без каких-либо дополнительных действий со стороны продавца. В случае запроса клиента в подобной ситуации (когда он утверждает, что транзакция была успешной, но платеж не найден в Cashfree), сообщите пользователю, что возврат будет обработан в течение нескольких дней.

Отмена заказа после успешной транзакции

Может возникнуть ситуация, когда Cashfree отправила сигнал об успешной оплате, но продавец не может выполнить заказ. В таком случае следует оформить возврат средств одним из следующих способов:

Используйте API возврата средств.Используйте панель управления Cashfree для продавцов.