Documentation API

Intégration des paiements crypto : wallets de dépôt, callbacks (IPN), vérification de la configuration on-chain (split). Tout le contenu est autonome dans ce fichier (HTML + CSS + JS).

Informations générales

Élément	Détail
Format	JSON — `Content-Type: application/json` pour les corps de requête
Encodage	UTF-8
CORS	`Access-Control-Allow-Origin: *` avec les bons en-têtes
Préflight	`OPTIONS` → `200` sans corps

URL de base

Remplacez {BASE_URL} selon l’environnement.

Environnement	URL
Production	`https://nxtgatew.com`
Local (ex. MAMP)	`http://localhost:8888/nxtgatew`

Chemins API : POST {BASE_URL}/api/v1/wallets/create · GET {BASE_URL}/api/v1/wallets/check-config

Authentification

Chaque requête doit inclure :

En-tête	Obligatoire	Description
`X-API-Key`	Oui	Clé API (`merchant`, `psp` ou `admin`)
`X-API-Secret`	Oui	Secret API associé

Les identifiants sont créés à l’inscription (marchand / PSP ; admin possible pour l’exploitation). Ne publiez pas le secret. Comptes active avec rôle merchant, psp ou admin — sinon 401.

Codes HTTP & erreurs

Schéma d’erreur typique :

Example

{
  "success": false,
  "error": "Message lisible expliquant le problème"
}

Champs additionnels possibles : hint, json_error_code, raw_input_preview, debug, etc.

Code	Signification
200	Succès (GET, OPTIONS)
201	Ressource créée (POST create wallet)
400	Requête invalide (JSON, champs, réseau, URL, adresse)
401	Identifiants API invalides ou compte non actif
403	Compte marchand inactif (contrôle métier)
404	Introuvable (wallet absent ou pas le vôtre)
405	Méthode HTTP non autorisée
409	Conflit (ex. adresse déjà en base)
429	Trop de requêtes (autres endpoints, ex. cron)
500	Erreur serveur

POST Créer un wallet de dépôt

Adresse de réception générée par la plateforme, callback IPN, affiliés optionnels. Sur Ethereum / Polygon, le détail split_config dans la réponse 201 est réservé aux clés API admin ; les marchands utilisent GET check-config.

POST {BASE_URL}/api/v1/wallets/create

Clé	Valeur
`Content-Type`	`application/json`
`X-API-Key`	Votre clé API
`X-API-Secret`	Votre secret API

Champ	Type	Req.	Description
`address`	string	Oui	Wallet marchand (destination après split). Format selon `network`.
`callback`	string	Oui	URL de notification IPN. Alias : `callback_url`.
`network`	string	Non	`ethereum` \| `polygon` \| `tron` \| `solana` — défaut `ethereum`
`affiliate_address`	string	Non	Adresse affilié — avec `affiliate_percent` ou `affiliate_percent_bps`
`subaff_address`	string	Non	Sous-affilié — avec `subaff_percent` ou `subaff_percent_bps`
`affiliate_percent`	number	Non	% du brut (ex. `1` = 1 %) — prioritaire sur `affiliate_percent_bps`
`subaff_percent`	number	Non	Idem sous-affilié
`split_amounts_unit`	string	Non	`bps` (défaut) ou `percent` : si `percent`, `*_percent_bps` = % du brut, pas des bps
`affiliate_percent_bps`	int	Non	Bps du brut (100 = 1 %) sauf si `split_amounts_unit` = `percent`
`subaff_percent_bps`	int	Non	Idem sous-affilié
`ipn_token`	string	Non	Votre jeton de corrélation ; sinon généré (64 hex)

Formats : EVM 0x + 40 hex · Tron T + 34 car. · Solana base58 (32–44 car.)

Affilié et sous-affilié

Parts en % du montant brut (stockage interne en bps). Exemple de champs dans le JSON :

JSON

"affiliate_address": "0x4B31D368067127D10C59e655b8B22937E35D1196",
"affiliate_percent": 1,
"subaff_address": "0x2222222222222222222222222222222222222222",
"subaff_percent": 0.5

HTTP	`error` (extrait)
400	`No JSON body provided`
400	`Invalid JSON input`
400	`Invalid network…`
400	`Missing required field: address` / `callback`
400	Formats adresse / callback invalides
401	`Invalid API credentials`
403	`Merchant account is not active`
405	`Method not allowed. Use POST.`
409	`Wallet address already exists…`
500	`Failed to generate wallet` / BDD / serveur

cURL

Shell

curl -X POST "https://nxtgatew.com/api/v1/wallets/create" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: VOTRE_CLE" \
  -H "X-API-Secret: VOTRE_SECRET" \
  -d '{
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "callback": "https://votre-site.com/webhooks/nxtgatew",
    "network": "polygon",
    "affiliate_address": "0x4B31D368067127D10C59e655b8B22937E35D1196",
    "affiliate_percent": 1,
    "subaff_address": "0x2222222222222222222222222222222222222222",
    "subaff_percent": 0.5
  }'

Réponse — 201 Created

Body 201 Created

{
  "success": true,
  "data": {
    "address": "0x…",
    "ipn_token": "64_caracteres_hex_ou_votre_token",
    "network": "polygon",
    "callback_url": "https://votre-site.com/webhooks/nxtgatew",
    "created_at": "2026-04-17 12:00:00",
    "affiliate_wallet_address": "0x4B31D368067127D10C59e655b8B22937E35D1196",
    "subaff_wallet_address": "0x2222222222222222222222222222222222222222",
    "platform_percent": 1,
    "affiliate_percent": 1,
    "subaff_percent": 0.5
  },
  "message": "Wallet created successfully"
}

Réponse marchand / PSP sur EVM : pas de split_config. Avec clé API admin, data.split_config peut inclure mode, created, contract_address, error, check_url.

Champ `data`	Description
`address`	Adresse générée à donner au client pour payer
`ipn_token`	À conserver pour lier / sécuriser les callbacks
`affiliate_wallet_address` / `subaff_wallet_address`	Absents du JSON si non fournis à la création
`platform_percent`	Part plateforme — % du brut uniquement (pas de `*_bps` dans la réponse JSON)
`affiliate_percent` / `subaff_percent`	% du brut — absents du JSON si aucune adresse affilié / sous-affilié à la création
`split_config`	`ethereum` / `polygon` et rôle API `admin` uniquement ; sinon `GET check-config`

GET Vérifier la configuration split

État d’un wallet de dépôt vous appartenant : base de données + lecture on-chain (EVM si le serveur exécute le script de vérification).

GET {BASE_URL}/api/v1/wallets/check-config?wallet_address=…&network=polygon

Clé	Valeur
`X-API-Key`	Votre clé API
`X-API-Secret`	Votre secret API

Content-Type optionnel sur GET sans corps.

Paramètre	Req.	Défaut	Description
`wallet_address`	Oui	—	Adresse générée (`data.address` du create)
`network`	Non	`polygon`	Doit correspondre au wallet

HTTP	`error`
400	`Missing parameter: wallet_address`
401	`Invalid API credentials`
404	`Wallet not found or does not belong to your account`
405	`Method not allowed. Use GET.`
500	`Server error: …`

cURL

Shell

curl -G "https://nxtgatew.com/api/v1/wallets/check-config" \
  -H "X-API-Key: VOTRE_CLE" \
  -H "X-API-Secret: VOTRE_SECRET" \
  --data-urlencode "wallet_address=0xVotreAdresseGeneree" \
  --data-urlencode "network=polygon"

Réponse — 200 OK

Body 200 OK

{
  "success": true,
  "data": {
    "wallet_address": "0x…",
    "network": "polygon",
    "database": {
      "merchant_wallet": "0x…",
      "affiliate_wallet": "0x4B31D368067127D10C59e655b8B22937E35D1196",
      "subaff_wallet": "0x2222222222222222222222222222222222222222",
      "platform_percent": 1,
      "affiliate_percent": 1,
      "subaff_percent": 0.5,
      "contract_address": "0x…",
      "status": "active",
      "created_at": "2026-04-17 12:00:00"
    },
    "on_chain": {
      "config_exists": true,
      "merchant_wallet": "0x…",
      "affiliate_wallet": "0x4B31D368067127D10C59e655b8B22937E35D1196",
      "subaff_wallet": "0x2222222222222222222222222222222222222222",
      "is_active": true
    },
    "match": true
  }
}

Champ	Description
`database.*`	Données stockées côté NxtGateW ; `platform_percent` toujours ; `affiliate_percent` / `subaff_percent` seulement si l’adresse en base est renseignée — pas de `*_bps`
`on_chain.config_exists`	Config lue sur la chaîne
`match`	`true` si config on-chain + adresse marchand alignée avec la base

Basis points (bps)

10 000 bps = 100 %

bps	%
100	1 %
50	0,5 %
1	0,01 %

Frais plateforme et plafonds (plateforme + affiliés ≤ 100 %) sont appliqués côté contrat.

Bonnes pratiques

HTTPS pour callback en production.
Valider ipn_token (ou signature) sur chaque webhook entrant.
Après create sur EVM, utiliser GET check-config pour valider base + on-chain (les admins peuvent aussi lire split_config dans la réponse create).
En 401, vérifier en-têtes, encodage et statut du compte marchand.

Récapitulatif

Méthode	Chemin	Rôle
POST	`/api/v1/wallets/create`	Créer adresse de dépôt + callback / split
GET	`/api/v1/wallets/check-config`	Vérifier base + on-chain

Référence source : api/v1/wallets/create.php, api/v1/wallets/check-config.php