Платежи Fast Track

Плательщик открывает этот URL и авторизует платёж в своём банке. Под капотом создаётся то же неизменяемое намерение оплаты, что и в остальном API: сумма, получатель и назначение платежа фиксируются до того, как что-либо попадёт в браузер, а заголовок Idempotency-Key предотвращает повторное списание, если вызов прервётся.

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

POST /payments/?action=fast-track

Обязательные заголовки: Content-Type: application/json, X-API-Key и Idempotency-Key. Ключ содержит от 16 до 128 символов, начинается с буквы или цифры и допускает только буквы, цифры и . _ : -; подойдёт UUID v4. Если ключ отсутствует или его длина недопустима, ответ — 400 idempotency_key_required; если в нём другие символы — 422 invalid_customer_reference. Этот ключ также служит референсом продавца: передавать его в теле не нужно. Если повторить тот же ключ с тем же телом, вы снова получите тот же URL. Если использовать его повторно с другими данными, ответ — 409 idempotency_conflict.

Все поля обязательны, кроме logo. Тело проверяется по белому списку. Лишнее поле или отсутствие обязательного возвращает 422 invalid_request. logo входит в состав платежа: повтор того же Idempotency-Key с другим logo также даёт 409 idempotency_conflict.

У мгновенного платежа нет собственного лимита в этом API. Банк отклоняет платёж, который не может принять, в том числе из-за суммы, и этот отказ приходит как KO на notification_url.

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"
: "${WR_PAYMENT_IDEMPOTENCY_KEY:?Genere un UUID v4 para este pago}"

curl --request POST 'https://api.wealthreader.com/payments/?action=fast-track' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --header "Idempotency-Key: ${WR_PAYMENT_IDEMPOTENCY_KEY}" \
  --data '{
    "amount": "15.50",
    "currency": "EUR",
    "beneficiary": {
      "name": "Comercio Online S.L.",
      "iban": "ES9121000418450200051332"
    },
    "reference": "Pedido 78901",
    "priority": "normal",
    "notification_url": "https://tienda.example.com/pagos/aviso",
    "logo": "https://tienda.example.com/marca/logo.svg"
  }'

Ответ — 201 в первый раз и 200, если ключ уже существовал, — содержит URL и идентификатор платежа:

{
  "url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…&api_origin=https%3A%2F%2Fapi.wealthreader.com",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

Перенаправьте плательщика на этот URL. Токен находится во фрагменте URL, истекает вместе с виджетом (обычно через 15 минут) и не должен попадать в ваши журналы. Сохраните payment_intent_id вместе с заказом.

Уведомление OK или KO

Когда Wealthreader проверяет статус платежа и обнаруживает, что он окончательный, он отправляет POST на notification_url с Content-Type: application/json и User-Agent: WealthReader-Payments:

{
  "outcome": "ok",
  "payment_status": "settled",
  "customer_reference": "11111111-1111-4111-8111-111111111111",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

• outcome равен ok, только если банк провёл расчёт (settled). При rejected, cancelled, expired и failed отправляется ko. Неоднозначный результат (reconciliation_required) не является окончательным, и уведомление о нём не отправляется.
• customer_reference — это ваш Idempotency-Key, а payment_intent_id — идентификатор, возвращённый при создании платежа.
• Ответьте 2xx, чтобы уведомление считалось доставленным. Wealthreader ждёт не более 3 секунд и не следует перенаправлениям.
• Одно и то же уведомление может прийти несколько раз: считайте сочетание customer_reference и outcome идемпотентным.
• URL, не являющийся публичным https, отклоняется при создании платежа и проверяется повторно перед каждой отправкой.

Когда приходит уведомление. Статус проверяется, пока плательщик остаётся на странице оплаты, которая опрашивает его до окончательного результата или до истечения платёжной сессии, а также каждый раз, когда вы вызываете POST /payments/?action=status. Отдельной отправки по расписанию нет: если плательщик закроет страницу до того, как банк завершит операцию, или если ваш сервер не ответит 2xx, уведомление будет отправлено при следующей проверке. Поэтому, если вы не получили уведомление через несколько минут после перенаправления плательщика, запросите статус по payment_intent_id; этот запрос также запускает отправку ожидающего уведомления. См. Статусы, периодический опрос и сверка платежей.

Уведомление не подписано. Прежде чем передать ценный товар или оказать услугу, подтвердите результат через POST /payments/?action=status, используя ваш X-API-Key и payment_intent_id: финансовым подтверждением является только payment_status: settled в этом ответе.