Se connecter

📚 Documentation API

🚀 Introduction

L'API PAYSENP Business vous permet d'émettre des cartes virtuelles USD Visa pour vos clients, de les recharger, geler, supprimer et recevoir des notifications en temps réel.

Base URL: https://paysenp.com/api/v2

Headers requis sur chaque requĂȘte:
X-API-Key: votre_api_key
X-API-Secret: votre_api_secret
Content-Type: application/json
⚠ Ne jamais exposer votre API Secret cĂŽtĂ© client. Toujours faire les appels depuis votre serveur.

🔄 Flow d'intĂ©gration

1
Rechargez votre solde PAYSENP Business — DĂ©posez des fonds via MonCash ou USDT depuis votre tableau de bord.
2
Créez un Customer via POST /customers/create avec les infos KYC de votre utilisateur (photos ID + selfie en base64).
3
RĂ©cupĂ©rez le customer_id retournĂ© — vous en aurez besoin pour crĂ©er des cartes.
4
CrĂ©ez une carte via POST /cards/create avec le customer_id — minimum $2 de solde requis sur la carte.
5
Rechargez la carte via POST /cards/fund.
6
Recevez les événements (achats, déclin, OTP) via votre URL webhook configurée dans API Keys.

đŸ‘„ Customers

POST /customers/create
CrĂ©er un customer et effectuer la vĂ©rification KYC (Tier 1 + Tier 2). Les photos doivent ĂȘtre en base64.

📾 Photos requises — Comment les convertir en base64

đŸȘȘ
id_front
Recto ID
đŸȘȘ
id_back
Verso ID
đŸ€ł
selfie
Visage clair
✅ Photo nette, bonne luminositĂ©, toutes infos visibles
❌ Pas floue, pas de reflet, pas de lunettes de soleil sur le selfie
ParamĂštreTypeRequisDescription
first_namestringRequisPrénom
last_namestringRequisNom de famille
emailstringRequisEmail unique du customer
phonestringRequisTéléphone avec indicatif ex: +50934000000
date_of_birthstringRequisFormat: YYYY-MM-DD ex: 1990-05-15
id_typestringRequisPASSPORT / NIN / DRIVERS_LICENSE / VOTERS_CARD
id_numberstringRequisNuméro du document d'identité
id_frontstringRequisPhoto recto ID en base64
id_backstringOptionnelPhoto verso ID en base64
selfiestringRequisSelfie du visage en base64
addressstringRequisAdresse complĂšte
citystringRequisVille
statestringRequisÉtat / DĂ©partement
postal_codestringRequisCode postal
countrystringOptionnelCode pays ISO à 2 lettres, ex: HT, US, FR (défaut: HT). Les noms de pays complets sont refusés.
Vérification d'identité. La demande n'est pas envoyée immédiatement au fournisseur : elle est d'abord examinée par l'équipe PaySenp. La réponse est status: pending_review, pas un customer actif. Vous recevez ensuite le webhook customer.approved (avec customer_id) ou customer.rejected (avec la raison). Vous ne pouvez créer une carte qu'aprÚs customer.approved.

Photos : id_front et selfie en base64, format JPEG ou PNG, 5 Mo maximum chacune (idéalement moins de 2 Mo). id_type : NIN, PASSPORT, VOTERS_CARD ou DRIVERS_LICENSE. date_of_birth : YYYY-MM-DD, client majeur uniquement.

Réponse

{
  "status": true,
  "message": "KYC submitted for review...",
  "data": { "customer_ref": 12, "status": "pending_review" }
}
# Convertir image en base64 d'abord:
# Linux/Mac: base64 -i photo.jpg
# Windows:   certutil -encode photo.jpg tmp.txt

curl -X POST https://paysenp.com/api/v2/customers/create \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: VOTRE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name":    "Jean",
    "last_name":     "Pierre",
    "email":         "jean@exemple.com",
    "phone":         "+50934000000",
    "date_of_birth": "1990-05-15",
    "id_type":       "PASSPORT",
    "id_number":     "A12345678",
    "id_front":      "'"$(base64 -i recto.jpg)"'",
    "selfie":        "'"$(base64 -i selfie.jpg)"'",
    "address":       "Rue Capois",
    "city":          "Port-au-Prince",
    "state":         "Ouest",
    "postal_code":   "HT6110",
    "country":       "HT"
  }'
<?php
// Convertir images en base64
$id_front = base64_encode(file_get_contents('recto.jpg'));
$selfie   = base64_encode(file_get_contents('selfie.jpg'));

$data = [
    'first_name'    => 'Jean',
    'last_name'     => 'Pierre',
    'email'         => 'jean@exemple.com',
    'phone'         => '+50934000000',
    'date_of_birth' => '1990-05-15',
    'id_type'       => 'PASSPORT',
    'id_number'     => 'A12345678',
    'id_front'      => $id_front,
    'selfie'        => $selfie,
    'address'       => 'Rue Capois',
    'city'          => 'Port-au-Prince',
    'state'         => 'Ouest',
    'postal_code'   => 'HT6110',
    'country'       => 'HT',
];

$ch = curl_init('https://paysenp.com/api/v2/customers/create');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($data),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-API-Key: pk_live_xxxxxxxxxxxxxxxx',
        'X-API-Secret: VOTRE_SECRET',
        'Content-Type: application/json',
    ],
]);
$response = json_decode(curl_exec($ch), true);
$customer_id = $response['data']['customer_id'];
import requests, base64

# Convertir images en base64
with open('recto.jpg', 'rb') as f:
    id_front = base64.b64encode(f.read()).decode()
with open('selfie.jpg', 'rb') as f:
    selfie = base64.b64encode(f.read()).decode()

headers = {
    'X-API-Key':     'pk_live_xxxxxxxxxxxxxxxx',
    'X-API-Secret':  'VOTRE_SECRET',
    'Content-Type':  'application/json',
}

data = {
    'first_name':    'Jean',
    'last_name':     'Pierre',
    'email':         'jean@exemple.com',
    'phone':         '+50934000000',
    'date_of_birth': '1990-05-15',
    'id_type':       'PASSPORT',
    'id_number':     'A12345678',
    'id_front':      id_front,
    'selfie':        selfie,
    'address':       'Rue Capois',
    'city':          'Port-au-Prince',
    'state':         'Ouest',
    'postal_code':   'HT6110',
    'country':       'HT',
}

r = requests.post(
    'https://paysenp.com/api/v2/customers/create',
    json=data, headers=headers
)
customer_id = r.json()['data']['customer_id']
// Node.js
const fs      = require('fs');
const axios   = require('axios');

const id_front = fs.readFileSync('recto.jpg').toString('base64');
const selfie   = fs.readFileSync('selfie.jpg').toString('base64');

const res = await axios.post(
    'https://paysenp.com/api/v2/customers/create',
    {
        first_name:    'Jean',
        last_name:     'Pierre',
        email:         'jean@exemple.com',
        phone:         '+50934000000',
        date_of_birth: '1990-05-15',
        id_type:       'PASSPORT',
        id_number:     'A12345678',
        id_front,
        selfie,
        address:       'Rue Capois',
        city:          'Port-au-Prince',
        state:         'Ouest',
        postal_code:   'HT6110',
        country:       'HT',
    },
    { headers: {
        'X-API-Key':    'pk_live_xxxxxxxxxxxxxxxx',
        'X-API-Secret': 'VOTRE_SECRET',
    }}
);
const customer_id = res.data.data.customer_id;
// Réponse succÚs
{
  "status":      true,
  "message":     "Customer created and verified successfully.",
  "data": {
    "customer_id": "cust_abc123",
    "name":        "Jean Pierre",
    "tier":        "2",
  }
}
GET /customers
Liste tous vos customers
curl https://paysenp.com/api/v2/customers \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: VOTRE_SECRET"
$ch = curl_init('https://paysenp.com/api/v2/customers');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: pk_live_xxxxxxxxxxxxxxxx',
        'X-API-Secret: VOTRE_SECRET',
    ],
]);
$customers = json_decode(curl_exec($ch), true)['data'];
r = requests.get(
    'https://paysenp.com/api/v2/customers',
    headers=headers
)
customers = r.json()['data']
const res = await axios.get(
    'https://paysenp.com/api/v2/customers',
    { headers: { 'X-API-Key': 'pk_live_xxxxxxxxxxxxxxxx', 'X-API-Secret': 'VOTRE_SECRET' }}
);
const customers = res.data.data;

💳 Cartes Virtuelles

POST /cards/create
CrĂ©er une carte virtuelle USD Visa. Le customer doit ĂȘtre vĂ©rifiĂ© (customer.approved reçu). La rĂ©ponse est immĂ©diate avec le statut PENDING. Le card_id dĂ©finitif arrive dans le webhook card.created (ou card.failed avec la raison). Utilisez fund, freeze et les autres actions seulement quand la carte est ACTIVE.
ParamĂštreTypeRequisDescription
customer_idstringRequisID retourné lors de la création du customer
curl -X POST https://paysenp.com/api/v2/cards/create \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: VOTRE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "cust_abc123"}'
$ch = curl_init('https://paysenp.com/api/v2/cards/create');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode(['customer_id' => 'cust_abc123']),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-API-Key: pk_live_xxxxxxxxxxxxxxxx',
        'X-API-Secret: VOTRE_SECRET',
        'Content-Type: application/json',
    ],
]);
$card = json_decode(curl_exec($ch), true);
$card_id = $card['data']['card_id'];
r = requests.post(
    'https://paysenp.com/api/v2/cards/create',
    json={'customer_id': 'cust_abc123'},
    headers=headers
)
card_id = r.json()['data']['card_id']
const res = await axios.post(
    'https://paysenp.com/api/v2/cards/create',
    { customer_id: 'cust_abc123' },
    { headers: { 'X-API-Key': 'pk_live_xxxxxxxxxxxxxxxx', 'X-API-Secret': 'VOTRE_SECRET' }}
);
const card_id = res.data.data.card_id;
POST /cards/fund
Recharger une carte. Le montant est déduit de votre solde PAYSENP Business.
ParamĂštreTypeRequisDescription
card_idstringRequisID de la carte Ă  recharger
amountnumberRequisMontant en USD (min: 1)
curl -X POST https://paysenp.com/api/v2/cards/fund \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: VOTRE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"card_id": "card_xyz789", "amount": 50}'
curl_setopt_array($ch, [
    CURLOPT_URL        => 'https://paysenp.com/api/v2/cards/fund',
    CURLOPT_POST       => true,
    CURLOPT_POSTFIELDS => json_encode([
        'card_id' => 'card_xyz789',
        'amount'  => 50,
    ]),
]);
r = requests.post(
    'https://paysenp.com/api/v2/cards/fund',
    json={'card_id': 'card_xyz789', 'amount': 50},
    headers=headers
)
await axios.post('https://paysenp.com/api/v2/cards/fund',
    { card_id: 'card_xyz789', amount: 50 },
    { headers });
POST /cards/withdraw
Retirer des fonds d'une carte. Le montant retiré est crédité sur votre solde PAYSENP Business.
ParamĂštreTypeRequisDescription
card_idstringRequisID de la carte
amountnumberRequisMontant en USD Ă  retirer (min: 1)
curl -X POST https://paysenp.com/api/v2/cards/withdraw \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: VOTRE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"card_id": "card_xyz789", "amount": 50}'
curl_setopt_array($ch, [
    CURLOPT_URL        => 'https://paysenp.com/api/v2/cards/withdraw',
    CURLOPT_POST       => true,
    CURLOPT_POSTFIELDS => json_encode([
        'card_id' => 'card_xyz789',
        'amount'  => 50,
    ]),
]);
r = requests.post(
    'https://paysenp.com/api/v2/cards/withdraw',
    json={'card_id': 'card_xyz789', 'amount':50},
    headers=headers
)
await axios.post('https://paysenp.com/api/v2/cards/withdraw',
    { card_id: 'card_xyz789', amount: 50 },
    { headers });

Réponse

{
  "status": true,
  "message": "Card withdrawal successful.",
  "data": { "amount": 50 }
}

Erreurs possibles

CodeDescription
404Carte introuvable
402Solde insuffisant
422Retrait refusé
409Carte non disponible (statut incompatible)
504Résultat inconnu : ne réessayez pas, contactez le support
ÉvĂ©nement webhook envoyĂ©: card.withdrawn (card_id, amount).
POST/cards/freeze
Geler une carte (bloque tous les paiements)
curl -X POST https://paysenp.com/api/v2/cards/freeze \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: VOTRE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"card_id": "card_xyz789"}'
json_encode(['card_id' => 'card_xyz789']); // POST /cards/freeze
requests.post('https://paysenp.com/api/v2/cards/freeze', json={'card_id':'card_xyz789'}, headers=headers)
await axios.post('https://paysenp.com/api/v2/cards/freeze', {card_id:'card_xyz789'}, {headers})
POST/cards/unfreeze
Dégeler une carte
curl -X POST https://paysenp.com/api/v2/cards/unfreeze \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: VOTRE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"card_id": "card_xyz789"}'
json_encode(['card_id' => 'card_xyz789']); // POST /cards/unfreeze
requests.post('https://paysenp.com/api/v2/cards/unfreeze', json={'card_id':'card_xyz789'}, headers=headers)
await axios.post('https://paysenp.com/api/v2/cards/unfreeze', {card_id:'card_xyz789'}, {headers})
POST/cards/delete
Temporairement indisponible : cet endpoint répond 503. Retirez le solde de la carte (/cards/withdraw) et contactez le support pour la fermeture.
Supprimer définitivement une carte. Action irréversible.
curl -X POST https://paysenp.com/api/v2/cards/delete \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: VOTRE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"card_id": "card_xyz789"}'
json_encode(['card_id' => 'card_xyz789']); // POST /cards/delete
requests.post('https://paysenp.com/api/v2/cards/delete', json={'card_id':'card_xyz789'}, headers=headers)
await axios.post('https://paysenp.com/api/v2/cards/delete', {card_id:'card_xyz789'}, {headers})
GET/cards
Liste toutes vos cartes
curl https://paysenp.com/api/v2/cards \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: VOTRE_SECRET"
$cards = json_decode(curl_exec($ch), true)['data']; // GET /cards
cards = requests.get('https://paysenp.com/api/v2/cards', headers=headers).json()['data']
const cards = (await axios.get('https://paysenp.com/api/v2/cards', {headers})).data.data;

🔔 Webhooks

Enregistrez votre URL dans le portail Business, page API Keys. Elle doit commencer par https:// (191 caractÚres maximum, adresses privées refusées). PaySenp envoie un POST JSON pour chaque événement.

Format

{
  "event": "card.created",
  "data": { "card_id": "..." },
  "timestamp": 1761400000
}

Vérifier la signature

Chaque requĂȘte contient les en-tĂȘtes X-Paysenp-Signature (HMAC-SHA256 du corps brut, avec votre API Secret comme clĂ©, en hexadĂ©cimal) et X-Paysenp-Event. Calculez la signature sur le corps brut reçu, avant tout dĂ©codage JSON, et comparez avec une fonction Ă  temps constant. Rejetez la requĂȘte si elle ne correspond pas.
<?php
$raw  = file_get_contents('php://input');
$sig  = $_SERVER['HTTP_X_PAYSENP_SIGNATURE'] ?? '';
$calc = hash_hmac('sha256', $raw, $apiSecret);
if (!hash_equals($calc, $sig)) { http_response_code(401); exit; }
RĂ©pondez avec un code 2xx rapidement. Un mĂȘme Ă©vĂ©nement peut ĂȘtre livrĂ© plus d'une fois : utilisez l'identifiant de la carte ou la rĂ©fĂ©rence pour ignorer les doublons.

ÉvĂ©nements

ÉvĂ©nementSignification
customer.approvedIdentité validée, contient customer_id
customer.rejectedIdentité refusée, contient la raison
card.createdCarte active, contient le card_id définitif
card.failedCréation échouée, contient la raison
card.fundedRechargement effectué
card.withdrawnRetrait effectué
card.transaction.approvedAchat accepté
card.transaction.declinedAchat refusé
card.transaction.reversedTransaction annulée
card.terminatedCarte fermée

⚠ Codes d'erreur et statuts

CodeSignification
401Clés API manquantes ou invalides
402Solde insuffisant
404Ressource introuvable
409Conflit : doublon ou statut incompatible
422Données invalides ou refus du fournisseur
503Fonction temporairement indisponible
504Résultat inconnu : ne réessayez pas, contactez le support
Statuts d'une carte : PENDING (en création), ACTIVE, FROZEN, FAILED, TERMINATED.
Il n'existe pas d'environnement de test : vos clés sont des clés de production, chaque appel est réel.

🏩 Compte

GET/account
Voir votre solde et informations du compte
curl https://paysenp.com/api/v2/account \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: VOTRE_SECRET"
$account = json_decode(curl_exec($ch), true)['data'];
account = requests.get('https://paysenp.com/api/v2/account', headers=headers).json()['data']
const account = (await axios.get('https://paysenp.com/api/v2/account', {headers})).data.data;
// Réponse
{
  "status": true,
  "data": {
    "business_name":    "Mon Business",
    "balance":          100.00,
    "status":           "active"
  }
}

🔔 Webhooks

Configurez votre URL dans API Keys. PAYSENP vous envoie tous les événements en temps réel: achats, déclins, OTP, etc.

ÉvĂ©nementDescription
transaction.approvedAchat approuvé sur la carte
transaction.declinedAchat décliné (fonds insuffisants, carte gelée...)
issuing.otpOTP pour paiement 3D Secure
card.createdCarte créée
card.fundedCarte rechargée
card.frozenCarte gelée
card.unfrozenCarte dégelée
card.deletedCarte supprimée

Payload reçu

{
  "event":     "transaction.declined",
  "card_id":   "card_xyz789",
  "amount":    25.00,
  "currency":  "USD",
  "status":    "DECLINED",
  "merchant":  "Amazon.com",
  "reference": "txn_ref_abc",
  "timestamp": "2026-06-29T10:30:00Z"
}

Vérifier la signature

<?php
$sig     = $_SERVER['HTTP_X_PAYSENP_SIGNATURE'];
$payload = file_get_contents('php://input');
$secret  = 'votre_webhook_secret';

if (!hash_equals(hash_hmac('sha256', $payload, $secret), $sig)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($payload, true);
switch($event['event']) {
    case 'transaction.approved':
        // Notifier votre client
        break;
    case 'transaction.declined':
        // Alerter votre client
        break;
    case 'issuing.otp':
        // Envoyer OTP Ă  votre client
        break;
}
import hmac, hashlib
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhook/paysenp', methods=['POST'])
def webhook():
    sig     = request.headers.get('X-PAYSENP-Signature')
    payload = request.get_data()
    secret  = b'votre_webhook_secret'

    expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig):
        return 'Invalid', 401

    event = request.json
    if event['event'] == 'transaction.declined':
        # Alerter client
        pass
    return 'OK'
// Express.js
const crypto = require('crypto');

app.post('/webhook/paysenp', express.raw({type:'application/json'}), (req, res) => {
    const sig    = req.headers['x-paysenp-signature'];
    const secret = 'votre_webhook_secret';
    const hash   = crypto.createHmac('sha256', secret)
                         .update(req.body).digest('hex');

    if (hash !== sig) return res.status(401).send('Invalid');

    const event = JSON.parse(req.body);
    switch(event.event) {
        case 'transaction.approved': /* notifier client */ break;
        case 'transaction.declined': /* alerter client  */ break;
        case 'issuing.otp':          /* envoyer OTP     */ break;
    }
    res.send('OK');
});

❌ Codes d'erreur

CodeErreurSolution
401UnauthorizedVérifiez X-API-Key et X-API-Secret
402Insufficient balanceRechargez votre solde PAYSENP Business
403Account suspendedContactez support@paysenp.com
404Not foundVérifiez le card_id ou customer_id
422Validation errorVérifiez les paramÚtres requis
429Rate limitMax 100 requĂȘtes/minute
500Server errorRéessayez ou contactez le support

📞 Support

📧 Email: support@paysenp.com
🕐 DisponibilitĂ©: 24h/7j