Documentation

Documentation API Genipay

Bienvenue dans la documentation de l'API Genipay. Cette API vous permet d'intégrer facilement les paiements dans votre application ou site web. Vous pouvez gérer les transactions, les clients et recevoir des notifications en temps réel via des webhooks.

L'API Genipay est actuellement en version v1. Toutes les requêtes doivent être adressées à https://api.genipay.com/v1/

Base URL

https://api.genipay.com/v1/

Authentification

L'API Genipay utilise des clés API pour authentifier les requêtes. Vous pouvez consulter et gérer vos clés API dans votre tableau de bord Genipay.

Toutes les requêtes API doivent être effectuées via HTTPS et inclure votre clé API dans l'en-tête Authorization. 

curl -X GET "https://api.genipay.com/v1/transactions" \
     -H "Authorization: Bearer votre_clé_api"

Attention : Gardez votre clé API secrète ! Ne la partagez jamais dans des dépôts publics ou avec des tiers non autorisés.

Gestion des erreurs

L'API Genipay utilise des codes d'état HTTP conventionnels pour indiquer le succès ou l'échec d'une requête API. En général, les codes 2xx indiquent un succès, les codes 4xx indiquent une erreur due à l'information fournie (par exemple, un paramètre requis manquant), et les codes 5xx indiquent une erreur avec les serveurs Genipay.

Codes d'erreur courants

Code Description
400 Requête incorrecte - Les paramètres fournis sont invalides
401 Non autorisé - Clé API invalide
403 Interdit - Vous n'avez pas les droits pour accéder à cette ressource
404 Non trouvé - La ressource demandée n'existe pas
429 Trop de requêtes - Vous avez dépassé la limite de taux
500 Erreur serveur - Quelque chose s'est mal passé de notre côté

Exemple de réponse d'erreur

{
  "error": {
    "code": "invalid_request",
    "message": "Le paramètre 'amount' est requis",
    "status": 400,
    "details": {
      "field": "amount",
      "reason": "required"
    }
  }
}
GET

/transactions

Récupère la liste des transactions. Les résultats sont paginés et triés par date de création, avec les plus récentes en premier.

Paramètres de requête

Paramètre Type Requis Description
limit integer Non Nombre de transactions à retourner (défaut: 10, max: 100)
offset integer Non Nombre de transactions à sauter (défaut: 0)
customer_id string Non Filtrer par ID client
status string Non Filtrer par statut (completed, pending, failed)

Exemple de requête

curl -X GET "https://api.genipay.com/v1/transactions?limit=5&status=completed" \
     -H "Authorization: Bearer votre_clé_api"

Exemple de réponse

{
  "data": [
    {
      "id": "tx_123456789",
      "amount": 24500,
      "currency": "EUR",
      "status": "completed",
      "customer_id": "cus_987654321",
      "description": "Abonnement Premium",
      "created_at": "2023-04-15T10:30:00Z"
    },
    {
      "id": "tx_123456788",
      "amount": 8950,
      "currency": "EUR",
      "status": "completed",
      "customer_id": "cus_987654322",
      "description": "Achat produit",
      "created_at": "2023-04-14T15:45:00Z"
    }
  ],
  "has_more": true,
  "total_count": 42
}
GET

/transactions/{id}

Récupère les détails d'une transaction spécifique.

Paramètres de chemin

Paramètre Type Requis Description
id string Oui ID unique de la transaction

Exemple de requête

curl -X GET "https://api.genipay.com/v1/transactions/tx_123456789" \
     -H "Authorization: Bearer votre_clé_api"

Exemple de réponse

{
  "id": "tx_123456789",
  "amount": 24500,
  "currency": "EUR",
  "status": "completed",
  "customer_id": "cus_987654321",
  "customer_email": "jean.dupont@example.com",
  "description": "Abonnement Premium",
  "payment_method": {
    "type": "card",
    "last4": "4242",
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2025
  },
  "metadata": {
    "order_id": "ORD-12345"
  },
  "created_at": "2023-04-15T10:30:00Z",
  "updated_at": "2023-04-15T10:31:05Z"
}
POST

/transactions

Crée une nouvelle transaction.

Paramètres de requête

Paramètre Type Requis Description
amount integer Oui Montant en centimes (ex: 2000 pour 20,00 €)
currency string Oui Code devise à 3 lettres (ISO 4217)
customer_id string Non ID du client existant
description string Non Description de la transaction
metadata object Non Métadonnées personnalisées (max 20 paires clé-valeur)

Exemple de requête

curl -X POST "https://api.genipay.com/v1/transactions" \
     -H "Authorization: Bearer votre_clé_api" \
     -H "Content-Type: application/json" \
     -d '{
       "amount": 2000,
       "currency": "EUR",
       "customer_id": "cus_987654321",
       "description": "Achat produit XYZ",
       "metadata": {
         "order_id": "ORD-12345"
       }
     }'

Exemple de réponse

{
  "id": "tx_123456790",
  "amount": 2000,
  "currency": "EUR",
  "status": "pending",
  "customer_id": "cus_987654321",
  "description": "Achat produit XYZ",
  "payment_url": "https://checkout.genipay.com/pay/tx_123456790",
  "metadata": {
    "order_id": "ORD-12345"
  },
  "created_at": "2023-04-16T14:22:00Z"
}
PUT

/transactions/{id}

Met à jour une transaction existante. Seuls certains champs peuvent être modifiés.

Paramètres de chemin

Paramètre Type Requis Description
id string Oui ID unique de la transaction

Paramètres de requête

Paramètre Type Requis Description
description string Non Description de la transaction
metadata object Non Métadonnées personnalisées (max 20 paires clé-valeur)

Exemple de requête

curl -X PUT "https://api.genipay.com/v1/transactions/tx_123456790" \
     -H "Authorization: Bearer votre_clé_api" \
     -H "Content-Type: application/json" \
     -d '{
       "description": "Achat produit XYZ - Version Premium",
       "metadata": {
         "order_id": "ORD-12345",
         "product_id": "PROD-789"
       }
     }'

Exemple de réponse

{
  "id": "tx_123456790",
  "amount": 2000,
  "currency": "EUR",
  "status": "pending",
  "customer_id": "cus_987654321",
  "description": "Achat produit XYZ - Version Premium",
  "payment_url": "https://checkout.genipay.com/pay/tx_123456790",
  "metadata": {
    "order_id": "ORD-12345",
    "product_id": "PROD-789"
  },
  "created_at": "2023-04-16T14:22:00Z",
  "updated_at": "2023-04-16T14:25:30Z"
}
DELETE

/transactions/{id}

Annule une transaction en attente. Les transactions déjà complétées ne peuvent pas être annulées.

Paramètres de chemin

Paramètre Type Requis Description
id string Oui ID unique de la transaction

Exemple de requête

curl -X DELETE "https://api.genipay.com/v1/transactions/tx_123456790" \
     -H "Authorization: Bearer votre_clé_api"

Exemple de réponse

{
  "id": "tx_123456790",
  "status": "canceled",
  "canceled_at": "2023-04-16T15:10:00Z"
}
GET

/customers

Récupère la liste des clients. Les résultats sont paginés et triés par date de création, avec les plus récents en premier.

Paramètres de requête

Paramètre Type Requis Description
limit integer Non Nombre de clients à retourner (défaut: 10, max: 100)
offset integer Non Nombre de clients à sauter (défaut: 0)
email string Non Filtrer par email

Exemple de requête

curl -X GET "https://api.genipay.com/v1/customers?limit=5" \
     -H "Authorization: Bearer votre_clé_api"

Exemple de réponse

{
  "data": [
    {
      "id": "cus_987654321",
      "email": "jean.dupont@example.com",
      "name": "Jean Dupont",
      "created_at": "2023-03-15T10:30:00Z"
    },
    {
      "id": "cus_987654322",
      "email": "marie.martin@example.com",
      "name": "Marie Martin",
      "created_at": "2023-03-14T15:45:00Z"
    }
  ],
  "has_more": true,
  "total_count": 28
}
GET

/customers/{id}

Récupère les détails d'un client spécifique.

Paramètres de chemin

Paramètre Type Requis Description
id string Oui ID unique du client

Exemple de requête

curl -X GET "https://api.genipay.com/v1/customers/cus_987654321" \
     -H "Authorization: Bearer votre_clé_api"

Exemple de réponse

{
  "id": "cus_987654321",
  "email": "jean.dupont@example.com",
  "name": "Jean Dupont",
  "phone": "+33612345678",
  "address": {
    "line1": "123 Rue de Paris",
    "city": "Paris",
    "postal_code": "75001",
    "country": "FR"
  },
  "metadata": {
    "user_id": "USER-12345"
  },
  "created_at": "2023-03-15T10:30:00Z",
  "updated_at": "2023-03-15T10:30:00Z"
}
POST

/customers

Crée un nouveau client.

Paramètres de requête

Paramètre Type Requis Description
email string Oui Adresse email du client
name string Non Nom complet du client
phone string Non Numéro de téléphone du client
address object Non Adresse du client
metadata object Non Métadonnées personnalisées

Exemple de requête

curl -X POST "https://api.genipay.com/v1/customers" \
     -H "Authorization: Bearer votre_clé_api" \
     -H "Content-Type: application/json" \
     -d '{
       "email": "nouveau.client@example.com",
       "name": "Nouveau Client",
       "phone": "+33612345678",
       "address": {
         "line1": "123 Rue de Paris",
         "city": "Paris",
         "postal_code": "75001",
         "country": "FR"
       },
       "metadata": {
         "user_id": "USER-67890"
       }
     }'

Exemple de réponse

{
  "id": "cus_987654323",
  "email": "nouveau.client@example.com",
  "name": "Nouveau Client",
  "phone": "+33612345678",
  "address": {
    "line1": "123 Rue de Paris",
    "city": "Paris",
    "postal_code": "75001",
    "country": "FR"
  },
  "metadata": {
    "user_id": "USER-67890"
  },
  "created_at": "2023-04-16T16:45:00Z",
  "updated_at": "2023-04-16T16:45:00Z"
}

Webhooks

Les webhooks vous permettent de recevoir des notifications en temps réel lorsque des événements se produisent dans votre compte Genipay. Vous pouvez configurer des URL de webhook dans votre tableau de bord Genipay.

Configuration

Pour configurer un webhook, vous devez fournir une URL HTTPS qui sera appelée lorsqu'un événement se produit. Genipay enverra une requête POST à cette URL avec les détails de l'événement.

Pour sécuriser vos webhooks, Genipay inclut une signature dans l'en-tête X-Genipay-Signature de chaque requête. Vous devez vérifier cette signature pour vous assurer que la requête provient bien de Genipay.

Format de la charge utile

{
  "id": "evt_123456789",
  "type": "transaction.completed",
  "created": 1681654800,
  "data": {
    "object": {
      "id": "tx_123456789",
      "amount": 24500,
      "currency": "EUR",
      "status": "completed",
      "customer_id": "cus_987654321",
      "description": "Abonnement Premium",
      "created_at": "2023-04-16T14:00:00Z"
    }
  }
}

Événements Webhook

Voici la liste des événements que vous pouvez recevoir via webhooks.

Événement Description
transaction.created Une nouvelle transaction a été créée
transaction.pending Une transaction est en attente de paiement
transaction.completed Une transaction a été complétée avec succès
transaction.failed Une transaction a échoué
transaction.canceled Une transaction a été annulée
customer.created Un nouveau client a été créé
customer.updated Les informations d'un client ont été mises à jour