Glossary
The vocabulary these docs use, and what each term maps to in the API.
Platform
Integrator - your tenant on the platform. Owns your API keys, your ledger balances, your
settlement accounts, your webhook configuration and your IP allowlist. Its id appears in several
endpoint paths as {integratorId}.
Key type - what a key does with money: DEVELOPMENT (a test key: always mocked, any
amount), SANDBOX (real money, at most GHS 1.00 per transaction) or PRODUCTION (real money).
Fixed when the key is issued. See Environments and key types.
Environment - TEST (pk_test_…, test keys) or LIVE (pk_live_…, sandbox and production
keys). Balances and transactions are fully separated between the two.
Verification - PayDirect's approval of your Integrator. Until it completes, production keys are limited to GHS 1.00 per transaction. See Onboarding.
Allowlist - the per-environment list of source addresses allowed to use your keys. Empty means any address. See IP allowlisting.
Scope - a capability grant on an API key, such as PAYOUTS_WRITE. See
API keys.
Narrowed key - a key PayDirect has limited to fewer scopes than it was issued with. It cannot change your Integrator's configuration.
Ledger - your accrued balance, keyed on (integrator, currency, environment). Credited by
confirmed collections, debited by payouts and withdrawals.
Balance check - payouts and withdrawals are debited from your ledger before dispatch; an insufficient balance is refused with nothing dispatched.
Settlement account - the pre-registered destination a withdrawal goes to. Registered by PayDirect, never expressible in a request.
Money movement
Collection - money in, from a payer. Transaction type COLLECTION.
Payout / disbursement - money out, to a recipient you name. Transaction type PAYOUT. The
endpoints /transactions/disburse and /transactions/payout-credit-transfer are the same thing.
Withdrawal - money out, to your own settlement account. Transaction type WITHDRAWAL.
Bill payment - collect from a payer and settle to a biller. Transaction type PAY_BILL.
Rail - the underlying network a payment travels over: the interbank network for banks, or a mobile money network (MTN, Telecel, AirtelTigo, Zeepay).
Reconcile - ask us to re-check the rail for a PENDING transaction and update our record.
Distinct from a plain read, which returns stored state without touching the rail.
Compensation - unwinding the completed leg of a multi-leg journey whose later leg failed.
Surfaces as the TRANSACTION_COMPENSATION_* webhook events.
Amounts
Principal - the nominal amount of the transaction: the amountToSend field.
totalDebit - what was actually debited, charge included. What you show a customer and
reconcile your outflow against.
amountReceived - what the beneficiary receives. totalDebit − charges.
Charge bearer - SENDER (default: charge added on top of the debit, beneficiary receives the
full principal) or RECIPIENT (charge deducted from what the beneficiary receives).
Major units - amounts are cedis, not pesewas. 150.75 is one hundred fifty cedis seventy-five
pesewas.
Requests
Envelope - the { code, status, message, data } shape every response uses.
Idempotency key - the Idempotency-Key header. A client-chosen string that makes a retried
request return the original response instead of executing again.
Signed request - the x-api-key-id / x-api-timestamp / x-api-signature header trio. The
only authentication a server-to-server integration should use.
Public key (pk_test_… / pk_live_…) - identifies the key. Sent on every request.
Raw API key - the message that gets signed. Never sent.
Secret key (sk_test_… / sk_live_…) - the HMAC key. Never sent.
GHIPSS routing code - the numeric code identifying a Ghanaian bank, from
GET /banks/list. Confusingly carried in fields named
swiftCode; it is not an ISO 9362 SWIFT/BIC.
Webhooks
Event - a record that something happened, identified by eventId.
Delivery - one attempt to POST an event to your endpoint. One event can have many deliveries.
At-least-once - an event may be delivered more than once and must be deduped on eventId.
Signing secret - the key we HMAC webhook payloads with. Distinct from your API secret key, and rotated separately, through support.