Developer Onboarding

Get started with FootBridge

FootBridge is Ghana’s MASLOC payment & verification ecosystem. Follow these five steps to register, obtain your credentials, make your first API call, and find help when you need it.

How to onboard

Five steps to your first integration

Everything below happens once — credentials are provisioned up front and stay stable for the life of your integration.

  1. Register as a client

    Contact the MASLOC administration team to register your application. You will receive:

    • A Client ID (GUID)
    • An API Key (random string)
    • Optionally, a Client Secret for token requests

    These credentials are provisioned once and remain static for your integration.

    If you already have them, skip ahead to step 2.

  2. Obtain your JWT audience & scope

    Each FootBridge API expects a JSON Web Token (JWT) with a specific audience claim:

    • footbridge:billpayments — ECG / Bill Payments API
    • footbridge:collections — Gra / Collections API
    • footbridge:mmapi — Mobile Money API
    • footbridge:identity-verification — Identity Verification API

    The audience is configured per-client in the gateway. Request the appropriate audience when you register.

  3. Call the APIs through the gateway

    All API calls go through the YARP gateway at https://gateway-host:7179 (or your deployed endpoint). The gateway validates two edge headers:

    • X-API-KEY — your provisioned API key
    • X-Client-Id — your client GUID

    The gateway then internally adds a short-lived JWT (X-FootBridge-Authorization) and forwards the request to the backend service. You don’t generate or manage JWTs yourself.

    Example cURL — an ECG prepaid card inquiry:

    curl -X POST "https://gateway-host:7179/billpayments/ecg/v1/prepaid/card/inquiry" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -H "X-Client-Id: <YOUR_CLIENT_GUID>" \
  -d '{"merchant":"ECG","request":{"asyncRequestId":"636ea0f4-649a-4907-9f64-bfa246f27576"},"card":{"cardId":null,"cardBuffer":{}},"meter":{"meterSerial":"P101084105","meterProvider":"ECash","meterModel":null,"regionId":"1001","districtId":"1060"}}'