Skip to content
API v1

API documentation: integrate in under 2 hours.

REST API, signed webhooks, SDKs and e-commerce plugins: clear documentation, copy-ready examples.

POST /api/v1/payments · 201
{
  "id": "pay_8Kd2xQ4mV9",
  "status": "pending",
  "amount": 2999,
  "currency": "EUR",
  "checkout_url": "https://pay.bridgepay.fr/c/8Kd2xQ4mV9"
}
Availability
99.9%
Support response time
2 days
Payout (business days)
3 days
Cryptocurrencies accepted
50+
Summary
  1. Getting Started
  2. First Integration
  3. Customization
  4. React Example
  5. PHP Example
  6. Webhooks
  7. API Reference
  8. Test Mode

Getting Started

Three steps to a first test payment: your API keys, one script tag, one test card.

  1. 1

    Get your API keys

    Create a Bridge Pay account and retrieve your API keys from your dashboard.

    pk_test_…
    Public key (frontend)
    sk_test_…
    Secret key (backend)
  2. 2

    Integrate the SDK

    Add our JavaScript SDK to your payment page with a single line of code.

  3. 3

    Test and deploy

    Use our test cards to validate your integration, then go to production.

First Integration

The bare minimum: one script tag and one BridgePay.init call. The payment form is hosted by Bridge Pay, no card data goes through your server.

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>

Tip

Use the public key (pk_...) client-side and the secret key (sk_...) server-side only, stored in an environment variable. Handle every API error code before redirecting the customer.

Customization

Customize the appearance and behavior of the payment form according to your needs.

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'
  }
});

React Example

Complete integration in a React application with state management.

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 receives the payment object with its id: verify it server-side with GET /api/v1/payments/:id before fulfilling the order.

PHP Example

Server-side integration with PHP to create and verify payments.

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;
}

The secret key, read from an environment variable, never leaves the server: the browser only receives checkout_url. When the customer comes back, getPayment() confirms the status before you fulfil the order.

Webhooks

Receive real-time notifications for each payment event.

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');
  }
);

Once the signature is valid, update the order from metadata.order_id, then reply 200. Make this handler idempotent: receiving the same event twice must not fulfil the order twice.

Webhook Security

Compare the HMAC-SHA256 signature in the x-bridgepay-signature header with the one computed from the raw request body and your webhook secret, in constant time (crypto.timingSafeEqual). Reject any request with a missing or invalid signature (401).

API Reference

The essential API v1 endpoints. All requests are authenticated with your secret key (Authorization: Bearer sk_... header) and respond in JSON.

MethodEndpointDescription
POST/api/v1/paymentsInitiates a transaction and returns checkout_url. Parameters: amount, currency, customer, metadata.
GET/api/v1/payments/:idRetrieves a payment's status and details: id, status, amount, created_at.
GET/api/v1/paymentsPaginated list of your transactions, filterable by status, date and amount.
POST/api/v1/payments/:id/refundFully or partially refunds a successful payment.
GET/api/v1/payoutsHistory of your settlements: dates, net amounts and statuses.
POST/api/v1/webhook-endpointsRegisters a notification URL for payment events.

Payment Statuses

pending
Pending: the customer has not completed the payment.
succeeded
Succeeded: funds captured, included in the next payout.
failed
Failed: issuer decline or failed 3D Secure; nothing charged.
cancelled
Cancelled: payment expired or abandoned by the customer before completion.
refunded
Refunded: full or partial refund issued via POST /api/v1/payments/:id/refund.

Test Mode

Test mode mirrors production responses without moving funds. Use the pk_test_ and sk_test_ keys with the cards below.

Test Cards

Card NumberResultDescription
4242 4242 4242 4242SuccessStandard successful payment
4000 0000 0000 0002DeclinedGeneric card declined
4000 0000 0000 9995DeclinedInsufficient funds

Test Information

  • Expiry date: any future date (e.g., 12/34)
  • CVC: any three digits (e.g., 123)
  • Postal code: any valid value

Your test keys in a few minutes.

Open an account, grab your pk_test_ and sk_test_ keys and run a first transaction today. Integration question? Support replies within 2 business days, Monday to Friday.