Documentation/Le widget

Le widget

La page de paiement s’ouvre dans un voile, sur votre site. Votre client ne part nulle part, et vous n’hébergez aucun formulaire.

Le script

Un seul fichier, servi par Payiz. Il pose window.Payiz et ne charge rien d’autre.

html

<script src="https://pay.payiz.app/payiz.js"></script>

La façon recommandée : votre serveur crée le paiement

Votre serveur appelle POST /v1/payments avec sa clé secrète, et reçoit un id et un client_secret. Le widget n’a besoin que de ces deux-là.

html

<script src="https://pay.payiz.app/payiz.js"></script>

<button id="payer">Payer 10 000 F</button>

<script>
  document.getElementById('payer').addEventListener('click', () => {
    Payiz.ouvrir({
      // Rendu par POST /v1/payments, depuis votre serveur.
      paiement: 'pay_01j9x3kq7m4tzv8qhw2n',
      secretClient: 'pcs_…',
      onReussi: ({ paiement }) => console.log('payé', paiement),
      onFerme: ({ paye }) => { if (paye) location.assign('/merci') },
    })
  })
</script>

Sans serveur : un lien

Créez un lien de paiement dans Encaisser, à prix fixe ou libre entre deux bornes, puis posez son adresse sur un bouton : le script s’y branche tout seul. Le prix vit dans votre espace, personne ne peut le changer depuis la page, et aucune clé n’y paraît.

html

<script src="https://pay.payiz.app/payiz.js"></script>

<button data-payiz data-lien="https://pay.payiz.app/l/tresses-kodjo">
  Payer les tresses
</button>

Ce que le widget vous dit

onReussi({ paiement }) — le payeur a validé.
onEchec({ paiement }) — une tentative a échoué ; le paiement reste payable.
onFerme({ paye, paiement }) — le voile s’est refermé, payé ou non.
onErreur(erreur) — le paiement n’a pas pu naître.

Payiz.ouvrir(…) rend une promesse avec l’identifiant du paiement, son secret de client, et une fonction fermer().

Ne livrez jamais sur la foi du navigateur

Un rappel dans une page web se falsifie. Ce qui fait foi, c’est le webhook payment.succeeded, ou une lecture de votre serveur. Sans serveur du tout, le secret du client permet au moins de vérifier avant d’afficher un merci :

javascript

const reponse = await fetch(
  `https://api.payiz.app/v1/widget/payments/${paiement}?client_secret=${secret}`,
)
const { status } = await reponse.json()
// « succeeded » suffit pour afficher un merci, pas pour livrer.

Ce que le voile fait

Plein écran sur téléphone, une fenêtre arrondie au-delà.
La touche Échap et la pastille en haut à droite ferment ; le fond ne se referme pas d’un clic distrait.
Une seule page de Payiz peut s’encadrer : celle d’un paiement, et seulement en widget.

La façon recommandée : votre serveur crée le paiement

Votre serveur appelle POST /v1/payments avec sa clé secrète, et reçoit un id et un client_secret. Le widget n’a besoin que de ces deux-là.

html

<script src="https://pay.payiz.app/payiz.js"></script>

<button id="payer">Payer 10 000 F</button>

<script>
  document.getElementById('payer').addEventListener('click', () => {
    Payiz.ouvrir({
      // Rendu par POST /v1/payments, depuis votre serveur.
      paiement: 'pay_01j9x3kq7m4tzv8qhw2n',
      secretClient: 'pcs_…',
      onReussi: ({ paiement }) => console.log('payé', paiement),
      onFerme: ({ paye }) => { if (paye) location.assign('/merci') },
    })
  })
</script>

Sans serveur : un lien

html

<script src="https://pay.payiz.app/payiz.js"></script>

<button data-payiz data-lien="https://pay.payiz.app/l/tresses-kodjo">
  Payer les tresses
</button>

Ce que le widget vous dit

onReussi({ paiement }) — le payeur a validé.

onEchec({ paiement }) — une tentative a échoué ; le paiement reste payable.

onFerme({ paye, paiement }) — le voile s’est refermé, payé ou non.

onErreur(erreur) — le paiement n’a pas pu naître.

Payiz.ouvrir(…) rend une promesse avec l’identifiant du paiement, son secret de client, et une fonction fermer().

Ne livrez jamais sur la foi du navigateur

javascript

const reponse = await fetch(
  `https://api.payiz.app/v1/widget/payments/${paiement}?client_secret=${secret}`,
)
const { status } = await reponse.json()
// « succeeded » suffit pour afficher un merci, pas pour livrer.