API compatible Cryptomus

blockwallets vous permet d’accepter l’USDT et l’USDC, ainsi que BTC, LTC, DOGE, BCH et des cryptos natives (créditées en dollars américains à un taux verrouillé) : le client paie, nous le confirmons on-chain, puis nous vous notifions. L’API, les signatures et les webhooks sont les mêmes que ceux de Cryptomus : si vous avez déjà intégré Cryptomus, changez le domaine et c’est fini. Le fonctionnement d’abord, l’API ensuite.

Deux façons d’encaisser

Les deux acceptent n’importe quel montant : commandes à prix fixe et recharges où le client saisit le montant. Une fois payé, vous expédiez ou créditez le solde du client. La seule différence est que chaque paiement reçoive ou non une adresse neuve.

En cas de doute, utilisez les factures. Sans code, les liens de paiement du tableau de bord sont des factures créées pour vous. Pas encore marchand ? Demandez l’accès sur la page d’accueil ; une fois approuvé, connectez-vous au tableau de bord marchand et commencez par « Tester un paiement » sur la page d’accueil du tableau de bord, avec un petit montant (l’argent va sur votre propre solde).

Le cycle d’une facture

Un paiement fait intervenir quatre parties : le client, votre site, blockwallets et la blockchain. Le schéma se lit de haut en bas dans le temps ; la colonne de droite indique le statut de la facture à chaque étape.

En bref, cinq étapes :

1. Vous créez une facture (un lien de paiement le fait pour vous, ou votre serveur appelle /v1/payment), obtenez l’url de la page de paiement et y redirigez le client.
2. Sur la page de paiement, le client choisit une crypto et un réseau, reçoit une adresse et un montant dédiés, et paie depuis un portefeuille ou une plateforme d’échange.
3. Nous voyons le transfert on-chain, attendons assez de confirmations, puis le recoupons avec un second fournisseur de nœuds (pour qu’un nœud ne puisse pas le falsifier).
4. La facture passe à paid et nous envoyons aussitôt un webhook signé en POST à votre url_callback ; quelques secondes plus tard, la page de paiement renvoie le client vers votre url_success.
5. L’argent est crédité sur votre solde ; retirez-le vers votre propre portefeuille depuis le tableau de bord marchand.

Statut de la facture

Quand is_final vaut true, le statut ne changera plus (sauf paiements tardifs).

Liens de paiement (sans code)

Tableau de bord marchand → « Encaissements › Liens de paiement » → saisissez une description et un montant (imposez un réseau ou laissez le client choisir) → créez. Chaque lien a une URL et un QR code.

• Chaque fois que quelqu’un ouvre le lien, une nouvelle facture est créée : un même lien peut donc être réutilisé (p. ex. « Abonnement 99 $ »).
• Chaque paiement apparaît dans « Encaissements › Transactions » ; retirez-le vers votre portefeuille depuis « Fonds › Solde et retraits ».
• Si vous avez créé des identifiants et une URL de webhook dans « Développeurs › Intégration et clés », les paiements par lien sont aussi notifiés au format ci-dessous.
• Pour arrêter d’encaisser, cliquez sur « Désactiver » : le lien cesse de fonctionner immédiatement.

Intégration par API

1. Identifiants et signature

Tableau de bord marchand → « Développeurs › Intégration et clés » → générez un merchant (UUID) et une API key. Il y a un jeu pour Live et un pour Test : Live manipule de l’argent réel, Test fonctionne sur des testnets. Ajoutez aussi vos domaines du site web : url_callback, url_return et url_success doivent s’y trouver. L’API key n’est affichée qu’une fois : conservez-la en lieu sûr, et uniquement sur votre serveur.

URL de base https://blockwallets.io. Tous les endpoints sont en POST + JSON, avec ces en-têtes :

• merchant : l’UUID de votre merchant (c’est lui qui détermine Live ou Test)
• sign : md5(base64(request body) + API key), où le corps est exactement la chaîne JSON que vous envoyez

En cas de succès, la réponse est {"state": 0, "result": {…}} ; en cas d’échec, {"state": 1, "message": "…"} (voir Erreurs).

Les principaux endpoints ci-dessous ont un panneau « Essayer » : saisissez votre merchant et votre API key de Test, et la page signe la requête dans votre navigateur, appelle l’endpoint et affiche la requête et la réponse complètes (les identifiants restent dans la mémoire de la page). Si une signature ne correspond pas, comparez-la étape par étape avec le vérificateur de signature.

import crypto from "node:crypto";

async function call(path, data) {
  const body = JSON.stringify(data);
  const sign = crypto.createHash("md5").update(Buffer.from(body).toString("base64") + process.env.BW_API_KEY).digest("hex");
  const res = await fetch("https://blockwallets.io" + path, {
    method: "POST",
    headers: { merchant: process.env.BW_MERCHANT, sign, "Content-Type": "application/json" },
    body,
  });
  return res.json();
}

function bw_call(string $path, array $data): array {
    $body = json_encode($data, JSON_UNESCAPED_UNICODE);
    $sign = md5(base64_encode($body) . getenv('BW_API_KEY'));
    $ch = curl_init('https://blockwallets.io' . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST => true, CURLOPT_POSTFIELDS => $body, CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['merchant: ' . getenv('BW_MERCHANT'), 'sign: ' . $sign, 'Content-Type: application/json'],
    ]);
    return json_decode(curl_exec($ch), true);
}

import base64, hashlib, json, os, requests

def bw_call(path: str, data: dict) -> dict:
    body = json.dumps(data, separators=(",", ":"), ensure_ascii=False)
    sign = hashlib.md5((base64.b64encode(body.encode()).decode() + os.environ["BW_API_KEY"]).encode()).hexdigest()
    headers = {"merchant": os.environ["BW_MERCHANT"], "sign": sign, "Content-Type": "application/json"}
    return requests.post("https://blockwallets.io" + path, data=body.encode(), headers=headers).json()

2. Créer une facture POST /v1/payment

Quand le client passe commande, ou saisit un montant sur votre page de recharge, appelez https://blockwallets.io/v1/payment et redirigez-le vers le result.url renvoyé.

{
  "amount": "42.00",
  "currency": "USD",
  "order_id": "order_1042",
  "url_callback": "https://shop.example/webhooks/crypto",
  "url_return": "https://shop.example/cart",
  "url_success": "https://shop.example/thanks?order=1042"
}

{
  "state": 0,
  "result": {
    "uuid": "6f1c2a7e-…",
    "order_id": "order_1042",
    "amount": "42.00",
    "currency": "USD",
    "network": null,
    "address": null,
    "payer_amount": null,
    "payment_amount": null,
    "url": "https://blockwallets.io/pay/inv_01J8…",
    "expired_at": 1760965200,
    "status": "check",
    "is_final": false
  }
}

network, address et payer_amount sont renseignés une fois que le client a choisi un réseau.

3. Consulter les factures

• POST /v1/payment/info {"order_id": "…"} ou {"uuid": "…"} : récupère une facture et interroge la chaîne au passage (au plus une fois toutes les 10 secondes).
• POST /v1/payment/list : liste, 15 par page, avec date_from / date_to facultatifs ; page suivante via le paginate.nextCursor renvoyé (?cursor=…).
• POST /v1/payment/services : réseaux disponibles et montant minimum de chacun.
• POST /v1/payment/resend {"order_id": "…"} : renvoie le webhook d’une facture payée / insuffisante.

Les webhooks sont le canal principal ; les requêtes servent de secours (par exemple si votre serveur était en panne et a manqué un webhook).

4. Portefeuilles statiques POST /v1/wallet

Ouvre une adresse permanente pour un client sur un réseau. Le même order_id (en général votre identifiant d’utilisateur) + réseau donne toujours la même adresse ; toutes les chaînes EVM (BNB Chain, Ethereum, Base, Polygon, Arbitrum, Optimism, Avalanche, X Layer) partagent une adresse, tandis que TRON, BTC, LTC, DOGE, BCH, Solana et TON ont chacune la leur. Tout ce que le client envoie est crédité, avec un webhook par transfert ; les transferts BTC / LTC / DOGE / BCH / TRX / BNB / ETH / POL / AVAX / OKB / SOL / TON sont convertis en dollars américains au taux du moment où chacun a été vu (payment_amount_usd).

{
  "order_id": "user_42",
  "currency": "USDT",
  "network": "tron",
  "url_callback": "https://shop.example/webhooks/crypto"
}

{
  "state": 0,
  "result": {
    "wallet_uuid": "0b9d…",
    "uuid": "5e2f…",
    "order_id": "user_42",
    "currency": "USDT",
    "network": "tron",
    "address": "TXy4…8kQ2",
    "url": "https://blockwallets.io/deposit/dac_01J8…"
  }
}

result.url est une page de dépôt hébergée (adresse + QR code + dépôts récents) que vous pouvez remettre au client. Les transferts inférieurs au minimum du réseau (généralement $1, BTC $5) ne sont pas crédités automatiquement ; contactez-nous pour les faire créditer. Le blocage d’adresses (/v1/wallet/block-address) n’est pas encore pris en charge.

Webhooks

Quand le statut d’une facture change (paid, paid_over, wrong_amount_waiting, wrong_amount, cancel) et à chaque transfert vers un portefeuille statique, nous envoyons un POST JSON à url_callback. Une réponse 2xx compte comme livrée ; sinon nous réessayons après 1 minute, 5 minutes, 30 minutes, 2 heures, 12 heures, 24 heures et 24 heures. Vous pouvez aussi renvoyer depuis le tableau de bord ou avec /v1/payment/resend.

{
  "type": "payment",
  "uuid": "6f1c2a7e-…",
  "order_id": "order_1042",
  "amount": "42.00",
  "payment_amount": "42",
  "payment_amount_usd": "42.00",
  "merchant_amount": "41.58",
  "commission": "0.42",
  "is_final": true,
  "status": "paid",
  "from": "TQ8m…",
  "wallet_address_uuid": null,
  "network": "tron",
  "currency": "USD",
  "payer_currency": "USDT",
  "payer_amount": "42",
  "payer_amount_exchange_rate": "1",
  "additional_data": null,
  "txid": "9c1e…",
  "sign": "5f0c9b…"
}

Vérifier la signature (obligatoire)

La signature est le champ sign du corps du webhook : retirez sign, ré-encodez le reste comme le fait json_encode de PHP (compact, / échappé en \/, caractères non ASCII non échappés), et md5(base64(encoded) + API key) doit être égal à sign. Utilisez l’API key du même mode. Un même webhook peut arriver plusieurs fois — dédoublonnez par uuid + status.

Si la vérification échoue, collez le corps brut du webhook dans le vérificateur de signature : il affiche le résultat de chaque étape et marque l’endroit où le vôtre diffère (tout s’exécute dans votre navigateur ; l’API key n’est jamais envoyée). Chaque webhook de « Développeurs › Journal des webhooks » dans le tableau de bord s’ouvre dans le vérificateur en un clic.

import crypto from "node:crypto";

function verify(rawBody, apiKey) {
  const { sign, ...data } = JSON.parse(rawBody);
  const json = JSON.stringify(data).replaceAll("/", "\\/");
  const expected = crypto.createHash("md5").update(Buffer.from(json).toString("base64") + apiKey).digest("hex");
  return typeof sign === "string" && sign.length === expected.length && crypto.timingSafeEqual(Buffer.from(sign), Buffer.from(expected));
}

$data = json_decode(file_get_contents('php://input'), true);
$sign = $data['sign'] ?? '';
unset($data['sign']);
$expected = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiKey);
if (!hash_equals($expected, $sign)) {
    http_response_code(401); exit;
}

import base64, hashlib, hmac, json

def verify(raw_body: bytes, api_key: str) -> bool:
    data = json.loads(raw_body)
    sign = data.pop("sign", "")
    encoded = json.dumps(data, separators=(",", ":"), ensure_ascii=False).replace("/", "\\/")
    expected = hashlib.md5((base64.b64encode(encoded.encode()).decode() + api_key).encode()).hexdigest()
    return hmac.compare_digest(expected, sign)

Mode test

Les factures créées avec le merchant et l’API key de Test fonctionnent sur des testnets, sans argent réel. La page de paiement affiche un bouton « Simuler un paiement » (complet / moitié / trop-perçu), pour voir les changements de statut et les webhooks sans avoir de cryptos de testnet.

• POST /v1/test-webhook/payment, /v1/test-webhook/wallet : envoient un webhook d’exemple signé à url_callback (passez url_callback, obligatoire et sur l’un de vos domaines enregistrés, ainsi que currency, network, et éventuellement status, order_id) pour déboguer votre code de vérification.
• Tableau de bord « Développeurs › Intégration et clés » → « Envoyer une notification de test » : envoie un exemple à votre URL de webhook.
• Tableau de bord « Développeurs › Journal des webhooks » : chaque tentative de livraison avec son heure, l’URL cible, le statut HTTP, la durée, le corps de la requête et la réponse de votre serveur (les 4 premiers Ko) ; filtrez par commande ou statut et renvoyez en un clic. Conservé 30 jours.

Migrer depuis Cryptomus

1. Tableau de bord « Développeurs › Intégration et clés » → générez un merchant et une API key.
2. Remplacez https://api.cryptomus.com dans votre code par https://blockwallets.io, et utilisez le nouveau merchant et la nouvelle API key.
3. Ajoutez vos domaines dans « Domaines du site web » (url_callback / url_return / url_success n’acceptent que ceux-ci).

Pris en charge : /v1/payment, /v1/payment/info, /v1/payment/list, /v1/payment/services, /v1/payment/resend, /v1/wallet, /v1/test-webhook/payment, /v1/test-webhook/wallet. Différences : les factures sont libellées uniquement en USD / USDT / USDC (toutes à 1:1, sans écart de change) ; commission correspond à nos frais de plateforme (le montant reçu × le taux du marchand à la création de la facture — 1% en standard, jusqu’à 0.5% selon le volume ; rien n’est facturé deux fois sur la part que couvre le client) et merchant_amount = reçu − commission ; quand le client paie en BTC / LTC / DOGE / BCH / TRX / BNB / ETH / POL / AVAX / OKB / SOL / TON, nous cotons la médiane de plusieurs plateformes, verrouillée 30 minutes — payer_amount est le nombre de pièces à envoyer, payer_amount_exchange_rate la valeur en USD d’une pièce, et le paiement est converti en payment_amount_usd au taux verrouillé (les pièces restent chez nous, rien n’est échangé) ; réseaux tron / bsc / eth / base / polygon / arbitrum / optimism / avalanche / xlayer / btc / ltc / doge / bch / sol / ton ; durée de vie minimale de la facture 10 minutes ; pas de is_refresh ni de blocage des portefeuilles statiques ; par défaut, les webhooks proviennent d’IP changeantes ; si vous filtrez par IP, activez « Webhooks depuis une IP fixe » dans le tableau de bord, sous « Développeurs › Intégration et clés », et les webhooks ne viendront que de 18.163.145.41 — une liste d’autorisation est une couche supplémentaire, continuez de vérifier sign.

Vous venez de NOWPayments ou de Coinbase Commerce ? Nous avons des API compatibles avec les deux — changez l’URL de base et les clés ; voir le guide de migration.

Réseaux et montants

Les frais ERC-20 sont élevés, le minimum est donc de 5 $ ; ceux de Bitcoin ne sont pas bas non plus, minimum 5 $ ; tout le reste est à 1 $. Les clients doivent envoyer sur le réseau affiché sur la page de paiement — l’argent envoyé sur un autre réseau n’est pas crédité automatiquement. BTC / LTC / DOGE / BCH s’affichent « détecté » dès qu’ils sont dans le mempool et comptent une fois assez confirmés ; les transactions remplacées (RBF) ou abandonnées ne comptent pas. Les cryptos natives (TRX, BNB, ETH, POL, AVAX, OKB, SOL, TON) sont cotées à un taux verrouillé et créditées en dollars américains comme BTC / LTC / DOGE / BCH ; indiquez le réseau et la crypto : factures network: "bsc", to_currency: "BNB", portefeuilles statiques network: "bsc", currency: "BNB". Un réseau seul vaut par défaut l’USDT de cette chaîne (l’USDC sur Base). Les transferts effectués par des contrats (multisig, paiements groupés) sont aussi reçus ; sur certaines chaînes, leur hash de transaction n’est pas disponible et txid dans le webhook vaut null.

Erreurs

{ "state": 1, "message": "amount must be a number like 10.28" }

Quand la signature est mauvaise (Invalid Sign.), la réponse contient un objet debug : body_base64 est le base64 du corps de requête que nous avons reçu (votre propre contenu, jamais l’API key) et body_bytes sa longueur. Comparez-le au base64 que vous avez signé : s’ils diffèrent, le corps envoyé n’est pas la chaîne signée (votre framework l’a re-sérialisé, un proxy a changé l’encodage, un retour à la ligne final) ; s’ils sont identiques, l’API key est fausse. Collez-le dans le vérificateur de signature pour voir la première différence.

{
  "state": 1,
  "message": "Invalid Sign.",
  "debug": {
    "body_base64": "eyJhbW91bnQiOiI0Mi4wMCIsImN1cnJlbmN5IjoiVVNEIiwi…",
    "body_bytes": 158,
    "sign_formula": "md5(body_base64 + API key)"
  }
}

FAQ

Mes clients rechargent le montant qu’ils veulent — quel mode ?

Les factures. Laissez le client saisir un montant sur votre page de recharge, créez une facture pour ce montant et créditez payment_amount_usd à l’arrivée. N’utilisez les portefeuilles statiques que si les clients doivent enregistrer une adresse et lui envoyer des fonds à répétition.

Que se passe-t-il si un client paie trop peu ?

Avant l’expiration, le client peut envoyer la différence depuis la page de paiement (elle indique ce qui reste dû ; statut wrong_amount_waiting, et s’il reste moins de 30 minutes au premier paiement insuffisant, l’échéance est repoussée à 30 minutes plus tard). S’il manque encore quelque chose à l’expiration, la facture passe à wrong_amount et payment_amount_usd dans le webhook est le montant reçu ; les activités de recharge peuvent simplement le créditer.

Et si un client paie en retard, ou deux fois ?

L’argent qui arrive après l’expiration est quand même crédité et notifié ; l’argent qui arrive alors qu’une facture est déjà entièrement payée est aussi enregistré et visible dans le tableau de bord.

Et si un client envoie sur le mauvais réseau ?

Par exemple, la facture est sur TRON et il envoie depuis BNB Chain : ce n’est pas crédité automatiquement — contactez-nous et nous le traitons manuellement.

Combien ça coûte ?

1% de chaque paiement reçu, abaissé automatiquement selon le volume du mois précédent (0.9% dès $50,000, 0.8% dès $100,000, 0.7% dès $250,000, 0.6% dès $500,000 et 0.5% dès $1,000,000), sans abonnement ni frais d’ouverture. Le client paie les frais de réseau à l’envoi ; pour les lui répercuter, définissez subtract à la création d’une facture ou comme valeur par défaut dans le tableau de bord. Les retraits n’entraînent aucun frais supplémentaire. Voir les tarifs.

Quand l’argent m’arrive-t-il ?

Il est crédité sur votre solde dès que le paiement est confirmé. Demandez un retrait vers votre propre portefeuille dans « Fonds › Solde et retraits » ; une fois que nous l’approuvons, nous effectuons le versement et la transaction on-chain apparaît dans votre historique de retraits.

Vous pouvez aussi activer le retrait automatique : quand votre solde disponible atteint un montant que vous fixez, ou une fois par jour à 00:00 UTC, tout le solde disponible est retiré. Les retraits automatiques sont examinés de la même façon, et chaque modification des réglages envoie un avis à votre e-mail.