DGS-Pay Integration Guide

Getting Started

DGS-Pay is a payment infrastructure layer built specifically for Rwanda. It lets you collect funds from customers via Mobile Money (MTN & Airtel) or card (Visa/Mastercard), disburse to bank accounts and mobile wallets, generate shareable payment links, manage your merchant wallet, and track everything through real-time webhooks and the merchant portal.

All API requests are made over HTTPS to a versioned base URL. You develop against a Sandbox environment that mirrors production but uses simulated money, then switch the base URL to go live — no code changes beyond that.

Base URLs

Every API endpoint is appended to one of these base URLs depending on your environment:

Request Format

All requests must use Content-Type: application/json and include your API credentials in the headers. Here is a minimal example using cURL:

curl -X POST \
  https://pay.digitalservicescenter.rw/generation/v2/charges \
  -H "X-DGS-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "currency": "RWF"
  }'

Authentication

Every DGS-Pay API request requires two headers: your API key and your account number. Both are available in your merchant portal under Settings → API Settings. Test and live environments each have their own separate set of credentials.

Required Headers

Include these on every request:

X-DGS-API-Key: YOUR_DGS_API_KEY
X-DGS-ACCOUNT-NUMBER: YOUR_DGS_ACCOUNT_NUMBER
Content-Type: application/json

cURL Example with Auth

curl -X GET \
  https://pay.digitalservicescenter.rw/generation/v2/balance \
  -H "X-DGS-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-DGS-ACCOUNT-NUMBER: ACC-0001234" \
  -H "Content-Type: application/json"

IP Whitelisting (Production only)

In production you can restrict API access to a specific set of server IP addresses. Any request arriving from an IP not on your whitelist will be rejected with a 91 Auth Error. Configure your allowed IPs in Settings → API Settings in the merchant portal. This feature is not enforced in sandbox.

Environments & Testing

DGS-Pay operates two isolated environments. The sandbox mimics production exactly but uses simulated money — no real funds move. When you are ready to go live, simply swap the base URL. Credentials are environment-specific and must not be mixed.

Simulating Scenarios with scenario_key

In sandbox, you can force specific outcomes by including a scenario_key field in your request body. This saves you from needing real cards, phones, or network responses to test your integration logic.

Example — Approved Card in Sandbox

{
  "scenario_key": "scenario:auth_pin&issuer:approved",
}

Mobile Money API

Collect payments directly from MTN or Airtel Money wallets in Rwanda. When you initiate a charge, the customer receives an STK push prompt on their handset — they enter their PIN to approve, and your webhook is notified of the outcome. No card details or card infrastructure needed.

Mobile Money payments are currently limited to Rwanda (RWF). Multi-currency and additional country support is planned for API v3.

Initiate a Mobile Money Payment

Send a POST /charges request with the customer and payment details. DGS-Pay forwards the STK push to the customer's phone and returns a pending status while waiting for the customer's approval.

curl -X POST \
  https://pay.digitalservicescenter.rw/generation/v2/charges \
  -H "X-DGS-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "currency": "RWF",
    "payment_type": "mobile_money",
    "customer_email": "jane.doe@example.com",
    "customer_first_name": "Jane",
    "customer_last_name": "Doe",
    "customer_phone": "789654321",
    "customer_phone_country_code": "250",
    "redirect_url": "https://yourdomain.com/payment-success",
    "narration": "Payment for Invoice #5678",
    "mobile_money_network": "MTN",
    "mobile_money_phone": "789654321"
  }'

{
  "amount": 2000,
  "currency": "RWF",
  "payment_type": "mobile_money",
  "customer_email": "jane.doe@example.com",
  "customer_first_name": "Jane",
  "customer_last_name": "Doe",
  "customer_phone": "789654321",
  "customer_phone_country_code": "250",
  "redirect_url": "https://yourdomain.com/payment-success",
  "narration": "Payment for Invoice #5678",
  "mobile_money_network": "MTN",
  "mobile_money_phone": "789654321"
}

Response Format

DGS-Pay returns one of three states. The initial response is almost always pending — the payment completes asynchronously when the customer approves or rejects the STK push.

{
  "status": "success",
  "message": "Charge initiated",
  "transaction_id": "123456789",
  "dgs_reference": "dgs_123456789",
  "amount": 2000,
  "currency": "RWF",
  "transaction_status": "pending",
  "payment_method_type": "mobile_money",
  "next_action_type": "redirect_url",
  "next_action_redirect_url": "https://provider.com/authorize",
  "display_text": "Complete payment on your mobile device"
}

{
  "status": "success",
  "message": "Payment completed",
  "transaction_id": "987654321",
  "dgs_reference": "dgs_987654321",
  "amount": 2000,
  "currency": "RWF",
  "transaction_status": "successful",
  "payment_method_type": "mobile_money",
  "mobile_money_network": "MTN",
  "mobile_money_phone": "789654321",
  "mobile_money_country_code": "250"
}

{
  "status": "failed",
  "message": "Charge failed",
  "transaction_id": "123456789",
  "dgs_reference": "dgs_123456789",
  "amount": 2000,
  "currency": "RWF",
  "transaction_status": "failed",
  "payment_method_type": "mobile_money",
  "issuer_response_type": "declined",
  "issuer_response_code": "05",
  "processor_response": "Insufficient funds"
}

Card Payments API

Accept Visa and Mastercard payments with AES-256-GCM client-side encryption. Sensitive card data (number, expiry, CVV) is encrypted in the browser or mobile app before it ever reaches your server. Your server then forwards the encrypted payload to DGS-Pay, which decrypts and processes it securely.

Card Data Encryption

Before sending a charge request you must encrypt all four card fields using your merchant encryption key (from Settings → API Settings). Test and live environments each have a different key.

Encryption Flow

1. Customer fills card form in browser/app
encryptCard() ← runs in browser using DGS Encryption Key
          ↓
2. Browser sends encrypted payload to YOUR server
          ↓
3. Your server forwards encrypted payload to DGS-Pay /charges
          ↓
4. DGS-Pay decrypts with private key and processes payment

JavaScript Encryption Implementation

// Load your encryption key from the merchant dashboard
const ENC_KEY = "YOUR_ENCRYPTION_KEY_FROM_DASHBOARD";

async function importKey(b64) {
  const raw = Uint8Array.from(atob(b64), c => c.charCodeAt(0));
  return crypto.subtle.importKey(
    'raw', raw, { name: 'AES-GCM' }, false, ['encrypt']
  );
}

function hexNonce() {
  // Produces a 12-byte (24 hex char) nonce — required by DGS-Pay
  const bytes = crypto.getRandomValues(new Uint8Array(6));
  return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
}

async function encryptField(plaintext, key, nonce) {
  const iv  = new TextEncoder().encode(nonce);
  const enc = await crypto.subtle.encrypt(
    { name: 'AES-GCM', iv, tagLength: 128 },
    key,
    new TextEncoder().encode(plaintext)
  );
  return btoa(String.fromCharCode(...new Uint8Array(enc)));
}

async function encryptCard(cardNumber, month, year, cvv) {
  const key   = await importKey(ENC_KEY);
  const nonce = hexNonce(); // all four fields share one nonce

  const [encCard, encMon, encYr, encCvv] = await Promise.all([
    encryptField(cardNumber, key, nonce),
    encryptField(month,      key, nonce),
    encryptField(year,       key, nonce),
    encryptField(cvv,        key, nonce),
  ]);

  return {
    card_encrypted_number:       encCard,
    card_encrypted_expiry_month: encMon,
    card_encrypted_expiry_year:  encYr,
    card_encrypted_cvv:          encCvv,
    card_nonce:                  nonce,
  };
}

// Usage example
const payload = await encryptCard("4532123456789010", "12", "2028", "123");
// payload now contains card_encrypted_* fields + card_nonce

Initiate a Card Payment

After encrypting the card fields on the client, send them along with the transaction details to /charges.

curl -X POST \
  https://pay.digitalservicescenter.rw/generation/v2/charges \
  -H "X-DGS-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "RWF",
    "payment_type": "card",
    "customer_email": "john.doe@example.com",
    "customer_first_name": "John",
    "customer_last_name": "Doe",
    "customer_phone": "788123456",
    "customer_phone_country_code": "250",
    "redirect_url": "https://yourdomain.com/payment-success",
    "narration": "Payment for Order #1234",
    "card_encrypted_number": "<encrypted_number>",
    "card_encrypted_expiry_month": "<encrypted_month>",
    "card_encrypted_expiry_year": "<encrypted_year>",
    "card_encrypted_cvv": "<encrypted_cvv>",
    "card_nonce": "<24_hex_nonce>"
  }'

{
  "amount": 5000,
  "currency": "RWF",
  "payment_type": "card",
  "customer_email": "john.doe@example.com",
  "customer_first_name": "John",
  "customer_last_name": "Doe",
  "customer_phone": "788123456",
  "customer_phone_country_code": "250",
  "redirect_url": "https://yourdomain.com/payment-success",
  "narration": "Payment for Order #1234",
  "card_encrypted_number": "<encrypted_number>",
  "card_encrypted_expiry_month": "<encrypted_month>",
  "card_encrypted_expiry_year": "<encrypted_year>",
  "card_encrypted_cvv": "<encrypted_cvv>",
  "card_nonce": "<24_hex_nonce>"
}

Payment Authorization

Some cards require additional verification after the initial charge. The charge response will include a next_action_type field telling you what the customer must do. You then submit their input to /authorize.

{
  "dgs_reference": "dgs_123456789",
  "auth_type": "pin",
  "auth_pin_encrypted": "<base64_encrypted_pin>",
  "auth_pin_nonce": "abc123def456"
}

{
  "dgs_reference": "dgs_123456789",
  "auth_type": "otp",
  "auth_otp": "123456"
}

{
  "dgs_reference": "dgs_123456789",
  "auth_type": "avs",
  "avs_line1": "123 Main Street",
  "avs_line2": "Apt 4B",
  "avs_city": "Kigali",
  "avs_state": "Kigali City",
  "avs_country": "RW",
  "avs_postal_code": "00000"
}

Payment Links

Payment Links let you generate shareable URLs that accept card, mobile money, bank transfer, or USSD payments — without writing a checkout form yourself. Useful for invoices, donations, event tickets, and any scenario where you need to collect money without a custom flow.

Links can be fixed-amount (you set the price) or flexible (the payer chooses within limits). They support use caps, expiry dates, custom slugs, and per-link analytics.

Endpoints

Create a Payment Link

curl -X POST \
  https://pay.digitalservicescenter.rw/generation/v2/payment-links \
  -H "X-DGS-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Invoice #123",
    "amount_type": "fixed",
    "amount": 50000,
    "currency": "RWF",
    "payment_types": ["card", "mobile_money"],
    "max_uses": 1,
    "expires_at": "2026-12-31 23:59:59"
  }'

{
  "title": "Invoice #123",
  "amount_type": "fixed",
  "amount": 50000,
  "currency": "RWF",
  "payment_types": ["card", "mobile_money"],
  "max_uses": 1,
  "expires_at": "2026-12-31 23:59:59"
}

{
  "status": "success",
  "message": "Payment link created",
  "link": {
    "id": "25a5643d-31de-490d-808d-82af72fdd097",
    "slug": "invoice-123",
    "url": "https://pay.digitalservicescenter.rw/generation/pay/invoice-123",
    "title": "Invoice #123",
    "amount_type": "fixed",
    "amount": 50000,
    "currency": "RWF",
    "payment_types": ["card", "mobile_money"],
    "use_count": 0,
    "max_uses": 1,
    "status": "active",
    "expires_at": "2026-12-31 23:59:59",
    "created_at": "2026-04-03 10:00:00"
  }
}

Get Link Details & Stats

curl -X GET \
  https://pay.digitalservicescenter.rw/generation/v2/payment-links/25a5643d-31de-490d-808d-82af72fdd097 \
  -H "X-DGS-API-Key: YOUR_API_KEY"

{
  "status": "success",
  "link": { /* same fields as create response */ },
  "stats": {
    "total_charges": 4,
    "successful_charges": 1,
    "pending_charges": 0,
    "failed_charges": 3,
    "total_collected": 500,
    "currency": "RWF"
  },
  "recent_charges": [
    {
      "id": "5de825d0-...",
      "amount": "500.00",
      "currency": "RWF",
      "status": "success",
      "created_at": "2026-03-09 15:56:32"
    }
  ]
}

Archive (Delete) a Link

{
  "status": "success",
  "message": "Payment link archived"
}

Disburse Funds

The Disbursement API lets you send money from your RWF merchant wallet to a recipient's bank account or mobile money wallet. This is useful for paying out vendors, refunding customers, or distributing salaries.

The merchant's wallet is debited the full amount. A fee is then deducted from the recipient's end — the recipient receives amount − fee. Always verify the amount exceeds the applicable fee before initiating.

curl -X POST \
  https://pay.digitalservicescenter.rw/generation/v2/disburse \
  -H "X-DGS-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "destination_type": "bank",
    "recipient": {
      "bank_key": "kcb_rw",
      "account_number": "1234567890",
      "name": "John Doe",
      "branch": "Kigali Main"
    },
    "narration": "Vendor payment April 2026"
  }'

curl -X POST \
  https://pay.digitalservicescenter.rw/generation/v2/disburse \
  -H "X-DGS-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "destination_type": "mobile_money",
    "recipient": {
      "msisdn": "+250788123456",
      "network": "MTN",
      "country": "RW",
      "name": "Jane Doe"
    }
  }'

Disbursement Webhook

The POST /disburse response only confirms the transfer is queued for processing. The actual outcome — success or failure — is delivered via a webhook after the provider processes the transfer. You must handle this webhook to reliably update your records.

{
  "event": "disbursement.success",
  "dgs_reference": "DGS123456789",
  "flw_transfer_id": 987654,
  "status": "success",
  "amount": 10000,
  "fee": 100,
  "recipient_gets": 9900,
  "currency": "RWF",
  "destination_type": "bank",
  "recipient": {
    "account_number": "1234567890",
    "bank_key": "kcb_rw",
    "name": "John Doe"
  },
  "proof": "FLW-PROOF-123456"
}

{
  "event": "disbursement.failed",
  "dgs_reference": "DGS123456789",
  "flw_transfer_id": 987654,
  "status": "failed",
  "amount": 10000,
  "fee": 100,
  "recipient_gets": 9900,
  "currency": "RWF",
  "destination_type": "mobile_money",
  "fail_reason": "Invalid account details"
}

Idempotent Handler — Pseudocode

Because webhooks can be retried on network failure, your handler must be idempotent. Use dgs_reference as the unique key to detect duplicates.

function handleWebhook(payload) {
  const ref = payload.dgs_reference;

  if (alreadyProcessed(ref)) {
    return HTTP_200; // duplicate — acknowledge but skip
  }

  if (payload.event === "disbursement.success") {
    markTransferSuccess(ref, payload.proof);
  } else if (payload.event === "disbursement.failed") {
    markTransferFailed(ref, payload.fail_reason);
  }

  recordAsProcessed(ref);
  return HTTP_200;
}

List Banks & Providers

Retrieve the current list of supported banks and mobile money providers for a given country. Always use this endpoint dynamically rather than hard-coding bank keys — providers change over time.

curl -X GET \
  https://pay.digitalservicescenter.rw/generation/v2/banks/RW \
  -H "X-DGS-API-Key: YOUR_API_KEY"

{
  "status": "success",
  "country": "RW",
  "data": [
    {
      "bank_key": "bk_rw",
      "name": "Banque de Kigali",
      "type": "bank",
      "code": "40",
      "currency": "RWF",
      "branch_required": 0
    },
    {
      "bank_key": "mtn_rw",
      "name": "MTN Mobile Money",
      "type": "mobile_money",
      "network": "MTN",
      "currency": "RWF",
      "branch_required": 0
    }
  ]
}

Merchant Balances

Retrieve available, pending, and total balances for all currencies in your merchant wallet. Use this before disbursements to verify you have sufficient funds.

curl -X GET \
  https://pay.digitalservicescenter.rw/generation/v2/balance \
  -H "X-DGS-API-Key: YOUR_API_KEY"

{
  "status": "success",
  "error_code": "00",
  "merchant_id": "merchant_uuid",
  "balances": [
    {
      "currency": "USD",
      "pending_balance": 50.00,
      "available_balance": 200.00,
      "total_balance": 250.00
    },
    {
      "currency": "RWF",
      "pending_balance": 1000.00,
      "available_balance": 5000.00,
      "total_balance": 6000.00
    }
  ]
}

Currency Conversion

Convert funds between currencies within your merchant wallet. Use action: "preview" to see the expected conversion amount and rate without moving any money, then call again with action: "convert" to execute.

{
  "status": "success",
  "message": "Conversion preview — no funds moved",
  "from_currency": "USD",
  "from_amount": 100,
  "to_currency": "EUR",
  "to_amount": 94.50,
  "rate": 0.945000,
  "rate_display": "1 USD = 0.9450 EUR",
  "fee": 0
}

{
  "status": "success",
  "message": "Conversion initiated. EUR balance will be credited shortly.",
  "dgs_conversion_ref": "DGSCONV1A2B3C4D",
  "conversion_status": "processing",
  "from_currency": "USD",
  "from_amount": 100,
  "to_currency": "EUR",
  "to_amount": 94.50,
  "rate": 0.945000,
  "fee": 0
}

{
  "status": "failed",
  "message": "Insufficient USD balance",
  "error_code": "VALIDATION_ERROR",
  "available_balance": 50,
  "required": 100,
  "currency": "USD"
}

Conversion Webhook

Sent automatically when a currency conversion changes status. Use this to update your records and reconcile wallet balances.

{
  "event": "conversion.success",
  "dgs_reference": "DGSCONV1A2B3C4D",
  "status": "success",
  "from_currency": "USD",
  "from_amount": 100,
  "to_currency": "EUR",
  "to_amount": 94.50,
  "rate": 0.945,
  "rate_display": "1 USD = 0.9450 EUR"
}

{
  "event": "conversion.failed",
  "dgs_reference": "DGSCONV1A2B3C4D",
  "status": "failed",
  "from_currency": "USD",
  "from_amount": 100,
  "to_currency": "EUR",
  "fail_reason": "Insufficient balance",
  "refund_amount": 100,
  "refund_currency": "USD"
}

Transactions

Retrieve transaction history for your merchant account. You can fetch a paginated list with optional filters, or look up a single transaction by its ID. Transaction records include settlement status, payment method details, and links to the payment link if applicable.

Endpoints

Query Parameters (List)

curl -X GET \
  "https://pay.digitalservicescenter.rw/generation/v2/transactions?page=1&limit=20&status=success" \
  -H "X-DGS-API-Key: YOUR_API_KEY"

curl -X GET \
  https://pay.digitalservicescenter.rw/generation/v2/transactions/dgs-reference \
  -H "X-DGS-API-Key: YOUR_API_KEY"

List Response

{
  "status": "success",
  "data": [
    {
      "id": "uuid1",
      "dgs_reference": "INV-123",
      "amount": 100,
      "currency": "USD",
      "status": "success",
      "payment_method_type": "card",
      "created_at": "2026-04-03 11:00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3
  }
}

Webhooks

Webhooks are HTTP POST requests that DGS-Pay sends to your server when a payment event occurs. They are the reliable mechanism for confirming payment completion — redirect URLs can be blocked or closed by the user, but webhooks are server-to-server.

Configure your webhook URL in the merchant portal under Settings → API Settings. You can also override the URL per-transaction using the callback_url field.

Signature Verification

Every webhook request includes an X-DGS-Signature header. This is an HMAC-SHA256 hash of the raw request body, signed with your Webhook Secret (find it in Settings → API Settings). Always verify this signature before processing any webhook payload — it proves the request came from DGS-Pay and was not tampered with.

<?php
$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_DGS_SIGNATURE'];
$expected  = hash_hmac('sha256', $payload, DGS_WEBHOOK_SECRET);

if (!hash_equals($expected, $signature)) {
  http_response_code(401);
  exit('Unauthorized');
}

$event = json_decode($payload, true);
// Handle $event['event'] here

http_response_code(200);
echo json_encode(['status' => 'received']);
?>

const crypto = require('crypto');

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig      = req.headers['x-dgs-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.DGS_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Unauthorized');
  }

  const event = JSON.parse(req.body);
  // Handle event.event here

  res.json({ status: 'received' });
});

import hmac, hashlib, os
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
  sig      = request.headers.get('X-DGS-Signature', '')
  secret   = os.environ['DGS_WEBHOOK_SECRET'].encode()
  expected = hmac.new(secret, request.data, hashlib.sha256).hexdigest()

  if not hmac.compare_digest(sig, expected):
    return 'Unauthorized', 401

  event = request.get_json()
  # Handle event['event'] here

  return jsonify({ 'status': 'received' })

Payment Event Payloads

{
  "event": "payment.success",
  "dgs_reference": "dgs_123456789",
  "flw_charge_id": "flw_987654321",
  "amount": 5000,
  "currency": "RWF",
  "merchant_fee": 150,
  "net_amount": 4850,
  "status": "success",
  "timestamp": "2026-04-02T10:30:00Z",
  "environment": "production"
}

{
  "event": "payment.failed",
  "dgs_reference": "dgs_123456789",
  "flw_charge_id": "flw_987654321",
  "amount": 5000,
  "currency": "RWF",
  "merchant_fee": 0,
  "net_amount": 0,
  "status": "failed",
  "timestamp": "2026-04-02T10:35:00Z",
  "environment": "production"
}

Error Codes

Every API response includes a status field ("success", "pending", or "failed"). When a request fails at the API level, an error_code field indicates the category of error. Payment-level outcomes (declined card, insufficient mobile money balance) are different — those use transaction_status and processor_response.

Status vs Error Code Explained

These two concepts operate at different layers: