InfinityPay

Partner Integration

Direct Wallet Push

A complete integration guide for a billing platform, ecommerce site, or app collecting payments on behalf of InfinityPay businesses and service providers — from the first API call through to handling a failed payment.

How it fits together

text
Your system ──API key──▶ InfinityPay ──▶ Mobile money ──▶ Customer's wallet
      ▲                        │
      └──────  webhook  ───────┘

You integrate with InfinityPay and nothing else. InfinityPay holds the provider relationships and reaches them from its own approved infrastructure. You never hold, see, or configure provider credentials.

A business's IP allowlist governs access to the InfinityPay API. It is unrelated to any provider-side allowlist, which covers InfinityPay's own servers and is not your concern.

What the business sets up first

  1. Creates an InfinityPay account and completes verification.
  2. Generates API credentials at /portal/api-credentials. Sandbox keys work immediately; live keys become available once the account is approved, verified, and priced — there is no per-key approval step.
  3. Gives you the secret key.
  4. Sets a webhook URL at /portal/webhooks. A signing secret is optional — see Proving a webhook came from us below.

The webhook URL is not optional in practice

With no webhook URL configured, no events are sent at all — silently, with no error. If you plan to react to payment outcomes rather than poll for them, confirm the business has set one before going live.

You cannot set the webhook URL for them

Steps 3 and 4 are done by hand, in the portal, by someone signed in to that business's own account. There is no API-key route to register a receiving URL. If you onboard businesses at scale, show each one the URL you expect to receive on and have them paste it in.

A signing secret is optional

A business that never generates one still receives every event; the delivery simply carries no X-Infinity-Signature header. How you prove a delivery is genuine is your choice — both options are below, and neither is more official than the other.

Authentication

Send the secret key as a bearer token, or as X-API-Key — both are accepted.

bash
Authorization: Bearer sk_live_YOUR_SECRET_KEY_HERE
  • sk_live_… moves real money. sk_test_… is sandbox — no provider call, no money.
  • pk_… is a public identifier, not a credential. It cannot authenticate and is rejected if sent as a token.
  • The secret is shown once at creation and stored only as a hash. It cannot be recovered — rotate if lost.
  • Server-side only. Never ship a secret key in a browser or mobile app.

There is no request signing today

Requests are authenticated by the bearer key over HTTPS, optionally narrowed by an IP allowlist. InfinityPay does not currently verify an HMAC signature on inbound API requests — do not build one expecting it to be checked. Outbound webhooks are signed; that is separate and covered below.

Sending a push

POST/v1/collections/wallet-push

Send a payment prompt to the customer's phone.

API key (collections:write)
bash
curl -X POST https://api.infinitypay.me/v1/collections/wallet-push \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY_HERE" \
  -H "Idempotency-Key: 8f1c2d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "5000.00",
    "currency": "TZS",
    "phone": "+255712345678",
    "customer_name": "Asha Mushi",
    "reference": "INV-2026-000412",
    "description": "March broadband subscription"
  }'
FieldRequiredNotes
amountYesDecimal string, e.g. "5000.00". Minimums are set by the customer's own network — see Minimum amounts below.
phoneYesThe customer's mobile money number.
currencyNoDefaults to TZS.
customer_nameNoShown on the business's records.
referenceNoYour order or invoice id. Echoed back on every response and webhook.
descriptionNoFree text.

Idempotency-Key is a required header, not a body field.

There is no account identifier to look up or send. Your API key is the only thing that identifies the business — nothing else has to be fetched or configured before your first call.

Phone number formats

Send the number however you already store it. All of these are accepted and normalised to the same number, so you do not need to reformat anything before calling:

You sendTreated as
+255712345678255712345678
255712345678255712345678
0712345678255712345678
712345678255712345678
0712 345 678255712345678
+255-712-345-678255712345678

Spaces, dashes, brackets and a leading + are all stripped. Anything that is not a recognisable Tanzanian mobile number is rejected with a 422 before any payment is attempted, so a mistyped number fails immediately rather than becoming a failed transaction.

json
{
  "success": true,
  "data": {
    "collection_id": "3f2a8c1e-...",
    "reference": "INV-2026-000412",
    "status": "processing",
    "message": "Payment prompt sent. Please approve on your phone."
  }
}

202 means the prompt was sent, not that payment succeeded

Never mark an order paid from this response. Wait for the collection.success webhook, or poll GET /v1/collections/{collection_id}.

Minimum amounts

Mobile money networks set their own floor, and a push below it is refused by the network itself — not by us. We check before sending, so a request under the minimum is rejected immediately and the customer is never shown a prompt that cannot work.

NetworkMinimumPrefixes
Tigo / Mixx by YasTZS 1,000065, 067, 071, 077
M-Pesa, Airtel Money, HaloPesa, TTCL PesaTZS 100all others

Below the minimum you get a 400 with the code AMOUNT_BELOW_OPERATOR_MINIMUM. No collection is created and no prompt is sent, so there is nothing to cancel and nothing to reconcile — fix the amount and send a new request.

json
{
  "success": false,
  "error": {
    "code": "AMOUNT_BELOW_OPERATOR_MINIMUM",
    "message": "Minimum amount for Tigo / Mixx by Yas is TZS 1,000. Please enter TZS 1,000 or more, or use another mobile money network.",
    "details": null
  }
}

Check this before you send

The message is written for your customer and is safe to show them as-is. Checking the prefix on your side first saves them a round trip and lets you offer another network before they commit to paying.

Idempotency

Retry with the same Idempotency-Key and you get the original result back — no second prompt to the customer, no second payment attempt. Reusing a key with a different body is rejected rather than silently returning the wrong result.

Generate one key per payment attempt and reuse it for every retry of that attempt. Do not reuse it for a genuinely new payment.

Webhooks

Events relevant to this flow: collection.success, collection.failed, and collection.pending_review. Full details, signature verification examples and the retry schedule are on the Webhooks page.

json
{
  "event": "collection.failed",
  "merchant_code": "27048391",
  "collection_id": "3f2a8c1e-...",
  "reference": "INV-2026-000412",
  "merchant_reference": "INV-2026-000412",
  "amount": "5000.00",
  "currency": "TZS",
  "status": "failed",
  "failure_reason_code": "user_cancelled",
  "failure_reason_message": "The customer cancelled the payment.",
  "failed_at": "2026-09-27T09:14:22Z",
  "timestamp": "2026-09-27T09:14:22Z"
}

Headers on every delivery

HeaderPurpose
X-Infinity-SignatureHMAC-SHA256 hex digest of the exact raw body, keyed with the webhook secret.
X-Infinity-EventThe event name, e.g. collection.success.
X-Infinity-DeliveryUnique per event. Deduplicate on this — deliveries are at-least-once.
X-Infinity-TimestampUnix seconds at send time, for rejecting very old replays. Not part of the signed material — verify the signature over the body alone.

Proving a webhook came from us

Your callback URL is not a secret — it appears in config screens, support threads, server logs and screenshots, so assume someone has it. Without a check, anyone who does can POST {"event":"collection.success", ...} and be believed. Two ways to close that; pick one, neither is more official than the other.

Option A — confirm by lookup (no secret needed)

Take collection_id from the delivery, ignore everything else it claims, and ask us what actually happened. Act only on the status in our reply.

python
def handle_webhook(request):
    payload = request.get_json(silent=True) or {}
    collection_id = payload.get("collection_id")
    # Always acknowledge: a non-2xx just earns a retry of something
    # we have decided to ignore.
    if not collection_id:
        return "", 200

    # Ask us, over TLS, with your own secret key.
    confirmed = requests.get(
        f"https://api.infinitypay.me/v1/collections/{collection_id}",
        headers={"Authorization": f"Bearer {SECRET_KEY}"},
        timeout=10,
    ).json().get("data")

    if not confirmed or confirmed["status"] != "successful":
        return "", 200                            # not paid, or not confirmable

    fulfil(confirmed["reference"], confirmed["amount"])
    return "", 200

A forged webhook then achieves nothing: it makes you ask us a question and we answer truthfully, and the forger cannot fake that answer without your secret key. No new credential to distribute or rotate. This is what InfinityPay itself does with its own provider's unsigned callbacks.

Option B — verify the signature

Generate a signing secret in the portal. Every delivery then carries X-Infinity-Signature. No extra HTTP call, but a second credential to carry to every business and rotate when it leaks.

python
import hashlib
import hmac
import json

def handle_webhook(request):
    raw = request.get_data()                      # raw BYTES, before any JSON parse
    sent = request.headers.get("X-Infinity-Signature", "")
    expected = hmac.new(SECRET.encode(), raw, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, sent):   # constant-time
        return "", 401

    payload = json.loads(raw)
    if payload.get("test") or payload.get("sandbox"):
        return "", 200                            # acknowledge, do not fulfil

    # Store it, return 200, then process. Do not process before responding.
    enqueue_for_processing(payload)
    return "", 200

Sign the raw bytes you received. Parsing the JSON and re-serialising it changes the bytes and the digest will not match — this is the single most common integration mistake.

Whichever you pick, check the amount and reference

Both options prove the event is real. Neither proves it belongs to the order you had in mind, and a genuine small payment must not settle a large invoice.

Retries

Any 2xx counts as delivered. Anything else — a non-2xx, a timeout, or an unreachable host — is retried up to 5 attempts, spaced immediately, then after 1, 5, 15 and 30 minutes. After the fifth the event is marked failed and is not retried again.

The timeout is 8 seconds, so return 200 as soon as you have stored the event and do your processing afterwards — a slow handler burns a retry. If your endpoint was down long enough to exhaust them, poll Transaction Status to catch up.

Three kinds of delivery — only one to act on

SourceMarkerFulfil?
Send Test Webhook"test": trueNo
Sandbox push"sandbox": trueNo
Live pushNeither field presentYes

A test delivery deliberately looks like a real success

Its body reads event: collection.success so that your real handler is what gets exercised. A handler keying only on that field would fulfil a fake order — check test and sandbox explicitly.

Testing without spending money

A sandbox key (sk_test_…) queues the same events a live push would, so you can exercise your real handler end to end for free. Use simulate_status on the create call to choose the outcome — successful, failed, pending_clearance or reversed.

json
{
  "amount": "1000.00",
  "phone": "+255712345678",
  "reference": "TEST-001",
  "simulate_status": "failed"
}

Statuses

StatusMeaningWhat to do
processingPrompt sent, customer has not acted yet.Wait for the webhook.
successfulPaid, and the business wallet is credited.Fulfil the order.
failedTerminal failure.Read failure_reason_code.
pending_clearanceHeld for review.Wait. Do not fulfil.
reversedReversed after completing.Reverse your fulfilment.

Failure reason codes

failure_reason_code is a closed set, safe to switch on. failure_reason_message is a sentence you may show a user. Handle unknown codes gracefully — the set can grow.

CodeMeaning
user_cancelledThe customer cancelled the prompt.
provider_declinedDeclined by the payment provider.
reversedReversed after it had completed.
expiredExpired before the customer approved it.
provider_unavailableProvider unreachable. Retryable.
unknown_provider_errorThe cause could not be identified.
insufficient_balanceNot enough balance in the wallet.
wrong_pinWrong PIN, or authorization failed.
timeoutAuthorization timed out.

A push does not stay pending forever

If the customer never acts — dismisses the prompt, walks away, mistypes their PIN — the collection is closed after about 30 minutes with collection.failed and failure_reason_code: "expired". Every push you start reaches a terminal state, so nothing sits in your system awaiting payment indefinitely. We ask the provider one final time before closing anything, so a payment that quietly succeeded is settled rather than expired.

A failed can, rarely, be followed by a success

For 24 hours after expiring a collection we keep asking the provider about it. If the customer did pay after all, it settles properly and you receive collection.success for a collection you were already told had failed. Key on collection_id and let the latest event win. Concretely: don't cut off a subscriber irreversibly the instant an expired failure lands, or make reactivation automatic when the later success arrives. Every other failure code is final.

Rate limits

Creation endpoints are limited on two dimensions at once, per minute: 30 per API key and 60 per source address. If you are a platform calling on behalf of several businesses, they all reach us from your servers and therefore share the second limit — so that is the one a bulk run hits first. The per-key limit exists so one business's billing cycle cannot consume the whole allowance and lock out its neighbours.

Over either limit you get 429 with a Retry-After header in seconds. For a bulk run, pace at roughly one request per second per key. A refused request still counts against the address limit, so retrying hard into a 429 makes the queue longer, not shorter.

IP allowlist (optional)

Off by default — a valid key works from any address. Enabled per key in the portal, it restricts that key to specific addresses; a request from anywhere else is rejected with a generic error that reveals nothing about the allowlist, and the rejection is recorded in the audit log. If you use it, add every egress address your servers can present, and update it when your infrastructure changes.

Go-live checklist

  1. Business account created, approved and verified.
  2. Live API key generated. Secret stored server-side only.
  3. Webhook URL set. Signing secret generated only if you intend to verify signatures rather than confirm by lookup.
  4. Send Test Webhook from the portal. Confirm your verifier accepts the signature.
  5. Sandbox run with sk_test_…, including a simulate_status: "failed" case.
  6. Optional: enable the IP allowlist and confirm a request still succeeds.
  7. One live push at the smallest workable amount, to a phone you control.
  8. Confirm the whole chain: 202 → webhook delivered → collection successful → business wallet credited.
  9. Confirm a deliberate failure — decline the prompt — arrives as collection.failed with failure_reason_code: "user_cancelled".