API QuickPay Connect

QuickPay Connect permet de créer des liens de paiement réutilisables que vous pouvez partager avec vos clients par email, SMS, WhatsApp ou QR code. AWDPay gère l'UX, la conformité et le routage ; vous ne fournissez que les métadonnées de commande et les URLs de redirection.

Quand utiliser QuickPay Connect

✅ Vous voulez accepter des paiements sans construire de composants UI
✅ Vous avez besoin d'un lien unique à partager par email, SMS, ou QR code
✅ Vous souhaitez qu'AWDPay gère la saisie OTP, les messages d'erreur et les flux localisés pour MTN, Orange, Wave, Moov, etc.
✅ Paiement de factures, abonnements, ventes de billets

Flux Résumé

Créer un lien via POST /api/v2/payments/link avec montant, devise, description et callbacks
Partager l'URL de paiement avec vos clients (email, SMS, WhatsApp, QR)
Recevoir webhook quand le paiement réussit, échoue ou expire
Interroger le statut ou lister l'historique si nécessaire

Endpoints

Méthode	Endpoint	Description
`POST`	`/api/v2/payments/link`	Créer un lien de paiement

URLs de Base :

Sandbox : https://api.awdpay.com/test/api/v2/payments/link
Production : https://api.awdpay.com/api/v2/payments/link

Créer un Lien de Paiement

Endpoint

POST /api/v2/payments/link

Requête Minimale

curl -X POST "https://api.awdpay.com/test/api/v2/payments/link" \
  -H "Authorization: Bearer $AWDPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000.0,
    "currency": "XOF",
    "description": "Abonnement Premium - 1 mois"
  }'

Requête Complète

curl -X POST "https://api.awdpay.com/test/api/v2/payments/link" \
  -H "Authorization: Bearer $AWDPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000.0,
    "currency": "XOF",
    "description": "Abonnement Premium - 1 mois",
    "customerName": "Jean Dupont",
    "customerEmail": "jean.dupont@example.com",
    "customerPhone": "+221701234567",
    "callbackUrl": "https://votresite.com/webhooks/payment",
    "returnUrl": "https://votresite.com/confirmation",
    "metadata": {
      "plan": "premium",
      "duration": "1_month",
      "customer_id": "CUST_12345"
    }
  }'

Paramètres

Paramètre	Type	Requis	Description
`amount`	number	Oui	Montant à payer (min : 100, max : 10,000,000)
`currency`	string	Oui	Code devise ISO 4217 (XOF, XAF, GNF, EUR, USD)
`description`	string	Oui	Description du paiement (max 500 caractères)
`customerName`	string	Non	Nom du client
`customerEmail`	string	Non	Email du client (pour notifications)
`customerPhone`	string	Non	Téléphone du client
`callbackUrl`	string	Non	URL pour recevoir les notifications webhook
`returnUrl`	string	Non	URL de redirection après paiement
`metadata`	object	Non	Métadonnées personnalisées (clé-valeur)

Réponse (200 OK)

{
  "reference": "LINK_TEST_1732115400000_B3C4D5E6",
  "paymentUrl": "https://sandbox.awdpay.com/p/LINK_TEST_1732115400000_B3C4D5E6",
  "status": "pending",
  "createdAt": "2025-11-20T16:50:00",
  "expiresAt": "2025-11-27T16:50:00",
  "message": "Lien de paiement de test créé avec succès. Ceci est un environnement sandbox."
}

Partage de l'URL

Une fois créé, partagez le lien avec vos clients :

Par Email :

Bonjour Jean,

Cliquez sur le lien pour effectuer votre paiement :
https://sandbox.awdpay.com/p/LINK_TEST_1732115400000_B3C4D5E6

Montant : 25,000 XOF
Description : Abonnement Premium - 1 mois
Expire le : 27/11/2025

Par SMS :

Votre lien de paiement AWDPay (25,000 XOF) :
https://sandbox.awdpay.com/p/LINK_TEST_1732115400000_B3C4D5E6
Expire le 27/11/2025

Par QR Code : Générez un QR code contenant l'URL pour faciliter le paiement en magasin.

Statuts des Liens

Statut	Description
`pending`	Lien créé, en attente de paiement
`completed`	Paiement effectué avec succès
`expired`	Lien expiré sans paiement
`failed`	Tentative de paiement échouée

Webhooks

Configurez callbackUrl pour recevoir des notifications en temps réel.

Événements

Event	Description
`payment_link.completed`	Paiement réussi
`payment_link.failed`	Paiement échoué
`payment_link.expired`	Lien expiré

Charge Utile Webhook

{
  "event": "payment_link.completed",
  "reference": "LINK_TEST_1732115400000_B3C4D5E6",
  "status": "completed",
  "amount": 25000.0,
  "currency": "XOF",
  "fees": 350.0,
  "gatewayName": "MTN",
  "customerEmail": "client@example.com",
  "completedAt": "2025-11-20T15:50:00",
  "metadata": {
    "plan": "premium",
    "customer_id": "CUST_12345"
  }
}

Sécurité

Validez toujours le statut côté serveur via GET /api/v2/payments/link/{reference} plutôt que de vous fier uniquement aux webhooks.

Cas d'Usage

1. E-commerce : Paiement de Commande

curl -X POST "https://api.awdpay.com/test/api/v2/payments/link" \
  -H "Authorization: Bearer $AWDPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 45000.0,
    "currency": "XOF",
    "description": "Commande #CMD12345 - 3 articles",
    "customerName": "Marie Diallo",
    "customerEmail": "marie.diallo@example.com",
    "returnUrl": "https://monsite.com/commande/confirmation",
    "metadata": {
      "order_id": "CMD12345",
      "items_count": "3"
    }
  }'

2. Facture Mensuelle

curl -X POST "https://api.awdpay.com/test/api/v2/payments/link" \
  -H "Authorization: Bearer $AWDPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000.0,
    "currency": "XOF",
    "description": "Facture Internet - Novembre 2025",
    "customerName": "Ibrahima Sow",
    "customerEmail": "i.sow@example.com",
    "metadata": {
      "invoice_id": "INV-2025-11-001",
      "service": "internet_fiber"
    }
  }'

3. Vente de Billets

curl -X POST "https://api.awdpay.com/test/api/v2/payments/link" \
  -H "Authorization: Bearer $AWDPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000.0,
    "currency": "XOF",
    "description": "Concert Jazz Festival 2025 - 2 billets",
    "customerEmail": "fan@example.com",
    "metadata": {
      "event_id": "EVT2025",
      "ticket_type": "VIP",
      "quantity": "2"
    }
  }'

Bonnes Pratiques

1. Utilisation des Métadonnées

Stockez des informations contextuelles pour la réconciliation :

{
  "metadata": {
    "customer_id": "CUST123",
    "order_id": "CMD456",
    "source": "mobile_app",
    "campaign": "black_friday_2025"
  }
}

2. Vérification du Statut

Vérifiez toujours le statut côté serveur après redirection :

curl -X GET "https://api.awdpay.com/test/api/v2/payments/link/LINK_REF" \
  -H "Authorization: Bearer $AWDPAY_TOKEN"

3. Tests en Sandbox

Toutes les transactions sont simulées (aucun argent réel)
Références préfixées par LINK_TEST_
URLs sur le domaine sandbox.awdpay.com

Prochaines Étapes

Tester en Sandbox → Créez vos premiers liens de paiement
Intégrer les Webhooks → Recevez les notifications en temps réel
Personnaliser l'Expérience → Utilisez metadata et returnUrl
Passer en Production → Remplacez /test par les endpoints de production

Besoin d'Aide ?

Contactez support@awdpay.com

Quand utiliser QuickPay Connect​

Flux Résumé​

Endpoints​

Créer un Lien de Paiement​

Endpoint​

Requête Minimale​

Requête Complète​

Paramètres​

Réponse (200 OK)​

Partage de l'URL​

Statuts des Liens​

Webhooks​

Événements​

Charge Utile Webhook​

Cas d'Usage​

1. E-commerce : Paiement de Commande​

2. Facture Mensuelle​

3. Vente de Billets​

Bonnes Pratiques​

1. Utilisation des Métadonnées​

2. Vérification du Statut​

3. Tests en Sandbox​

Prochaines Étapes​