Aller au contenu
API v1

Documentation API : intégrez en moins de 2 h.

API REST, webhooks signés, SDK et plugins e-commerce : une documentation claire, des exemples prêts à copier.

POST /api/v1/payments · 201
{
  "id": "pay_8Kd2xQ4mV9",
  "status": "pending",
  "amount": 2999,
  "currency": "EUR",
  "checkout_url": "https://pay.bridgepay.fr/c/8Kd2xQ4mV9"
}
Disponibilité
99,9 %
Réponse du support
2 jours
Versement des fonds
3 j ouvrés
Cryptomonnaies acceptées
50+
Sommaire
  1. Démarrage rapide
  2. Première intégration
  3. Personnalisation
  4. Exemple React
  5. Exemple PHP
  6. Webhooks
  7. Référence API
  8. Mode test

Démarrage rapide

Trois étapes pour encaisser un premier paiement de test : vos clés API, une balise script, une carte de test.

  1. 1

    Obtenez vos clés API

    Créez un compte Bridge Pay et récupérez vos clés API dans votre tableau de bord.

    pk_test_…
    Clé publique (frontend)
    sk_test_…
    Clé secrète (backend)
  2. 2

    Intégrez le SDK

    Ajoutez notre SDK JavaScript à votre page de paiement avec une seule ligne de code.

  3. 3

    Testez et déployez

    Utilisez nos cartes de test pour valider votre intégration, puis passez en production.

Première intégration

Le strict minimum : une balise script et un appel à BridgePay.init. Le formulaire de paiement est hébergé par Bridge Pay, aucune donnée de carte ne transite par votre serveur.

index.html
<!-- Simple integration -->
<script src="https://cdn.bridgepay.fr/v1/bridgepay.js"></script>
<script>
  BridgePay.init({
    publicKey: 'pk_test_your_public_key',
    amount: 2999, // €29.99
    currency: 'EUR',
    description: 'Premium product purchase',
    onSuccess: function(payment) {
      console.log('Payment successful:', payment);
      window.location.href = '/success';
    },
    onError: function(error) {
      console.log('Payment error:', error);
    }
  });
</script>

Conseil

Utilisez la clé publique (pk_...) côté client et la clé secrète (sk_...) côté serveur uniquement, stockée dans une variable d'environnement. Traitez chaque code d'erreur de l'API avant de rediriger le client.

Personnalisation

Personnalisez l'apparence et le comportement du formulaire de paiement selon vos besoins.

checkout.js
// Advanced customization
BridgePay.init({
  publicKey: 'pk_test_your_public_key',
  amount: 4999,
  currency: 'EUR',
  customer: {
    email: 'client@example.com',
    name: 'John Doe',
    phone: '+33123456789'
  },
  theme: {
    primaryColor: '#3B82F6',
    borderRadius: '8px',
    fontFamily: 'Inter, sans-serif'
  },
  metadata: {
    order_id: 'ORD-12345',
    customer_id: 'CUST-67890'
  },
  webhooks: {
    success: 'https://yoursite.com/webhook/success',
    cancel: 'https://yoursite.com/webhook/cancel',
    refund: 'https://yoursite.com/webhook/refund'
  }
});

Exemple React

Intégration complète dans une application React avec gestion d'état.

PaymentComponent.jsx
// SDK loaded once in index.html (see First integration)
import { useEffect, useState } from 'react';

export default function PaymentComponent({ amount, orderId }) {
  const [status, setStatus] = useState('idle');
  useEffect(() => {
    window.BridgePay.init({
      publicKey: process.env.REACT_APP_BRIDGEPAY_PUBLIC_KEY,
      amount, currency: 'EUR',
      metadata: { order_id: orderId },
      onSuccess: (payment) => setStatus(payment.status),
      onError: () => setStatus('failed'),
    });
  }, [amount, orderId]);

  const pay = () => { setStatus('pending'); window.BridgePay.open(); };
  return (
    <button onClick={pay} disabled={status === 'pending'}>
      {status === 'pending' ? 'Processing...' : 'Pay now'}
    </button>
  );
}

onSuccess reçoit l'objet payment avec son id : vérifiez-le côté serveur via GET /api/v1/payments/:id avant de livrer la commande.

Exemple PHP

Intégration serveur avec PHP pour créer et vérifier les paiements.

BridgePayAPI.php
<?php
function bridgepay($method, $path, $body = null) {
    $baseUrl = 'https://api.bridgepay.fr/api/v1';
    $ch = curl_init($baseUrl . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('BRIDGEPAY_SECRET_KEY'),
            'Content-Type: application/json',
        ],
    ]);
    if ($body !== null) curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    $data = json_decode(curl_exec($ch), true);
    return ['status_code' => curl_getinfo($ch, CURLINFO_HTTP_CODE), 'data' => $data];
}

function createPayment($amount, $currency, $metadata = []) {
    return bridgepay('POST', '/payments', compact('amount', 'currency', 'metadata'));
}

function getPayment($id) {
    return bridgepay('GET', '/payments/' . rawurlencode($id));
}

$payment = createPayment(2999, 'EUR', ['order_id' => 'ORD-12345']);
if ($payment['status_code'] === 201) {
    header('Location: ' . $payment['data']['checkout_url']);
    exit;
}

La clé secrète, lue dans une variable d'environnement, ne sort jamais du serveur : le navigateur ne reçoit que checkout_url. Au retour du client, getPayment() confirme le statut avant toute livraison.

Webhooks

Recevez des notifications en temps réel pour chaque événement de paiement.

webhook.js
const express = require('express');
const crypto = require('crypto');
const app = express();

function verifyWebhookSignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(String(signature || ''));
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post(
  '/webhook/bridgepay',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-bridgepay-signature'];
    const secret = process.env.WEBHOOK_SECRET;
    if (!verifyWebhookSignature(req.body, signature, secret)) {
      return res.status(401).send('Invalid signature');
    }

    const { event, data } = JSON.parse(req.body);
    const orderId = data.metadata.order_id;
    switch (event) {
      case 'payment.succeeded': updateOrderStatus(orderId, 'paid'); break;
      case 'payment.failed': updateOrderStatus(orderId, 'failed'); break;
      case 'payment.refunded': updateOrderStatus(orderId, 'refunded'); break;
    }
    res.status(200).send('OK');
  }
);

Une fois la signature validée, mettez à jour la commande à partir de metadata.order_id, puis répondez 200. Rendez ce traitement idempotent : recevoir deux fois le même événement ne doit pas livrer deux fois la commande.

Sécurité des webhooks

Comparez la signature HMAC-SHA256 de l'en-tête x-bridgepay-signature avec celle calculée à partir du corps brut de la requête et de votre secret de webhook, en temps constant (crypto.timingSafeEqual). Rejetez toute requête dont la signature est absente ou invalide (401).

Référence API

Les endpoints essentiels de l'API v1. Toutes les requêtes sont authentifiées par votre clé secrète (en-tête Authorization: Bearer sk_...) et répondent en JSON.

MéthodeEndpointDescription
POST/api/v1/paymentsInitie une transaction et renvoie checkout_url. Paramètres : amount, currency, customer, metadata.
GET/api/v1/payments/:idRécupère le statut et les détails d'un paiement : id, status, amount, created_at.
GET/api/v1/paymentsListe paginée de vos transactions, filtrable par statut, date et montant.
POST/api/v1/payments/:id/refundRembourse totalement ou partiellement un paiement réussi.
GET/api/v1/payoutsHistorique de vos virements : dates, montants nets et statuts.
POST/api/v1/webhook-endpointsEnregistre une URL de notification pour les événements de paiement.

Statuts de paiement

pending
En attente : le client n'a pas finalisé le paiement.
succeeded
Réussi : fonds capturés, inclus dans le prochain payout.
failed
Échoué : refus de l'émetteur ou 3D Secure non validé ; aucun montant débité.
cancelled
Annulé : paiement expiré ou abandonné par le client avant validation.
refunded
Remboursé : remboursement total ou partiel émis via POST /api/v1/payments/:id/refund.

Mode test

Le mode test reproduit les réponses de production sans mouvement de fonds. Utilisez les clés pk_test_ et sk_test_ avec les cartes ci-dessous.

Cartes de test

Numéro de carteRésultatDescription
4242 4242 4242 4242SuccèsPaiement réussi standard
4000 0000 0000 0002RefuséCarte générique refusée
4000 0000 0000 9995RefuséFonds insuffisants

Informations de test

  • Date d'expiration : n'importe quelle date future (par ex. 12/34)
  • CVC : trois chiffres quelconques (par ex. 123)
  • Code postal : n'importe quelle valeur valide

Vos clés de test en quelques minutes.

Ouvrez un compte, récupérez vos clés pk_test_ et sk_test_ et lancez une première transaction aujourd'hui. Une question d'intégration ? Le support répond sous 2 jours ouvrés, du lundi au vendredi.