canonical: https://jentic.com/apis/pawapay.io/pawapay

# pawaPay Merchant API V2

The pawaPay Merchant API V2 enables businesses to send and receive mobile money payments across African markets. It provides 24 endpoints covering deposits (collections from customers), payouts (disbursements to recipients), remittances (cross-border transfers), refunds, payment page creation, wallet balance queries, and financial statements. The API supports both individual and bulk payment operations with callback notifications for asynchronous payment status updates.

## For AI agents

Process mobile money deposits, payouts, and remittances across African markets. Handle bulk disbursements, refunds, wallet balance checks, and payment page creation for mobile money transactions.

## Scope

Does not handle card payments, bank transfers, or non-African markets - use for mobile money deposits, payouts, and remittances in African corridors only.

## Capabilities

- Collect mobile money deposits from customers across multiple African corridors
- Disburse payouts to mobile money wallets individually or in bulk batches
- Process cross-border remittance transfers between supported African countries
- Issue refunds against completed deposit transactions
- Generate hosted payment pages for customer-initiated mobile money collections
- Query real-time wallet balances across active mobile money corridors
- Retrieve financial statements with transaction-level detail for reconciliation

## Use cases

### Mobile Money Collection

Collect payments from customers via mobile money wallets across African markets using the deposits endpoint. Each deposit request specifies the amount, currency, recipient MSISDN (mobile number), and corridor. The API processes the request asynchronously and delivers status updates via configured callback URLs, supporting high-volume collection scenarios.

Example prompt: Create a deposit of 5000 UGX from mobile number '+256700123456' via POST `/v2/deposits` with a unique depositId and verify the callback confirms success

### Bulk Payout Disbursement

Disburse funds to multiple mobile money recipients in a single API call using the bulk payouts endpoint. This supports payroll, marketplace seller payments, and mass disbursement scenarios. Each payout in the batch is processed independently with individual status tracking, and failed payouts can be retried without reprocessing the entire batch.

Example prompt: Submit a bulk payout of 3 recipients via POST `/v2/payouts/bulk` with amounts in KES and verify each payout status via GET `/v2/payouts/{payoutId}`

### Cross-Border Remittance

Process international mobile money transfers between supported African corridors. The remittances endpoint handles currency conversion and routing between countries, supporting both individual and bulk transfer operations. Each remittance is tracked independently with callback notifications for settlement confirmation.

Example prompt: Initiate a remittance transfer from Kenya (KES) to Uganda (UGX) via POST `/v2/remittances` with source and destination mobile numbers

### AI Agent Mobile Payment Orchestration

AI agents process mobile money transactions across African markets through Jentic without managing Bearer token lifecycle or callback webhook infrastructure directly. Agents search for payment operations like 'collect a mobile money deposit' and receive structured schemas with authentication handled by your Jentic One instance.

Example prompt: Search Jentic for 'collect a mobile money payment', load the operation schema for POST `/v2/deposits`, and execute with the customer MSISDN, amount, and corridor parameters

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v2/deposits` | Create a mobile money deposit (collection) |
| GET | `/v2/deposits/{depositId}` | Check deposit status |
| POST | `/v2/payouts` | Send a payout to a mobile wallet |
| POST | `/v2/payouts/bulk` | Send bulk payouts |
| POST | `/v2/remittances` | Initiate a cross-border remittance |
| POST | `/v2/refunds` | Issue a refund for a deposit |
| GET | `/v2/wallet-balances` | Query wallet balances |
| POST | `/v2/paymentpage` | Create a hosted payment page |

## Key resources

- **Deposits** — Collect mobile money payments from customers with async status callbacks
- **Payouts** — Disburse funds to mobile wallets individually or in bulk batches
- **Remittances** — Process cross-border mobile money transfers between countries
- **Refunds** — Issue refunds against completed deposit transactions
- **Payment Pages** — Generate hosted pages for customer self-service collections
- **Finances** — Query wallet balances and retrieve financial statements

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 54 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 72 / 100
  - Developer Experience & Jentic Compatibility: 66 / 100
  - AI-Readiness & Agent Experience: 31 / 100
  - Agent Usability: 94 / 100
  - Security: 75 / 100
  - AI Discoverability: 50 / 100
- **View full report:** https://jentic.com/apis/pawapay.io/pawapay/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring pawaPay by hand means handling its bearer auth, choosing the right sandbox or production host, and matching corridor codes and MSISDN formats yourself. Through Jentic you install once, import the pawaPay Merchant API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** pawaPay carries the deposit, payout, and remittance targets in the request body, so scope your agent to the operations it needs, such as checking a deposit status or reading wallet balances. You choose the operations it may call, so initiating payouts or refunds is not included unless you add them.
- **Credential handling:** Your pawaPay token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a mobile money payout in Kenya' or 'check a deposit status', and Jentic returns the matching pawaPay operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Flutterwave API** — Pan-African payment gateway supporting cards, bank transfers, and mobile money
- **Paystack API** — African payment infrastructure for cards and mobile money in select markets
- **Stripe API** — Global payment processing for cards, wallets, and bank debits

## FAQ

### What authentication does the pawaPay API use?

The pawaPay API uses Bearer token authentication. All requests require an Authorization header with a Bearer token issued from the pawaPay dashboard. Sandbox and production environments use separate tokens. Through Jentic, Bearer tokens are stored encrypted in the credential vault and injected automatically.

### Which African countries does pawaPay support?

pawaPay supports mobile money operations across multiple African corridors including Uganda (UGX), Kenya (KES), Tanzania (TZS), Ghana (GHS), Cameroon (XAF), and others. Each corridor corresponds to specific mobile money operators in that country. Available corridors can change - check the API documentation for the current list.

### How do bulk payouts work?

POST `/v2/payouts/bulk` accepts an array of payout objects, each with a unique payoutId, recipient MSISDN, amount, and corridor. Each payout processes independently - a failure in one does not affect others. Individual payout status is tracked via GET `/v2/payouts/{payoutId}` and callbacks are sent per payout.

### Can I issue refunds for collected deposits?

Yes. POST `/v2/refunds` creates a refund against a completed deposit transaction. You provide the original depositId and a unique refundId. Refund status is tracked via GET `/v2/refunds/{refundId}` and callback notifications are sent when the refund settles.

### How do I collect a mobile money payment through Jentic?

Search Jentic for 'collect a mobile money deposit', load the operation schema for POST `/v2/deposits`, and execute with the customer MSISDN, amount, currency, and corridor. Jentic injects the Bearer token and returns the deposit status. Install with pip install jentic.

### What is the difference between payouts and remittances?

Payouts disburse funds within a single country corridor (same currency). Remittances transfer funds across borders between different countries and currencies, with pawaPay handling the conversion. Both support individual and bulk operations with the same callback notification mechanism.

### Can I limit what my agent is allowed to do with the pawaPay API?

Yes. Because you run Jentic One yourself, you decide exactly which pawaPay operations your agent may call, so you can allow read-only actions like checking a deposit status with GET `/v2/deposits/{depositId}` or reading wallet balances with GET `/v2/wallet-balances` while leaving money-moving operations out of scope. Since pawaPay carries the deposit, payout, and remittance targets in the request body, initiating payouts via POST `/v2/payouts` or issuing refunds via POST `/v2/refunds` is not available to the agent unless you explicitly add those operations. Your pawaPay Bearer token stays with your own Jentic One instance and is injected at execution time, so it never enters the agent's prompt or logs.