Guide

Payments

SwiftGoma settles mobile money through PawaPay. On SwiftGoma, PawaPay is scoped narrowly to two internal flows — collecting seller subscription payments, and paying out approved expenses to vendors. Every endpoint on this page requires an ADMIN or ACCOUNTANT role and lives under https://api.swiftgoma.com/api/v1/pawapay.

Not the buyer-facing payment provider

Buyer checkout, order refunds, and seller wallet payouts all run through MbiyoPay instead — see that guide for those flows. POST /deposits here is used by subscription billing specifically, and payouts here are used by the expense-approval flow specifically — this section isn't a general-purpose payment gateway for the rest of the platform.

The OTP-approval pattern

Every payout and refund goes through the same two-step, human-verified flow before any money actually moves — no single API call sends funds.

1
Request approval
Validates the request and emails a one-time verification code to the requesting admin. Nothing is sent to PawaPay yet, and the amount and count are checked against that admin's daily limits.
2
Confirm
Submitting the correct code within 5 minutes actually sends the payout or refund to PawaPay. Repeated wrong codes lock the flow out temporarily.

	Request approval	Confirm
Payouts	POST /payouts/request-approval	POST /payouts/confirm
Refunds	POST /refunds/request-approval	POST /refunds/confirm

Direct-send endpoints are deliberately disabled

POST /refunds exists but always returns a validation error telling you to use the request-approval / confirm pair instead — there's intentionally no way to move money in a single call.

Deposits

POST /deposits requests a mobile money charge directly, without the OTP flow — it's the one money-moving call that isn't OTP-gated, since it only ever takes money in. Duplicate submissions with identical amount, currency, provider, and phone number within a 5-minute window resolve to the same deposit instead of charging twice, even without an explicit idempotency key.

Checking status

Resource	Status	History
Deposits	GET /deposits/:depositId	—
Payouts	GET /payouts/:payoutId	GET /payouts/history
Refunds	GET /refunds/:refundId	—

Phone numbers

PawaPay expects MSISDN format — digits only, country code included, no leading +. For example 243812345678, not +243812345678.

Wallet & configuration

GET /wallet-balances returns the platform's current PawaPay balances by currency. GET /active-configuration returns which countries, providers, and currencies are currently enabled, and how each one formats amounts — useful before constructing a deposit or payout payload for a provider you haven't used yet.

Browse the Payments endpoints in the API Reference