Платежи

Всё, что нужно знать о работе с платежами через 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)