Intégration API Nourapay

Vue d'ensemble

Cette section présente le guide complet d'intégration de l'API NOURAPAY, couvrant l'ensemble du processus de mise en œuvre de la solution de paiement. Elle constitue le point d'entrée technique pour les développeurs souhaitant intégrer nos services de paiement dans leurs applications.

Fonctionnalités couvertes

Notre API d'intégration offre deux solutions complètes de traitement des transactions :

Solution de Paiement Standard (OTP Marchand)

  • Authentification sécurisée avec clés API dédiées
  • Création d'ordres avec génération d'URL de paiement personnalisées
  • Session de paiement avec support multi-opérateurs (Orange Money, Moov Money)
  • Validation OTP avec codes USSD automatisés
  • Confirmation transactionnelle avec traçabilité complète

Solution BulkPay (Retraits Groupés)

  • Demandes de retrait pour les marchands avec multiple méthodes (VISA, cartes bancaires)
  • Validation administrative avec workflow d'approbation
  • Gestion multi-devises (FCFA, USD, EUR)
  • Notifications configurables (SMS, EMAIL, EMAIL_AND_SMS)

Workflow d'intégration

Processus de Paiement Standard (4 étapes)

  1. Création d'ordre (POST /api/v1/order) :

    • Génération d'URL de paiement sécurisée
    • Configuration des paramètres transactionnels
    • Définition des URLs de redirection

  2. Préparation de session (POST /api/v1/payment/prepare) :

    • Initialisation avec informations client
    • Génération des codes USSD et timeouts OTP
    • Configuration de la méthode de paiement

  3. Exécution de paiement (POST /api/v1/payment/execute) :

    • Validation OTP en temps réel
    • Traitement sécurisé de la transaction
    • Génération d'identifiant de transaction

  4. Confirmation finale (POST /api/v1/order/confirm) :

    • Validation définitive du paiement
    • Mise à jour du statut transactionnel
    • Finalisation du processus

Processus BulkPay (2 étapes)

  1. Demande de retrait (POST /api/v1/bulk-transaction-request) :

    • Soumission des informations de retrait
    • Validation des données bancaires
    • Génération de slug de suivi

  2. Validation administrative (PUT /api/v1/admin/bulk-transaction-request) :

    • Approbation par l'administrateur
    • Exécution du transfert
    • Confirmation du retrait

Prérequis d'intégration

Pour utiliser nos APIs, vous devez disposer :

  • Compte marchand NOURAPAY validé et actif
  • Identifiant marchand unique attribué
  • Clé API (x-api-key) pour l'authentification
  • Référence plateforme pour l'identification

Cette architecture modulaire garantit la flexibilité d'intégration tout en maintenant les plus hauts standards de sécurité et de conformité réglementaire.

Étape 1 : Obtenir l’URL de paiement de la commande NOURAPAY.

  • Méthode : POST
  • URL : https://api.ingenovatech.com/ingenovapay-um/api/v1/order
  • Description : Cela permet aux commerçants Nouapay d’envoyer leurs commandes et d’obtenir une URL de paiement d’NOURAPAY à transmettre à leurs clients.

En-têtes (HEADERS)

| Clé | Valeur | |---------------|------------------------------------------------------------------------| | Content-Type | application/json | | x-api-key | « Token (clé API) fourni par NOURAPAY à ses commerçants » |

Pour ce test,peut utiliser ce token (x-api-key) : FVVJeQcJZx1ykn4yIMnAPvNCDcYjzPjk8wtPFi0slxQ

POST BODY

| Nom | Type | Obligatoire | Description | |-----------------|---------|-------------|----------------------------------------------------------------------------------------------| | Amount | Double | Oui | Montant total de la commande | | Currency | Enum | Oui | Devise dans laquelle tu veux payer. Doit être : FCFA, USD, EUR | | NotifyBy | Enum | Oui | Méthode de notification souhaitée par le client. Doit être : SMS, EMAIL, EMAIL_AND_SMS | | OrderPlatformId | String | Oui | ID du commerçant |

Note
Les valeurs possibles pour Currency sont : FCFA, USD, EUR
Pour NotifyBy : SMS, EMAIL, EMAIL_AND_SMS

Pour ce test, on peut utiliser cette reference : ING406222.

La clé x-api-key et reference sont utilisés pour vérifier l’autorisation du commerçant à se connecter à l’API NOURAPAY, comme indiqué dans l’introduction.

Exemple de Requête

{
    "amount": 100, 
    "currency": "CFA", 
    "langKey": "fr", 
    "notifyBy": "SMS", 
    "metaData": "86d20598-1277-442d-a7f2-4e67c835740f", 
    "reference": "ING406222", 
    "successURL": "https://site86d205-1277-442d-a7f2-4e67c835740f-ingenovatech.com", 
    "failureURL": "https://site86d20598-1277-442d-a7f2-4e67c835740f-ingenovatech.com"
}

Réponse

{
    "message": "OK",
    "body": {
        "paymentId": "Emk5Ps0LzBX22_TjD7FjaCUHbwb9tG8tYdwq3s_mxHE",
        "url": "https://pay.nourama.com/checkout/Emk5Ps0LzBX22_TjD7FjaCUHbwb9tG8tYdwq3s_mxHE"
    }
}

Ici, paymentId est : Emk5Ps0LzBX22_TjD7FjaCUHbwb9tG8tYdwq3s_mxHE

Étape 2 : Session de paiement, récupérer les informations du client pour le paiement.

  • Méthode : POST

  • URL : https://api.ingenovatech.com/ingenovapay-co/api/v1/payment/prepare

  • Description : Cela permet à NOURAPAY d'obtenir les informations du client pour le paiement.

Vous devez placer paymentId dans le champ customerOrderSlug.

Tous les attributs sont requis pour cette requête.

Exemple de requête :

{
    "amount": 100, 
    "orderSlug": "Emk5Ps0LzBX22_TjD7FjaCUHbwb9tG8tYdwq3s_mxHE", 
    "paymentMethod": "ORANGE_MONEY", 
    "phoneNumber": {
        "indicator": "226", 
        "telephone": "74841922"    
        },
        "paymentInformation": {
            "firstname": "Louverture", 
            "lastname": "tousaint", 
            "email": "JfccJwvb@ingenovatech.com", 
            "address": "AepdYIKLJfccJwvb", 
            "metaData": "JfccJwvbAepdYIKL"
        }
 
}

Réponse

  {
    "message": "OK",
    "body": {
        "otpTimeout": 500,
        "otpManualGenerationRequired": true,
        "otpManualUSSDCode": "*144*4*6*100.0#",
        "sessionId": "1750097478609",
        "sessionTimeout": 600
    }
}

Étape 3 : Session de paiment, Excecution du paiment

Vous devez placer paymentId dans le champ orderSlug,

Executer le contenue du champ otpManualUSSDCode, ce qui va generer un identifiant

placer l’identifiant généré lors de la génération de l’OTP dans le champ otp de cette requête.

Exemple de requête :

{
    "orderSlug": "Emk5Ps0LzBX22_TjD7FjaCUHbwb9tG8tYdwq3s_mxHE", 
    "otp": "NKADEPOK"
}

Réponse

  {
    "message": "SUCCESS",
    "body": {
        "transactionId": "1750097993461",
        "successRedirectURL": "https://site86d205-1277-442d-a7f2-4e67c835740f-ingenovatech.com?payment_id=Emk5Ps0LzBX22_TjD7FjaCUHbwb9tG8tYdwq3s_mxHE&transaction_id=1750097993461",
        "failureRedirectURL": null,
        "status": "SUCCESS",
        "remainingRetries": 1
    }
}

Étape 4 : Confimation de la commande

Ce service permet au client d’un commerçant NOURAPAY de valider un paiment.

  • Méthode : POST
  • URL : https://api.ingenovatech.com/ingenovapay-um/api/v1/order/confirm
  • Description : Ce service permet au client de valider le paiement.

| Clé | Valeur | |---------------|------------------------------------------------------------------------| | Content-Type | application/json | | x-api-key | « Token (clé API) fourni par NOURAPAY à ses commerçants » |

Pour ce test,peut utiliser ce token (x-api-key) : FVVJeQcJZx1ykn4yIMnAPvNCDcYjzPjk8wtPFi0slxQ

Vous devez placer l'identifiant du paiement (paymentId) dans le champ paymentId, retourné lors de l'obtention de l'URL de paiement de la commande ;

insérer l'identifiant de la transaction (transactionId) dans le champ transactionId, retourné lors de l'exécution du paiement ;

et renseigner la référence de la plateforme (platformReference), fournie au tout début, dans le champ platformReference de cette requête.

Exemple de requête :

{
    "paymentId": "YowdJW2PSi8DN8koCTV3AReDyth7nkYusTDqbwwxeVg", 
    "transactionId": "1749483091083",
    "platformReference": "ING406222" 
}

Réponse

  {
    "message": "OK",
    "body": {}
}

II - DOCUMENTATION D’INTEGRATION DE BulkPay

Introduction

Cette documentation est un guide pour l’intégration à l'API BULKPAY de NOURAPAY.

Vous devez disposer d'un compte marchand valide chez NOURAPAY.

Une fois celui-ci créé, vous devez récupérer les informations suivantes :

  • l'identifiant marchand, qui est votre identifiant unique chez NOURAPAY
  • La clé API qui vous permettra de vous connecter.

La création d'un compte NOURAPAY vous permet de récupérer vos clés API afin d'intégrer la solution de paiement.

Étape 1: Service de demande de retrait

Ce service permet aux commerçants NOURAPAY d'initier une demande de retrait des paiements reçus à partir de NOURAPAY.

  • Method: POST
  • URL:https://api.ingenovatech.com/ingenovapay-um/api/v1/bulk-transaction-request
  • Description: Il permet aux marchands d’initier une demande de retrait.

CORPS DU POSTE

| Champ | Type | Requis | Description | |---------------|---------|--------|-----------------------------------------------------------------------------| | firstname | String | Oui | Nom du marchand | | lastname | String | Oui | Prénom du marchand | | email | String | Oui | Email du marchand | | phoneNumber | String | Oui | Numéro de téléphone du marchand | | paymentMethod | String | Oui | Méthode de paiement à choisir | | ref | Long | Non | Référence de la carte bancaire | | exp_month | Integer | Non | Mois d’expiration | | exp_year | Integer | Non | Année d’expiration | | cvc | Integer | Non | Numéro CVC | | Amount | Double | Oui | Montant à retirer | | currency | String | Oui | Devise | | reference | String | Oui | Identifiant de la plateforme | | notifyBy | Enum | Oui | Méthode de notification : SMS, EMAIL, EMAIL_AND_SMS | | metaData | String | Non | Champ supplémentaire |

Exemple de requête :

{
    {
  "firstname": "test 009", 
  "lastname": "test 009", 
  "email": "adamadzenco@gmail.com", 
  "phoneNumber": {
    "indicator": "+226",
    "telephone": "74732249"
  }, *
  "paymentMethod": "VISA", 
  "ref": 12345589289200,
  "exp_month": 10,
  "exp_year": 2025,
  "cvc": 156,
  "Amount":300, 
  "currency": "CFA", 
 
  "metaData": "string",
  "reference": "ING461114",
  "notifyBy": "EMAIL_AND_SMS" 
}
}

Réponse

 {
    "message": "Saved Successfully!",
    "body": {
        "transactionId": "1750174945870",
        "slug": "8og0pvLK-2cqfQILXHpzApxSAdbLEc-uNP2vs-9Z0Sc",
        "amount": 300.0,
        "currency": "CFA",
        "status": "WAITING_MERCHANT_CONFIRMATION",
        "paymentMethod": "VISA",
        "metaData": null,
        "reference": null,
        "platformDTO": {
            "slug": "sYkV5vSJIJ4ZBg8TmEkjK-tO5klzblY1hCni1efaJLI",
            "name": "test",
            "image": null,
            "reference": "ING461114",
            "url": "sdfttr",
            "description": null,
            "status": "ACTIVATED",
            "metaData": "string"
        },
        "bulkRecipientDTO": {
            "slug": "j0WpZp_HL9Goy-PuC85PCxYv1Wc6vCVemfTBADlOWyY",
            "firstname": "test 009",
            "lastname": "test 009",
            "email": "adamadzenco@gmail.com",
            "phoneNumber": {
                "indicator": "+226",
                "telephone": "74732249"
            },
            "reference": 12345589289200,
            "provider": "VISA",
            "exp_month": 10,
            "exp_year": 2025,
            "cvc": 156,
            "metaData": "string",
            "notifyBy": "EMAIL_AND_SMS"
        }
    }
}

NB: "slug": "8og0pvLK-2cqfQILXHpzApxSAdbLEc-uNP2vs-9Z0Sc",

sera utilisé dans la requête de validation de demande de retrait.

Etape 2 : Service de validation de demande de retrait

Ce service permet à un admin de valider la demande de retrait.

  • Method: PUT
  • URL: https://api.ingenovatech.com/ingenovapay-adm/api/v1/admin/bulk-transaction-request
  • Description: Il permet à NOURAPAY d'obtenir les informations du client pour le paiement.

Exemple de requête :

{
    
  "slug": "8og0pvLK-2cqfQILXHpzApxSAdbLEc-uNP2vs-9Z0Sc", *
  "metaData": "string"
}

Le “slug” représente le slug de la demande de retrait initiée.

Réponse

{
    "message": "Edited Successfully!",
    "body": {
        "transactionId": "1750174945870",
        "slug": "8og0pvLK-2cqfQILXHpzApxSAdbLEc-uNP2vs-9Z0Sc",
        "amount": 300.0,
        "currency": "CFA",
        "status": "SUCCESS",
        "paymentMethod": "VISA",
        "metaData": null,
        "reference": null,
        "platformDTO": {
            "slug": "sYkV5vSJIJ4ZBg8TmEkjK-tO5klzblY1hCni1efaJLI",
            "name": "test",
            "image": null,
            "reference": "ING461114",
            "url": "sdfttr",
            "description": null,
            "status": "ACTIVATED",
            "metaData": "string"
        },
       
        "bulkRecipientDTO": {
        "slug": "j0WpZp_HL9Goy-PuC85PCxYv1Wc6vCVemfTBADlOWyY",
        "firstname": "test 009",
        "lastname": "test 009",
        "email": "adamadzenco@gmail.com",
        "phoneNumber": {
            "indicator": "+226",
            "telephone": "74732249"
        },
        "reference": 12345589289200,
        "provider": "VISA",
        "exp_month": 10,
        "exp_year": 2025,
        "cvc": 156,
        "metaData": "string",
        "notifyBy": "EMAIL_AND_SMS"
        }
    }
}

Codes d'erreur

| Code | Message | Description | |------|---------------------------|------------------------------------------------| | 400 | Bad Request | Paramètres de requête invalides | | 401 | Unauthorized | Token d'authentification manquant ou invalide | | 403 | Forbidden | Accès refusé à cette ressource | | 404 | Not Found | Transaction ou plateforme introuvable | | 429 | Too Many Requests | Limite de débit atteinte | | 500 | Internal Server Error | Erreur interne du serveur |

Notes importantes

  • Toutes les dates sont au format ISO 8601 (UTC)
  • Les montants sont toujours des nombres décimaux avec 2 chiffres après la virgule
  • La pagination commence à 0 pour le premier élément
  • Les devises supportées sont : FCFA, USD, EUR
  • Les taux de change sont mis à jour quotidiennement
Suivant
Introduction