API Documentation

Getting Started

Avant de commencer, créez un compte marchand et récupérez vos clés API.

POST /v2/merchants/register Inscription — aucune authentification requise

Headers

Header	Value
Content-Type	application/json

Request Body

Paramètre	Type	Description
business_nameoptional	string	Nom légal de l'entreprise (ex: "KSN Holding SARL") — peut être complété dans le dashboard
emailrequired	string	Email de contact (uniquement)
passwordrequired	string	Mot de passe (min. 8 caractères)
riboptional	string	RIB/BAN algérien (20 chiffres, pour les virements DZD) — peut être renseigné lors du KYC
callback_urloptional	string	URL de webhook (optionnel, peut être défini plus tard)

Réponse

JSON Response — 201 Created

{
  "merchant_id": "mrc_01J9X2...",
  "business_name": "KSN Holding SARL",
  "email": "contact@ksnholding.com",
  "status": "PENDING_AUDIT",
  "dp_test_key": "dp_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "dp_live_key": null,
  "whsec": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

// Conservez dp_test_key et whsec en lieu sûr.
// dp_live_key est généré après validation KYB.

Authentification : Après inscription, utilisez votre clé API dans chaque requête : Authorization: Bearer dp_test_xxx

Tester : Utilisez votre clé test pour développer en sandbox. Aucun paiement réel n'est traité.

Sandbox

L'environnement sandbox vous permet de tester l'intégration sans frais ni risque.

Clé	Usage	Paiement réel
dp_test_*	Développement, tests, intégration	Non
dp_live_*	Production après validation KYB	Oui

POST /v2/charge/initiate

Créez une session de paiement Stripe pour facturer un client en euros.

POST /v2/charge/initiate Authorization: Bearer dp_test_* | dp_live_*

Request Body

Paramètre	Type	Description
amount_eurrequired	integer	Montant en euros (centimes). Ex: 4999 = 49,99 €. Minimum : 100 (1 €). Maximum : 99999999.
currencyrequired	string	Devise : `"EUR"` uniquement (paiements en euros)
order_idrequired	string	Référence unique de votre commande (max 100 caractères)
customer_emailrequired	string	Email du client pour la page Stripe Checkout
product_namerequired	string	Description courte du produit/service (max 200 caractères)
success_urlrequired	string	URL de redirection après paiement réussi
cancel_urlrequired	string	URL de redirection si le client annule
metadataoptional	object	Données personnalisées (max 20 clés, valeurs en strings)

Exemple cURL

cURL

curl -X POST https://deepypay.polsia.app/v2/charge/initiate \n
  -H "Authorization: Bearer dp_test_xxxxxxxxxxxxxxxx" \n
  -H "Content-Type: application/json" \n
  -d '{
    "amount_eur": 4999,
    "currency": "EUR",
    "order_id": "ORDER-12345",
    "customer_email": "client@example.com",
    "product_name": "Abonnement Pro — 1 mois",
    "success_url": "https://votresite.com/success",
    "cancel_url": "https://votresite.com/cancel"
  }'

Réponse — 201 Created

JSON Response

{
  "transaction_id": "txn_01J9X3...",
  "checkout_url": "https://checkout.stripe.com/pay/cs_xxx",
  "amount_eur": 4999,
  "currency": "EUR",
  "status": "PENDING",
  "expires_at": "2026-05-22T12:00:00Z"
}

// Redirigez le client vers checkout_url pour finaliser le paiement.
// Le statut passe à CAPTURED après paiement Stripe confirmé.

POST /v2/payment-links

Créez un lien de paiement partageable (WhatsApp, email, SMS) avec montant fixe.

POST /v2/payment-links Authorization: Bearer dp_test_* | dp_live_*

Request Body

Paramètre	Type	Description
amount_eur_centsrequired	integer	Montant en centimes d'euros. Ex: 4999 = 49,99 €.
product_namerequired	string	Nom du produit/service (max 200 caractères)
order_idrequired	string	Référence unique de commande (max 100 caractères)
expires_in_daysoptional	integer	Durée de validité en jours (défaut : 30, max : 365)

Exemple cURL

cURL

curl -X POST https://deepypay.polsia.app/v2/payment-links \n
  -H "Authorization: Bearer dp_test_xxxxxxxxxxxxxxxx" \n
  -H "Content-Type: application/json" \n
  -d '{
    "amount_eur_cents": 4999,
    "product_name": "Abonnement Pro — 1 mois",
    "order_id": "ORDER-12345",
    "expires_in_days": 30
  }'

Réponse — 201 Created

JSON Response

{
  "payment_link": "https://deepypay.polsia.app/v2/pay/abcdef123456...",
  "token": "abcdef1234567890abcdef1234567890",
  "amount_eur": 49.99,
  "product_name": "Abonnement Pro — 1 mois",
  "order_id": "ORDER-12345",
  "expires_at": "2026-06-21T23:59:59Z",
  "used": false
}

// Partagez payment_link par WhatsApp, email ou SMS.
// Le client est redirigé vers Stripe Checkout pour payer.

GET /v2/pay/:token

Redirection Stripe pour les liens de paiement. Les clients paient sur Stripe Checkout ; DeepyPay traite le reste.

GET /v2/pay/:token Public — aucune authentification requise

Path Parameters

Paramètre	Description
token	Jeton unique du lien de paiement (32 caractères hex)

Flux : Le client scanne le QR ou clique sur le lien → DeepyPay valide le token → redirige vers Stripe Checkout → après paiement, webhook notifie le marchand.

Comportement

État	Redirection
Token valide + non utilisé	→ `Stripe Checkout Session`
Token déjà utilisé	→ Page "Ce lien a déjà été utilisé" (code 410)
Token expiré	→ Page "Ce lien a expiré" (code 410)
Token invalide	→ Page 404

Webhooks

DeepyPay envoie des notifications HTTP à votre callback_url pour chaque étape du cycle de paiement.

Événements disponibles

CAPTURED Paiement Stripe confirmé. Commission DeepyPay prélevée (4,9%).

SPLIT Commission DeepyPay prélevée. Montant net en euros calculé pour le virement.

PAYOUT_PENDING Virement SofizPay vers votre RIB initialisé.

PAYOUT_SUCCESS Virement DZD reçu sur votre compte. Transaction finalisée.

RETRY_PENDING Échec initial, nouvelle tentative programmée (max 10 tentatives).

PAYOUT_FAILED Échec après 10 tentatives. Transaction en Dead Letter Queue (DLQ).

Payload example

JSON — Webhook Payload

{
  "event": "CAPTURED",
  "transaction_id": "txn_01J9X3...",
  "order_id": "ORDER-12345",
  "merchant_id": "mrc_01J9X2...",
  "amount_eur": 49.99,
  "net_eur": 47.54,
  "payout_amount_dzd": 11885,
  "exchange_rate": 250,
  "customer_email": "client@example.com",
  "timestamp": "2026-05-22T12:00:00Z",
  "metadata": {}
}

Vérification de signature (Node.js)

Node.js — HMAC-SHA256 verification

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expectedSig, 'hex'),
    Buffer.from(signature.replace('sha256=', ''), 'hex')
  );
}

// Usage:
const sig = req.headers['x-deepypay-signature'];
const rawBody = req.rawBody;
const isValid = verifyWebhookSignature(rawBody, sig, process.env.WHSEC);

if (!isValid) {
  return res.status(401).send('Invalid signature');
}

Note : Conservez votre whsec_xxx en sécurité. Elle est affichée une seule fois lors de l'inscription.

POST /v2/payout/trigger

Déclenchez manuellement un virement SofizPay pour une transaction capturée.

POST /v2/payout/trigger Authorization: Bearer dp_live_* requis

Request Body

Paramètre	Type	Description
transaction_idrequired	string	ID de la transaction (doit avoir le statut CAPTURED)

Exemple cURL

cURL

curl -X POST https://deepypay.polsia.app/v2/payout/trigger \n
  -H "Authorization: Bearer dp_live_xxxxxxxxxxxxxxxx" \n
  -H "Content-Type: application/json" \n
  -d '{ "transaction_id": "txn_01J9X3..." }'

Réponse — 200 OK

JSON Response

{
  "status": "PAYOUT_SUCCESS",
  "payout_amount_dzd": 10459,
  "sofizpay_reference": "VIR-XXXXXX"
}

KYC — Vérification d'identité

Avant d'accéder aux paiements en production, chaque marchand doit compléter la vérification KYC. Le parcours suit trois statuts : SANDBOX → PENDING_AUDIT → LIVE (ou REFUSED si refus).

PATCH /v2/merchants/kyc Upload CNI + selfie — Authorization: Bearer dp_test_*

Headers

Header	Value
Content-Type	multipart/form-data
Authorization	Bearer dp_test_xxx

Form Fields (multipart)

Champ	Type	Description
identity_docrequired	file	Carte nationale d'identité (CNI) — image/* ou application/pdf, max 5 Mo
selfierequired	file	Selfie tenant la CNI — image/*, max 5 Mo

Exemple cURL

cURL

curl -X PATCH https://deepypay.polsia.app/v2/merchants/kyc \n
  -H "Authorization: Bearer dp_test_xxxxxxxxxxxxxxxx" \n
  -F "identity_doc=@/chemin/vers/cni.jpg" \n
  -F "selfie=@/chemin/vers/selfie.jpg"

Réponse — 200 OK

JSON Response

{
  "message": "KYC documents uploaded successfully",
  "status": "PENDING_AUDIT"
}

Délai d'examen : L'équipe DeepyPay examine les documents sous 24–48h ouvrées. Vous recevez une notification email à la validation ou au refus.

GET /v2/merchants/kyc/status

Consultez le statut de validation KYC de votre compte marchand.

GET /v2/merchants/kyc/status Authorization: Bearer dp_test_* | dp_live_*

Réponse — 200 OK

JSON Response

{
  "merchant_id": "mrc_01J9X2...",
  "kyc_status": "PENDING_AUDIT",
  "kyc_submitted_at": "2026-05-23T10:00:00Z",
  "kyc_verified_at": null
}

Statuts possibles

Statut	Description
SANDBOX	Compte créé, aucun document soumis. Accès sandbox uniquement.
PENDING_AUDIT	Documents reçus, examen en cours par l'équipe DeepyPay (24–48h).
LIVE	KYC validé. Clé `dp_live_*` active, paiements réels disponibles.
REFUSED	Documents refusés. Contactez support@deepypay.polsia.app pour soumettre à nouveau.

Error Codes

Toutes les erreurs suivent le format standard HTTP avec un corps JSON explicatif.

Error Response Format

{
  "error": "DESCRIPTIVE_ERROR_CODE",
  "message": "Explication lisible pour le développeur.",
  "status": 400
}

Code	Erreur	Description & Solution
400	INVALID_REQUEST	Corps JSON mal formé, champs manquants ou types incorrects.
400	AMOUNT_TOO_LOW	Montant inférieur au minimum (1 €). Augmentez le montant.
401	UNAUTHORIZED	Clé API absente ou invalide. Vérifiez le header `Authorization: Bearer dp_xxx`.
401	KEY_REVOKED	Clé API révoquée. Contactez le support DeepyPay.
403	SANDBOX_ONLY	Tentative d'utiliser une clé test en environnement live. Utilisez `dp_live_*`.
403	MERCHANT_NOT_LIVE	Compte marchand non validé KYB. Complétez la vérification dans le dashboard.
409	DUPLICATE_ORDER	order_id déjà utilisé. Utilisez un order_id unique par transaction.
422	INVALID_RIB	Le RIB marchand est invalide. Mettez à jour votre RIB dans le dashboard.
429	RATE_LIMIT_EXCEEDED	Trop de requêtes. Limite : 10 req/s. Réessayez dans quelques secondes.
500	INTERNAL_ERROR	Erreur interne DeepyPay. Réessayez dans 5 secondes.
503	SERVICE_UNAVAILABLE	Maintenance planifiée. Vérifiez le status ou réessayez.

API Documentation

Getting Started

Sandbox

Environnement de test

POST /v2/charge/initiate

POST /v2/payment-links

GET /v2/pay/:token

Webhooks

POST /v2/payout/trigger

KYC — Vérification d'identité

GET /v2/merchants/kyc/status

Error Codes