Developers

Accept mobile money in your app with one API call.

A REST API with API-key authentication, signed callbacks and safe retries. Full docs live in the portal.

The API docs need you to sign in to the portal.

// Base URL
https://api.deonpay.app/v1
// Endpoints
POST/payments method: "ussd" | "url"
GET/payments/:orderId
POST/cashouts · /withdrawals
GET/balance · /ledger
// Callbacks, signed HMAC-SHA256
payment.completed · payment.failed
cashout.completed · withdrawal.paid …

Walkthrough

From request to paid, in three steps

Create a payment

One endpoint for both ways to collect. Use method "ussd" to send a PIN prompt, or "url" to get a payment link. Pass your own reference so retries are safe.

create-payment.sh

curl https://api.deonpay.app/v1/payments \
  -H "Authorization: Bearer $DEONPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "method": "ussd",
    "phone": "0760100100",
    "reference": "order-1042"
  }'

Receive the signed callback

When the payment completes or fails, we POST to your callback URL. Verify the HMAC-SHA256 signature before you trust it. Failed deliveries are retried automatically.

verify-callback.sh

# Your callback URL receives a signed POST, for example:
#   X-DeonPay-Timestamp: 1793528171
#   X-DeonPay-Signature: sha256=<hex HMAC-SHA256>
#   {"event": "payment.completed", "data": {"reference": "order-1042", ...}}
 
# Sign "<timestamp>.<raw body>" with your webhook secret and compare:
echo "sha256=$(printf '%s.%s' "$TIMESTAMP" "$RAW_BODY" \
  | openssl dgst -sha256 -hmac "$DEONPAY_WEBHOOK_SECRET" | cut -d" " -f2)"

Check the status

Missed a callback, or want to double-check? Fetch the payment at any time with its orderId.

check-status.sh

curl https://api.deonpay.app/v1/payments/$ORDER_ID \
  -H "Authorization: Bearer $DEONPAY_API_KEY"

Create a payment

One endpoint for both ways to collect. Use method "ussd" to send a PIN prompt, or "url" to get a payment link. Pass your own reference so retries are safe.

CreatePayment.java

String json = "{\"amount\": 25000, \"method\": \"ussd\","
    + " \"phone\": \"0760100100\", \"reference\": \"order-1042\"}";
 
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.deonpay.app/v1/payments"))
    .header("Authorization", "Bearer " + System.getenv("DEONPAY_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

Receive the signed callback

When the payment completes or fails, we POST to your callback URL. Verify the HMAC-SHA256 signature before you trust it. Failed deliveries are retried automatically.

WebhookController.java

@PostMapping("/deonpay/webhook")
public ResponseEntity<Void> webhook(@RequestBody String body,
    @RequestHeader("X-DeonPay-Timestamp") String timestamp,
    @RequestHeader("X-DeonPay-Signature") String given) throws Exception {
  Mac mac = Mac.getInstance("HmacSHA256");
  mac.init(new SecretKeySpec(System.getenv("DEONPAY_WEBHOOK_SECRET").getBytes(UTF_8), "HmacSHA256"));
  String expected = "sha256=" + HexFormat.of().formatHex(mac.doFinal((timestamp + "." + body).getBytes(UTF_8)));
  if (!MessageDigest.isEqual(expected.getBytes(UTF_8), given.getBytes(UTF_8))) {
    return ResponseEntity.status(401).build();
  }
 
  JsonNode payload = new ObjectMapper().readTree(body);
  if (payload.get("event").asText().equals("payment.completed")) {
    // mark payload.get("data").get("reference") as paid
  }
  return ResponseEntity.ok().build();
}

Check the status

Missed a callback, or want to double-check? Fetch the payment at any time with its orderId.

CheckStatus.java

HttpRequest request = HttpRequest.newBuilder(
        URI.create("https://api.deonpay.app/v1/payments/" + orderId))
    .header("Authorization", "Bearer " + System.getenv("DEONPAY_API_KEY"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body()); // {"data": {"status": "COMPLETED", ...}}

Create a payment

One endpoint for both ways to collect. Use method "ussd" to send a PIN prompt, or "url" to get a payment link. Pass your own reference so retries are safe.

create_payment.go

body, _ := json.Marshal(map[string]any{
    "amount":    25000,
    "method":    "ussd", // or "url" for a payment link
    "phone":     "0760100100",
    "reference": "order-1042",
})
req, _ := http.NewRequest("POST", "https://api.deonpay.app/v1/payments", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("DEONPAY_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

Receive the signed callback

When the payment completes or fails, we POST to your callback URL. Verify the HMAC-SHA256 signature before you trust it. Failed deliveries are retried automatically.

webhook.go

func deonpayWebhook(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    timestamp := r.Header.Get("X-DeonPay-Timestamp")
    mac := hmac.New(sha256.New, []byte(os.Getenv("DEONPAY_WEBHOOK_SECRET")))
    mac.Write([]byte(timestamp + "." + string(body)))
    expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
    if !hmac.Equal([]byte(expected), []byte(r.Header.Get("X-DeonPay-Signature"))) {
        w.WriteHeader(http.StatusUnauthorized)
        return
    }
 
    var payload struct {
        Event string `json:"event"`
        Data  struct{ Reference string `json:"reference"` } `json:"data"`
    }
    json.Unmarshal(body, &payload)
    if payload.Event == "payment.completed" {
        // mark payload.Data.Reference as paid
    }
    w.WriteHeader(http.StatusOK)
}

Check the status

Missed a callback, or want to double-check? Fetch the payment at any time with its orderId.

check_status.go

req, _ := http.NewRequest("GET", "https://api.deonpay.app/v1/payments/"+orderID, nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("DEONPAY_API_KEY"))
res, err := http.DefaultClient.Do(req)
 
var out struct {
    Data struct{ Status string `json:"status"` } `json:"data"`
}
json.NewDecoder(res.Body).Decode(&out)
fmt.Println(out.Data.Status) // PENDING, COMPLETED, EXPIRED ...

Short examples. Every field, error code and response is in the API docs in the portal.

The API

Built for real money

Callbacks with retries

payment.completed, payment.failed, cashout.completed, withdrawal.paid and more. Signed, and retried automatically.

Safe retries with reference

Send a unique reference. A retried payment, cash-out or withdrawal can’t happen twice.

Cash-out API

Send money to any mobile wallet from your balance.

Withdrawals

Withdraw to your business’s registered bank account.

Balance and statement API

Read your balance and statement from your own systems.

Test events from the portal

Send test callbacks to your URL to check your handler.

Build with AI

Hand the whole API to your AI assistant

The API docs in the portal have a Copy docs for AI button. One click copies the full docs, ready to paste into ChatGPT, Claude or Cursor.

1Open the API docs in the portal.
2Click Copy docs for AI.
3Paste into your assistant and describe what you want to build.

Go live

Five steps to your first payment

01
Request an account
02
Sign in to the portal
03
Create an API key
04
Set your callback URL
05
Collect your first payment

Read the API docs Request an account