Documentation API Coinvera
Introduction
L’API Coinvera est une API REST en JSON, versionnée (/v1). Elle permet de créer des paiements par carte, de consulter leur statut, vos transactions, votre solde et votre profil marchand. Seuls les endpoints listés ici sont disponibles.
Quick Start
1) Créez un compte et générez une clé test dans « API & Développeurs ». 2) Signez vos requêtes (voir Authentification). 3) Créez un paiement et redirigez le client vers checkoutUrl. 4) Attendez la confirmation (webhook ou GET /payments/{id}). Vous disposez de 2 essais gratuits en mode test ; la production nécessite l’activation.
Authentication
Base URL : https://api.coinvera.me. Chaque requête porte : X-Api-Key (clé publique), X-Timestamp (millisecondes, tolérance 5 min), X-Nonce (unique par requête) et X-Signature = HMAC-SHA256(secret, "{timestamp}.{nonce}.{METHOD}.{path}.{sha256(corps brut)}"). Pour un GET, le corps est vide. Un nonce réutilisé est refusé (401).
TS=$(date +%s000); NONCE=$(openssl rand -hex 12); BODY='{"amount":49.9,"title":"Commande #1042"}'
HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $2}')
SIG=$(printf '%s' "$TS.$NONCE.POST./v1/payments.$HASH" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')
curl -X POST https://api.coinvera.me/v1/payments -H "Content-Type: application/json" \
-H "X-Api-Key: $PUBLIC_KEY" -H "X-Timestamp: $TS" -H "X-Nonce: $NONCE" -H "X-Signature: $SIG" \
-H "Idempotency-Key: order-1042" -d "$BODY"Create Payment
POST /v1/payments — corps : amount (nombre, 1 à 50000 USD), title (texte), customerEmail (optionnel), orderRef (optionnel). En-tête optionnel Idempotency-Key : rejouer la même clé renvoie la même réponse sans créer de doublon. Réponse 201 : { id, status: "pending", amount, mode, checkoutUrl, fees: { processingBps, platformBps, totalBps } }. Erreur 402 activation_required une fois les essais gratuits épuisés.
TS=$(date +%s000); NONCE=$(openssl rand -hex 12); BODY='{"amount":49.9,"title":"Commande #1042"}'
HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $2}')
SIG=$(printf '%s' "$TS.$NONCE.POST./v1/payments.$HASH" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')
curl -X POST https://api.coinvera.me/v1/payments -H "Content-Type: application/json" \
-H "X-Api-Key: $PUBLIC_KEY" -H "X-Timestamp: $TS" -H "X-Nonce: $NONCE" -H "X-Signature: $SIG" \
-H "Idempotency-Key: order-1042" -d "$BODY"Get Payment
GET /v1/payments/{id} — renvoie le paiement du marchand authentifié : status (pending, confirmed), amount, net, fees { processing, platform, total }, mode (test ou live). Un paiement d’un autre marchand renvoie 404.
Transactions
GET /v1/transactions?page=1&size=20 — vos transactions, de la plus récente à la plus ancienne. Paramètres : page (défaut 1) et size (défaut 20, maximum 100). Réponse : { data, total, page, size }.
Balances
GET /v1/balances — { currency: "USD", available, reserved }.
Merchant
GET /v1/merchant — { merchantCode, company, keyMode, apiActivated, trialsUsed }.
Webhooks
Configurez jusqu’à 5 URL https dans « Webhooks » : chaque événement est envoyé à toutes. Coinvera envoie un POST JSON { type: "payment.confirmed", data: { id, orderRef }, createdAt } avec l’en-tête X-Coinvera-Signature = HMAC-SHA256 du corps brut, avec votre secret de webhook. Vérifiez la signature, puis relisez le paiement via GET /payments/{id} avant de livrer.
Webhook automatique
PUT /v1/webhooks — corps : { url } (https). AJOUTE l’URL à la liste de notification de votre compte (5 maximum, sans remplacer les autres, appel répété sans effet) et renvoie { url, urls, secret } ; le secret de signature est le même pour toutes les URL. Les plugins WooCommerce et de dons l’appellent automatiquement à l’enregistrement des réglages : aucune configuration manuelle. Erreurs : 400 unsafe_url (https obligatoire), 409 webhook_limit. GET /v1/webhooks renvoie { url, urls }.
Error Codes
400 invalid_request · 401 missing_auth_headers, timestamp_out_of_range, invalid_or_revoked_key, bad_signature, nonce_reused · 402 activation_required · 404 not_found · 429 rate_limited · 500 internal_error.
Rate Limits
Des limites de débit s’appliquent ; au-delà, la réponse est 429 rate_limited. Les montants vont de 1 à 50 000 USD par paiement.
Security
Conservez le secret côté serveur uniquement, ne l’exposez jamais dans un navigateur ou une application mobile. Révoquez toute clé compromise (effet immédiat). Ne livrez une commande qu’après statut confirmed lu côté serveur.
WooCommerce Integration
Installez le plugin Coinvera Crypto Gateway, activez votre licence, saisissez vos clés API. Le plugin crée le paiement, redirige le client, puis vérifie le statut côté serveur toutes les 5 minutes : la commande n’est marquée payée qu’après confirmation.
SDKs and Examples
Pas de SDK officiel pour l’instant ; exemples ci-dessous.
TS=$(date +%s000); NONCE=$(openssl rand -hex 12); BODY='{"amount":49.9,"title":"Commande #1042"}'
HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $2}')
SIG=$(printf '%s' "$TS.$NONCE.POST./v1/payments.$HASH" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')
curl -X POST https://api.coinvera.me/v1/payments -H "Content-Type: application/json" \
-H "X-Api-Key: $PUBLIC_KEY" -H "X-Timestamp: $TS" -H "X-Nonce: $NONCE" -H "X-Signature: $SIG" \
-H "Idempotency-Key: order-1042" -d "$BODY"Réponse type (201) : { "id": "…", "status": "pending", "amount": 49.9, "mode": "test", "checkoutUrl": "https://…" }