Quick Start Guide

Get started with Lipachap in under 5 minutes. This guide will walk you through making your first API call.

Step 1: Get Your API Keys

1. Create a merchant account on Lipachap
2. Navigate to Settings → API Keys in your dashboard
3. Copy your TEST API Key and API Secret
4. Store them securely in environment variables

Step 2: Set Environment Variables

LIPACHAP_BASE_URL=https://sandbox.api.lipachap.com
LIPACHAP_API_KEY=your_test_api_key_here
LIPACHAP_API_SECRET=your_test_api_secret_here

Step 3: Authenticate Your Request

Lipachap uses GATEWAY authentication. Here's how to sign your requests:

const crypto = require("crypto");

// digest = sha256(apiSecret + requestPath + rawRequestBody)
const digest = crypto.createHash("sha256")
  .update(apiSecret + "/api/v1/gateway/payments/cashin" + rawBody)
  .digest("hex");

// token = base64(apiKey + ":" + digest)
const authorization = "GATEWAY " + Buffer.from(`${apiKey}:${digest}`).toString("base64");

Step 4: Make Your First Payment Request

Let's collect 10,000 TZS from a customer:

curl -X POST https://sandbox.api.lipachap.com/api/v1/gateway/payments/cashin \
  -H "Content-Type: application/json" \
  -H "Authorization: GATEWAY <base64_token>" \
  -d '{
    "transid": "ORDER-12345",
    "amount": 10000,
    "msisdn": "255712345678",
    "utilityref": "INVOICE-001"
  }'

Step 5: Check Transaction Status

const statusPath = '/api/v1/gateway/payments/status';
const statusBody = { transid: 'TEST-1701234567890' };

const statusResponse = await fetch(baseUrl + statusPath, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': createAuthHeader(apiKey, apiSecret, statusPath, statusBody)
  },
  body: JSON.stringify(statusBody)
});

const status = await statusResponse.json();
console.log(status.status); // PENDING, SUCCESS, or FAILED

Step 6: Set Up Webhooks (Recommended)

Instead of polling for status, receive real-time notifications:

1. Go to Settings → Webhooks in your dashboard
2. Add your webhook URL (e.g., https://yourapi.com/webhooks/lipachap)
3. Save the webhook secret for signature verification
4. Implement the webhook handler (see Webhooks documentation)

What's Next?