API Reference

Feasable Payments API

RESTful payment infrastructure for Namibian commerce. Create checkout sessions, retrieve transaction state, and receive signed webhooks. All endpoints are authenticated via Bearer tokens and protected by idempotency keys.

Quick Start

install.ts

npm install @feasable/node

import { Feasable } from "@feasable/node";

const feasable = new Feasable(process.env.FEASABLE_KEY);

// Create a checkout sessionconst session = await feasable.checkout.create({amount: 15000,currency: "NAD",success_url: "https://yoursite.com/success",});

// Redirect the customerres.redirect(session.checkout_url);

Authentication

All API requests require a Bearer token in the Authorization header. API keys are prefixed by environment: sk_sandbox_ for testing, sk_live_ for production. Keys are scoped per-merchant and enforce Row-Level Security at the database layer.

curl https://api.feasable.org/v1/transactions \-H "Authorization: Bearer sk_live_..." \-H "Content-Type: application/json"

Endpoints

POST/v1/checkout/sessions

Initiates a new checkout session. Returns a hosted checkout URL where the customer selects a payment method and is redirected to the gateway.

Request Body

{
  "amount": 15000,
  "currency": "NAD",
  "success_url": "https://yoursite.com/success",
  "cancel_url": "https://yoursite.com/cancel",
  "metadata": {
    "order_id": "ORD-2026-001"
  }
}

Response

{
  "session_id": "cs_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "checkout_url": "https://pay.feasable.org/cs_a1b2c3d4-..."
}

Webhook Events

Outbound webhooks are signed with HMAC-SHA256 and delivered via a serverless queue with automatic retries and exponential backoff. Every payload includes a unique event ID for idempotency.

transaction.succeededPayment confirmed by gateway. Funds captured.

transaction.failedPayment declined or errored at the gateway level.

transaction.reversedRefund or chargeback processed on a prior transaction.

transaction.expiredSession TTL exceeded (24hr) without completion.

checkout.cancelledCustomer explicitly cancelled the checkout flow.

Webhook Payload

{
  "event_type": "transaction.succeeded",
  "event_id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2026-05-31T00:15:00Z",
  "data": {
    "transaction_id": "txn_...",
    "amount": 15000,
    "currency": "NAD",
    "provider": "dpo",
    "provider_reference": "DPO-REF-12345"
  }
}

Error Codes

400Bad RequestInvalid request body or missing required fields.

401UnauthorizedMissing or invalid API key.

402Payment RequiredRouting fee cannot be calculated, merchant configuration incomplete.

409ConflictIdempotency key already used with different parameters.

429Rate LimitedToken-bucket limit exceeded for this API key.

503Provider UnavailableAll configured payment providers failed or timed out.

SDKs & Libraries

Node.js

npm install @feasable/node

Python

pip install feasable

PHP

composer require feasable/payments