Руководство по странице оплаты

Как по шагам собрать кассу, которая отправляет плательщика на страницу оплаты, и как её проверить в тестовом контуре.

Руководство для кассы, у которой нет своей платёжной формы: плательщика отправляют на страницу оплаты, а исход узнают уведомлением или чтением платежа. Что умеет сама страница: Страница оплаты.

Перед началом

  1. Тестовый ключ и проверенный вызов GET /api/v1/me: Начало работы.
  2. Список источников адреса возврата: попросите администратора Target внести схему, имя узла и порт страницы, на которую плательщик вернётся. Без этого returnUrl получит отказ.
  3. Адрес уведомлений и его секрет, если касса будет ждать уведомлений, а не только читать платёж: Уведомления.

Шаг 1. Создать платёж

Создайте платёж с ключом повтора, адресом возврата и fieldsOnPage: true, если поля плательщика должна собрать страница:

Тело запроса
{
  "reference": "order-1001",
  "service": "pix_brl_requisite",
  "amountMinor": "1250",
  "customer": { "id": "player-42", "country": "BR" },
  "returnUrl": "https://shop.example/return/order-1001",
  "fieldsOnPage": true
}

Сохраните id и pageUrl из ответа рядом с заказом. Ответ на обрыв связи: повторите тот же запрос с тем же ключом, Повтор запроса.

Шаг 2. Отправить плательщика

Отправьте плательщика по pageUrl переходом. Язык задаётся параметром lang перед #. Если pageUrl равен null, страницы нет. Платёж с полями в fields покажите своей формой по action. Платёж с fieldsOnPage без страницы не оплатить, он истечёт по сроку: соберите поля своей формой и создайте новый платёж с fields и новым номером заказа.

Шаг 3. Узнать исход

Возврат плательщика на returnUrl исход не сообщает. Исход приходит одним из двух путей:

  • уведомление payment.updated на ваш адрес: проверьте подпись, затем прочитайте платёж по payment.id из уведомления;
  • чтение GET /api/v1/payments/:id, не чаще раза в 5 секунд, до финального статуса без разбора либо до PARTIALLY_PAID или OVERPAID.

При любом пути истёкшие платежи перечитывайте сверкой: деньги по ним могут прийти позже, а уведомление может не дойти.

Зачисляйте при SUCCEEDED, когда inReview равен false, ровно paidMinor, один раз на платёж: Когда зачислять.

Шаг 4. Проверить в тестовом контуре

  1. Платёж с fieldsOnPage: true открывается по pageUrl, форма просит поля сервиса, после отправки платёж уходит из CREATED.
  2. Платёж без fieldsOnPage с полями в fields открывается сразу на реквизите или переходе к провайдеру.
  3. returnUrl вне списка источников получает отказ return_url_not_allowed, адрес из списка принимается.
  4. Метки тестовых данных paid, declined, timeout_paid и underpaid дают на странице и в кассе один и тот же исход, и зачисляется только оплаченный без разбора.
  5. Ссылка с lang=es открывает страницу по-испански.
  6. Повтор создания с тем же ключом отдаёт тот же pageUrl.

API v1 · собрано 18.11.2026 · выпуск f13e6bf

Справочник методов собирается из кода сервера: он не описывает адрес, которого нет.