Comment accepter des paiements en USDC sur son site

Pour accepter des USDC sur votre site, associez la commande à une facture Cryptanio et déterminez à l’avance le réseau et le jeton exact. Prenons une boutique ayant convenu d’un paiement en USDC sur Ethereum. Le serveur crée une facture distincte, l’acheteur reçoit une page de paiement et la commande est confirmée après vérification du résultat. Les fonds arrivent à votre adresse.

Ce scénario utilise un actif fixé : l’acheteur doit envoyer la version d’USDC indiquée, pas une autre monnaie au nom similaire. Le choix général entre lien de paiement et intégration côté serveur est expliqué dans le guide d’acceptation des cryptomonnaies sur un site.

1. Déterminez quel USDC vous acceptez

Comparez le réseau et l’identifiant du jeton au répertoire officiel de Circle. Le nom USDC et le logo du portefeuille ne suffisent pas. Le fait que Circle prenne en charge un réseau ne prouve pas que ce parcours soit activé dans votre projet Cryptanio.

Circle distingue native USDC, émis par l’émetteur lui-même sur le réseau, de bridged USDC, créé par un pont tiers. Ne considérez pas ces formes comme interchangeables pour votre facture ; leurs différences sont présentées dans le document de Circle. Ici, nous choisissons l’USDC Circle pris en charge sur Ethereum. Pour un autre réseau, revérifiez son jeton et sa disponibilité.

Le mot native dans native USDC ne désigne pas la monnaie native de la blockchain. Sur Ethereum, USDC reste un jeton et la monnaie native est ETH. Cette différence est importante pour configurer l’adresse.

2. Préparez l’adresse pour le bon actif

Il vous faut un projet dont le service « Paiements » est actif, l’adresse publique de votre propre portefeuille et le droit de configurer le projet. Ouvrez « Paiements », sélectionnez le projet et « Adresses », puis « Ajouter des adresses ». Dans l’onglet « Manuellement », choisissez Ethereum et indiquez une adresse que vous contrôlez.

Choisissez « Un actif » et renseignez « Actif » avec l’identifiant de l’USDC pris en charge sur ce réseau, vérifié dans le répertoire Circle. Un champ vide désigne la monnaie native, pas native USDC. Laissez « Entrant » activé, ajoutez l’adresse et vérifiez que la connexion est active et le réseau disponible. Un simple enregistrement dans le carnet d’adresses ne connecte pas la réception au service nécessaire.

Pour un pool manuel, préparez une adresse libre pour émettre les coordonnées de paiement. Ne transmettez ni clé privée ni phrase de récupération : elles ne sont pas nécessaires pour connecter une adresse publique. Les bases de la vérification du parcours figurent dans Réseau et jeton : quelles différences.

3. Créez une facture pour la commande

Préparez une clé API de production côté serveur avec accès à ce projet, à la section invoices (« Factures ») et l’autorisation « Lire et écrire ». Enregistrez votre propre numéro de commande avant la requête. La clé ne doit pas être transmise à l’acheteur.

Voici un exemple pris en charge de l’API v1 pour un actif fixé. Vérifiez le réseau, l’actif et le montant de votre commande dans la requête générée. Un montant en USDC représente une quantité de jetons, pas un dépôt de dollars sur un compte bancaire :

#!/usr/bin/env bash
set -euo pipefail
: "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}"
: "${CRYPTANIO_OPERATION_ID:?Set CRYPTANIO_OPERATION_ID}"
: "${CRYPTANIO_PROJECT_ID:?Set CRYPTANIO_PROJECT_ID}"
json_string() {
  local text="$1" char code index output='"'
  for ((index=0; index<${#text}; index++)); do
    char="${text:index:1}"
    case "$char" in
      '"'|'\') output+="\\$char" ;;
      *) printf -v code '%d' "'$char"
         if ((code < 32)); then printf -v char '\\u%04x' "$code"; fi
         output+="$char" ;;
    esac
  done
  printf '%s"' "$output"
}
response_file="$(mktemp)"
trap 'rm -f "$response_file"' EXIT
transfer_status=0
http_status="$(curl \
  --silent --show-error --max-time 30 --request POST \
  --header "Authorization: Bearer $CRYPTANIO_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $CRYPTANIO_OPERATION_ID" \
  --data-binary '{"project":'"$(json_string "$CRYPTANIO_PROJECT_ID")"',"chain":"ethereum","asset":"USDC","amount":"12.50","reference":"order-42","expires_in":60,"customer":{"id":"customer-42"},"metadata":{"order":"42"}}' \
  "https://api.cryptanio.com/v1/invoices" \
  --output "$response_file" --write-out '%{http_code}')" || transfer_status=$?
if [[ "$http_status" == 2?? ]]; then
  cat "$response_file"
  exit "$transfer_status"
fi
printf 'HTTP %s\n' "$http_status" >&2
cat "$response_file" >&2
exit 1

Télécharger l’exemple

Indiquez votre projet et les données de la commande. Utilisez un Idempotency-Key unique pour une nouvelle opération ; conservez la même clé lorsque vous réessayez la même requête après une panne. Enregistrez le lien entre la commande et l’ID de la facture créée, la checkout_url reçue et les coordonnées exactes de la réponse. N’arrondissez pas le montant renvoyé et ne le remplacez pas par celui de votre grille tarifaire.

4. Transmettez la page de paiement au client

Ouvrez la checkout_url reçue depuis la commande sur votre site. Ne construisez pas l’adresse de la page à partir de l’ID de facture et ne remplacez pas les coordonnées émises par une adresse permanente du portefeuille. Dans ce scénario, le réseau et l’actif sont déjà choisis : le client doit les vérifier dans son portefeuille avant l’envoi.

Demandez l’envoi du montant exact en tenant compte des règles de frais du portefeuille et de l’échéance. Si le client possède une autre version d’USDC, renommer le jeton ne rendra pas le transfert adapté. Convenez d’abord du bon parcours ; ne promettez pas d’échange ou de pont automatique assuré par Cryptanio.

5. Confirmez la commande et vérifiez tout le parcours

Le serveur doit vérifier l’état actuel de la facture avec un webhook ou une interrogation de l’API. Exécutez la commande à l’état paid, en conservant la protection contre une double exécution. Une transaction détectée, une capture d’écran ou le retour de l’acheteur sur le site ne remplacent pas cette vérification.

Traitez les montants insuffisants ou excessifs, les versements tardifs et les retours en arrière de transactions selon l’état de la facture concernée. En cas de litige, conservez le TXID et consultez le diagnostic des commandes impayées. N’affectez pas un autre actif à cette commande simplement parce que le montant semble similaire.

Vérifiez le processus complet sur votre propre commande : coordonnées, envoi, confirmation et exécution. Le mode de production utilise des fonds réels et des frais réseau. Vérifier seulement l’apparence de la page ou des événements artificiels ne prouve pas que l’USDC choisi arrive réellement et soit correctement comptabilisé.