API Integration Guide

A step-by-step guide for merchants to integrate the Danipa Payment API into their website or application.

Overview

This guide walks you through integrating Danipa payments into your website or application. By the end, you'll be able to accept payments from customers using mobile money and Danipa wallets.

Prerequisites:

• A Danipa merchant account
• Basic programming knowledge (examples are in cURL, Node.js, and Python)
• For full API reference, see the Developer Documentation

Step 1 — Get Your API Keys

1. Log in to the Merchant Dashboard at merchant.danipa.com
2. Go to Settings → API Keys
3. You'll see two environments:

4. Click Generate Key for each environment
5. Copy and securely store your:
   • API Key — used in the Authorization header
   • API Secret — used for webhook signature verification

Important: Your API Secret is shown only once. If you lose it, you'll need to regenerate your keys.

Step 2 — Test Connectivity

Verify your keys work by calling the health endpoint:

curl https://sandbox.api.danipa.com/ms/v1/health \
  -H "Authorization: Bearer YOUR_SANDBOX_API_KEY"

Expected response:

{
  "status": "healthy",
  "version": "1.0.0",
  "environment": "sandbox"
}

Step 3 — Create a Payment Link via API

The simplest integration — create a payment link and redirect your customer to it.

curl -X POST https://sandbox.api.danipa.com/ms/v1/payment-links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Order #1234",
    "amount": 150.00,
    "currency": "GHS",
    "description": "Payment for 3x widgets",
    "redirect_url": "https://yoursite.com/payment/success",
    "cancel_url": "https://yoursite.com/payment/cancel"
  }'

Response:

{
  "id": "pl_abc123",
  "url": "https://pay.danipa.com/pl_abc123",
  "status": "active",
  "amount": 150.00,
  "currency": "GHS",
  "created_at": "2026-03-15T10:30:00Z"
}

Redirect your customer to the url — they'll see a Danipa-branded payment page where they can complete the payment.

Step 4 — Set Up Webhooks

Webhooks notify your server when a payment is completed (or fails), so you can fulfill orders automatically.

Register a Webhook URL

1. Go to Merchant Dashboard → Settings → Webhooks
2. Click Add Endpoint
3. Enter your webhook URL (e.g., https://yoursite.com/api/webhooks/danipa)
4. Select the events you want to receive:
   • payment.completed
   • payment.failed
   • invoice.paid
   • payout.completed
5. Click Save

Webhook Payload

When a payment completes, Danipa sends a POST request to your URL:

{
  "event": "payment.completed",
  "data": {
    "id": "txn_xyz789",
    "payment_link_id": "pl_abc123",
    "amount": 150.00,
    "currency": "GHS",
    "customer": {
      "name": "Kwame Mensah",
      "phone": "+233241234567"
    },
    "status": "completed",
    "completed_at": "2026-03-15T10:35:22Z"
  },
  "timestamp": "2026-03-15T10:35:23Z"
}

Verifying Webhook Signatures

Always verify that webhooks are genuinely from Danipa by checking the signature:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post('/api/webhooks/danipa', (req, res) => {
  const signature = req.headers['x-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.DANIPA_WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  const { event, data } = req.body;
  if (event === 'payment.completed') {
    // Fulfill the order
  }

  res.status(200).send('OK');
});

Important: Always respond with a 200 status within 30 seconds, or Danipa will retry the webhook.

Step 5 — Create Invoices via API

For more detailed billing:

curl -X POST https://sandbox.api.danipa.com/ms/v1/invoices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Ama Darko",
    "customer_email": "ama@example.com",
    "due_date": "2026-04-01",
    "items": [
      {
        "description": "Web design services",
        "quantity": 1,
        "unit_price": 2000.00
      },
      {
        "description": "Hosting (3 months)",
        "quantity": 3,
        "unit_price": 50.00
      }
    ],
    "tax_rate": 0,
    "notes": "Payment due within 15 days"
  }'

Step 6 — Go Live

When you're ready to accept real payments:

1. Test thoroughly in sandbox — try successful payments, failed payments, and webhook handling
2. Replace your sandbox API key with your production API key
3. Update the base URL to https://api.danipa.com/ms/v1
4. Update your webhook URL if different for production
5. Make a small test payment (GHS 1) to verify everything works

Go-Live Checklist

• Webhook signature verification is implemented
• Your server responds to webhooks within 30 seconds
• Error handling covers failed payments and network issues
• Customer receives confirmation after successful payment
• Order fulfillment is triggered by webhook, not by redirect (redirects can be unreliable)
• Production API key is stored securely (environment variable, not in code)
• HTTPS is enabled on your webhook endpoint

SDKs

Danipa provides official SDKs for faster integration:

See the SDKs documentation for detailed usage.

Common Integration Patterns

E-commerce Checkout

1. Customer adds items to cart
2. Your server creates a payment link via API
3. Redirect customer to the payment URL
4. Customer pays on Danipa's page
5. Danipa sends a webhook to your server
6. Your server fulfills the order and redirects customer to success page

Subscription Billing

1. Create a recurring invoice via API on each billing cycle
2. Customer receives email/SMS with payment link
3. Webhook notifies you when paid
4. If unpaid after due date, send reminder or suspend service

In-App Payments

1. Your mobile app calls your backend to create a payment link
2. Open the payment URL in a webview or external browser
3. After payment, Danipa redirects back to your app
4. Webhook confirms payment on your backend

Need Help?

• Developer documentation: API Reference | API Explorer
• SDKs & code examples: SDKs
• Webhook guide: Webhooks
• Developer support: developers@danipa.com