Formularz przesłania płatności

Przegląd

Formularz płatności polega na integracji MakePay o najniższym współczynniku tarcia. Zwykły HTML formularz wysyła pola zamówienia do MakePay, MakePay tworzy hostowaną płatność checkout link, a kupujący zostaje przekierowany na stronę płatności.

Użyj tej opcji, jeśli Twoja witryna może renderować formularz HTML, ale nie chcesz pisać formularza jeszcze klient API po stronie serwera. W przypadku zaawansowanych platform e-commerce, wtyczek, SDK lub systemy zamówień serwerowych, preferuj aplikacje Payment Links API, OAuth lub oficjalną moduły magazynowe.

Model bezpieczeństwa

Akcja formularza używa identyfikatora klucza MakePay API jako publicznego klucza formularza:

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

Sekret API nigdy nie jest używany w przeglądarce. Przed włączeniem formularza otwórz plik MakeCrypto, utwórz lub wybierz klucz integracji MakePay i dodaj dokładne pochodzenie strony internetowej na Dozwolone źródła, na przykład:

https://merchant.example

MakePay akceptuje tylko zgłoszenia z przeglądarki, których Origin lub Referer pasują do jednego z dozwolonych źródeł. Klucze bez dozwolonego pochodzenia są odrzucane przez formularz brama.

Podstawowa forma

<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>

Kiedy kupujący wysyła formularz, MakePay tworzy jednorazowy link do płatności i odpowiada 303 See Other na hostowany adres URL checkout.

Pola

Pole	Wymagany	Notatki
amount	Tak	Dodatnia liczba dziesiętna. Do 8 miejsc po przecinku.
currency	NIE	Preferowany symbol rozliczeń kryptowalut, na przykład USDT, USDC, BTC, ETH, LTC lub DOGE.
asset	NIE	Dokładny identyfikator zasobu docelowego, jeśli symbol istnieje w wielu łańcuchach.
fiat_currency	NIE	Wyświetl walutę, np. USD lub EUR. Akceptuje również fiatCurrency, display_currency i displayCurrency.
title	NIE	Tytuł Checkout. Akceptuje również name i label.
description	NIE	Opis Checkout.
order_id	NIE	Identyfikator zamówienia sprzedawcy lub faktury. Akceptuje również orderId, invoice_id i invoiceId.
client_id	NIE	Identyfikator klienta/klienta sprzedawcy. Akceptuje również clientId.
customer_email	NIE	E-mail klienta. Akceptuje również customerEmail i email.
customer_name	NIE	Nazwa klienta. Akceptuje również customerName.
return_url	NIE	Bezwzględny adres URL http lub https dla ogólnego miejsca docelowego powrotu.
success_url	NIE	Bezwzględny adres URL http lub https używany po pomyślnej płatności.
failure_url	NIE	Bezwzględny adres URL http lub https używany w przypadku nieudanych płatności i błędów sprawdzania poprawności formularza.
expiration_time	NIE	15m, 1h, 12h, 24h, 72h lub never. Wartość domyślna to 12h.
send_payment_request_email	NIE	Ustaw na true, 1, yes lub on, aby wysłać żądanie płatności również pocztą elektroniczną. Wymaga customer_email.
metadata[key]	NIE	Dodatkowe metadane ciągu. Klucze mogą zawierać litery, cyfry, _, ., : i -. Do 25 pól metadanych.

Formy dynamiczne

Serwer wyrenderuje formularz z rzeczywistą kwotą zamówienia i identyfikatorem zamówienia. Nie ufaj kwoty przesłane ze strony edytowalnej przez klienta, chyba że serwer zatwierdzi lub odbudowuje je.

<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>

Przekieruj zachowanie

Pomyślne przesłanie formularza przekierowuje do hostowanego MakePay checkout. The Pola success_url, failure_url i return_url są zapisywane na płatności link i używany przez checkout po dokonaniu płatności.

Jeśli weryfikacja nie powiedzie się, a failure_url jest prawidłowe, MakePay przekierowuje z powrotem z:

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

Błędy pochodzenia/uwierzytelnienia są wyświetlane zamiast strony błędu MakePay przekierowanie na niezaufany adres URL.

Webhooks

Użyj MakePay webhooks do aktualizacji zamówień końcowych. Przekierowanie klienta jest przydatne dla doświadczenia użytkownika, ale webhooks są wiarygodnym źródłem prawdy o płatnościach stanu, niedopłaty, nadpłaty, zwrotów i wygaśnięcia.

Zobacz przewodnik Webhooks dotyczący weryfikacji podpisu i ładunków zdarzeń.

Rozwiązywanie problemów

• Allowed origin required: dodaj pochodzenie swojej witryny do klucza integracji MakePay.
• Origin not allowed: wysyłany jest formularz z innej domeny, schemat lub port niż skonfigurowane dozwolone źródło.
• invalid_amount: Brak amount, zero, wartość ujemna lub nie jest to liczba dziesiętna.
• invalid_currency: użyj symbolu waluty, takiego jak USD, USDT lub BTC.
• invalid_url: pola przekierowań muszą być bezwzględnymi adresami URL http lub https.
• onboarding_required: sprzedawca nie skonfigurował domyślnego MakePay jeszcze rozliczenie aktywów.