Collection API

Introduction

La solution de paiement Djamo vous permet de recevoir des paiements de la part d'utilisateurs Djamo.

Que vous intégriez des paiements sur un site web, une application mobile ou un système de caisse personnalisé, nos API flexibles vous donnent un contrôle total sur l'expérience tout en maintenant des transactions fluides et sécurisées.

L'API de collecte

L'API de collecte vous permet de collecter des paiements de vos clients. Une charge représente une demande de paiement qu'un utilisateur Djamo peut régler.

Considérez une charge comme une facture numérique que vous créez et envoyez à votre client. Lorsqu'il règle cette facture, l'argent est transféré sur votre compte Business Djamo.

Créer une charge

POST /v1/charges

Cet endpoint crée une demande de paiement pour votre client.

Paramètre	Requis	Type	Description
amount	OUI	Montant	Montant à collecter. Exemple : 10000
externalId	OUI	String	Votre propre identifiant de référence pour cette transaction. Exemple : SF32JTK3DEO478WNF
description	OUI	String	Objet du paiement. Exemple : Paiement chaussures
onCanceledRedirectionUrl	OUI	String	URL marchande pour rediriger l'utilisateur après un paiement annulé. Exemple : https://www.merchant.com/djamo-cancel/1744728413766
onCompletedRedirectionUrl	OUI	String	URL marchande pour rediriger l'utilisateur après un paiement complété. Exemple : https://www.merchant.com/djamo-success/1744728413766
metadata	Non	Object	Toute information supplémentaire à stocker avec cette charge. Exemple : { "catalogId": "3DW24FTG" }

RequêteRéponse

curl --request POST \
--url <BASE_URL>/v1/charges \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'X-Company-Id: <YOUR_COMPANY_ID>' \
--data '{
  "amount": 10000,
  "externalId": "12182912",
  "description": "Product purchase",
  "metadata": {
    "purchaseReference": "00DDAAEESDS"
  },
  "onCanceledRedirectionUrl": "https://www.merchant.com/djamo-success/1744728413766",
  "onCompletedRedirectionUrl": "https://www.merchant.com/djamo-cancel/1744728413766"
}'

{
  "id": "20c8a4c5822c-43dd-967c-e0619fb5da46",
  "createdAt": "20250128T083908.249Z",
  "externalId": "12182912",
  "description": "Product purchase",
  "currency": "XOF",
  "amount": 10000,
  "due": 10000,
  "fees": {
    "currency": "XOF",
    "rate": 1,
    "value": 100
  },
  "status": "created",
  "paid": 0,
  "refunded": 0,
  "attempts": 0,
  "metadata": {
    "purchaseReference": "00DDAAEESDS"
  },
  "paymentUrl": "<https://djamo.ci/?type=payment_confirmation>...",
  "transactions": []
}

La partie la plus importante de cette réponse est le paymentUrl. C'est le lien vers lequel vous devez rediriger votre client ou le partager avec lui pour qu'il puisse finaliser le paiement.

Warning

Assurez-vous de vous abonner au topic webhook charge/events pour recevoir les mises à jour de statut de vos charges.

Payer une charge (Staging)

POST /v1/charges/:id/pay

Danger

Ceci fonctionne uniquement en staging. N'essayez pas en production. Cela ne fonctionnerait de toute façon pas.

Cet endpoint simule le paiement d'une charge. Vous pouvez utiliser les numéros suivants pour simuler différents statuts :

Numéro de téléphone	Statut souhaité
2250747000000	paid
2251212121205	failed

RequêteRéponse

curl --request POST \
--url <BASE_URL>/v1/charges/:id/pay \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "recipientMsisdn": <TEST_PHONE_NUMBER>
}'

{
  "id": "bf6db759-9933-446f-be08-749d553bcb86",
  "createdAt": "2025-07-29T12:22:26.568Z",
  "externalId": "174473164430-",
  "description": "Product purchase",
  "currency": "XOF",
  "amount": 100,
  "due": 0,
  "fees": {
    "currency": "XOF",
    "rate": 1,
    "value": 1
  },
  "status": "paid",
  "droppedReason": null,
  "paid": 100,
  "refunded": 0,
  "attempts": 1,
  "metadata": {},
  "transactions": [
    {
      "id": "DJAMONEXUSMDOIC4S0CV8I5GOY7R",
      "recipientMsisdn": "2250747000000",
      "amount": 100,
      "service": "djamo",
      "status": "completed",
      "type": "payment",
      "error": null
    }
  ],
  "webRedirectionUrl": "https://www.yumyum.sn/djamo-cancel/1744728413766"
}

Récupérer une charge

GET /v1/charges/:id

Cet endpoint vous permet de vérifier le statut d'une charge — si elle a été payée, combien a été payé, etc.

RequêteRéponse

curl -X GET "<BASE_URL>/v1/charges/:id" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "20c8a4c5822c-43dd-967c-e0619fb5da46",
  "reference": "DJAMONEXUSM6J5V4J639PAQWPGTAI",
  "status": "paid",
  "paid": 10000,
  "refunded": 0,
  // autres détails de la charge...
  "transactions": [
    {
      "id": "DJAMONEXUSM6J5V4J639PAQWPGTAI",
      "status": "completed",
      // détails de la transaction...
    }
  ]
}

Ceci est utile pour vérifier si votre client a finalisé son paiement. Le champ status sera l'un des suivants :

Statut	Description
due	La charge est créée mais pas encore payée
paid	La charge a été payée avec succès
refunded	La charge a été payée mais a été remboursée
dropped	La charge a été abandonnée ou annulée

Cycle de vie d'une charge

La durée de vie d'une charge due est de 1 heure. Cela signifie que si aucune transaction réussie n'a lieu, la charge restera au statut due pendant une heure après sa création. Une fois ce délai écoulé, la charge due est automatiquement marquée comme dropped. Un webhook est déclenché sur le topic charge/events chaque fois qu'une charge passe au statut paid ou dropped.

graph LR
    start(charge créée) --> due(due<br/>TTL: 1 heure)
    due -->|Transaction réussie<br/>dans l'heure| paid(paid)
    due -->|TTL expiré<br/>après 1 heure| dropped(dropped)

    paid --> webhook(Webhook<br/>charge/events<br/>)
    dropped --> webhook

    paid -->|Remboursement émis| refunded(refunded)
    paid -->|Remboursement partiel émis| refundedpartially(refunded_partially)
    refundedpartially --> webhook
    refunded --> webhook

    style start stroke-width:2px
    style due fill:#FFF9C4,stroke:#F9A825,stroke-width:3px
    style paid fill:#C8E6C9,stroke:#388E3C,stroke-width:3px
    style dropped fill:#FFCDD2,stroke:#D32F2F,stroke-width:3px
    style refunded fill:#E1BEE7,stroke:#7B1FA2,stroke-width:3px
    style refundedpartially fill:#E1BEE7,stroke:#7B1FA2,stroke-width:3px
    style webhook stroke-width:2px

Rembourser une charge

POST /v1/charges/:id/refund

Cet endpoint vous permet de renvoyer de l'argent à un client qui a déjà payé.

Note

Si vous n'incluez pas de montant, la totalité de la charge sera remboursée. Si vous incluez un montant, vous pouvez ne rembourser qu'une partie de la charge (utile pour les remboursements partiels).

Remboursement partiel

Requête

curl -X POST \
  <BASE_URL>/v1/charges/:id/refund \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "amount": 10000
  }'

Remboursement total

RequêteRéponse

curl -X POST \
  <BASE_URL>/v1/charges/:id/refund \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{}'

    {
  "id": "bfad6e0a-eba5-4fa9-b477-7bc0d3ce2c01",
  "createdAt": "2025-10-30T11:30:32.075Z",
  "externalId": "SF32JTK3DEO478WNH",
  "description": "Product purchase",
  "currency": "XOF",
  "amount": 100,
  "due": 0,
  "fees": {
    "currency": "XOF",
    "rate": 1,
    "value": 1
  },
  "status": "refunded",
  "droppedReason": null,
  "paid": 100,
  "refunded": 100,
  "attempts": 2,
  "metadata": {},
  "transactions": [
    {
      "id": "DJAMONEXUSMHDD73FAN8KPSXIZ83",
      "recipientMsisdn": "2250747000000",
      "amount": 100,
      "service": "djamo",
      "status": "completed",
      "type": "refund",
      "error": null
    },
    {
      "id": "DJAMONEXUSMHDCJ7XGJSFSQZERIWE",
      "recipientMsisdn": "2250747000000",
      "amount": 100,
      "service": "djamo",
      "status": "completed",
      "type": "payment",
      "error": null
    }
  ]
}