Développeurs

Référence API

Une API REST prévisible : ressources au pluriel, JSON en entrée comme en sortie, montants en plus petite unité de la devise et erreurs explicites.

Obtenir des clés de test Guide de démarrage

Référence en cours d'alignement avec l'implémentation : vérifier chaque signature auprès de l'équipe technique avant de s'y fier en production. Cet encadré est à supprimer une fois la documentation validée.

URL de base

Toutes les requêtes se font en HTTPS sur cette base. Les appels en HTTP simple sont refusés.

https://api.nexet.io/v1

La version fait partie du chemin. Une nouvelle version majeure n'est publiée que pour un changement incompatible ; les ajouts de champs se font sans changer de version.

Authentification

L'authentification se fait par clé secrète, en authentification HTTP basique : la clé sert d'identifiant, le mot de passe reste vide.

curl https://api.nexet.io/v1/payments \
  -u sk_test_4dLm…:

Chaque environnement a sa paire de clés : sk_test_… en sandbox, sk_live_… en production.
La clé secrète ne doit jamais être exposée côté navigateur ni versionnée dans un dépôt. Elle se révoque et se remplace depuis l'espace marchand, sans coupure.

Idempotence

Toutes les créations acceptent un en-tête Idempotency-Key. Rejouer la même clé renvoie la réponse d'origine au lieu de créer un second objet : aucun double paiement en cas de retry réseau.

-H "Idempotency-Key: ord-1042"

Erreurs

Les erreurs utilisent les codes HTTP standards et renvoient un objet error décrivant la cause. L'identifiant de requête est à communiquer au support.

{
  "error": {
    "type": "card_declined",
    "code": "insufficient_funds",
    "message": "The card has insufficient funds.",
    "request_id": "req_8Kd92mLp"
  }
}

Code	type	Signification
400	invalid_request	Paramètre manquant ou invalide.
401	authentication_error	Clé API absente, invalide ou révoquée.
402	card_declined	Paiement refusé par l'émetteur de la carte.
404	not_found	La ressource demandée n'existe pas.
409	idempotency_conflict	Clé d'idempotence réutilisée avec un corps différent.
429	rate_limit	Trop de requêtes : réessayer avec un délai croissant.
500	api_error	Incident côté Nexet Pay. La requête peut être rejouée.

Pagination

Les listes sont paginées par curseur : limit fixe la taille de page, starting_after reprend après l'identifiant fourni. La réponse indique s'il reste des éléments.

GET /v1/payments?limit=50&starting_after=pay_3jF8dK2m

Paiements

Encaisser, consulter, capturer et rembourser un paiement.

POST	/v1/payments	Créer un paiement (encaissement immédiat ou autorisation).
GET	/v1/payments/{id}	Récupérer un paiement et son statut.
GET	/v1/payments	Lister les paiements, avec filtres par statut et par date.
POST	/v1/payments/{id}/capture	Capturer tout ou partie d'une autorisation.
POST	/v1/payments/{id}/refunds	Rembourser un paiement, totalement ou partiellement.

Liens de paiement

Créer des liens de paiement partageables, avec montant fixe ou libre.

POST	/v1/payment_links	Créer un lien de paiement et son QR code.
GET	/v1/payment_links/{id}	Récupérer un lien et son compteur de paiements.
GET	/v1/payment_links	Lister les liens de paiement.
POST	/v1/payment_links/{id}/deactivate	Désactiver un lien avant sa date d'expiration.

Abonnements

Définir des plans et gérer le cycle de vie des abonnements.

POST	/v1/plans	Créer un plan d'abonnement (montant, périodicité, essai).
POST	/v1/subscriptions	Abonner un client à un plan.
GET	/v1/subscriptions/{id}	Récupérer un abonnement et son cycle en cours.
POST	/v1/subscriptions/{id}/cancel	Résilier un abonnement, immédiatement ou en fin de période.

Factures

Émettre des factures et suivre leur règlement.

POST	/v1/invoices	Créer une facture avec ses lignes et sa TVA.
POST	/v1/invoices/{id}/send	Envoyer la facture par e-mail avec son bouton de paiement.
GET	/v1/invoices/{id}	Récupérer une facture et son statut de règlement.
GET	/v1/invoices	Lister les factures.

Clients

Enregistrer vos clients et leurs moyens de paiement tokenisés.

POST	/v1/customers	Créer un client et enregistrer ses moyens de paiement.
GET	/v1/customers/{id}	Récupérer un client.
GET	/v1/customers	Lister les clients.

Webhooks

Déclarez une URL d'endpoint depuis votre espace marchand : chaque événement y est envoyé en POST, avec retentatives exponentielles jusqu'à acquittement (réponse 2xx).

Chaque requête porte un en-tête Nexet-Signature contenant l'horodatage et une signature HMAC du corps. Vérifiez-la avant de traiter l'événement, et rejetez les horodatages trop anciens.

Nexet-Signature: t=1786982400,v1=5f2c…

Événements émis

payment.succeededpayment.failedpayment.refundeddispute.openedsubscription.renewedsubscription.canceledinvoice.paidinvoice.payment_failedpayout.paid

Environnement de test

La sandbox est gratuite et illimitée. Les cartes de simulation permettent de déclencher chaque scénario sans mouvement réel.

Scénario	Résultat attendu
Paiement accepté	Statut succeeded, règlement simulé.
Authentification 3-D Secure requise	Statut requires_action puis redirection 3DS.
Carte refusée	Erreur card_declined avec le motif de refus.

La liste complète des cartes de test et de leurs codes de refus est disponible dans votre espace marchand, onglet Environnement de test.

Une question sur l'intégration ?

Décrivez votre cas d'usage : notre équipe technique répond sous un jour ouvré.

Contacter l'équipe technique