Выплата в 1 клик (виджет)

Перед тем как начать

Обзор

Виджет выплаты — это страница, которую вы встраиваете на свой сайт в iframe (или открываете поп-апом). Он выплачивает на рублёвый счёт физического лица в российском банке — это та же выплата BANK_ACCOUNT, что и в разделе Россия (банковский счёт), но реквизиты клиент вводит в виджете, а не на вашем сайте:

• Первая выплата. Клиент указывает ФИО, телефон, привязанный к счёту, номер счёта, БИК банка и по желанию дату рождения. Мы сохраняем реквизиты за этим клиентом и создаём выплату.
• Следующие выплаты. Виджет показывает сохранённый счёт (логотип банка, последние четыре цифры, ФИО), и клиент подтверждает выплату одной кнопкой. Перед подтверждением клиент может заменить реквизиты.

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

Порядок действий

{
  "merchantId": "0198c3f1-1111-7222-8333-444455556666",
  "userId": "user_12345",
  "amount": "1500.00",
  "currency": "RUB",
  "externalId": "payout-123",
  "serviceId": 123,
  "expiresAt": 1790000000
}

https://pay.platinout.com/payout-widget?payload={payload}&signature={signature}

Поля payload

Все поля, кроме serviceId, обязательны. Неизвестные поля отклоняются, а строковые поля не должны содержать управляющих символов (переводов строки и т. п.).

Подпись

payload — base64url-кодировка (RFC 4648 §5: - и _ вместо + и /, выравнивание = не обязательно) JSON в UTF-8. signature — hex(HMAC-SHA512(apiToken, payload)), где payload — закодированная строка, а не JSON. Оба значения безопасны для URL и подставляются как есть.

import crypto from "crypto";

const params = {
  merchantId: process.env.MERCHANT_ID,
  userId: "user_12345",
  amount: "1500.00",
  currency: "RUB",
  externalId: "payout-123",
  serviceId: 123,
  expiresAt: Math.floor(Date.now() / 1000) + 30 * 60, // 30 минут
};

const payload = Buffer.from(JSON.stringify(params)).toString("base64url");
const signature = crypto
  .createHmac("sha512", process.env.API_TOKEN)
  .update(payload)
  .digest("hex");

const widgetUrl = `https://pay.platinout.com/payout-widget?payload=${payload}&signature=${signature}`;

import base64, hashlib, hmac, json, os, time

params = {
    "merchantId": os.environ["MERCHANT_ID"],
    "userId": "user_12345",
    "amount": "1500.00",
    "currency": "RUB",
    "externalId": "payout-123",
    "serviceId": 123,
    "expiresAt": int(time.time()) + 30 * 60,  # 30 минут
}

raw = json.dumps(params, separators=(",", ":")).encode()
payload = base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
signature = hmac.new(os.environ["API_TOKEN"].encode(), payload.encode(), hashlib.sha512).hexdigest()

widget_url = f"https://pay.platinout.com/payout-widget?payload={payload}&signature={signature}"

<?php
$params = [
    'merchantId' => getenv('MERCHANT_ID'),
    'userId' => 'user_12345',
    'amount' => '1500.00',
    'currency' => 'RUB',
    'externalId' => 'payout-123',
    'serviceId' => 123,
    'expiresAt' => time() + 30 * 60, // 30 минут
];

$json = json_encode($params, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$payload = rtrim(strtr(base64_encode($json), '+/', '-_'), '=');
$signature = hash_hmac('sha512', $payload, getenv('API_TOKEN'));

$widgetUrl = "https://pay.platinout.com/payout-widget?payload={$payload}&signature={$signature}";

Проверьте свою реализацию

С API-токеном YOUR_API_TOKEN и параметрами из первого шага должны получиться:

payload   = eyJtZXJjaGFudElkIjoiMDE5OGMzZjEtMTExMS03MjIyLTgzMzMtNDQ0NDU1NTU2NjY2IiwidXNlcklkIjoidXNlcl8xMjM0NSIsImFtb3VudCI6IjE1MDAuMDAiLCJjdXJyZW5jeSI6IlJVQiIsImV4dGVybmFsSWQiOiJwYXlvdXQtMTIzIiwic2VydmljZUlkIjoxMjMsImV4cGlyZXNBdCI6MTc5MDAwMDAwMH0
signature = 7c39e6f057794d8efdcf2b8859daa91bfdab06caf59e940ecb4d20e4905af2d1c8ef1cdbe6c0d9ab16f4c44deca24bcff3663e6123bc7eafd20ea20176045109

Ваш язык может сериализовать JSON иначе (порядок ключей, пробелы) — это не страшно: главное, подписать ту самую строку payload, которая попадёт в URL.

Встраивание

<iframe
  id="payout-widget"
  src="https://pay.platinout.com/payout-widget?payload=...&signature=..."
  title="Выплата"
  style="width: 100%; max-width: 440px; height: 560px; border: 0"
></iframe>

• Размер. Виджет подстраивается под ширину от 320 px, удобнее всего — 360–480 px. Высота меняется от экрана к экрану: задавайте высоту iframe по событию resize, а не фиксированным значением.
• Поп-ап. Тот же адрес можно открыть через window.open(widgetUrl, "payout", "width=480,height=720"). Тогда события приходят в window.opener, а «Закрыть» закрывает поп-ап сам.
• Повторное открытие. Ссылка, по которой выплата уже создана, показывает её текущее состояние (принята, выполнена или не удалась) вместо формы, поэтому перезагрузка страницы не создаст вторую выплату.
• Замена реквизитов. Клиент может заменить сохранённые реквизиты в виджете, пока выплата по ссылке не создана. После этого ссылка их больше не меняет.

События

Виджет отправляет сообщения странице, которая его встроила (родителю iframe) или открыла (opener поп-апа):

{ "source": "payout-widget", "type": "payout_created", "data": { "externalId": "payout-123", "payoutId": "0198c3f1-2222-7333-8444-555566667777", "status": "CREATED" } }

Прежде чем доверять сообщению, проверьте его источник:

const WIDGET_ORIGIN = "https://pay.platinout.com";
const frame = document.getElementById("payout-widget");

window.addEventListener("message", (event) => {
  if (event.origin !== WIDGET_ORIGIN) return;
  const message = event.data;
  if (!message || message.source !== "payout-widget") return;

  switch (message.type) {
    case "resize":
      frame.style.height = `${message.data.height}px`;
      break;
    case "payout_created":
      // Покажите «выплата принята»; итоговый статус ждите в вебхуке.
      break;
    case "payout_failed":
    case "error":
      // Предложите клиенту повторить позже или запишите message.data.code.
      break;
    case "close":
      frame.remove();
      break;
  }
});

Коды error

Проверка реквизитов

Виджет проверяет реквизиты по мере ввода и ещё раз при сохранении — по тем же правилам, что и выплаты на счёт: ФИО кириллицей, телефон в формате +7XXXXXXXXXX, БИК из списка банков и 20-значный рублёвый счёт физического лица, контрольный ключ которого сходится с БИК. Необязательная дата рождения должна давать возраст от 14 до 120 лет.

Рекомендации

• Создавайте ссылку в момент, когда клиент запрашивает выплату, с коротким expiresAt и каждый раз с новым externalId.
• Не записывайте ссылки в логи и никому их не передавайте: пока выплата не создана, по ссылке можно заменить реквизиты клиента.
• Зарезервируйте сумму у себя до открытия виджета и проведите её по вебхуку выплаты.

Следующие шаги