đ 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:
Headers requis sur chaque requĂȘte:
https://paysenp.com/api/v2Headers requis sur chaque requĂȘte:
X-API-Key: votre_api_keyX-API-Secret: votre_api_secretContent-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
Recto ID
Verso ID
Visage clair
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_frontRecto ID
đȘȘ
id_backVerso ID
đ€ł
selfieVisage clair
â
Photo nette, bonne luminosité, toutes infos visibles
â Pas floue, pas de reflet, pas de lunettes de soleil sur le selfie
â Pas floue, pas de reflet, pas de lunettes de soleil sur le selfie
| ParamĂštre | Type | Requis | Description |
|---|---|---|---|
first_name | string | Requis | Prénom |
last_name | string | Requis | Nom de famille |
email | string | Requis | Email unique du customer |
phone | string | Requis | Téléphone avec indicatif ex: +50934000000 |
date_of_birth | string | Requis | Format: YYYY-MM-DD ex: 1990-05-15 |
id_type | string | Requis | PASSPORT / NIN / DRIVERS_LICENSE / VOTERS_CARD |
id_number | string | Requis | Numéro du document d'identité |
id_front | string | Requis | Photo recto ID en base64 |
id_back | string | Optionnel | Photo verso ID en base64 |
selfie | string | Requis | Selfie du visage en base64 |
address | string | Requis | Adresse complĂšte |
city | string | Requis | Ville |
state | string | Requis | Ătat / DĂ©partement |
postal_code | string | Requis | Code postal |
country | string | Optionnel | Code 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
Photos :
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Útre | Type | Requis | Description |
|---|---|---|---|
customer_id | string | Requis | ID 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Ăštre | Type | Requis | Description |
|---|---|---|---|
card_id | string | Requis | ID de la carte Ă recharger |
amount | number | Requis | Montant 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Ăštre | Type | Requis | Description |
|---|---|---|---|
card_id | string | Requis | ID de la carte |
amount | number | Requis | Montant 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
| Code | Description |
|---|---|
404 | Carte introuvable |
402 | Solde insuffisant |
422 | Retrait refusé |
409 | Carte non disponible (statut incompatible) |
504 | Ré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Ă©nement | Signification |
|---|---|
customer.approved | Identité validée, contient customer_id |
customer.rejected | Identité refusée, contient la raison |
card.created | Carte active, contient le card_id définitif |
card.failed | Création échouée, contient la raison |
card.funded | Rechargement effectué |
card.withdrawn | Retrait effectué |
card.transaction.approved | Achat accepté |
card.transaction.declined | Achat refusé |
card.transaction.reversed | Transaction annulée |
card.terminated | Carte fermée |
â ïž Codes d'erreur et statuts
| Code | Signification |
|---|---|
401 | Clés API manquantes ou invalides |
402 | Solde insuffisant |
404 | Ressource introuvable |
409 | Conflit : doublon ou statut incompatible |
422 | Données invalides ou refus du fournisseur |
503 | Fonction temporairement indisponible |
504 | Résultat inconnu : ne réessayez pas, contactez le support |
Statuts d'une carte :
Il n'existe pas d'environnement de test : vos clés sont des clés de production, chaque appel est réel.
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Ă©nement | Description |
|---|---|
transaction.approved | Achat approuvé sur la carte |
transaction.declined | Achat décliné (fonds insuffisants, carte gelée...) |
issuing.otp | OTP pour paiement 3D Secure |
card.created | Carte créée |
card.funded | Carte rechargée |
card.frozen | Carte gelée |
card.unfrozen | Carte dégelée |
card.deleted | Carte 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
| Code | Erreur | Solution |
|---|---|---|
| 401 | Unauthorized | Vérifiez X-API-Key et X-API-Secret |
| 402 | Insufficient balance | Rechargez votre solde PAYSENP Business |
| 403 | Account suspended | Contactez support@paysenp.com |
| 404 | Not found | Vérifiez le card_id ou customer_id |
| 422 | Validation error | Vérifiez les paramÚtres requis |
| 429 | Rate limit | Max 100 requĂȘtes/minute |
| 500 | Server error | Réessayez ou contactez le support |
đ Support
đ§ Email: support@paysenp.com
đ DisponibilitĂ©: 24h/7j