> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centipidbilling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DaliPay

> Configure DaliPay wallet push for Tanzanian mobile-money collection.

# Collect payments with DaliPay

`DALIPAY` collects by **wallet push**. The payer enters their number on the
portal, a PIN prompt appears on their phone, and they approve it there. They
never leave the portal page.

Offered in the country catalog for **Tanzania (TZ)**.

Centipid Billing uses two calls from DaliPay's
[Collections API](https://dalipay.co.tz/documentation):

1. `POST /api/v1/collections` sends the PIN prompt to the payer's number.
2. `GET /api/v1/collections/{uuid}/status` reports whether it was paid.

Nothing is credited until the status reads `success`.

## Before you start

Register a merchant account at [dalipay.co.tz](https://dalipay.co.tz) for the
ISP. Test keys work straight away and simulate every payment. Live payouts
("Toa Pesa") need DaliPay to verify the account's KYC first.

## Configure the gateway

<Steps>
  <Step title="Generate an API key pair in DaliPay">
    Under **API keys**, generate a pair for **Live** (or **Test** to try it
    first). Copy the secret key straight away: DaliPay shows it only once.
  </Step>

  <Step title="Open Settings → Payments → DaliPay in Centipid">
    Enter the **Public key** and **Secret key**.
  </Step>

  <Step title="Paste the webhook URL into DaliPay">
    Copy the **Webhook URL** Centipid shows under Callback URLs into DaliPay's
    **Settings**. Copy the **callback secret** DaliPay shows beside it back into
    Centipid.
  </Step>

  <Step title="Run a controlled test payment">
    Pay a small amount from the captive portal, approve the prompt on the
    phone, and confirm the payment reaches the ledger.
  </Step>
</Steps>

## Credentials

| Field | Required | Notes |
| - | - | - |
| Public key | Yes | `gw_pk_test_…` or `gw_pk_production_…`. The key decides test or live. |
| Secret key | Yes | Sent on every request from Centipid's servers only. |
| Callback secret | No | Checks DaliPay's webhook signature. Without it the webhook is ignored and payments connect through the status check alone. |

## Callback URL

Paste `/api/dalipay/callback` on the ISP's domain into DaliPay Settings (the
settings page shows the full URL). DaliPay calls it when a payment succeeds or
fails, and does not retry. So Centipid also checks the payment's status every
5 seconds for about 3 minutes after the prompt is sent. That check is what
connects the payer if the webhook is lost. A webhook whose signature does not
match the callback secret is rejected.

## Networks

DaliPay needs to know the payer's network, and the portal only asks for a
number, so Centipid reads it from the prefix:

| Prefix | Network |
| - | - |
| 074, 075, 076 | Vodacom M-Pesa |
| 068, 069, 078 | Airtel Money |
| 065, 067, 071, 077 | Tigo Pesa (Yas) |
| 061, 062 | HaloPesa |

Any other number, TTCL (073) for example, is refused before a prompt is sent.
AzamPesa is not offered, because its wallets are not tied to a prefix.

## Troubleshooting

* **"Unable to send the DaliPay payment prompt"**: a key is wrong or revoked,
  or DaliPay's IP whitelist is on and does not include Centipid's servers
  (DaliPay answers `403`). DaliPay's exact response is in the application log.
* **"Enter a Vodacom, Airtel, Tigo or Halotel number"**: the number's prefix is
  not in the table above.
* **Test payments succeed but no money arrives**: the keys start `gw_pk_test_`.
  Test keys only simulate. Generate a Live pair.
* **The payer paid but did not connect**: search the payment by DaliPay's
  reference (`col_…`), shown in the DaliPay Collections ledger.