Form submit payment

Overview

Form submit payment is the lowest-friction MakePay integration. A normal HTML form posts order fields to MakePay, MakePay creates a hosted checkout payment link, and the shopper is redirected to the payment page.

Use this when your site can render an HTML form but you do not want to write a server-side API client yet. For advanced ecommerce platforms, plugins, SDKs, or server order systems, prefer the Payment Links API, OAuth apps, or the official store modules.

Security model

The form action uses the MakePay API key ID as a public form key:

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

The API secret is never used in the browser. Before enabling a form, open the MakeCrypto dashboard, create or choose a MakePay integration key, and add the exact website origin to Allowed origins, for example:

https://merchant.example

MakePay only accepts browser submissions whose Origin or Referer matches one of those allowed origins. Keys without allowed origins are rejected by the form gateway.

Basic form

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

When the shopper submits the form, MakePay creates a one-time payment link and responds with 303 See Other to the hosted checkout URL.

Fields

Field	Required	Notes
amount	Yes	Positive decimal amount. Up to 8 decimal places.
currency	No	Preferred crypto settlement symbol, for example USDT, USDC, BTC, ETH, LTC, or DOGE.
asset	No	Exact destination asset identifier when a symbol exists on multiple chains.
fiat_currency	No	Display currency such as USD or EUR. Also accepts fiatCurrency, display_currency, and displayCurrency.
title	No	Checkout title. Also accepts name and label.
description	No	Checkout description.
order_id	No	Merchant order or invoice ID. Also accepts orderId, invoice_id, and invoiceId.
client_id	No	Merchant customer/client ID. Also accepts clientId.
customer_email	No	Customer email. Also accepts customerEmail and email.
customer_name	No	Customer name. Also accepts customerName.
return_url	No	Absolute http or https URL for a generic return destination.
success_url	No	Absolute http or https URL used after successful payment.
failure_url	No	Absolute http or https URL used for failed payment and form validation errors.
expiration_time	No	15m, 1h, 12h, 24h, 72h, or never. Defaults to 12h.
send_payment_request_email	No	Set to true, 1, yes, or on to also email the payment request. Requires customer_email.
metadata[key]	No	Extra string metadata. Keys may contain letters, numbers, _, ., :, and -. Up to 25 metadata fields.

Dynamic forms

Server-render the form with the actual order amount and order ID. Do not trust amounts submitted from a customer-editable page unless your server validates or rebuilds them.

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

Redirect behavior

Successful form submissions redirect to the hosted MakePay checkout. The success_url, failure_url, and return_url fields are saved on the payment link and used by the checkout after payment.

If validation fails and failure_url is valid, MakePay redirects back with:

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

Origin/authentication failures are shown as a MakePay error page instead of redirecting to an untrusted URL.

Webhooks

Use MakePay webhooks for final order updates. The customer redirect is useful for user experience, but webhooks are the reliable source of truth for payment state, underpayment, overpayment, refunds, and expiration.

See the Webhooks guide for signature verification and event payloads.

Troubleshooting

• Allowed origin required: add your site origin to the MakePay integration key.
• Origin not allowed: the form is being submitted from a different domain, scheme, or port than the configured allowed origin.
• invalid_amount: amount is missing, zero, negative, or not a decimal.
• invalid_currency: use a currency symbol such as USD, USDT, or BTC.
• invalid_url: redirect fields must be absolute http or https URLs.
• onboarding_required: the merchant has not configured a default MakePay settlement asset yet.