Comment accepter l’USDC sur Stellar avec des liens SEP-7
Avec Cosmos Pay, un lien de paiement sur Stellar est une demande SEP-7 : votre client scanne son QR code ou l’ouvre dans un wallet comme Freighter, LOBSTR ou xBull, puis y approuve le paiement en USDC. L’USDC va directement sur votre compte Stellar, et Cosmos Pay marque le lien comme payé dès qu’il trouve le paiement grâce au mémo du lien. Pour recevoir l’USDC, votre compte doit déjà avoir une trustline vers cet actif.
Ce que contient un lien SEP-7
SEP-7 est la norme de Stellar pour les demandes de paiement : un lien web+stellar:pay, ou son QR code, avec votre adresse, le montant, l’actif et son émetteur, et un mémo numérique.
Cosmos Pay crée un mémo pour chaque lien et le recherche parmi les paiements reçus par votre compte. Il accepte un paiement qui porte ce mémo, vers votre adresse, dans l’actif du lien et, quand le lien fixe un montant, pour exactement ce montant, effectué après la création du lien.
Préparez votre compte
- Votre compte Stellar doit exister sur le réseau et avoir une trustline vers l’USDC avant de pouvoir en recevoir. Cosmos Pay ne le vérifie pas quand vous ajoutez le compte, et un paiement vers un compte sans la trustline échoue après la signature de votre client.
- Ajoutez le compte à votre organisation dans le tableau de bord, puis signez ce qu’il demande pour prouver que ce compte est à vous.
- Pour les tests, faites de même sur Testnet. Friendbot, le faucet de Testnet, envoie des XLM de test à un compte, et les liens peuvent y encaisser en XLM.
Ce qu’il faut à votre client
- Un wallet Stellar qui ouvre les liens SEP-7, comme Cosmos Pay Wallet, Freighter, LOBSTR, xBull, Albedo ou Rabet, avec l’USDC et un peu de XLM pour les frais de réseau. Aucun compte chez Cosmos Pay.
- Un paiement direct en USDC. Un wallet qui convertit un autre actif en USDC en chemin (un path payment) ne règle pas le lien.
- Sur Testnet, un wallet configuré sur Testnet avant de payer : le lien n’indique pas le réseau, et un wallet qui suit SEP-7 suppose alors le réseau principal.
Acceptez votre premier paiement en USDC sur Stellar
Passez en Sandbox
Connectez-vous au tableau de bord et choisissez Sandbox en haut. Les liens que vous y créez fonctionnent sur Stellar Testnet et ne déplacent aucun argent réel.
Ajoutez votre compte Stellar
Vérifiez que le compte existe et qu’il a une trustline vers l’USDC, puis ajoutez-le dans les paramètres de votre organisation et signez ce que le tableau de bord demande.
Créez le lien
Dans Paiements, cliquez sur Créer un lien de paiement, choisissez Stellar, le montant (ou aucun) et l’USDC, puis votre compte et, si vous le souhaitez, un message.
Payez-le depuis un wallet
Ouvrez la page de paiement et scannez son QR code avec un wallet Stellar configuré sur le même réseau, ou ouvrez le lien sur le même appareil. Approuvez le paiement : le checkout passe à Payé dès que Cosmos Pay le trouve.
Confirmez-le sur votre serveur
Ajoutez un endpoint webhook dans le tableau de bord. Quand le paiement est confirmé, Cosmos Pay envoie PAYMENT_INTENT_SUCCEEDED, signé en HMAC-SHA256. Livrez la commande quand cet événement arrive.
Passez en Production
Choisissez Production et créez une clé d’API de production (elle commence par prod_). Les liens fonctionnent alors sur le réseau principal de Stellar, où l’USDC de Circle est préconfiguré.
Créer le lien depuis votre serveur
Appelez POST /v1/payment-intents/pay avec votre compte comme destination, le montant et, pour l’USDC, le code d’actif avec son émetteur, ou utilisez client.paymentIntents.createPay dans le SDK TypeScript : Stellar est la valeur par défaut de chain. La réponse contient le lien (son uri commence par web+stellar:pay) et son QR code.
Quand vous connaissez le compte de votre client, une intention de transaction (POST /v1/payment-intents/tx, ou createTx dans le SDK) renvoie à la place une transaction non signée qu’il doit signer. Elle doit être signée dans les cinq minutes.
Si vous définissez votre propre mémo, utilisez-le pour un seul paiement : le même mémo avec d’autres conditions est refusé.
API des intentions de paiementLes intentions de paiement dans le SDK
Bon à savoir
- Vous pouvez laisser le montant vide pour que votre client le choisisse. Un message de 300 caractères maximum s’affiche dans le wallet de votre client.
- Avec vos propres frais sur le paiement, le checkout demande le compte de votre client et construit une seule transaction qui vous paie, vous et votre wallet de frais.
- Dans le tableau de bord, un lien Stellar en attente dispose d’une vérification qui le règle à partir d’un hash de transaction.
- Un paiement qui arrive après l’expiration du lien est réglé en envoyant le hash de sa transaction à POST /v1/payment-intents/:id/validate.
- Le wallet de votre client règle les frais de réseau Stellar, en XLM. Les paiements privés, qui masquent le montant on-chain, fonctionnent sur Stellar en XLM, pour l’instant sur Testnet.
Questions et réponses.
Paiements par réseau :Paiements sur StellarPaiements sur SolanaPaiements sur Monad
Pourquoi un paiement vers mon compte a-t-il échoué ?
La raison la plus fréquente est l’absence de trustline USDC sur le compte qui reçoit. Ajoutez la trustline, puis créez un nouveau lien et envoyez-le de nouveau.
Quels wallets peuvent payer un lien SEP-7 ?
Tout wallet Stellar qui ouvre les liens SEP-7, comme Cosmos Pay Wallet, Freighter, LOBSTR, xBull, Albedo ou Rabet.
Mon client peut-il payer un lien en USDC avec des XLM ?
Non. Seul un paiement direct en USDC le règle : un paiement qui convertit des XLM en USDC en chemin ne le règle pas.
Puis-je tester sans argent réel ?
Oui. En Sandbox et avec des clés de test (dv_), les liens fonctionnent sur Stellar Testnet, où l’USDC est préconfiguré et où Friendbot envoie des XLM de test.
