Skip to content
PayDirect Docs

Docs › Getting started

Introduction

What the PayDirect API does, how these docs are organised, and the handful of facts that apply to every request you will make.

PayDirect is a payments API for Ghana. One integration gives you mobile money and card collections, bank and wallet payouts, bill payments, a hosted checkout page you do not have to build, and a per-integrator ledger you can withdraw from.

Everything is an HTTPS JSON API with signed requests. There is no SDK to install and nothing to run on your side beyond an HTTP client and, if you want push updates, a webhook endpoint.

What you can build

If you want to… Start here
Charge a customer's mobile money wallet Collections
Take card or wallet payments on a page we host for you Hosted checkout
Pay a vendor, supplier or beneficiary Payouts
Pay a utility, ISP or other biller on a customer's behalf Bill payments
Move your accrued balance to your own bank account Withdrawals
Be told when a payment resolves, instead of polling Webhooks

How these docs are organised

  • Getting started - onboarding, credentials, signing a request, the sandbox and IP allowlisting. Read this once, in order.
  • Core concepts - the envelope, idempotency, transaction states, charges, the ledger, rate limits. These apply to every endpoint, so each payment guide assumes them rather than repeating them.
  • Accepting payments / Sending money - one guide per money-movement flow.
  • Webhooks - receiving and verifying outcome events.
  • Reference - a reconciliation playbook, the go-live checklist, the changelog, security practices and how to reach support.

The API reference is separate: an interactive OpenAPI browser with every endpoint, every field and a working "Try it out". These guides explain why and when; the reference is the exhaustive what. It sits behind a login - ask us if you do not have one yet.

The three facts that apply everywhere

1. One base URL, versioned

text
https://<your-assigned-host>/api/v1

Every path in these guides is relative to that prefix. POST /transactions/collect means POST https://<host>/api/v1/transactions/collect.

The version is part of the path, so a new version can never change the behaviour of code you have already shipped - your requests keep going to /api/v1 until you change them yourself. These guides document v1; if another version exists, the switcher at the top of the page moves between them.

2. Every response uses the same envelope

Success and failure share one shape, so your client can parse one thing:

json
{
  "code": 200,
  "status": "success",
  "message": "Action completed successfully",
  "data": { "id": "3f9a…", "status": "PENDING" }
}

status is "success" or "error". data carries the result, and is absent on most errors.

Warning

On money-movement endpoints a 200 can carry "status": "error" - that is a payment that reached the rail and definitively failed. Always read data.status, never infer success from the HTTP code alone. Errors and status codes has the full table.

3. Every request is signed

There is no bearer token to paste and no key sent in a header for us to compare. You send your public key, a timestamp and an HMAC signature computed with your secret key, which never leaves your server. Authentication shows exactly how, with code.

Next

How you get credentials, and what applies before verification - Onboarding and verification. Then make one real request - Quickstart takes about five minutes.