Mobile money collections

POST /api/deposit

Ask a customer to approve a mobile-money collection into the wallet.

Authentication

HTTP Basic, as described in Authentication. No extra scope is checked.

Headers

Header	Required	Description
Authorization	Yes	Basic base64(api_user_id:api_key).
Content-Type	Yes	application/json
Accept	No	application/json

Body

Field	Required	Rules	Description
externalReference string	Yes	required|string|max:255|unique:api_requests,external_id	Your reference for this payment.
msisdn string	Yes	Ugandan mobile number	Accepts 0, 256, or +256 followed by a 9-digit number starting with 2, 3, or 7.
amount number	Yes	required|numeric|min:500	Collection amount in UGX.
currency string	Yes	required|string|in:UGX	Must be UGX.
reason string	No	sent to the collection service	Not validated as required on this endpoint. Keep it short and plain.
name string	No	nullable|string	Payer name, when you have it.
success_callback string	No	nullable|url|max:255	URL that receives one unsigned POST after success. The legacy field callback is used when success_callback is empty.
failure_callback string	No	nullable|url|max:255	URL that receives one unsigned POST after failure.

Behavior

• The external reference is stored before the remaining fields are validated. A rejected request can still consume that reference.
• The phone number selects MTN or Airtel. There is no provider field.
• Minimum amount enforced by the API and the collection service is UGX 500. The fee comes from the organization collection policy.
• A successful response means the prompt was created. transactionStatus is pending until the customer approves and reconciliation completes.

Idempotency. externalReference must be unique in api_requests. There is no Idempotency-Key header.

Rate limit. No rate limit is configured on the API.

Example request

{
    "externalReference": "order-1001",
    "msisdn": "256772123456",
    "amount": 5000,
    "currency": "UGX",
    "reason": "Order 1001",
    "name": "Ada Lovelace",
    "success_callback": "https://example.com/payments/ssentezo",
    "failure_callback": "https://example.com/payments/ssentezo"
}

Success · HTTP 200

{
    "response": "OK",
    "data": {
        "transactionStatus": "PENDING",
        "ssentezoWalletReference": "generated-uuid",
        "financialTransactionId": ""
    }
}

Errors

Status	When
401 NO_AUTHORIZATION_HEADER	The Authorization header is missing.
403 INVALID_AUTHORIZATION_HEADER	The header must start with "Basic ".
403 MISSING_USER_OR_KEY	The decoded value must be api_user_id:api_key.
403 INVALID_USER_OR_KEY	The API user or key was not recognized.
403 ORGANIZATION_SUSPENDED	The organization user is suspended.
400	Validation failed, or the collection service rejected the request. error.message or error.errors explains it.
500	The collection could not be started.

Code

curl

curl --request POST \
  --url "$SSENTEZO_BASE_URL/api/deposit" \
  --header "Authorization: Basic $SSENTEZO_BASIC_TOKEN" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "externalReference": "order-1001",
    "msisdn": "256772123456",
    "amount": 5000,
    "currency": "UGX",
    "reason": "Order 1001",
    "name": "Ada Lovelace",
    "success_callback": "https://example.com/payments/ssentezo",
    "failure_callback": "https://example.com/payments/ssentezo"
}'

php

$client = new Ssentezo\Wallet\SsentezoClient(
    getenv('SSENTEZO_API_USER'),
    getenv('SSENTEZO_API_KEY'),
    getenv('SSENTEZO_BASE_URL')
);

$result = $client->request('POST', '/api/deposit', json_decode(<<<'JSON'
{
    "externalReference": "order-1001",
    "msisdn": "256772123456",
    "amount": 5000,
    "currency": "UGX",
    "reason": "Order 1001",
    "name": "Ada Lovelace",
    "success_callback": "https://example.com/payments/ssentezo",
    "failure_callback": "https://example.com/payments/ssentezo"
}
JSON, true));

javascript

const token = Buffer.from(process.env.SSENTEZO_API_USER + ':' + process.env.SSENTEZO_API_KEY).toString('base64');
const response = await fetch(process.env.SSENTEZO_BASE_URL + '/api/deposit', {
  method: 'POST',
  headers: {
    Authorization: 'Basic ' + token,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "externalReference": "order-1001",
    "msisdn": "256772123456",
    "amount": 5000,
    "currency": "UGX",
    "reason": "Order 1001",
    "name": "Ada Lovelace",
    "success_callback": "https://example.com/payments/ssentezo",
    "failure_callback": "https://example.com/payments/ssentezo"
}),
});
const payload = await response.json();

python

import base64, json, os, urllib.request

token = base64.b64encode(f"{os.environ['SSENTEZO_API_USER']}:{os.environ['SSENTEZO_API_KEY']}".encode()).decode()
request = urllib.request.Request(
    os.environ['SSENTEZO_BASE_URL'] + '/api/deposit',
    data=json.dumps({
    "externalReference": "order-1001",
    "msisdn": "256772123456",
    "amount": 5000,
    "currency": "UGX",
    "reason": "Order 1001",
    "name": "Ada Lovelace",
    "success_callback": "https://example.com/payments/ssentezo",
    "failure_callback": "https://example.com/payments/ssentezo"
}).encode(),
    headers={'Authorization': f'Basic {token}', 'Accept': 'application/json', 'Content-Type': 'application/json'},
    method='POST',
)
with urllib.request.urlopen(request, timeout=20) as response:
    payload = json.load(response)

java

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(System.getenv("SSENTEZO_BASE_URL") + "/api/deposit"))
    .timeout(Duration.ofSeconds(20))
    .header("Authorization", "Basic " + Base64.getEncoder().encodeToString((System.getenv("SSENTEZO_API_USER") + ":" + System.getenv("SSENTEZO_API_KEY")).getBytes(StandardCharsets.UTF_8)))
    .header("Accept", "application/json")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{\"externalReference\":\"order-1001\",\"msisdn\":\"256772123456\",\"amount\":5000,\"currency\":\"UGX\",\"reason\":\"Order 1001\",\"name\":\"Ada Lovelace\",\"success_callback\":\"https://example.com/payments/ssentezo\",\"failure_callback\":\"https://example.com/payments/ssentezo\"}"))
    .build();

Set SSENTEZO_API_USER, SSENTEZO_API_KEY, and SSENTEZO_BASE_URL. SSENTEZO_BASIC_TOKEN is the base64 of user:key.