Créer un lien de paiement : chaque réglage, du portail à l'API

Créer un lien de paiement demande peu de réglages : un montant en dirhams, une description, une expiration, puis, si vous le souhaitez, un client enregistré et l'option « Paiement en agence » ; le lien réutilisable, lui, se crée par l'API. Le portail ChariPay vous rend un lien à usage unique à partager — par message, e-mail, QR code ou affiche — et vous dit quand il est payé. Ce guide passe chaque réglage en revue, du portail à l'API : ce qu'il fait, quand le choisir, les erreurs qui coûtent un double paiement ou un client perdu, et l'appel unique qui crée le même lien depuis votre code sans jamais le créer deux fois.

Créer un lien de paiement : ce qu'il vous faut avant de commencer

Un lien de paiement, c'est un montant et une description ; le client paie sur une page hébergée par ChariPay. ChariPay est une plateforme de paiement marocaine, un PSP opéré par Chari Money, établissement de paiement agréé par Bank Al-Maghrib. Pour créer un lien, il ne vous faut ni site web ni développeur : seulement un accès au portail.

Pour suivre ce guide en le pratiquant, un compte en mode test suffit. Le mode test s'ouvre dès l'activation de votre compte, sans validation à attendre : Commencer en mode test — trois champs (nom, e-mail professionnel, entreprise), un lien d'activation reçu par e-mail pour choisir votre mot de passe, puis le portail, où vous créez vous-même votre clé de test après une ré-authentification ; la clé complète ne s'affiche qu'une seule fois. Payez vos liens de test avec la carte de test 4918 9141 0719 5005, CVV 123, n'importe quelle date d'expiration future, code 3-D Secure 555 : seule cette carte est acceptée, et aucun argent réel ne circule. La vérification de votre entreprise (KYB) se fait en parallèle et ne conditionne que le passage en production. Le mode test est gratuit, sans limite de durée et sans engagement.

Deux lectures complètent celle-ci sans la répéter : la page des liens de paiement présente l'offre, et l'article lien de paiement ou checkout vous aide à choisir entre un lien et une session de paiement intégrée à votre site. Ici, le lien est choisi : il reste à bien le régler.

Créer un lien de paiement dans le portail, étape par étape

Dans le portail, tout part de l'écran « Liens de paiement », qui liste les liens déjà créés avec leur statut.

1. 1Ouvrez les liens de paiement du portail et lancez la création d'un nouveau lien.
2. 2Saisissez le montant en dirhams (MAD) et la description que le client lira sur la page : l'objet de la vente et votre référence interne.
3. 3Gardez l'usage unique pour une vente précise : le lien est consommé après un paiement réussi. Le lien réutilisable, pour un même montant payé par plusieurs clients, est présenté plus bas.
4. 4Choisissez l'expiration : 24 heures, 7 jours, 30 jours, jamais, ou une date précise.
5. 5Rattachez un client enregistré si vous le souhaitez : vous retrouvez ainsi ses coordonnées pour vos prochains liens.
6. 6Activez « Paiement en agence » si vous savez que le client paiera en espèces : cette option désactive l'expiration du lien, qui reste payable sans limite de temps ; un lien qui porte une date d'expiration se présente donc comme un lien à régler par carte.
7. 7Créez le lien et copiez-le, ou affichez son QR code, pour le partager.

Le lien créé apparaît dans la liste au statut actif. Tout est en dirhams marocains (MAD) : encaissements, soldes, virements et versements, sans conversion. Si vous vous trompez de montant avant le paiement, ne bricolez pas : annulez ce lien et créez-en un nouveau.

Les réglages d'un lien, champ par champ

La description mérite plus d'attention qu'on ne lui en donne. Le client la lit au moment de payer : « Commande #1042 — 2 coffrets » le rassure davantage qu'un intitulé vague. Et c'est par elle que vous retrouverez le lien dans le portail, puis le mouvement dans vos exports. Une règle simple tient longtemps : l'objet, puis votre numéro de commande, de devis ou de facture.

Usage unique ou réutilisable : ce que le choix change

Le lien à usage unique porte une vente : une commande, un client, un montant. Il est consommé après un paiement réussi, ce qui exclut qu'un client règle deux fois la même commande. C'est aussi le seul lien qui ouvre les espèces : sur sa page, le client choisit entre la carte et les espèces en agence. Le paiement en espèces en agence s'appuie toujours sur un lien à usage unique — une référence par dépôt. Le fonctionnement complet, de la référence au dépôt, est expliqué dans notre guide pour encaisser en espèces en agence.

Le lien réutilisable porte un prix : le même montant, payé par autant de clients que nécessaire jusqu'à son expiration ou son annulation — une cotisation, un billet, un produit phare. Il encaisse par carte uniquement. C'est le lien qui va sur une affiche, en bio d'un réseau social ou sur une page de votre site. Depuis le portail, chaque lien de paiement créé est à usage unique. Le lien réutilisable — un même montant payé par plusieurs clients — se crée par l'API, avec singleUse: false ; une fois créé, il apparaît dans le portail comme les autres. Sans développeur, pour vendre plusieurs fois au même prix, publiez un produit sur votre boutique hébergée et partagez son lien.

Dans le doute, choisissez l'usage unique : un lien réutilisable envoyé à un seul client fonctionne, mais il reste payable après son paiement, et il ferme la porte aux espèces.

Partager le lien là où votre client vous lit

Un lien se partage par lien, QR code, affiche PDF à imprimer, e-mail ou WhatsApp. Choisissez le canal où la vente se conclut déjà :

• Lien à copier : dans une conversation WhatsApp, un message privé, un SMS ou un e-mail que vous écrivez vous-même. Le SMS est votre geste : ChariPay n'envoie votre lien de paiement ni par SMS ni par WhatsApp.
• E-mail : depuis le portail, ou par l'API avec POST /v1/payment-links/{reference}/send, qui répond 202 et envoie le lien au client enregistré ou à l'adresse que vous indiquez.
• QR code et affiche PDF : pour un comptoir, un stand ou un document imprimé. Leur usage — où les placer, quel lien imprimer — est détaillé dans notre guide du paiement par QR code.

Accompagnez toujours le lien d'une phrase qui rappelle le montant et l'objet : le client retrouve ainsi sur la page exactement ce qu'il vient de lire.

Suivre, annuler et personnaliser un lien

Chaque lien a un statut clair : actif, payé, annulé, expiré. À l'encaissement, vous êtes notifié dans le portail, et la liste montre l'origine de chaque lien — tableau de bord ou API —, ce qui évite de confondre les liens de votre équipe et ceux de votre site.

Pour annuler un lien, passez par le portail, ou par l'API avec POST /v1/payment-links/{reference}/cancel. Un lien annulé ne peut plus être payé : annulez systématiquement l'ancien lien avant d'en envoyer un autre pour la même vente.

Côté client, la page d'un lien affiche votre nom et votre logo ; elle se règle depuis les paramètres de votre compte.

Créer le même lien par l'API

Un appel suffit : POST /v1/payment-links renvoie le payUrl à partager. La base est unique, https://api-psp.charipay.ma, en test comme en production : c'est la clé qui choisit l'environnement. Les montants sont en unités majeures (149.90 = 149,90 MAD).

curl -X POST 'https://api-psp.charipay.ma/v1/payment-links' \
  -H 'X-CHARI-PAY-API-KEY: chari_sk_test_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042-link' \
  -d '{
    "amount": 149.90,
    "description": "Commande #1042",
    "singleUse": true,
    "externalId": "order-1042",
    "customerEmail": "amine.bennani@example.com",
    "customerPhone": "+212600000000",
    "metadata": { "cartId": "c_987" }
  }'

La réponse 201 — ou 200 si le lien existait déjà avec cet externalId — porte la reference du lien (pl_…) et son payUrl, l'adresse à envoyer au client. Pour un lien réutilisable, passez singleUse à false : il encaisse alors par carte uniquement. Le metadata, un objet plat, vous revient tel quel à la lecture du lien et dans l'événement de paiement : c'est par lui que votre système retrouve la commande.

Pour un lien à régler en espèces, ajoutez paymentMethod: "CASH" et laissez singleUse à true :

curl -X POST 'https://api-psp.charipay.ma/v1/payment-links' \
  -H 'X-CHARI-PAY-API-KEY: chari_sk_test_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1043-link' \
  -d '{
    "amount": 320.00,
    "description": "Commande #1043",
    "singleUse": true,
    "paymentMethod": "CASH",
    "externalId": "order-1043",
    "customerPhone": "+212600000000",
    "metadata": { "orderNumber": "1043" }
  }'

Le code à présenter en agence (cashinCode) et l'entité de dépôt (cashinEntity) ne figurent pas dans la réponse de création : ils naissent à la première ouverture de la page de paiement et se lisent ensuite par GET /v1/payment-links/{reference}. Sur cette lecture, testez status contre "ACTIVE" pour savoir si le lien est encore ouvert, et lisez useCount et totalCollected pour savoir ce qu'il a encaissé. Les autres appels — liste, annulation, envoi, QR, affiche — sont décrits dans le module « Liens de paiement » de la documentation.

Ne jamais créer deux fois le même lien

Le scénario classique : votre serveur envoie la création, la connexion coupe avant la réponse, votre code réessaie. Sans précaution, votre client reçoit deux liens pour une commande. Deux outils l'évitent.

• Le champ `externalId` : votre identifiant, unique par compte et par environnement. Une création avec un externalId existant renvoie la ressource existante en 200 OK au lieu de 201 Created. Les deux sont des succès : testez le statut, et ne traitez pas le 200 comme une erreur.
• L'en-tête `Idempotency-Key` : rejouer la même valeur renvoie le premier résultat ; la même clé avec un corps différent répond 409 IDEMPOTENCY_CONFLICT. Il est borné au compte : gardez des clés distinctes entre sandbox et production.

Conséquence pratique : un externalId déjà utilisé vous renverra toujours le même lien, même expiré ou annulé. Pour un nouveau lien sur la même commande, donnez-lui un nouvel externalId (order-1042-2, par exemple). Le principe, et ses limites, sont développés dans notre article sur l'idempotence des paiements.

Questions fréquentes

Comment créer un lien de paiement à régler en espèces ?

Créez un lien à usage unique avec « Paiement en agence » dans le portail — sans expiration —, ou par l'API avec paymentMethod: "CASH" et singleUse à true. Le client reçoit une référence sur la page, la règle dans une agence du réseau Chari, et le lien passe « Payé » dès que le réseau confirme le dépôt. Un lien réutilisable, lui, n'accepte que la carte.

Quelle expiration choisir pour un lien de paiement ?

Celle de votre offre. 24 heures pour une vente conclue en conversation, 7 ou 30 jours pour un devis ou une facture, une date précise pour une offre de saison, jamais pour une affiche permanente. Passé ce délai, la page indique au client que l'offre n'est plus disponible, et aucun paiement ne peut plus passer : s'il veut toujours acheter, créez un nouveau lien.

Comment savoir qu'un lien de paiement a été payé ?

À l'encaissement, vous êtes notifié dans le portail et le lien à usage unique passe « Payé ». Par l'API, GET /v1/payment-links/{reference} renvoie notamment useCount et totalCollected, et l'événement de paiement par carte vous renvoie votre metadata. Ne vous fiez jamais à une capture d'écran envoyée par le client : seul le statut du lien, dans votre portail ou lu par l'API, fait foi.

Comment annuler un lien de paiement déjà envoyé ?

Depuis le portail, ou par l'API avec POST /v1/payment-links/{reference}/cancel. Un lien annulé ne peut plus être payé, même si le client l'a encore dans sa conversation : s'il l'ouvre, il ne pourra pas régler. Prévenez-le, et envoyez-lui le nouveau lien si la vente continue. Annulez toujours l'ancien lien avant d'en envoyer un autre pour la même vente.

Peut-on enregistrer un client pour lui envoyer d'autres liens ?

Oui. Enregistrez vos clients et leurs contacts dans le portail : vous les rattachez ensuite à vos prochains liens sans ressaisir leurs coordonnées. Par l'API, un lien porte aussi customerName, customerEmail et customerPhone. L'e-mail enregistré sert notamment à l'envoi du lien par POST /v1/payment-links/{reference}/send, quand vous n'indiquez pas d'autre adresse.

Peut-on afficher son logo sur la page de paiement ?

Oui. La page d'un lien affiche votre nom et votre logo, et ce réglage se fait depuis les paramètres de votre compte. Votre client voit ainsi, sur une page hébergée par ChariPay, le commerce auquel il paie, le montant et la description, avant de saisir sa carte et de confirmer avec 3-D Secure.

Peut-on créer un lien de paiement par l'API ?

Oui : un appel suffit, POST /v1/payment-links renvoie le payUrl à partager. Les champs requis sont amount et description ; singleUse, paymentMethod, expiresAt, les coordonnées du client, externalId et metadata sont optionnels. La clé de test chari_sk_test_… crée des liens de test, payables avec la carte de test, sur la même base https://api-psp.charipay.ma.

Que se passe-t-il si la même création de lien est envoyée deux fois ?

Avec le même externalId, la seconde création renvoie le lien existant en 200 OK au lieu de 201 Created : aucun doublon n'est créé. Avec le même Idempotency-Key, le premier résultat est rejoué ; la même clé avec un corps différent répond 409 IDEMPOTENCY_CONFLICT. Sans l'un ni l'autre, deux liens distincts sont créés, et votre client peut en recevoir deux.

Prochaine étape

Ouvrez votre compte de test — Commencer en mode test —, créez votre premier lien dans le portail et payez-le avec la carte de test, puis créez le même lien par l'API avec votre clé de test et un externalId. Pour aller plus loin, imprimez son QR code avec notre guide du paiement par QR code, ou vendez en conversation avec notre méthode pour vendre sur Instagram et WhatsApp.