Pagamento pelo envio do formulário

Resumo

O pagamento por envio de formulário é a integração MakePay de menor atrito. Um formulário HTML normal envia os campos do pedido para MakePay, MakePay cria um link de pagamento hospedado checkout e o comprador é redirecionado para a página de pagamento.

Use-o quando seu site puder renderizar um formulário HTML, mas você ainda não quiser escrever um cliente do lado do servidor API. Para plataformas avançadas de comércio eletrônico, plugins, SDKs ou sistemas de pedidos de servidores, prefira os links de pagamento API, aplicativos OAuth ou os módulos oficiais da loja.

Modelo de segurança

A ação do formulário usa o ID da chave API de MakePay como a chave pública do formulário:

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

O segredo API nunca é usado no navegador. Antes de ativar um formulário, abra o painel MakeCrypto, crie ou escolha uma chave de integração MakePay e adicione a origem exata do site a Origens permitidas, por exemplo:

https://merchant.example

MakePay aceita apenas envios de navegador cujo Origin ou Referer corresponda a uma dessas origens permitidas. Chaves sem origens permitidas são rejeitadas pelo gateway de formulário.

Formulário 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>

Quando o comprador envia o formulário, MakePay cria um link de pagamento único e responde com 303 See Other ao checkout URL hospedado.

Campos

Campo	Solicitado	Notas
amount	Sim	Quantidade decimal positiva. Até 8 casas decimais.
currency	Não	Símbolo de liquidação criptográfica preferido, por exemplo USDT, USDC, BTC, ETH, LTC ou DOGE.
asset	Não	Identificador exato do ativo alvo quando existe um símbolo em múltiplas cadeias.
fiat_currency	Não	Moeda visível como USD ou EUR. Também aceita fiatCurrency, display_currency e displayCurrency.
title	Não	Título de checkout. Também aceita name e label.
description	Não	Descrição do checkout.
order_id	Não	Pedido do comerciante ou ID da fatura. Também aceita orderId, invoice_id e invoiceId.
client_id	Não	ID do cliente do comerciante. Também aceita clientId.
customer_email	Não	E-mail do cliente. Também aceita customerEmail e email.
customer_name	Não	Nome do cliente. Também aceita customerName.
return_url	Não	URL absoluto http ou https para um destino de retorno genérico.
success_url	Não	URL absoluto http ou https usado após pagamento bem-sucedido.
failure_url	Não	URL absoluto http ou https usado para pagamentos com falha e erros de validação de formulário.
expiration_time	Não	15m, 1h, 12h, 24h, 72h ou never. Padrão: 12h.
send_payment_request_email	Não	Utilize true, 1, yes ou on para enviar também o pedido de pagamento por email. Requer customer_email.
metadata[key]	Não	Metadados extras como string. As chaves podem conter letras, números, _, ., : e -. Até 25 campos de metadados.

Formulários dinâmicos

Renderiza o formulário do servidor com o valor real e o ID do pedido. Não confie nos valores enviados de uma página editável pelo cliente, a menos que seu servidor os valide ou reconstrua.

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

Redirecionar comportamento

Os envios de formulário bem-sucedidos redirecionam para checkout hospedado em MakePay. Os campos success_url, failure_url e return_url são salvos no link de pagamento e utilizados por checkout após o pagamento.

Se a validação falhar e failure_url for válido, MakePay redirecionará de volta com:

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

As falhas de origem/autenticação são exibidas como uma página de erro MakePay em vez de redirecionar para um URL não confiável.

Webhooks

Use webhooks de MakePay para atualizações finais do pedido. O redirecionamento do cliente é útil para a experiência do usuário, mas webhooks é a fonte confiável para status de pagamento, pagamentos incompletos, pagamentos indevidos, reembolsos e vencimentos.

Consulte o guia do webhooks para verificação de assinatura e cargas úteis de eventos.

Solução de problemas

• Allowed origin required – Adicione a origem do seu site à chave de integração MakePay.
• Origin not allowed: O formulário é enviado de um domínio, esquema ou porta diferente da origem permitida configurada.
• invalid_amount: amount está faltando, é zero, negativo ou não é decimal.
• invalid_currency: Use um símbolo de moeda como USD, USDT ou BTC.
• invalid_url: Os campos de redirecionamento devem ser URLs absolutos http ou https.
• onboarding_required: O estabelecimento comercial ainda não configurou um ativo de liquidação padrão MakePay.