GosentePay API

Introduction

The GosentePay API lets your application collect payments and send money to any MTN or Airtel Uganda mobile wallet. All requests use JSON over HTTPS. Every endpoint except the token endpoint requires a Bearer token.

Your money lives in a GosentePay wallet. Deposits credit your wallet with the full amount (free); withdrawals debit it plus a tiered fee. You can watch your balance from your dashboard.

Get your API keys

Log in to your dashboard and open API Keys. You'll find two values:

Key	Purpose
api_key	Exchanged for a short-lived Bearer token (step 1).
secret_key	Identifies your merchant account on each transaction. Keep it server-side only.

1. Get an access token

Exchange your api_key for a Bearer token (valid 24 hours).

# Request
curl -X POST https://api.gosentepay.com/v1/authorization_token \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "YOUR-API-KEY" }'

# Response
{ "status": "success", "token": "eyJhbGci...", "expires_in": 86400 }

2. Request a deposit (collect)

Sends an STK push to the customer's phone. They approve it with their mobile-money PIN. The full amount is credited to your wallet once the payment confirms (deposits are free), and a callback is fired to your callback URL.

Field		Description
secret_key	required	Your merchant secret key.
phone	required	Customer phone, e.g. 256770000000 or 0770000000.
amount	required	Amount in UGX. Minimum 500.
email	required	Customer email for the receipt.
ref	required	Your unique reference for this transaction.
callback	required	URL we POST the result to.
currency	optional	Defaults to UGX.

# Request
curl -X POST https://api.gosentepay.com/v1/deposit \
  -H "Authorization: Bearer YOUR-TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_key": "YOUR-SECRET-KEY",
    "phone":      "256770000000",
    "amount":     5000,
    "email":      "customer@email.com",
    "ref":        "ORDER-1001",
    "callback":   "https://yoursite.com/gosente-callback"
  }'

# Response
{
  "status": "success",
  "message": "Payment request sent. Please check your phone and approve the prompt.",
  "ref": "ORDER-1001",
  "gateway_reference": "a1b2c3...",
  "amount": 5000, "channel": "Mtn", "code": 200
}

3. Send a withdrawal (disburse)

Sends money from your GosentePay wallet to any MTN/Airtel wallet. Your wallet is debited the amount plus a tiered withdrawal fee (from UGX 1,100) up front; if the transfer fails, the full amount and fee are refunded automatically. Tip: call GET /withdraw-fee?amount=X to preview the fee first.

Field		Description
secret_key	required	Your merchant secret key.
phone	required	Recipient phone number.
amount	required	Amount in UGX. Minimum 500.
email	required	Recipient email.
reason	required	Payment description.
ref	required	Your unique reference.

# Request
curl -X POST https://api.gosentepay.com/v1/withdraw \
  -H "Authorization: Bearer YOUR-TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_key": "YOUR-SECRET-KEY",
    "phone":      "256770000000",
    "amount":     5000,
    "email":      "recipient@email.com",
    "reason":     "Payout for June",
    "ref":        "PAYOUT-77"
  }'

4. Check a transaction status

Poll for the latest status of any deposit or withdrawal by its ref. We verify live with the provider and update our records.

curl -X POST https://api.gosentepay.com/v1/transaction-status \
  -H "Authorization: Bearer YOUR-TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ref": "ORDER-1001" }'

# Response
{ "status": "success", "type": "deposit",
  "transaction_status": "successful", "amount": 5000 }

5. Callbacks (webhooks)

When a transaction settles, we POST JSON to the callback URL you supplied on the deposit. Always respond with HTTP 200. Verify by matching the ref to your records.

# Deposit success callback (sent to YOUR callback URL)
{
  "status": "successful",
  "ref": "ORDER-1001",
  "amount": 5000,     // paid by customer
  "credited": 5000,   // full amount added to your wallet (deposits are free)
  "receipt_number": "..."
}

Error responses

HTTP	status	Meaning
400	missingFields	A required field is missing.
400	invalidAmount	Amount below the UGX 500 minimum.
400	invalidPhone	Not a valid MTN/Airtel Uganda number.
401	invalidToken	Missing or expired Bearer token.
401	invalidKey	Secret key wrong or account inactive.
409	ref_already_used	That ref was already used — use a unique one.

Need help integrating? Contact our team.