Vue d'ensemble

Le Direct Charge permet à votre backend d’initier un paiement directement avec un provider, sans créer d’abord une URL de checkout.

Quand utiliser Direct Charge

Flux pilotes par le backend

Idéal pour une initiation de paiement serveur à serveur, quand vous contrôlez tout le cycle de vie de la transaction.

Champs specifiques au provider

À utiliser quand le paiement requiert des champs propres au provider, comme network ou des codes OTP client.

UX recurrente ou embarquee

Utile pour des expériences fortement intégrées où le checkout par redirection n’est pas souhaité.

Endpoints

Méthode	Endpoint	Objet
`GET`	`/payments/v1/payments/direct-charge/{provider}/properties`	Récupérer les propriétés spécifiques au provider (optionnel pour certains providers)
`POST`	`/payments/v1/payments/direct-charge`	Initier un direct charge
`GET`	`/payments/v1/payments/verify/{reference}`	Vérifier le statut final de la transaction

Étapes d’intégration

Choisir le slug provider

Sélectionnez un provider valide depuis Providers pris en charge.

Recuperer les proprietes du provider (optionnel)

Pour des providers comme Bank Transfer (bank-transfer-nigeria), récupérez les propriétés requises, par exemple les valeurs network, avant de débiter.

Envoyer la requête de direct charge

Appelez l’endpoint direct-charge avec provider, amount et customerInput.

Traiter l'action puis confirmer le statut final

Utilisez l’action de la réponse (processing, redirect, bankTransfer) puis finalisez selon le webhook ou la vérification.

Récupérer les propriétés du provider (optionnel)

curl --location 'https://sandbox-api.payfonte.com/payments/v1/payments/direct-charge/{provider}/properties' \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>'

Exemple de réponse :

{
  "data": {
    "networks": [
      { "name": "Airtel", "value": "airtel" },
      { "name": "MTN MoMo", "value": "mtn-momo" }
    ]
  }
}

Requête Direct Charge

curl --location 'https://sandbox-api.payfonte.com/payments/v1/payments/direct-charge' \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "reference": "ORDER-1001",
    "amount": 10000,
    "provider": "mtn-momo-ivory-coast",
    "webhook": "https://yourapp.com/webhooks/payfonte",
    "narration": "Order payment",
    "customerInput": {
      "phoneNumber": "2250512345678"
    }
  }'

Exemple de réponse :

{
  "data": {
    "action": "processing",
    "sessionId": "1031-4120-a98f-9357692945",
    "provider": "mtn-momo-ivory-coast",
    "channel": "mobile-money",
    "reference": "ORDER-1001",
    "amount": 10000,
    "status": "pending",
    "statusDescription": "Awaiting Provider's Feedback"
  },
  "statusCode": 201
}

Champs de la requête

Champ	Type	Requis	Description
`provider`	string	Oui	Slug du provider (par exemple `mtn-momo-ivory-coast`)
`amount`	integer	Oui	Montant en sous-unités, sans décimales
`customerInput`	object	Oui	Champs provider/client, par exemple `phoneNumber`
`reference`	string	Recommandé	Référence marchand unique
`webhook`	string	Non	Webhook spécifique à cette transaction
`narration`	string	Non	Description de la transaction
`metadata`	object	Non	Métadonnées personnalisées renvoyées en aval

Types d’action et traitement

processing

L’interaction client/provider est en cours, par exemple une autorisation USSD ou STK en attente. Conservez l’état du paiement à pending et attendez le statut final via webhook ou vérification.

redirect

Redirigez le client vers l’URL du provider, souvent dans data.data.link. Ne considerez jamais la simple fin de la redirection comme un succes de paiement.

bankTransfer

Affichez les instructions de virement renvoyées, comme le nom du compte, le numéro, le montant et l’expiration. Attendez le webhook ou la vérification avant de marquer le paiement comme réussi.

Règle de montant importante

Payfonte ne prend pas en charge les montants décimaux dans les requêtes API. Envoyez uniquement des valeurs entières en sous-unités.

100.00 NGN -> 10000
2500.75 NGN -> 250075

Voir Spécification des montants.

Confirmation du statut final

Pour l’exécution de commande, appuyez-vous sur :

Les webhooks pour les mises à jour asynchrones.
GET /payments/v1/payments/verify/{reference} pour la vérification backend.

Documentation associée

Flux de traitement

Comprendre les modèles processing, redirect, bankTransfer et pre-OTP.

Exemples de payloads

Copier des exemples de requêtes spécifiques par provider.

Providers pris en charge

Slugs providers, limites et couverture pays.

Premiers pas

Concepts clés

Prestataires et couverture

Développement

Encaisser des paiements

Décaissements

Quand utiliser Direct Charge

Flux pilotes par le backend

Champs specifiques au provider

UX recurrente ou embarquee

Endpoints

Étapes d’intégration

Récupérer les propriétés du provider (optionnel)

Requête Direct Charge

Champs de la requête

Types d’action et traitement

Règle de montant importante

Confirmation du statut final

Documentation associée

Flux de traitement

Exemples de payloads

Providers pris en charge

​Quand utiliser Direct Charge

Flux pilotes par le backend

Champs specifiques au provider

UX recurrente ou embarquee

​Endpoints

​Étapes d’intégration

​Récupérer les propriétés du provider (optionnel)

​Requête Direct Charge

​Champs de la requête

​Types d’action et traitement

​Règle de montant importante

​Confirmation du statut final

​Documentation associée

Flux de traitement

Exemples de payloads

Providers pris en charge

Quand utiliser Direct Charge

Endpoints

Étapes d’intégration

Récupérer les propriétés du provider (optionnel)

Requête Direct Charge

Champs de la requête

Types d’action et traitement

Règle de montant importante

Confirmation du statut final

Documentation associée