Transfer API

Djamo Transfers provides a suite of services that enable you to send money seamlessly to Djamo users from your business account.

At the moment, what you can do trough the Business API, is debit your business account and credit one or many Djamo clients. ie: Send money to one or multiple Djamo clients.

You can also get the list of transactions that have impacted your business account or the status for a particular transaction.

The transaction object

Attribute	Type	Description
id	String	The ID for the transaction
amount	Amount	The amount charged for the transaction.
fee	Amount	The fee charged for the tranasction.
totalAmount	Amount	The total amount charged for the transaction (amount + fee).
msisdn	Phone Number	The msisdn of the Djamo client
status	String	The current status of the transaction. Can be one of the following : `pending`, `completed` or `failed`
reference	String	The reference that you indicated when creating the transaction. Can be your internal ID for exemple.
type	String	The type of the transaction. At the moment, the only type allowed is `transfer`.
batchId	String	The ID for the batch that created this transaction (only if the transation was created as part of a batch).
createdAt	Timestamp	Timestamp indicating when the transactions was created.
updatedAt	Timestamp	Timestamp indicating when the transaction has been updated.
failureReason	String	The reason why the transaction failed. `null` when the transaction has not failed. See Failure reasons.

Sending money to one Djamo client

POST /v1/transactions

Parameter	Type	Description
amount	Amount	The amount charged for the transaction. Should be in the range of 5.000 - 500.000
msisdn	Phone Number	The msisdn of the Djamo client
reference	String	A reference that you indicate. Can be your internal ID for exemple.
type	String	The type of the transaction. At the moment, the only type allowed is `transfer`.

RequestResponse

curl \
-XPOST \
-H "Content-type: application/json" \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-d '{
      "msisdn": "+22507XXXXXX00",
      "amount": 50000,
      "reference": "17f99xApUe472A",
      "description": "Salaire de juin",
      "type": "transfer"
    }' \
<BASE_URL>/v1/transactions

{
  "id": "txn_2cdc8ab1-6d50-49cc-ba14-54e4ac7ec231",
  "createdAt": "2023-05-25T17:43:15.970Z",
  "updatedAt": "2023-05-25T17:43:15.970Z",
  "amount": 500000,
  "fee": 5000,
  "totalAmount": 505000,
  "status": "pending",
  "msisdn": "+22507XXXXXX00",
  "reference": "17f99xApUe472A",
  "description": "Prime de juin",
  "type": "transfer"
}

For your test, you can use the following numbers to simulate different statuses:

Phone Number	Desired Status
2250747000000	`completed`
2251212121205	`failed`

Error responses

HTTP code	Cause
`400`	Missing or invalid parameter (`amount`, `msisdn`, `reference`, `type`).
`401`	Invalid or missing access token.
`402`	Insufficient funds on your business account to complete this transfer.
`409`	A transaction with this `reference` already exists.
`422`	An unexpected error occurred. Contact support if the issue persists.

For general HTTP error codes, see Handling errors.

Sending money to multiple Djamo clients

The batch endpoint only available for transactions with type transfer. 2. You will receive a JSON representing the the batch object.

POST /v1/transactions/batch

Parameter	Type	Description
transactions	Array	A list of transaction parameters objects used in the endpoint to create a single transaction. See example below

Example

RequestResponse

curl \
-XPOST \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-d '{
      "transactions": [
        {
          "msisdn": "+22507XXXXXX00",
          "amount": 500000,
          "reference": "17f99xApUe472A",
          "description": "Prime de juin"
        },
        {
          "msisdn": "+22507XXXXXX01",
          "amount": 550000,
          "reference": "12E94bDeOP209T",
          "description": "Prime de juin"
        }
      ]
    }' \
<BASE_URL>/v1/transactions/batch

{
  "id": "bat_27fb25f4-3246-44c9-9f30-f0df3d9188cf",
  "createdAt": "2023-03-16T22:01:11.070Z",
  "updatedAt": "2023-03-16T22:01:11.269Z",
  "totalAmount": 8300,
  "status": "processing",
  "totalFee": 5,
  "transactions": [
      {
        "id": "txn_2cdc8ab1-6d50-49cc-ba14-54e4ac7ec231",
        "createdAt": "2023-11-24T17:43:15.970Z",
        "updatedAt": "2023-11-24T17:43:15.970Z",
        "amount": 500000,
        "fee": 5000,
        "totalAmount": 505000,
        "status": "pending",
        "msisdn": "+22507XXXXXX00",
        "reference": "17f99xApUe472A",
        "description": "Prime de juin",
        "type": "transfer"
      },
      {
        "id": "txn_ae189ba6-0dc9-492a-9bde-ffdcf0decb0b",
        "createdAt": "2023-11-24T17:44:15.970Z",
        "updatedAt": "2023-11-24T17:44:15.970Z",
        "amount": 430000,
        "fee": 4300,
        "totalAmount": 434300,
        "status": "pending",
        "msisdn": "+22507XXXXXX01",
        "reference": "2E94bDeOP209T",
        "description": "Prime de juin",
        "type": "transfer"
      }
  ]
}

Error responses

HTTP code	Cause
`400`	Missing or invalid parameter in one or more transactions.
`401`	Invalid or missing access token.
`402`	Insufficient funds on your business account to complete this transfer.
`409`	A transaction with this `reference` already exists.
`422`	An unexpected error occurred. Contact support if the issue persists.

For general HTTP error codes, see Handling errors.

Retrieving a transaction by ID

GET /v1/transactions/<id>

You can alternatively use webhooks to be notified about transaction status changes.

RequestResponse

curl  \
-X GET \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
<BASE_URL>/v1/transactions/txn_fbf960c4-294b-43cd-99a4-920b61efb17d

{
  "id": "txn_fbf960c4-294b-43cd-99a4-920b61efb17d",
  "createdAt": "2023-11-24T17:43:15.970Z",
  "updatedAt": "2023-11-24T17:43:16.970Z",
  "amount": 5000,
  "fee": 50,
  "totalAmount": 5050,
  "status": "completed",
  "msisdn": "+225079932203",
  "reference": "17f9956f-0965-4964-b2c1-40b4fef141a7",
  "failureReason": null,
  "description": "July's salary",
  "type": "transfer",
  "batchId": "17f9956f-0965-4964-b2c1-40b4fef141a7"
}

Error responses

HTTP code	Cause
`401`	Invalid or missing access token.
`404`	Transaction not found.

For general HTTP error codes, see Handling errors.

Retrieving transactions by reference

GET /v1/transactions

Use the reference query parameter to search for transactions matching the reference you provided when the transaction was created. This is useful to look up a transaction using your internal ID.

Parameter	Type	Description
reference	String	The reference you indicated when creating the transaction. Can be your internal ID for example.

RequestResponse

curl  \
-X GET \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
<BASE_URL>/v1/transactions?reference=197

{
  "count": 1,
  "limit": 15,
  "cursor": {
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "txn_79ccf5fe-578e-4ae8-bf0c-a9cee365a9f3",
      "createdAt": "2026-04-27T11:16:47.103Z",
      "updatedAt": "2026-04-27T11:16:47.515Z",
      "amount": 500,
      "fee": 0,
      "totalAmount": 500,
      "status": "failed",
      "msisdn": "2250700888830",
      "reference": "197",
      "failureReason": "TRANSACTION_AMOUNT_OVER_ACCOUNT_LIMIT",
      "description": "Test transfert",
      "type": "api-transfer"
    }
  ]
}

Failure reasons

When a transaction status is failed, the failureReason field indicates the cause.

Value	Description
`TRANSACTION_AMOUNT_OVER_ACCOUNT_LIMIT`	The recipient has reached their Djamo account limit and cannot receive this amount.
`DJAMO_ACCOUNT_NOT_FOUND`	The recipient phone number does not match any registered Djamo user.
`INTERNAL_ERROR`	An internal Djamo service failure occurred. Retry the transaction or contact support if the issue persists.
`UNKNOWN_ERROR`	An unexpected error occurred. Contact support if the issue persists.

Check customer

GET /v1/transactions/customers/check

This endpoint is used to check the information a user has entered. For the moment, it just returns the customer's KYC status. The complete status is the only one that indicates that the client has been validated by the system. Any other status indicates that there is a problem with client identification.

Parameter	Type	Description
subCompanyId (Optional)	String	The ID of the sub company
msisdn (Required)	Phone Number	The msisdn of the Djamo client

RequestResponse

curl  \
-X GET \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
<BASE_URL>/v1/transactions/customers/check?msisdn=2250747105623

User found

{
  "kycStatus": "complete",
  "firstName": "John",
  "lastName": "Doe"
}

User not found

{
  "kycStatus": "unknown",
  "firstName": "unknown",
  "lastName": "unknown"
}

Check balance

GET /v1/balance

This represents your Djamo Business account balance. You can retrieve it to see what you currently have on your business account.

RequestResponse

curl \
-X GET \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
<BASE_URL>/v1/balance

{
  "balance": 1000,
  "currency": "XOF"
}