Tokens de paiement

Chaque paiement réussi crée automatiquement un token réutilisable (pt_…). Cette page couvre les endpoints de lecture + révocation de tokens déjà enregistrés. Pour créer un token en important un token existant d'une autre passerelle, voir Tokenisation.

Tokenize vs Payment Tokens

• POST /tokenize — importer un token existant d'une passerelle sous un client (utilisé par les intégrateurs migrant depuis un autre processeur).
• GET /customers/{external_customer_id}/payment-tokens — lister les cartes déjà enregistrées via les flux normaux de checkout.
• POST /payment-tokens/{id}/deactivate — révoquer un token pour qu'il ne puisse plus être facturé.

Aucun de ces endpoints ne capture une carte à neuf. Une nouvelle carte est toujours tokenisée via une session de paiement.

Statuts du token

Statut	Signification
active	Éligible pour POST /charge-token et pour les abonnements.
inactive	Révoqué par le marchand ou le client. Non débitable.
expired	Au-delà de expiry_month / expiry_year. Non débitable.

Un token passe également en inactif automatiquement lorsque la passerelle sous-jacente le marque comme inutilisable (rétro-facturation / blocage fraude).

Lister les cartes enregistrées d'un client

GET /api/v1/customers/{external_customer_id}/payment-tokens

{external_customer_id} est l'ID client côté marchand (votre wp_users.ID, votre Magento customer_id, votre Shopify customer_gid). Genius Checkout le mappe lors du premier paiement — les plugins de boutique le font automatiquement.

Réponse (200)

{
  "data": [
    {
      "id": "pt_xyz789",
      "brand": "visa",
      "last4": "4242",
      "expiry_month": "12",
      "expiry_year": "2030"
    }
  ]
}

Si le client n'a jamais payé via Genius Checkout, la réponse est {"data": []} (200, pas 404) afin que les UI de boutique puissent afficher la section de manière inconditionnelle.

Le token chiffré n'est jamais renvoyé — utilisez l'id (pt_…) pour référencer le token dans POST /charge-token ou POST /subscriptions.

Désactiver un token

POST /api/v1/payment-tokens/{external_id}/deactivate

Idempotent — appelé sur un token déjà inactif, renvoie 200 avec l'état actuel. À utiliser quand :

• Un client annule son abonnement côté marchand et que vous voulez révoquer la carte enregistrée.
• Un signal de fraude rend la carte non débitable.
• Vous nettoyez après suppression de compte / droit à l'effacement.

Réponse (200)

{
  "id": "pt_xyz789",
  "status": "inactive",
  "brand": "visa",
  "last4": "4242"
}

Exemples de code

# Afficher un sélecteur de cartes enregistrées sur votre boutique
curl -H "Authorization: Bearer $GC_API_KEY" \
  "https://app.geniuscheckout.com/api/v1/customers/wp_user_42/payment-tokens"

// Node — révoquer après l'annulation d'un abonnement
await fetch(`https://app.geniuscheckout.com/api/v1/payment-tokens/${tokenId}/deactivate`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GC_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
})

# Python — lister les cartes enregistrées d'un client
import requests
r = requests.get(
    f"https://app.geniuscheckout.com/api/v1/customers/{external_id}/payment-tokens",
    headers={"Authorization": f"Bearer {GC_API_KEY}"},
)
cards = r.json()["data"]

Notes de sécurité

• Les clés API sont isolées par marchand. Une requête avec la clé d'un marchand ne peut jamais voir ni révoquer les tokens d'un autre marchand — les requêtes croisées renvoient data: [] ou 404, jamais l'existence de la ressource.
• Les cartes enregistrées ne sont jamais exposées dans le code navigateur. Les plugins récupèrent la liste depuis PHP / côté serveur, puis n'affichent que {id, brand, last4, expiry_*}. Le token chiffré reste sur la plateforme GC.

Suite

• Tokenisation — débiter une carte enregistrée avec POST /charge-token
• Abonnements — lier un token à un calendrier récurrent