Getting Started with the DGateway API in 5 Minutes

DGateway is a unified payment and commerce platform for Africa that lets you accept mobile money (MTN, Airtel) and card payments through a single API. It also provides tools to sell digital products, courses, and templates — but in this guide, we focus on the API.

Integrating payments should not take weeks. With DGateway, you can go from zero to collecting your first payment in under five minutes. This guide walks you through every step.

Step 1: Create Your Account

Head to dgateway.io and sign up for an account. You will need a valid email address and a phone number. Once you verify your email, you will land on the DGateway dashboard.

The dashboard is your command center. From here you can manage API keys, view transactions, configure webhooks, and monitor provider health. Take a moment to explore, but do not worry about configuring everything right away — the defaults are sensible.

Step 2: Get Your API Keys

Navigate to Settings > API Keys in your dashboard. You will see two sets of credentials:

• Test keys — Use these during development. Transactions made with test keys are simulated and no real money moves.
• Live keys — Use these in production. Transactions are real.

Each set includes a public key and a secret key. The public key identifies your account and can be safely included in client-side code. The secret key must be kept confidential and should only be used on your server.

Copy your test secret key. You will need it for the next step.

Step 3: Make Your First Collection

A collection is a request to receive money from a customer. This is the most common operation for most integrations.

Here is how to initiate a collection using cURL:

curl -X POST https://api.dgateway.io/v1/collections \
  -H "Authorization: Bearer YOUR_TEST_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "UGX",
    "phone_number": "256771234567",
    "provider": "mtn",
    "description": "Test payment",
    "callback_url": "https://your-app.com/webhooks/dgateway",
    "metadata": {
      "order_id": "order_12345"
    }
  }'

Let us break down the request body:

• amount — The amount to collect, in the smallest denomination of the currency (for UGX, this is the full amount since there are no subunits).
• currency — The three-letter currency code. Supported values include UGX, KES, TZS, RWF, and USD.
• phone_number — The customer's mobile money number in international format.
• provider — The payment provider. Options include mtn, airtel, and card. You can also omit this field and let DGateway auto-detect the best provider based on the phone number.
• description — A human-readable description that may appear on the customer's payment prompt.
• callback_url — The URL where DGateway will send webhook notifications about this transaction.
• metadata — An optional object where you can attach your own reference data. DGateway stores this and returns it in webhooks, making it easy to match transactions to your internal records.

The API will respond with a transaction object:

{
  "id": "txn_abc123",
  "status": "pending",
  "amount": 5000,
  "currency": "UGX",
  "provider": "mtn",
  "created_at": "2026-03-30T10:00:00Z"
}

In test mode, the transaction will automatically transition to successful after a few seconds.

Step 4: Handle Webhooks

When a transaction changes status — from pending to successful, failed, or expired — DGateway sends a POST request to your callback URL with the transaction details.

Here is what a webhook payload looks like:

{
  "event": "collection.completed",
  "data": {
    "id": "txn_abc123",
    "status": "successful",
    "amount": 5000,
    "currency": "UGX",
    "provider": "mtn",
    "phone_number": "256771234567",
    "metadata": {
      "order_id": "order_12345"
    },
    "completed_at": "2026-03-30T10:00:05Z"
  }
}

Your webhook handler should:

1. Verify the webhook signature — DGateway signs every webhook with your secret key. Always verify the signature before processing the event. The signature is included in the X-DGateway-Signature header.
2. Check the transaction status — Only fulfill orders for transactions with a successful status.
3. Respond with a 200 status code — This tells DGateway that you received the webhook. If your endpoint returns a non-200 response, DGateway will retry the webhook with exponential backoff.
4. Make your handler idempotent — Webhooks can be delivered more than once. Use the transaction id to ensure you do not process the same event twice.

Here is a minimal webhook handler in Node.js:

app.post("/webhooks/dgateway", (req, res) => {
  const signature = req.headers["x-dgateway-signature"];
 
  if (!verifySignature(req.body, signature, process.env.DGATEWAY_SECRET)) {
    return res.status(401).send("Invalid signature");
  }
 
  const { event, data } = req.body;
 
  if (event === "collection.completed" && data.status === "successful") {
    // Fulfill the order using data.metadata.order_id
    fulfillOrder(data.metadata.order_id);
  }
 
  res.status(200).send("OK");
});

Step 5: Go Live

Once you are confident that your integration works correctly in test mode, switching to production is simple:

1. Replace your test API keys with your live API keys.
2. Ensure your webhook endpoint is publicly accessible and uses HTTPS.
3. Update your callback URL if it differs between environments.

That is it. No separate approval process, no lengthy review. When you are ready, flip the keys and start collecting real payments.

What Comes Next

This guide covered the basics — creating a collection and handling the result via webhooks. But DGateway can do much more:

• Disbursements — Send money to mobile money accounts and bank accounts.
• Subscription billing — Create recurring payment plans.
• Payment links — Generate shareable links that accept payments without any code.
• Transaction queries — Check the status of any transaction at any time via the API.

Explore the full API documentation at docs.dgateway.io and build something great.