Payments

Collect from customers. Pay the people you work with.

Collections and disbursements live on one merchant account, in Tanzanian shillings. A customer pays from the wallet already on their phone. A payout leaves only what that account can cover.

Collections

A collection is one payment object. You create it, AFRIPEI asks the customer to confirm, and the object stays open until they pay, the wallet refuses, or the request expires. A create response means the request was accepted. It does not mean you have been paid. Fulfill the order when the payment reaches success.

There are two ways to collect.

• A prompt on the handset. Send the customer’s mobile-money number. They receive a prompt and enter their wallet PIN. Until they do, the payment stays pending.
• A control number. The customer pays from their own wallet or bank menu. You share the number AFRIPEI returns. The amount has to be paid in full.

Customers pay with M-Pesa, Airtel Money, Mixx by Yas, or Halopesa. You send the number. AFRIPEI delivers the prompt to that phone. You do not open a separate account for each wallet.

Mobile-money collections are accepted from 500.00 TZS through 3,000,000.00 TZS. Send the amount as a decimal string with two places, such as 15000.00. Currency is TZS. An amount outside that range is rejected before a prompt is sent.

What you store

Every collection has an id. That id is what you keep in your order, what you pass when you read the payment back, and what arrives on the webhook. You may also send your own merchant reference, such as an order number, and read the list back by that reference.

The payment records the amount, the currency, the method, the customer phone when you sent one, the status, and the fee snapshot taken when the payment was created. The snapshot is the provider cost, the AFRIPEI fee, and the merchant net. It is not rewritten after the money moves.

Statuses you act on

• Pending. The prompt was accepted. The customer has not confirmed. Do not fulfill.
• Awaiting customer. A control number is open. Do not fulfill.
• Success. The customer paid. This is the status to fulfill on.
• Failed. The wallet or the rail rejected it. The payment carries a failure message. A blank rejection is shown as “The payment was rejected.”
• Cancelled or expired. You cancelled it, the customer cancelled the prompt, or the request timed out.

You can cancel a payment while it is pending or awaiting the customer. Cancelling a control number closes it.

Disbursements

A disbursement is a payout from available balance. AFRIPEI reserves the amount and the fee together before the money is sent. If the balance cannot cover both, no payout is created. Read the balance first. The available figure is what a new payout can reserve.

A payout can go to a mobile wallet or to a bank account in Tanzania.

• Mobile money. Send the recipient’s number and name. The wallets are the same ones your customers already use: M-Pesa, Airtel Money, Mixx by Yas, and Halopesa.
• Bank transfer. Send the account number, the account name, the bank, and whether the transfer is ACH or RTGS. The bank list comes from the API.

A successful payout means the recipient was paid. The ledger keeps the fee snapshot from the moment the payout was created. A failed payout releases the reservation and stores the reason. A payout that is still pending is still reserved. AFRIPEI completes it and tells you when that happens.

One account

Money in and money out stay on the same merchant. The portal shows today’s collections, today’s disbursements, the balance, and each transaction with the wallet the customer or recipient used. A live key moves real shillings. There is no sandbox on the production API.

A new account waits for verification. Collections and payouts stay closed until the account is active. Rejecting a submission sends the reason back to the merchant.

Create requests need an idempotency key that you choose, such as the order id. The same key and the same body return the original payment or payout. Use that key again if a request times out. A new key can create a second prompt.

How your system hears the result

Register an HTTPS endpoint. AFRIPEI signs each delivery. Treat payment.success as the signal that a customer paid, and payout.success as the signal that a recipient was paid. A create response is only the acceptance of the request.

The same account is what you open in the merchant portal, what a secret key calls, and what an assistant can reach through MCP once you connect a key. The key is shown once. Store it, and send it as a bearer token.