Платежи

Всё, что нужно знать о работе с платежами через Yang Cash.

Как работает платёж

Создание платежа

Вы отправляете запрос на create-payment с указанием кассы, суммы и валюты.

Обработка

Система рассчитывает комиссию и создаёт заказ. В ответе — реквизиты для оплаты.

Оплата

Клиент оплачивает по реквизитам. Система автоматически отслеживает статус платежа.

Уведомление

Когда платёж достигает финального статуса (включая amount_mismatch), система отправляет вебхук на ваш сервер.

Статусы платежа

new

Платёж создан, ожидает обработки

processing

Платёж обрабатывается, система подбирает реквизиты

credentials_obtained

Реквизиты получены, ожидается оплата клиентом

completed

Платёж успешно завершён, средства зачислены

failed

Платёж не удалось провести

expired

Время ожидания оплаты истекло

cancelled

Платёж отменён

amount_mismatch

Средства поступили, но сумма не совпадает с ожидаемой: поле fact_amount содержит фактически поступившую сумму. Платёж заморожен до решения администратора — после решения придёт финальный вебхук (completed или failed)

Возврат клиента на вашу страницу (redirect_urls)

При создании платежа можно передать необязательный объект redirect_urls — адреса, на которые система возвращает клиента после достижения платёжом финального статуса. Ключи объекта соответствуют статусам платежа; дополнительные GET-параметры для идентификации заказа вы задаёте на своей стороне прямо в URL.

Примеры

JSON — только успех

{"amount": 1000.00, "type": "p2p", "bank_id": "vtb_rub", "idempotency_key": "order-12345", "redirect_urls": {"completed": "https://shop.example.com/payment/success?order=12345"}}

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

JSON — успех + любой неуспех

{"redirect_urls": {"completed": "https://shop.example.com/payment/success?order=12345", "any_error": "https://shop.example.com/payment/error?order=12345"}}

Служебный ключ any_error покрывает любой неуспешный финальный статус — при желании можно указать только его, не перечисляя каждый статус отдельно. Отдельно заданный URL конкретного статуса имеет приоритет над any_error; сам any_error на статус completed не распространяется.

Допустимые ключи

Ключ	Когда выполняется редирект
completed	Платёж успешно завершён
failed	Платёж не удалось провести
expired	Время ожидания оплаты истекло
cancelled	Платёж отменён
amount_mismatch	Поступившая сумма не совпала с ожидаемой
any_error	Любой неуспешный финальный статус, для которого не задан отдельный URL

Как это работает

На нашей платёжной странице клиент находится, пока платёж в процессе: страница периодически обновляется и проверяет статус на сервере.

Как только статус становится финальным, сервер перенаправляет клиента на адрес, заданный для этого статуса (а если для статуса адрес не задан — на any_error, кроме статуса completed). Переданные адреса никогда не попадают в код платёжной страницы — клиент не может узнать их заранее и сымитировать успешную оплату, просто перейдя по ссылке.

Важно: редирект — это только удобство навигации для клиента, а не подтверждение оплаты. Клиент может не дождаться редиректа или закрыть страницу. Источник истины о статусе платежа — вебхук или запрос GET /v1/merchant/payment/{id}; идентификацию заказа на своей странице выполняйте по GET-параметрам, которые вы сами вложили в URL.

QR-платежи (СБП)

Для оплаты по QR-коду передайте type: "qr" при создании платежа. В ответе придёт объект credentials.qr со ссылкой на оплату в формате СБП и готовым изображением QR-кода. Клиент сканирует QR-код камерой телефона или переходит по ссылке — открывается приложение его банка.

Пример запроса

JSON

{"amount": 1000.00, "currency": "RUB", "type": "qr", "bank_id": "alfa_rub", "idempotency_key": "order-12345-qr-1"}

Поле bank_id для QR-платежа необязательно: без него банк-получатель выбирается автоматически. Список доступных значений — GET /v1/merchant/banks.

Ответ (фрагмент)

JSON

{"data": {"status": "credentials_obtained", "credentials": {"qr": {"payment_url": "https://pay.example.com/AS1K3P9RH0LJ2A9R0O038L6NT5RU1M7X?type=02&bank=100000000008&sum=105263&cur=RUB&crc=848C", "qr_code_id": "AS1K3P9RH0LJ2A9R0O038L6NT5RU1M7X", "image": {"media_type": "image/png", "content": "iVBORw0KGgo..."}}}}}

Поля объекта credentials.qr

Поле	Тип	Описание
payment_url	string	Ссылка на оплату в формате СБП. Открывается в мобильном приложении банка клиента
qr_code_id	string \| null	Идентификатор QR-кода. Может отсутствовать
image.media_type	string	Тип изображения (например, image/png)
image.content	string	Изображение QR-кода в base64. Готово для отображения: <img src="data:image/png;base64,...">

Разделы

Вебхуки (уведомления)

Как получать и обрабатывать уведомления о статусе платежа

API Reference

Полное описание методов API, параметров и примеров (Swagger UI)