API Keys & HTTP Fallback

How to authenticate with Wistfare, when to stay with the SDKs, and how to use curl as a fallback for uncovered endpoints.

This page is the bridge between the SDK-first integration path and direct HTTP access. The rule is simple: use the SDK whenever it covers your workflow, and keep direct HTTP calls as a narrow fallback for the gaps.

Recommended default

Start with the Server SDKs. Reach for direct HTTP only when your chosen SDK does not yet wrap a specific endpoint you need.

What Every Backend Needs

Requirement	Why it matters
Wistfare API key	Authenticates server-to-server requests.
Trusted backend environment	Keeps `wf_live_` and `wf_test_` keys off the browser and mobile clients.
Base URL configuration	Lets you target production, staging, or local gateway environments.
Retry and idempotency strategy	Protects payment and wallet write operations from duplicate side effects.

Configure the SDK Client

Use the same language tabs across the SDK docs to stay in one stack while you read:

import { Wistfare } from '@wistfare/core';

const wf = new Wistfare({
  apiKey: process.env.WISTFARE_API_KEY!,
  baseUrl: 'https://api-production.wistfare.com',
});

from wistfare import Wistfare

wf = Wistfare(
    api_key="wf_live_xxx",
    base_url="https://api-production.wistfare.com",
)

import "github.com/wistfare/wistfare-go/core"

client := core.New("wf_live_xxx")

import 'package:wistfare_core/wistfare_core.dart';

final wf = Wistfare(
  apiKey: 'wf_live_xxx',
  baseUrl: 'https://api-production.wistfare.com',
);

use wistfare::Wistfare;

let client = Wistfare::new("wf_live_xxx")?;

import Wistfare

let client = try Wistfare(
  apiKey: "wf_live_xxx",
  baseURL: URL(string: "https://api-production.wistfare.com")!
)

import com.wistfare.sdk.Wistfare
import com.wistfare.sdk.WistfareConfig

val client = Wistfare(
    WistfareConfig(
        apiKey = "wf_live_xxx",
        baseUrl = "https://api-production.wistfare.com",
    )
)

using Wistfare.Core;

var client = new WistfareClient(new WistfareOptions
{
    ApiKey = Environment.GetEnvironmentVariable("WISTFARE_API_KEY")!,
    BaseUrl = "https://api-production.wistfare.com",
});

curl Fallback Example

When you need one endpoint before your SDK catches up, call the platform directly with the same API key:

curl -X POST https://api-production.wistfare.com/v1/collections \
  -H "X-API-Key: wf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "biz_123",
    "walletId": "wal_456",
    "customerPhone": "250788000000",
    "amount": "10000",
    "paymentMethod": "mtn",
    "currency": "RWF",
    "description": "Invoice #1234"
  }'

When HTTP Fallback Is a Good Idea

You need one endpoint that is not yet wrapped by your SDK.
You are validating a new API contract before the SDK adds first-class helpers.
You want to smoke-test an environment quickly with curl before debugging application code.

When HTTP Fallback Is the Wrong Default

When the SDK already supports the workflow you need.
When you would need to manually recreate retries, errors, or pagination logic the SDK already handles.
When the request performs money movement or other important write operations and you have not built idempotency protections around it.

Common Headers

Header	Purpose
`X-API-Key`	Required server-to-server authentication header.
`Content-Type: application/json`	Required for JSON request bodies.
`Accept: application/json`	Recommended for predictable response handling.

Environment Guidance

Use wf_test_* keys in development and staging.
Use wf_live_* keys only in production.
Store keys in your server environment manager, not in source code.
Rotate keys when team ownership changes or when a secret has been exposed.