Paiement pour la soumission du formulaire

Aperçu

Le paiement par soumission de formulaire est l'intégration MakePay à moindre friction. Un formulaire HTML normal publie les champs de commande sur MakePay, MakePay crée un lien de paiement checkout hébergé et l'acheteur est redirigé vers la page de paiement.

Utilisez-le lorsque votre site peut afficher un formulaire HTML mais que vous ne souhaitez pas encore écrire de client API côté serveur. Pour les plateformes de commerce électronique avancées, les plugins, les SDK ou les systèmes de commande de serveur, préférez les applications Payment Links API, OAuth ou les modules de la boutique officielle.

Modèle de sécurité

L'action de formulaire utilise l'ID de clé MakePay API comme clé de formulaire publique :

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

Le secret API n'est jamais utilisé dans le navigateur. Avant d'activer un formulaire, ouvrez le tableau de bord MakeCrypto, créez ou choisissez une clé d'intégration MakePay et ajoutez l'origine exacte du site Web à Origines autorisées, par exemple :

https://merchant.example

MakePay n'accepte que les soumissions de navigateur dont Origin ou Referer correspond à l'une de ces origines autorisées. Les clés sans origines autorisées sont rejetées par la passerelle de formulaire.

Formulaire de base

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

Lorsque l'acheteur soumet le formulaire, MakePay crée un lien de paiement unique et répond avec 303 See Other au checkout URL hébergé.

Champs

Champ	Requis	Remarques
amount	Oui	Montant décimal positif. Jusqu'à 8 décimales.
currency	Non	Symbole de règlement cryptographique préféré, par exemple USDT, USDC, BTC, ETH, LTC ou DOGE.
asset	Non	Identificateur exact de l'actif de destination lorsqu'un symbole existe sur plusieurs chaînes.
fiat_currency	Non	Afficher la devise telle que USD ou EUR. Accepte également les fiatCurrency, display_currency et displayCurrency.
title	Non	Titre de paiement. Accepte également les name et label.
description	Non	Description du paiement.
order_id	Non	Numéro de commande ou de facture du marchand. Accepte également les orderId, invoice_id et invoiceId.
client_id	Non	Client marchand/ID client. Accepte également clientId.
customer_email	Non	E-mail du client. Accepte également les customerEmail et email.
customer_name	Non	Nom du client. Accepte également customerName.
return_url	Non	Absolute http ou https URL pour une destination de retour générique.
success_url	Non	Absolu http ou https URL utilisé après un paiement réussi.
failure_url	Non	Absolu http ou https URL utilisé pour les échecs de paiement et les erreurs de validation de formulaire.
expiration_time	Non	15m, 1h, 12h, 24h, 72h ou never. La valeur par défaut est 12h.
send_payment_request_email	Non	Définissez sur true, 1, yes ou on pour également envoyer la demande de paiement par courrier électronique. Nécessite customer_email.
metadata[key]	Non	Métadonnées de chaîne supplémentaires. Les clés peuvent contenir des lettres, des chiffres, _, ., : et -. Jusqu'à 25 champs de métadonnées.

Formulaires dynamiques

Le serveur rend le formulaire avec le montant réel de la commande et l'ID de la commande. Ne faites pas confiance aux montants soumis à partir d’une page modifiable par le client à moins que votre serveur ne les valide ou ne les reconstruise.

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

Comportement de redirection

Les soumissions de formulaire réussies redirigent vers le MakePay checkout hébergé. Les champs success_url, failure_url et return_url sont enregistrés sur le lien de paiement et utilisés par le checkout après le paiement.

Si la validation échoue et que failure_url est valide, MakePay redirige avec :

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

Les échecs d'origine/d'authentification sont affichés sous la forme d'une page d'erreur MakePay au lieu d'être redirigés vers un URL non fiable.

Webhooks

Utilisez MakePay webhooks pour les mises à jour finales des commandes. La redirection client est utile pour l'expérience utilisateur, mais webhooks est la source fiable de vérité sur l'état du paiement, le sous-paiement, le trop-payé, les remboursements et l'expiration.

Consultez le guide Webhooks pour la vérification des signatures et les charges utiles des événements.

Dépannage

• Allowed origin required : ajoutez l'origine de votre site à la clé d'intégration MakePay.
• Origin not allowed : le formulaire est soumis depuis un autre domaine, schéma ou port que l’origine autorisée configurée.
• invalid_amount : amount est manquant, zéro, négatif ou non décimal.
• invalid_currency : utilisez un symbole monétaire tel que USD, USDT ou BTC.
• invalid_url : les champs de redirection doivent être des URL absolues http ou https.
• onboarding_required : le merchant n'a pas configuré de MakePay par défaut actif de règlement encore.