API Documentation

API Authentication

All DGS API endpoints require Bearer Token authentication. Include your token in the Authorization header for every request.

Authentication Header

Authorization: Bearer YOUR_DGS_API_TOKEN
Content-Type: application/json
    

Base URL

https://pay.digitalservicescenter.rw/api-v2
    

Requesting a Token

Use the following endpoint to request a token for sandbox or live environments:

Example Request (PHP)

<?php
$data = [
    'account_number' => 'ACC-2322-0001',
    'client_secret' => 'sk_sandbox_abc123yoursandboxkey'
];

$ch = curl_init('https://pay.digitalservicescenter.rw/api-v2/api/auth/token');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

$tokenData = json_decode($response, true);

if (isset($tokenData['access_token'])) {
    $accessToken = $tokenData['access_token'];
    echo "Token: " . $accessToken;
} else {
    echo "Error: " . ($tokenData['error'] ?? 'Unknown error');
}
?>

Example Request (Node.js)

const fetch = require('node-fetch');

async function getToken() {
  const response = await fetch(
    'https://pay.digitalservicescenter.rw/api-v2/api/auth/token', 
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        account_number: 'ACC-2322-0001',
        client_secret: 'sk_sandbox_abc123yoursandboxkey'
      })
    }
  );

  const data = await response.json();
  if (data.access_token) {
    console.log('Token:', data.access_token);
  } else {
    console.log('Error:', data.error || 'Unknown error');
  }
}

getToken();
    

Token Refresh (PHP)

<?php
// Check if token exists and is still valid
$tokenFile = '/path/to/token.json';
$refreshToken = true;

if (file_exists($tokenFile)) {
    $saved = json_decode(file_get_contents($tokenFile), true);
    if (isset($saved['expires_at']) && time() < $saved['expires_at']) {
        $accessToken = $saved['access_token'];
        $refreshToken = false;
    }
}

if ($refreshToken) {
    // Request new token as before
    $data = [
        'account_number' => 'ACC-2322-0001',
        'client_secret' => 'sk_sandbox_abc123yoursandboxkey'
    ];
    $ch = curl_init('https://pay.digitalservicescenter.rw/api-v2/api/auth/token');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    $response = curl_exec($ch);
    curl_close($ch);

    $tokenData = json_decode($response, true);
    if (isset($tokenData['access_token'])) {
        $accessToken = $tokenData['access_token'];
        $tokenData['expires_at'] = time() + 600;
        file_put_contents($tokenFile, json_encode($tokenData));
    } else {
        echo "Error refreshing token: " . ($tokenData['error'] ?? 'Unknown error');
    }
}
echo "Current token: $accessToken";
?>

Token Refresh (Node.js)

// Token refresh example
const fs = require('fs');
const fetch = require('node-fetch');
const tokenFile = './token.json';

async function getToken() {
  let accessToken;
  let refresh = true;

  if (fs.existsSync(tokenFile)) {
    const saved = JSON.parse(fs.readFileSync(tokenFile));
    if (saved.expires_at && Date.now() / 1000 < saved.expires_at) {
      accessToken = saved.access_token;
      refresh = false;
    }
  }

  if (refresh) {
    const response = await fetch(
      'https://pay.digitalservicescenter.rw/api-v2/api/auth/token',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          account_number: 'ACC-2322-0001',
          client_secret: 'sk_sandbox_abc123yoursandboxkey'
        })
      }
    );
    const data = await response.json();
    if (data.access_token) {
      accessToken = data.access_token;
      data.expires_at = Math.floor(Date.now() / 1000) + 600;
      fs.writeFileSync(tokenFile, JSON.stringify(data));
    } else {
      console.log('Error refreshing token:', data.error || 'Unknown error');
    }
  }

  console.log('Current token:', accessToken);
}

getToken();
    

Mobile Money API

The Mobile Money API allows you to collect payments from customers across supported African countries using local mobile money providers. Each country supports specific providers and a fixed currency. Using an unsupported provider, country code, or currency will result in a failed transaction.

Supported Countries & Providers

Initiate Mobile Money Payment

Use this endpoint to collect funds via mobile money. Always provide the correct currency, country code, and provider for successful processing.

Request Parameters

Complete Request Example

{
  "pay_info": {
    "amount": 100,
    "currency": "RWF",
    "api_code": "PAYIN_MOBILE",
    "reference": "MMTEST001",
    "callback_url": "https://your-callback.url",
    "description": "Test Mobile Money Payment"
  },
  "from": {
    "payment_type": "mobile_money",
    "provider": "MTN",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "782589800",
    "country_code": "250"
  },
  "metadata": {
    "order_id": "12345",
    "custom_info": "DGS Mobile Money Test"
  },
  "simulation": {
    "context": "auth_pin",
    "response": "approved"
  }
}

Response Format

Pending/Success Response

{
  "status": "pending",
  "message": "Charge created",
  "code": "02",
  "transaction_id": 100,
  "tx_ref": "MM1764319676",
  "payment_type": "mobile_money",
  "amount": 550,
  "currency": "RWF",
  "customer_id": "cus_haqG7fRTfv",
  "reference": "MM1764319676",
  "network": "MTN",
  "phone_number": "0782589800",
  "fee": 39,
  "next_action": {
    "type": "payment_instruction",
    "note": "Please authorise this payment on your mobile device..."
  }
}

Error Response

{
  "status": "failed",
  "message": "Request is not valid",
  "code": "10400",
  "transaction_id": 95,
  "tx_ref": "MM_1764318847",
  "payment_type": "mobile_money",
  "errors": {
    "reference": "must be an alphanumeric string"
  }
}

Webhook Handling

DGS sends final payment status updates to your configured callback_url. All webhook requests include a HTTP_DGS_WEBHOOK_SECRET header for verification.

Webhook Security

// Example webhook verification
$webhookSecret = $_SERVER['HTTP_DGS_WEBHOOK_SECRET'];
if ($webhookSecret !== 'YOUR_WEBHOOK_SECRET') {
    http_response_code(401);
    exit('Unauthorized');
}

Card Payments API

Secure card processing with AES-256-CBC encryption, supporting VISA, Mastercard, and local card networks with comprehensive fraud protection.

Card Data Encryption & PCI Compliance

DGS-Pay uses a secure, PCI-aligned encryption model similar to Flutterwave and Stripe. Raw card details must never reach the merchant server. All sensitive card data must be encrypted on the client side using the DGS-Pay public key before being sent to any API.

Encryption Model

DGS-Pay uses an asymmetric encryption model:

• Public Key: Used on frontend (safe to expose)
• Private Key: Stored securely by DGS-Pay only
• Merchant Server: Never decrypts card data
• DGS-Pay: Decrypts and processes payments

Recommended Data Flow

Customer Browser / App
        ↓
Encrypt card data using DGS-Pay Public Key
        ↓
Send encrypted payload to Merchant Server (or directly to DGS-Pay)
        ↓
Merchant Server forwards encrypted data unchanged
        ↓
DGS-Pay decrypts using Private Key
        ↓
Payment Processing

Fields That Must Be Encrypted

• Card Number (PAN)
• Expiry Month
• Expiry Year
• CVV
• PIN (when required)

Plaintext Payload (Before Encryption)

{
  "card_number": "4532123456789010",
  "expiry_month": "01",
  "expiry_year": "2028",
  "cvv": "123",
  "pin": "0000"
}

Encrypted Payload Sent to API

{
  "encrypted_card_data": "ENCRYPTED_STRING"
}

JavaScript Encryption Example

const encryptor = new JSEncrypt();
encryptor.setPublicKey(DGS_PUBLIC_KEY);

const cardPayload = JSON.stringify({
  card_number: "4532123456789010",
  expiry_month: "01",
  expiry_year: "2028",
  cvv: "123",
  pin: "0000"
});

const encryptedCardData = encryptor.encrypt(cardPayload);

Initialize Card Payment

Start a card payment transaction with encrypted card details. This endpoint handles the initial payment request and returns the payment status.

Request Example

{
  "pay_info": {
    "amount": 100,
    "currency": "USD",
    "api_code": "PAYIN_CARD_LOCAL",
    "callback_url": "https://my-callback.test",
    "description": "Test Card Payment"
  },
  "from": {
    "payment_type": "card",
    "provider": "VISA",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "782589800",
    "country_code": "1",
    "encrypted_card_data": "COMBINATION OF ENCRYPTED DATA. FROM CARD NUMBER, CVV, EXPIRY MONTH AND YEAR"
  },
  "metadata": {
    "order_id": "12345",
    "custom_info": "DGS test"
  }
}

Response - Requires PIN

{
  "status": "pending",
  "charge_id": "chg_ABC123XYZ",
  "transaction_id": "chg_ABC123XYZ",
  "amount": 150,
  "currency": "USD",
  "customer_id": "cus_ABC123XYZ",
  "reference": "DGS-1764359999-8888",
  "processor_code": "02",
  "next_action": {
    "type": "requires_pin",
    "requires_pin": true
  }
}

Payment Authorization

Complete additional verification steps required by the card issuer, such as PIN, OTP, or address verification.

PIN Authorization

{
  "charge_id": "chg_xxxx",
  "method": "pin",
  "fields": {
    "encrypted_pin": ""
  }
}

OTP Authorization

{
  "charge_id": "chg_xxxx",
  "method": "otp",
  "fields": {
    "code": "123456"
  }
}

AVS Verification

{
  "charge_id": "chg_xxxx",
  "method": "avs",
  "fields": {
    "city": "Gotham",
    "state": "Colorado",
    "line1": "221B Baker Street",
    "country": "US",
    "postal_code": "94105"
  }
}

Multi-Step Authentication

Some card issuers require multiple verification steps. Your integration must handle next_action responses and continue authorization until completion.

Payout & Disbursement API

Send money securely to bank accounts and mobile wallets across Rwanda. For international payouts, our team is ready to assist with tailored cross-border transfer solutions.

Payout / Disbursement Flow

Payouts on DGS Pay follow a clear two-step process: an immediate acknowledgement followed by a final webhook notification once the transfer is completed or fails.

Bank Payout Example

{
  "pay_info": {
    "api_code": "PAYOUT_BANK",
    "amount": 1000,
    "source_currency": "RWF",
    "destination_currency": "RWF",
    "callback_url": "https://your-domain.com/webhook",
    "description": "Vendor payout",
    "reference": "REF87287328787"
  },
  "to": {
    "bank": {
      "account_number": "18287377638728",
      "bank_code_name": "access_rwanda",
      "first_name": "Client first name",
      "last_name": "Client last name",
      "email": "Client Email"
    }
  },
  "type": "bank",
  "action": "instant",
  "simulation": {
    "context": "successful"
  }
}

Mobile Money Payout Example

{
  "pay_info": {
    "api_code": "PAYOUT_MOBILE_MONEY",
    "amount": 1000,
    "source_currency": "RWF",
    "destination_currency": "RWF",
    "callback_url": "https://your-domain.com/webhook",
    "description": "Vendor mobile money payout",
    "reference": "REF87287328787"
  },
  "to": {
    "mobile_money": {
      "phone_number": "250788123456",
      "provider": "MTN",
      "country": "RW",
      "first_name": "Client first name",
      "last_name": "Client last name",
      "email": "Client Email"
    }
  },
  "type": "mobile_money",
  "action": "instant",
  "simulation": {
    "context": "successful"
  }
}

Immediate Response (Acknowledgement)

{
  "status": "NEW",
  "message": "Transfer created",
  "code": null,
  "transfer_id": "trf_7nyftY7EzWWgv7",
  "transaction_id": 97,
  "tx_ref": "DGSPAYOUT176588029657501",
  "payout_type": "bank",
  "amount": 1000,
  "currency": "RWF",
  "fee": 500,
  "created_at": "2025-12-16T10:18:16.788Z",
  "bank": {
    "account_number": "2323389387",
    "bank_code": "30",
    "branch": " ",
    "account_name": "Customer Payout"
  }
}

Bank Payout Success Webhook

{
  "event": "transaction.completed",
  "status": "success",
  "direction": "disbursement",
  "reference": "5748745ug8ufdgjhveyebjhcdbchb",
  "transaction_id": "trf_yMZATJ11yVPNkZ",
  "amount": 50000,
  "currency": "RWF",
  "fee": 500,
  "net_amount": 49500,
  "payout_type": "bank",
  "beneficiary": {
    "type": "bank",
    "account_number": "0122333334",
    "bank_code": "044",
    "branch": " ",
    "name": null
  },
  "actual_debit_amount": 50000,
  "vat": 3750,
  "rate_used": 0.00123,
  "metadata": {},
  "proof": "504828363550713897092362940989"
}

Wallet & Transactions API

Retrieve your wallet balances across multiple currencies, including withdrawable and pending funds, list all transactions, and check individual transaction status. This API is settlement-aware and designed for delayed provider payouts.

Request Parameters

Get All Wallet Balances

curl -X POST "https://pay.digitalservicescenter.rw/api-v2/api/wallet" \
-H "Authorization: Bearer YOUR_DGS_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"balance"}'

Response

{
  "status": "success",
  "environment": "live",
  "wallets": [
    {
      "currency": "RWF",
      "balance": 150000.00,
      "withdrawable_balance": 120000.00,
      "pending_balance": 30000.00,
      "total_incoming": 200000.00,
      "total_outgoing": 50000.00,
      "net_incoming": 200000.00,
      "net_outgoing": 50000.00
    }
  ]
}

Get Single Currency Wallet

curl -X POST "https://pay.digitalservicescenter.rw/api-v2/api/wallet" \
-H "Authorization: Bearer YOUR_DGS_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"balance_single","currency":"RWF"}'

{
  "status": "success",
  "wallet": {
    "currency": "RWF",
    "balance": 150000.00,
    "withdrawable_balance": 120000.00,
    "pending_balance": 30000.00,
    "total_incoming": 200000.00,
    "total_outgoing": 50000.00,
    "net_incoming": 200000.00,
    "net_outgoing": 50000.00
  }
}

List Transactions

curl -X POST "https://pay.digitalservicescenter.rw/api-v2/api/wallet" \
-H "Authorization: Bearer YOUR_DGS_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"transaction_list","limit":20,"offset":0}'

{
  "status": "success",
  "limit": 20,
  "offset": 0,
  "count": 1,
  "transactions": [
    {
      "id": 102,
      "direction": "collection",
      "reference": "TXN-2025-0002",
      "currency": "USD",
      "base_amount": 100.00,
      "charged_amount": 102.00,
      "total_fee": 2.00,
      "client_net_amount": 100.00,
      "status": "successful",
      "created_at": "2025-01-10 14:21:10",
      "updated_at": "2025-01-10 14:22:02"
    }
  ]
}

Get Transaction Status

curl -X POST "https://pay.digitalservicescenter.rw/api-v2/api/wallet" \
-H "Authorization: Bearer YOUR_DGS_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"transaction_status","reference":"TXN-2025-0002"}'

{
  "status": "success",
  "transaction": {
    "id": 102,
    "direction": "collection",
    "reference": "TXN-2025-0002",
    "currency": "RWF",
    "base_amount": 100.00,
    "charged_amount": 102.00,
    "total_fee": 2.00,
    "client_net_amount": 100.00,
    "status": "successful",
    "created_at": "2025-01-10 14:21:10",
    "updated_at": "2025-01-10 14:22:02"
  }
}

Testing & Simulation

DGS Pay provides comprehensive simulation capabilities to test payment flows without real transactions.

Simulation Context Values

Simulation Response Options

Payout Simulation Context

Simulation Example

{

  "simulation": {
    "context": "auth_pin",
    "response": "approved"
  }
}

Error Codes