Интеграция

Оплата через отправку формы

Запускает размещенный checkout MakePay из простой формы HTML без написания серверного клиента API.

Обзор

Оплата за отправку формы — это интеграция MakePay с минимальными трудностями. Обычная форма HTML отправляет поля заказа в MakePay, MakePay создает размещенную ссылку для оплаты checkout, и покупатель перенаправляется на страницу оплаты.

Используйте его, если ваш сайт может отображать форму HTML, но вы пока не хотите писать серверный клиент API. Для продвинутых платформ электронной коммерции, плагинов, SDK или серверных систем заказов отдайте предпочтение платежным ссылкам API, приложениям OAuth или модулям официального магазина.

Модель безопасности

Действие формы использует идентификатор ключа API из MakePay в качестве открытого ключа формы:

https://makepay.io/gateway/pay/{makepayKeyId}

Секрет API никогда не используется в браузере. Прежде чем активировать форму, откройте панель мониторинга MakeCrypto, создайте или выберите ключ интеграции MakePay и добавьте точный источник сайта в поле Разрешенные источники, например:

https://merchant.example

MakePay принимает только материалы браузера, Origin или Referer которых соответствует одному из этих разрешенных источников. Ключи без разрешенного происхождения отклоняются шлюзом форм.

Основная форма

<form
  method="post"
  action="https://makepay.io/gateway/pay/mk_makepay_YOUR_KEY_ID"
>
  <input type="hidden" name="title" value="Order #1042" />
  <input type="hidden" name="description" value="Checkout for order #1042" />
  <input type="hidden" name="amount" value="129.99" />
  <input type="hidden" name="fiat_currency" value="USD" />
  <input type="hidden" name="currency" value="USDT" />
  <input type="hidden" name="order_id" value="order_1042" />
  <input type="hidden" name="customer_email" value="buyer@example.com" />
  <input
    type="hidden"
    name="success_url"
    value="https://merchant.example/orders/1042/success"
  />
  <input
    type="hidden"
    name="failure_url"
    value="https://merchant.example/orders/1042/failed"
  />
  <input
    type="hidden"
    name="return_url"
    value="https://merchant.example/orders/1042"
  />
  <input type="hidden" name="metadata[cart_id]" value="cart_7M2V" />

  <button type="submit">Pay with crypto</button>
</form>

Когда покупатель отправляет форму, MakePay создает ссылку для одноразового платежа и отправляет ответ 303 See Other на URL размещенного checkout.

Поля

Поле	Запрошено	Оценки
`amount`	Ага	Положительная десятичная сумма. До 8 десятичных знаков.
`currency`	Нет	Предпочтительный символ криптовалютного расчета, например `USDT`, `USDC`, `BTC`, `ETH`, `LTC` или `DOGE`.
`asset`	Нет	Точный идентификатор целевого актива, если символ существует в нескольких цепочках.
`fiat_currency`	Нет	Валюта отображается как `USD` или `EUR`. Также принимает `fiatCurrency`, `display_currency` и `displayCurrency`.
`title`	Нет	Название checkout. Также принимает `name` и `label`.
`description`	Нет	Описание checkout.
`order_id`	Нет	Идентификатор заказа или счета-фактуры merchant. Также принимает `orderId`, `invoice_id` и `invoiceId`.
`client_id`	Нет	Идентификатор стороннего клиента merchant. Также принимает `clientId`.
`customer_email`	Нет	Электронная почта клиента. Также принимает `customerEmail` и `email`.
`customer_name`	Нет	Имя клиента. Также принимает `customerName`.
`return_url`	Нет	Абсолютный URL `http` или `https` для общего пункта назначения возврата.
`success_url`	Нет	Абсолютный URL, `http` или `https` используется после успешной оплаты.
`failure_url`	Нет	URL Абсолютный `http` или `https` используется для неудачных платежей и ошибок проверки формы.
`expiration_time`	Нет	`15m`, `1h`, `12h`, `24h`, `72h` или `never`. По умолчанию: `12h`.
`send_payment_request_email`	Нет	Используйте `true`, `1`, `yes` или `on`, чтобы также отправить запрос платежа по электронной почте. Требуется `customer_email`.
`metadata[key]`	Нет	Дополнительные метаданные в виде строки. Ключи могут содержать буквы, цифры, `_`, `.`, `:` и `-`. До 25 полей metadata.

Динамические формы

Отображает форму с сервера с фактической суммой и идентификатором заказа. Не доверяйте суммам, отправленным с редактируемой клиентом страницы, если ваш сервер не проверит или не восстановит их.

<form
  method="post"
  action="https://makepay.io/gateway/pay/mk_makepay_YOUR_KEY_ID"
>
  <input type="hidden" name="amount" value="{{ order.total }}" />
  <input type="hidden" name="fiat_currency" value="{{ order.currency }}" />
  <input type="hidden" name="order_id" value="{{ order.id }}" />
  <input type="hidden" name="customer_email" value="{{ customer.email }}" />
  <button type="submit">Pay with MakePay</button>
</form>

Поведение перенаправления

Успешные отправки формы перенаправляются на checkout, размещенный на сервере MakePay. Поля success_url, failure_url и return_url сохраняются в платежной ссылке и используются checkout после оплаты.

Если проверка не удалась и failure_url действителен, MakePay перенаправляет обратно с помощью:

?makepay_status=error&makepay_error=invalid_amount&makepay_error_message=...

Ошибки источника/аутентификации отображаются в виде страницы ошибок MakePay вместо перенаправления на ненадежный URL.

Вебхуки

Используйте webhooks из MakePay для окончательного обновления заказа. Перенаправление клиентов полезно для удобства пользователей, но webhooks являются надежным источником информации о статусе платежа, незавершенных платежах, переплатах, возмещениях и сроках действия.

См. руководство webhooks для проверки подписи и полезных данных событий.

Устранение неполадок

Allowed origin required — добавьте источник вашего сайта в ключ интеграции MakePay.
Origin not allowed: форма отправлена из домена, схемы или порта, отличного от настроенного разрешенного источника.
invalid_amount: amount отсутствует, равен нулю, является отрицательным или не десятичным.
invalid_currency: используйте символ валюты, например USD, USDT или BTC.
invalid_url: поля перенаправления должны быть абсолютными URL-адресами http или https.
onboarding_required: merchant еще не настроил расчетный актив по умолчанию MakePay.