Pago por envío de formulario

Resumen

El pago por envío de formulario es la integración MakePay con menor fricción. Un formulario HTML normal envía los campos del pedido a MakePay, MakePay crea un enlace de pago de checkout alojado y el comprador es redirigido a la página de pago.

Úsalo cuando tu sitio pueda renderizar un formulario HTML pero todavía no quieras escribir un cliente API server-side. Para plataformas e-commerce avanzadas, plugins, SDKs o sistemas de pedidos de servidor, prefiere la API de enlaces de pago, apps OAuth o los módulos oficiales de tienda.

Modelo de seguridad

La acción del formulario usa el ID de clave API de MakePay como clave pública de formulario:

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

El secreto API nunca se usa en el navegador. Antes de habilitar un formulario, abre el dashboard de MakeCrypto, crea o elige una clave de integración MakePay y agrega el origen exacto del sitio a Allowed origins, por ejemplo:

https://merchant.example

MakePay solo acepta envíos de navegador cuyo Origin o Referer coincida con uno de esos orígenes permitidos. Las claves sin orígenes permitidos son rechazadas por el gateway de formulario.

Formulario básico

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

Cuando el comprador envía el formulario, MakePay crea un enlace de pago de un solo uso y responde con 303 See Other hacia la URL de checkout alojado.

Campos

Campo	Requerido	Notas
amount	Sí	Importe decimal positivo. Hasta 8 decimales.
currency	No	Símbolo preferido de liquidación cripto, por ejemplo USDT, USDC, BTC, ETH, LTC o DOGE.
asset	No	Identificador exacto del activo de destino cuando un símbolo existe en varias cadenas.
fiat_currency	No	Moneda visible como USD o EUR. También acepta fiatCurrency, display_currency y displayCurrency.
title	No	Título del checkout. También acepta name y label.
description	No	Descripción del checkout.
order_id	No	ID de pedido o factura del merchant. También acepta orderId, invoice_id e invoiceId.
client_id	No	ID de cliente del lado merchant. También acepta clientId.
customer_email	No	Email del cliente. También acepta customerEmail y email.
customer_name	No	Nombre del cliente. También acepta customerName.
return_url	No	URL absoluta http o https para un destino genérico de retorno.
success_url	No	URL absoluta http o https usada después de un pago exitoso.
failure_url	No	URL absoluta http o https usada para pagos fallidos y errores de validación de formulario.
expiration_time	No	15m, 1h, 12h, 24h, 72h o never. Predeterminado: 12h.
send_payment_request_email	No	Usa true, 1, yes u on para enviar también la solicitud de pago por email. Requiere customer_email.
metadata[key]	No	Metadata extra como string. Las claves pueden contener letras, números, _, ., : y -. Hasta 25 campos de metadata.

Formularios dinámicos

Renderiza el formulario desde el servidor con el importe real y el ID de pedido. No confíes en importes enviados desde una página editable por el cliente a menos que tu servidor los valide o los reconstruya.

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

Comportamiento de redirección

Los envíos de formulario correctos redirigen al checkout alojado de MakePay. Los campos success_url, failure_url y return_url se guardan en el enlace de pago y el checkout los usa después del pago.

Si la validación falla y failure_url es válida, MakePay redirige de vuelta con:

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

Los fallos de origen/autenticación se muestran como una página de error de MakePay en lugar de redirigir a una URL no confiable.

Webhooks

Usa webhooks de MakePay para actualizaciones finales de pedidos. La redirección del cliente es útil para la experiencia de usuario, pero los webhooks son la fuente confiable para estado de pago, pagos incompletos, sobrepagos, reembolsos y expiraciones.

Consulta la guía de webhooks para verificación de firmas y payloads de eventos.

Solución de problemas

• Allowed origin required: agrega el origen de tu sitio a la clave de integración MakePay.
• Origin not allowed: el formulario se envía desde un dominio, esquema o puerto diferente al origen permitido configurado.
• invalid_amount: falta amount, es cero, negativo o no es decimal.
• invalid_currency: usa un símbolo de moneda como USD, USDT o BTC.
• invalid_url: los campos de redirección deben ser URLs absolutas http o https.
• onboarding_required: el merchant todavía no configuró un activo de liquidación MakePay predeterminado.