API de collecte - Carte

Les paiements par carte peuvent nécessiter plusieurs appels API avant que Payfonte puisse confirmer le résultat final. La première requête de carte renvoie une action qui indique à votre backend ce qu’il doit collecter ou faire ensuite.

Endpoints

Méthode	Endpoint	Objet
`POST`	`/payments/v1/cards/process`	Soumettre les détails de carte et démarrer le paiement par carte
`POST`	`/payments/v1/cards/pin`	Soumettre le code PIN de carte quand l’action de réponse est `pin`
`POST`	`/payments/v1/cards/otp`	Soumettre l’OTP client quand l’action de réponse est `otp`
`GET`	`/payments/v1/payments/verify/{reference}`	Vérifier le statut final de la transaction quand l’action de réponse est `verification`

Tests

Les données de test des cartes sandbox sont disponibles dans Tests.

Étapes d’intégration

Soumettre les détails de carte

Appelez /payments/v1/cards/process avec provider, amount et card. Vous pouvez aussi transmettre des valeurs racine reference, redirectURL et webhook pour le suivi de transaction, le retour client et la surcharge webhook. Envoyez votre identifiant client dans l’en-tête client-id.

Lire l'action

Utilisez data.action pour déterminer s’il faut collecter le code PIN, collecter l’OTP, rediriger pour la 3DS ou vérifier le paiement.

Continuer l'étape requise

Soumettez le code PIN ou l’OTP quand il est demandé, ou redirigez le client vers data.data.redirectURL pour l’authentification 3DS.

Confirmer le statut final

Quand l’action est verification, appelez GET /payments/v1/payments/verify/{reference} depuis votre backend avant de livrer la commande.

Soumettre les détails de carte

curl --request POST \
  --url https://sandbox-api.payfonte.com/payments/v1/cards/process \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>' \
  --header 'content-type: application/json' \
  --data '{
    "reference": "ORDER-1001",
    "provider": "card-nigeria",
    "amount": 50000,
    "redirectURL": "https://yourapp.com/payment/complete",
    "webhook": "https://yourapp.com/webhooks/payfonte",
    "card": {
      "pan": "5061 4604 1012 1111 102",
      "expiry": {
        "month": "12",
        "year": "2050"
      },
      "cvv": "558",
      "cardHolderName": "Emily Heidenreich-Kohler",
      "email": "Darrick.OHara@hotmail.com",
      "phoneNumber": "(536) 393-0857",
      "address": "Address 1, Lokoja",
      "city": "my-city"
    }
  }'

Champs de requête

Champ	Type	Requis	Description
`provider`	string	Oui	Slug du provider carte, par exemple `card-nigeria`
`amount`	integer	Oui	Montant en sous-unités
`card`	object	Oui	Détails de carte et de facturation client
`reference`	string	Recommandé	Identifiant de transaction unique depuis votre système
`redirectURL`	string	Non	URL de retour du client après paiement
`webhook`	string	Non	URL de webhook spécifique à cette transaction

Soumettre le code PIN

Utilisez cet endpoint quand la réponse précédente renvoie data.action avec la valeur pin.

curl --request POST \
  --url https://sandbox-api.payfonte.com/payments/v1/cards/pin \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>' \
  --header 'content-type: application/json' \
  --data '{
    "reference": "DCD20260701144120NCDZW",
    "provider": "card-nigeria",
    "card": {
      "pan": "5061 4604 1012 1111 106",
      "expiry": {
        "month": "12",
        "year": "2050"
      },
      "cvv": "562",
      "pin": "1106",
      "cardHolderName": "Donna Flatley",
      "email": "Darrick.OHara@hotmail.com",
      "phoneNumber": "(536) 393-0857",
      "address": "Address 1, Lokoja",
      "city": "my-city"
    }
  }'

Soumettre l’OTP

Utilisez cet endpoint quand la réponse précédente renvoie data.action avec la valeur otp.

curl --request POST \
  --url https://sandbox-api.payfonte.com/payments/v1/cards/otp \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>' \
  --header 'content-type: application/json' \
  --data '{
    "reference": "DCD20260701144120NCDZW",
    "otp": "543210"
  }'

Actions de réponse

Collectez le code PIN de carte du client et appelez POST /payments/v1/cards/pin avec la reference renvoyée.

{
  "statusCode": 200,
  "data": {
    "reference": "DCD20260701133425EIQWF",
    "action": "pin",
    "data": {}
  }
}

otp

Collectez l’OTP envoyé au client et appelez POST /payments/v1/cards/otp avec la reference renvoyée.

{
  "statusCode": 201,
  "data": {
    "reference": "DCD20260701133425EIQWF",
    "action": "otp",
    "data": {}
  }
}

redirect

Redirigez le client vers data.data.redirectURL pour terminer l’authentification 3DS. Après le flux de redirection, vérifiez le paiement côté serveur.

{
  "statusCode": 201,
  "data": {
    "reference": "DCD20260701144120NCDZW",
    "action": "redirect",
    "data": {
      "redirectURL": "https://s.6bd.co/card-3ds/mce1aN"
    }
  }
}

verification

Appelez GET /payments/v1/payments/verify/{reference} avec la reference renvoyée pour confirmer le statut final de la transaction.

{
  "statusCode": 200,
  "data": {
    "reference": "DCD20260701133425EIQWF",
    "action": "verification",
    "data": {}
  }
}

Résumé de décision des flux

Action	Étape suivante pour le client	Étape suivante pour le marchand
`pin`	Saisir le code PIN de carte	Appeler `POST /payments/v1/cards/pin`
`otp`	Partager l’OTP	Appeler `POST /payments/v1/cards/otp`
`redirect`	Terminer l’authentification 3DS	Rediriger vers `data.data.redirectURL`, puis vérifier
`verification`	Aucune autre saisie client	Appeler `GET /payments/v1/payments/verify/{reference}`

Règles importantes

Les valeurs de montant doivent être des entiers en sous-unités. Les décimales ne sont pas prises en charge.

Voir Spécification des montants.

Collectez et soumettez les données de carte uniquement depuis des environnements sécurisés et conformes PCI. Ne journalisez pas les valeurs PAN, CVV, PIN ou OTP.

Documentation associée

Référence API

Consultez les définitions d’endpoints carte et les schémas de requête.

Webhooks

Confirmez les résultats finaux des transactions de manière asynchrone.

Tests

Utilisez les données de carte sandbox pour les scénarios PIN, OTP, 3DS, success, failed et pending.

Premiers pas

Concepts clés

Prestataires et couverture

Développement

Encaisser des paiements

Décaissements

API de collecte - Carte

Endpoints

Tests

Étapes d’intégration

Soumettre les détails de carte

Champs de requête

Soumettre le code PIN

Soumettre l’OTP

Actions de réponse

Résumé de décision des flux

Règles importantes

Documentation associée

Référence API

Webhooks

Tests

​Endpoints

​Tests

​Étapes d’intégration

​Soumettre les détails de carte

​Champs de requête

​Soumettre le code PIN

​Soumettre l’OTP

​Actions de réponse

​Résumé de décision des flux

​Règles importantes

​Documentation associée

Référence API

Webhooks

Tests

Endpoints

Tests

Étapes d’intégration

Soumettre les détails de carte

Champs de requête

Soumettre le code PIN

Soumettre l’OTP

Actions de réponse

Résumé de décision des flux

Règles importantes

Documentation associée