Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt

Use this file to discover all available pages before exploring further.

Truthlocks automatically routes payments through the best payment provider for your region. This ensures compliance with local regulations, localized currency support, and the highest possible transaction success rates.

​
Country detection

When you reach checkout, your country is detected automatically so you see the correct regional pricing and currency. You don’t need to set your country manually — the billing system resolves it from your account profile and applies the appropriate provider and rate.
If your country is set incorrectly, update it in your account settings before starting a checkout session.

​
Routing logic

​
How routing works

When you initiate a checkout or subscription change, the billing service resolves the payment provider based on your organization’s country code. You do not need to configure this — it is determined automatically from your account settings.
1

Country detection

Your organization’s registered country is read from your tenant profile.
2

Provider resolution

The billing service matches your country code against the routing table to select the optimal provider.
3

Checkout

A checkout session is created with the selected provider in your local currency.

​
Routing table

RegionCountry codesProviderCurrency
NigeriaNGPaystackNGN
Africa (other)GH, KE, ZA, and othersFlutterwaveGHS, KES, ZAR
Global (default)All other countriesStripeUSD
If your country is not explicitly mapped, payments default to Stripe in USD.

​
Supported payment methods

Each provider supports different payment methods depending on the region:
ProviderPayment methods
StripeCredit/debit cards, ACH, wire transfer
PaystackCards, bank transfer, USSD, mobile money
FlutterwaveCards, bank transfer, mobile money, USSD

​
Purchase orders

Enterprise and government customers can pay via purchase order instead of card. Submit a purchase order from the console at Settings > Billing with:
  • A signed PO document (PDF upload)
  • Billing contact and address
  • PO number and expiration date
Your account team reviews and activates the PO. Invoices are then issued against the PO balance.

​
Testing in development

You can simulate different regions during development to verify that the correct provider is selected: 
# Append ?country=CODE to the billing config endpoint
curl https://api.truthlocks.com/v1/billing/config?country=NG \
  -H "X-API-Key: tl_test_..."
The response includes the resolved provider and currency for the given country: 
{
  "provider": "paystack",
  "currency": "NGN",
  "country": "NG",
  "checkout_url": "https://checkout.paystack.com/..."
}
You can also use the DevTools override context in the console to switch regions without modifying API calls.
Country overrides via query parameter are only available in sandbox environments. Production always uses your organization’s registered country.

Billing overview

Plan tiers, rates, and usage management.

Rate limits

API rate limiting by plan tier.