Virevo ← Retour

API développeurs

Encaissez par virement instantané depuis votre site

Une API REST pour intégrer Virevo à un site sur mesure ou un plugin CMS : créez un paiement, redirigez le client, recevez un webhook signé à l'encaissement.

Base URL : https://app.virevo.fr · Référence détaillée par endpoint : Référence API.

1. Authentification

Créez une clé d'API depuis votre dashboard → Développeurs. Deux modes : vrv_test_… (bac à sable, paiements fictifs) et vrv_live_… (réel). Passez-la en en-tête sur chaque appel /v1 :

Authorization: Bearer vrv_live_xxxxxxxx

2. Créer un paiement

curl -X POST https://app.virevo.fr/v1/payments \
  -H "Authorization: Bearer vrv_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-1042" \
  -d '{
    "amount_cents": 250000,
    "currency": "EUR",
    "reference": "CMD-1042",
    "return_url": "https://votre-site.fr/merci",
    "cancel_url": "https://votre-site.fr/panier",
    "payer_email": "client@exemple.fr"
  }'

Réponse :

{
  "id": "b3f1…",
  "status": "pending",
  "amount_cents": 250000,
  "currency": "EUR",
  "reference": "CMD-1042",
  "payment_url": "https://app.virevo.fr/p/…",
  "test": false,
  "created_at": "2026-06-24T09:00:00.000Z",
  "expires_at": "2026-07-01T09:00:00.000Z",
  "payer_email": "client@exemple.fr",
  "due_date": null,
  "payer_is_business": false,
  "send_email": false,
  "emails_sent": 0,
  "settled_elsewhere": false
}

Redirigez ensuite le client vers payment_url pour qu'il valide le virement. L'Idempotency-Key (recommandée) garantit qu'un même envoi ne crée pas deux paiements.

Champ	Description
amount_cents	Montant en centimes, entier. Minimum 100 (1 €), maximum 10 000 000. En dessous, erreur AMOUNT_BELOW_MINIMUM.
currency	EUR.
reference	Votre référence de commande (sert au rapprochement), 140 caractères au plus. Sur le relevé bancaire du client, elle apparaît sans accents, limitée à 50 caractères, et les caractères comme / y deviennent des espaces.
payer_email	Optionnel. E-mail de votre client : il n'a pas à le saisir pendant le paiement, et il peut mémoriser son compte bancaire pour ses paiements suivants chez vous.
return_url	Optionnel. Redirection du client après paiement réussi (avec ?virevo_payment_id&status=succeeded&reference).
cancel_url	Optionnel. Redirection du client si le paiement échoue ou est annulé (avec ?virevo_payment_id&status=failed ou canceled&reference). À défaut, return_url. Adresses en https:// uniquement.
due_date	Optionnel. Échéance d'une facture, AAAA-MM-JJ, entre aujourd'hui et dans 120 jours. Le lien reste alors valable 180 jours (cf. ci-dessous).
send_email	Optionnel, false par défaut. Virevo envoie le lien à payer_email (obligatoire dans ce cas) dès la création, puis le relance.
payer_is_business	Optionnel. Avec due_date : votre client est un professionnel, le dernier rappel cite les pénalités de retard et l'indemnité forfaitaire de 40 €.

Encaisser une facture (logiciels de facturation)

Transmettez l'échéance et l'e-mail du client : Virevo envoie la facture, relance le client, et vous prévient si elle reste impayée. Vous n'avez rien d'autre à gérer.

curl -X POST https://app.virevo.fr/v1/payments \
  -H "Authorization: Bearer vrv_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: facture-FA-2026-0412" \
  -d '{
    "amount_cents": 45000,
    "reference": "Facture FA-2026-0412",
    "payer_email": "compta@client.fr",
    "due_date": "2026-11-30",
    "send_email": true,
    "payer_is_business": true
  }'

Avec send_email	E-mails au payeur
Avec due_date	La facture à la création, puis des rappels 3 jours avant l'échéance, le jour même, puis à 7, 15 et 30 jours de retard. Une semaine après le dernier, vous êtes prévenu par e-mail ; le lien reste payable jusqu'à son expiration.
Sans due_date	Le lien à la création, puis deux relances à J+3 et J+6. S'il expire sans paiement (7 jours), vous êtes prévenu.

3. Suivre le statut

curl https://app.virevo.fr/v1/payments/b3f1… \
  -H "Authorization: Bearer vrv_live_xxxxxxxx"

Statuts possibles :

Statut	Signification
pending	En attente de règlement.
succeeded	Virement reçu, vous pouvez valider la commande.
failed	Refusé par la banque du client. Définitif : le lien n'accepte pas de nouvelle tentative. Si votre client veut réessayer, créez un nouveau paiement. Exception : une facture (due_date ou send_email), que le client peut réessayer depuis le même lien.
canceled	Annulé par vous (settled_elsewhere indique une facture réglée hors Virevo), ou expiré : un lien de paiement est valable 7 jours, 180 jours avec due_date (date exacte dans expires_at).

Lister les paiements

Pagination par curseur. La liste est limitée au mode de votre clé (une clé test ne voit que les paiements de test). Paramètres : limit (1–100, défaut 20), starting_after (id du dernier élément reçu), status, from, to (dates ISO sur created_at).

curl "https://app.virevo.fr/v1/payments?limit=20&status=succeeded" \
  -H "Authorization: Bearer vrv_live_xxxxxxxx"

{
  "object": "list",
  "data": [ { "id": "b3f1…", "status": "succeeded", … } ],
  "has_more": true
}

# page suivante : reprendre à partir du dernier id reçu
curl "https://app.virevo.fr/v1/payments?limit=20&starting_after=b3f1…" \
  -H "Authorization: Bearer vrv_live_xxxxxxxx"

Annuler un paiement

Un paiement encore pending peut être annulé : le lien cesse de fonctionner et l'événement payment.canceled est émis.

curl -X POST https://app.virevo.fr/v1/payments/{id}/cancel \
  -H "Authorization: Bearer vrv_live_xxxxxxxx"

# facture réglée hors Virevo (chèque, virement classique) : mêmes effets,
# mais le paiement porte settled_elsewhere: true
curl -X POST https://app.virevo.fr/v1/payments/{id}/cancel \
  -H "Authorization: Bearer vrv_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"settled_elsewhere": true}'

Remboursements

Créez un remboursement (total ou partiel) sur un paiement réglé, puis relisez-les. Idempotency-Key recommandé sur la création (un rejeu ne crée pas de doublon). Émet l'événement payment.refunded.

# créer (montant en centimes ; sans amount_cents = solde restant)
curl -X POST https://app.virevo.fr/v1/payments/{id}/refund \
  -H "Authorization: Bearer vrv_live_xxxxxxxx" \
  -H "Idempotency-Key: refund-cmd-1042" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 2000, "reason": "geste commercial"}'

# lister les remboursements d'un paiement
curl https://app.virevo.fr/v1/payments/{id}/refunds \
  -H "Authorization: Bearer vrv_live_xxxxxxxx"
# → { "object": "list", "data": [ { "id": "ref_…", "amount_cents": 2000, … } ] }

# relire un remboursement par id
curl https://app.virevo.fr/v1/refunds/{refund_id} \
  -H "Authorization: Bearer vrv_live_xxxxxxxx"

4. Mode test (sans compte vérifié)

Avec une clé vrv_test_…, les paiements sont fictifs (aucun KYC, aucun mouvement réel). Pour simuler un encaissement et déclencher le webhook :

curl -X POST https://app.virevo.fr/v1/payments/{id}/simulate \
  -H "Authorization: Bearer vrv_test_xxxxxxxx"
# → status: "succeeded" + envoi du webhook payment.succeeded

Vous pouvez ainsi développer toute votre intégration de bout en bout avant la mise en production.

5. Webhooks

Enregistrez l'URL de votre serveur dans le dashboard → Développeurs. Vous recevez un secret (whsec_…). Événements émis : payment.succeeded, payment.failed, payment.canceled, payment.expired, payment.refunded, et pour les échéanciers installment.paid, installment.unpaid, installment_plan.completed, installment_plan.canceled (§6). À chaque encaissement, Virevo envoie :

POST https://votre-site.fr/virevo/webhook
Virevo-Signature: t=1750000000,v1=<hmac-sha256>
Virevo-Event-Type: payment.succeeded

{
  "id": "evt_…",
  "type": "payment.succeeded",
  "created_at": "2026-06-24T09:01:00.000Z",
  "data": { "payment": {
    "id": "b3f1…", "status": "succeeded",
    "amount_cents": 250000, "currency": "EUR", "reference": "CMD-1042",
    "created_at": "2026-06-24T09:00:00.000Z",
    "due_date": null, "settled_elsewhere": false
  } }
}

Vérifier la signature

La signature est un HMAC-SHA256 de "{t}.{corps_brut}" avec votre secret. Recalculez-la et comparez à v1 ; rejetez si l'écart de temps dépasse 5 minutes (anti-rejeu). L'en-tête peut contenir plusieurs v1 (pendant une rotation de secret, cf. §5.1) : acceptez si l'un d'eux correspond.

PHP (WordPress / WooCommerce) :

$payload = file_get_contents('php://input');
$sig = $_SERVER['HTTP_VIREVO_SIGNATURE'] ?? '';
$t = null; $sigs = [];
foreach (explode(',', $sig) as $part) {            // t=…,v1=…,v1=…
    [$k, $v] = array_pad(explode('=', $part, 2), 2, '');
    if (trim($k) === 't') $t = (int) trim($v);
    elseif (trim($k) === 'v1') $sigs[] = trim($v);
}
$expected = hash_hmac('sha256', $t . '.' . $payload, $secret);
$ok = false;
foreach ($sigs as $v1) { if (hash_equals($expected, $v1)) { $ok = true; break; } }
if (!$ok || $t === null || abs(time() - $t) > 300) {
    http_response_code(400); exit;
}
$event = json_decode($payload, true);
// $event['data']['payment']['reference'] → valider la commande

Node.js :

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, header, rawBody) {
  let t = NaN; const sigs = [];
  for (const kv of header.split(",")) {            // t=…,v1=…,v1=…
    const i = kv.indexOf("="); if (i < 0) continue;
    const k = kv.slice(0, i).trim(), v = kv.slice(i + 1).trim();
    if (k === "t") t = Number(v); else if (k === "v1") sigs.push(v);
  }
  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`).digest("hex");
  const eb = Buffer.from(expected);
  const ok = sigs.some((v1) => v1.length === expected.length &&
    timingSafeEqual(eb, Buffer.from(v1)));
  return ok && Number.isFinite(t) && Math.abs(Date.now() / 1000 - t) <= 300;
}

5.1 Renouveler le secret (rotation)

Depuis le dashboard → Développeurs, le bouton « Renouveler le secret » génère un nouveau whsec_…. L'ancien reste valide 24 h : pendant cette fenêtre, Virevo signe chaque livraison avec les deux secrets (deux v1 dans l'en-tête). Vous pouvez donc déployer le nouveau secret sans aucune livraison perdue, du moment que votre vérification accepte l'un des v1 (code ci-dessus). Passé 24 h, seul le nouveau secret signe.

6. Échéanciers (paiement en plusieurs fois)

Vous fixez les échéances, Virevo s'occupe du reste : le jour de chaque échéance, votre client reçoit par e-mail son lien de paiement, puis une relance à J+3 et J+7. Il peut essayer jusqu'à 3 fois si sa banque refuse. Sans paiement à J+14, l'échéance est déclarée impayée et vous êtes prévenu.

curl -X POST https://app.virevo.fr/v1/installment_plans \
  -H "Authorization: Bearer vrv_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: devis-207" \
  -d '{
    "reference": "Devis 207",
    "payer": { "name": "Marie Martin", "email": "marie@exemple.fr" },
    "installments": [
      { "amount_cents": 50000, "due_date": "2026-10-10" },
      { "amount_cents": 50000, "due_date": "2026-11-10" },
      { "amount_cents": 50000, "due_date": "2026-12-10" }
    ]
  }'

Réponse (même forme pour la lecture, la liste et l'annulation) :

{
  "id": "5a9c…",
  "status": "active",
  "reference": "Devis 207",
  "payer": { "name": "Marie Martin", "email": "marie@exemple.fr" },
  "total_cents": 150000,
  "paid_cents": 0,
  "currency": "EUR",
  "created_at": "2026-10-03T10:00:00.000Z",
  "installments": [
    { "id": "e1…", "seq": 1, "amount_cents": 50000, "due_date": "2026-10-10",
      "status": "scheduled", "rejections": 0,
      "payment_url": "https://app.virevo.fr/e/…", "paid_at": null },
    …
  ]
}

Règle	Détail
Nombre d'échéances	De 2 à 12.
Montant	1 € minimum par échéance (amount_cents ≥ 100).
Dates	due_date au format AAAA-MM-JJ, strictement croissantes, la première pas avant aujourd'hui.
Commission	Due sur chaque échéance réglée, comme un paiement ordinaire, et facturée au mois.

# lire
curl https://app.virevo.fr/v1/installment_plans/{id} \
  -H "Authorization: Bearer vrv_live_xxxxxxxx"

# lister (curseur, comme les paiements)
curl "https://app.virevo.fr/v1/installment_plans?limit=20&starting_after={id}" \
  -H "Authorization: Bearer vrv_live_xxxxxxxx"

# annuler : les échéances non réglées ne sont plus envoyées ni relancées
curl -X POST https://app.virevo.fr/v1/installment_plans/{id}/cancel \
  -H "Authorization: Bearer vrv_live_xxxxxxxx"

Statut d'une échéance	Signification
scheduled	Date à venir, rien n'a encore été envoyé.
due	Lien envoyé, en attente de paiement.
paid	Réglée.
unpaid	3 refus de la banque, ou rien reçu 14 jours après la date. Un virement tardif peut encore la régler.
canceled	Échéancier annulé.

L'échéancier lui-même est active, puis completed quand plus aucune échéance n'est à venir, ou canceled.

Webhooks d'échéancier

Événement	Quand
installment.paid	Une échéance est réglée.
installment.unpaid	Une échéance est déclarée impayée.
installment_plan.completed	Plus aucune échéance à venir.
installment_plan.canceled	L'échéancier est annulé.

{
  "id": "evt_…",
  "type": "installment.paid",
  "created_at": "2026-10-10T09:12:00.000Z",
  "data": {
    "installment_plan": { "id": "5a9c…", "status": "active", … },
    "installment": { "id": "e1…", "seq": 1, "status": "paid", … }
  }
}

7. Erreurs

Toute erreur renvoie un code HTTP et un corps {"error": {"code": "…", "message": "…"}}. Le message est en français et peut être montré tel quel ; basez votre logique sur code.

HTTP	Code	Cause
400	VALIDATION_ERROR	Champ manquant ou invalide (le détail est dans details).
400	AMOUNT_BELOW_MINIMUM	Montant inférieur à 1 €.
400	INSTALLMENT_DATE_PAST	Première échéance datée d'avant aujourd'hui.
401	UNAUTHORIZED	Clé d'API absente, invalide ou révoquée.
402	INVOICE_UNPAID	Facture Virevo impayée depuis plus de 15 jours : réglez-la depuis le dashboard. Les paiements déjà créés aboutissent normalement.
403	MANDATE_REQUIRED	Prélèvement de la commission pas encore autorisé : une case à cocher dans le dashboard. Les paiements déjà créés aboutissent normalement.
403	KYC_NOT_VERIFIED	Compte pas encore vérifié. Le mode test reste disponible.
403	IBAN_NOT_VERIFIED	Titulaire de l'IBAN à vérifier.
403	PROVIDER_KYC_NOT_VERIFIED	Vérification par notre partenaire bancaire en cours, en général quelques minutes après la validation du compte.
403	ACCOUNT_CLOSED	Compte résilié.
404	PAYMENT_NOT_FOUND, INSTALLMENT_PLAN_NOT_FOUND	Identifiant inconnu, ou d'un autre compte.
409	CONFLICT	Idempotency-Key déjà utilisée avec d'autres paramètres.
409	PAYMENT_NOT_CANCELLABLE, PAYMENT_TRANSFER_IN_PROGRESS	Annulation impossible (§3).
429	RATE_LIMITED	Trop de requêtes : 120 créations de paiement par minute au plus.
502	BRIDGE_UNAVAILABLE	Partenaire bancaire momentanément injoignable : réessayez avec la même Idempotency-Key.

Référence complète

Détail de chaque endpoint (paramètres, corps, réponses, authentification) : Référence API.