Skip to content

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 payment. Exemple: https://www.merchant.com/djamo-cancel/1744728413766
onCompletedRedirectionUrl YES String Merchant URL to redirect the user after 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" } 
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.

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 
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.

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
created 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

Refund a charge

GET /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

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

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