Collection API

Introduction

Djamo’s payment solution lets you receive payments from Djamo users.

Whether you're integrating payments into a website, mobile app, or custom checkout system, our flexible APIs give you full control over the experience while keeping transactions smooth and secure.

The Charge API

The Charge API allows you to collect payments from customers. A charge represents a payment request that a Djamo user can pay.

Think of a charge as a digital invoice that you create and send to your customer. When they pay this invoice, the money gets transferred to your Djamo business account.

Create a charge

POST /v1/charges

This endpoint creates a payment request for your customer.

Parameter	Required	Type	Description
amount	YES	Amount	How much money to collect. Example: 10000
externalId	YES	String	Your own reference ID for this transaction. Example: SF32JTK3DEO478WNF
description	YES	String	What the payment is for. Example: Shoe payment
onCanceledRedirectionUrl	YES	String	Merchant URL to redirect the user after canceled payment. Exemple: https://www.merchant.com/djamo-cancel/1744728413766
onCompletedRedirectionUrl	YES	String	Merchant URL to redirect the user after completed payment. Exemple: https://www.merchant.com/djamo-sucess/1744728413766
metadata	No	Object	Any extra information you want to store with this charge. Example: { "catalogId": "3DW24FTG" }

RequestResponse

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": []
}

The most important part of this response is the paymentUrl. This is the link you need to redirect your customer to or share with them so they can complete the payment.

Warning

Make sure to subscribe to the webhook topic charge/events to receive status updates about your charges.

Pay a charge (Staging)

POST /v1/charges/:id/pay

Danger

This only works in staging. Do not try in production. It wouldn't work anyways.

This endpoint simulates paying for a charge. You can use the following numbers to simulate different statuses:

Phone Number	Desired Status
2250747000000	paid
2251212121205	failed

RequestResponse

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"
}

Retrieve a charge

GET /v1/charges/:id

This endpoint lets you check the status of a charge - whether it's been paid, how much was paid, etc.

RequestResponse

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,
  // other charge details...
  "transactions": [
    {
      "id": "DJAMONEXUSM6J5V4J639PAQWPGTAI",
      "status": "completed",
      // transaction details...
    }
  ]
}

This is useful for checking if your customer has completed their payment. The status field will be one of:

Status	Description
due	The charge is created but not paid yet
paid	The charge has been paid successfully
refunded	The charge was paid but has been refunded
dropped	The charge was abandoned or canceled

Charge status flow

The time-to-live of a due charge is 1 hour. This means that if no successful transaction occurs, the charge will remain in the due status for one hour after its creation. Once this period has elapsed, the due charge is automatically marked as dropped. A webhook is triggered on the charge/events topic whenever a charge transitions to either the paid or dropped status.

graph LR
    start(charge created) --> due(due<br/>TTL: 1 hour)
    due -->|Transaction successful<br/>within 1 hour| paid(paid)
    due -->|TTL expired<br/>after 1 hour| dropped(dropped)

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

    paid -->|Refund issued| refunded(refunded)
    paid -->|Partial refund issued| 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

Refund a charge

POST /v1/charges/:id/refund

This endpoint lets you send money back to a customer who has already paid.

Note

If you don't include an amount, the entire charge will be refunded. If you do include an amount, you can refund just part of the charge (useful if you're giving a partial refund).

Partial refund

Request

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

Full refund

RequestResponse

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
    }
  ]
}