LindaPay API Documentation

Welcome to the LindaPay Developer Platform! Build powerful payment solutions with our comprehensive API.

Table of Contents

• Getting Started
• Authentication
• API Endpoints
• Rate Limits
• Errors
• Webhooks
• SDKs & Libraries

Getting Started

Base URL

Production: https://api.lindapay.com/v1
Sandbox:    https://sandbox-api.lindapay.com/v1

Quick Start

1. Sign up for a LindaPay account
2. Create an API key in your dashboard
3. Make your first request:

curl https://api.lindapay.com/v1/customers \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json"

Authentication

LindaPay uses API keys to authenticate requests. You can manage your API keys in the Dashboard.

API Key Types

• Publishable Keys (pk_live_... or pk_test_...): Use in client-side code. Limited permissions.
• Secret Keys (sk_live_... or sk_test_...): Use in server-side code. Full permissions. Keep these secret!

Making Authenticated Requests

Include your API key in the Authorization header:

Authorization: Bearer sk_live_xxxxxxxxxxxx

Test vs Live Mode

• Test mode: Use test API keys (pk_test_... or sk_test_...) for development
• Live mode: Use live API keys (pk_live_... or sk_live_...) for production

API Endpoints

Customers

Manage your customers and their payment information.

Create a Customer

POST /v1/customers

Request:

{
  "email": "customer@example.com",
  "phone": "+254712345678",
  "firstName": "John",
  "lastName": "Doe",
  "metadata": {
    "internal_id": "cust_12345"
  }
}

Response:

{
  "id": "cus_abc123",
  "email": "customer@example.com",
  "phone": "+254712345678",
  "firstName": "John",
  "lastName": "Doe",
  "status": "ACTIVE",
  "metadata": {
    "internal_id": "cust_12345"
  },
  "createdAt": "2026-03-16T10:00:00Z",
  "updatedAt": "2026-03-16T10:00:00Z"
}

List Customers

GET /v1/customers

Query Parameters:

• page (integer): Page number (default: 1)
• limit (integer): Items per page (default: 20, max: 100)
• search (string): Search by email, name, or phone

Example:

curl "https://api.lindapay.com/v1/customers?page=1&limit=20" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

Get a Customer

GET /v1/customers/:id

Update a Customer

PATCH /v1/customers/:id

Delete a Customer

DELETE /v1/customers/:id

---

Payment Links

Create and manage payment links for easy customer payments.

Create a Payment Link

POST /v1/payment-links

Request:

{
  "amount": 100.00,
  "currency": "USD",
  "description": "Premium Subscription",
  "allowCustomAmount": false,
  "maxUses": 100,
  "expiresAt": "2026-12-31T23:59:59Z",
  "successUrl": "https://yoursite.com/success",
  "cancelUrl": "https://yoursite.com/cancel",
  "metadata": {
    "product_id": "prod_123"
  }
}

Response:

{
  "id": "pl_abc123",
  "slug": "a1b2c3d4e5f6g7h8",
  "url": "https://lindapay.com/pay/a1b2c3d4e5f6g7h8",
  "amount": 100.00,
  "currency": "USD",
  "description": "Premium Subscription",
  "status": "ACTIVE",
  "allowCustomAmount": false,
  "currentUses": 0,
  "maxUses": 100,
  "expiresAt": "2026-12-31T23:59:59Z",
  "createdAt": "2026-03-16T10:00:00Z"
}

List Payment Links

GET /v1/payment-links

Query Parameters:

• page (integer): Page number
• limit (integer): Items per page
• status (string): Filter by status (ACTIVE, INACTIVE, EXPIRED)

---

Payments

Process payments through various payment methods.

Create a Payment

POST /v1/payments

Request:

{
  "amount": 50.00,
  "currency": "USD",
  "customerId": "cus_abc123",
  "connectorId": "conn_stripe_123",
  "description": "Product Purchase",
  "paymentMethod": {
    "type": "CARD",
    "details": {
      "customerEmail": "customer@example.com"
    }
  },
  "successUrl": "https://yoursite.com/success",
  "cancelUrl": "https://yoursite.com/cancel",
  "metadata": {
    "order_id": "ord_456"
  }
}

Response:

{
  "id": "txn_abc123",
  "externalId": "pi_stripe_xyz789",
  "status": "PENDING",
  "amount": 50.00,
  "currency": "USD",
  "message": "Payment initiated",
  "redirectUrl": "https://checkout.stripe.com/...",
  "metadata": {
    "clientSecret": "pi_xxx_secret_yyy"
  }
}

---

Transactions

View transaction history and details.

List Transactions

GET /v1/transactions

Query Parameters:

• page (integer): Page number
• limit (integer): Items per page
• status (string): Filter by status (COMPLETED, PENDING, FAILED)
• type (string): Filter by type (PAYMENT, REFUND, PAYOUT)
• customer_id (string): Filter by customer
• start_date (string): ISO 8601 date
• end_date (string): ISO 8601 date

Example:

curl "https://api.lindapay.com/v1/transactions?status=COMPLETED&start_date=2026-03-01" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

Get a Transaction

GET /v1/transactions/:id

Response:

{
  "id": "txn_abc123",
  "externalId": "pi_stripe_xyz789",
  "type": "PAYMENT",
  "status": "COMPLETED",
  "amount": 50.00,
  "currency": "USD",
  "netAmount": 48.50,
  "platformFee": 1.50,
  "totalFee": 1.50,
  "description": "Product Purchase",
  "customer": {
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "connector": {
    "name": "Stripe",
    "type": "STRIPE"
  },
  "refunds": [],
  "metadata": {
    "order_id": "ord_456"
  },
  "createdAt": "2026-03-16T10:00:00Z",
  "updatedAt": "2026-03-16T10:05:00Z"
}

---

Rate Limits

API requests are rate-limited to ensure system stability:

• Default: 100 requests per minute per API key
• Burst: Up to 200 requests in a 10-second window

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1678963200

If you exceed the rate limit, you'll receive a 429 Too Many Requests response.

---

Errors

LindaPay uses conventional HTTP response codes and returns JSON error objects.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
409	Conflict - Resource already exists
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Common Error Codes

• UNAUTHORIZED: Missing or invalid API key
• INVALID_API_KEY: API key format is invalid
• EXPIRED_API_KEY: API key has expired
• INACTIVE_MERCHANT: Merchant account is not active
• VALIDATION_ERROR: Request validation failed
• NOT_FOUND: Resource not found
• INSUFFICIENT_SCOPE: API key lacks required permissions
• RATE_LIMIT_EXCEEDED: Too many requests

---

Webhooks

Webhooks allow you to receive real-time notifications about events in your account.

Setting Up Webhooks

1. Go to Webhooks Settings
2. Click "Add Endpoint"
3. Enter your webhook URL
4. Select the events you want to receive
5. Save and note the webhook signing secret

Webhook Events

Common events:

• checkout.session.completed
• payment.succeeded
• payment.failed
• refund.created
• customer.created
• customer.updated

Verifying Webhook Signatures

Webhook requests include a Stripe-Signature header. Verify it using your webhook secret:

const crypto = require('crypto');

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

---

SDKs & Libraries

Official SDKs

• Node.js: npm install @lindapay/node
• Python: pip install lindapay
• PHP: composer require lindapay/lindapay-php
• Ruby: gem install lindapay

Quick Example (Node.js)

const LindaPay = require('@lindapay/node');
const lindapay = new LindaPay('sk_live_xxxxxxxxxxxx');

// Create a customer
const customer = await lindapay.customers.create({
  email: 'customer@example.com',
  firstName: 'John',
  lastName: 'Doe'
});

// Create a payment link
const paymentLink = await lindapay.paymentLinks.create({
  amount: 100.00,
  currency: 'USD',
  description: 'Premium Subscription'
});

console.log('Payment URL:', paymentLink.url);

---

Support

Need help? We're here for you:

• Documentation: https://docs.lindapay.com
• API Reference: https://docs.lindapay.com/api
• Support Email: developers@lindapay.com
• Discord Community: https://discord.gg/lindapay
• Status Page: https://status.lindapay.com

---

Changelog

v1.0.0 (2026-03-16)

• Initial API release
• Customer management endpoints
• Payment links
• Payment processing
• Transaction tracking
• Webhook support

---

Built with ❤️ by the LindaPay Team