收款
Accept payments
Prompt-to-pay, dynamic QR, till and pay bill (C2B), invoices, standing orders and business-to-business requests.
阅读约 7 分钟
开发者指南以英文撰写，以确保代码、字段名和错误信息与 API 完全一致。
本页内容
Prompt-to-pay
POST /partner/stk pushes a payment prompt to the customer's phone. They approve with their PIN on their own device; you get the result by webhook.
| Field | Required | Description |
|---|---|---|
payer_msisdn | Yes | Payer phone in international format, e.g. 254708374149. |
amount | Yes | Positive amount in the account currency. |
reference | No | Your order or invoice reference, echoed back in the webhook. |
callback_url | No | Overrides your default webhook for this one charge. |
idem | No | Idempotency key. A retry with the same key returns the original charge. |
Charge lifecycle
| State | Meaning | Event |
|---|---|---|
pending | Prompt sent, waiting for the customer. | charge.created |
authorised | Approved, settling. | |
completed | Money moved. transaction holds the ledger reference. | charge.completed |
declined | The customer rejected the prompt. | charge.declined |
expired | No answer before expiry. | charge.expired |
failed | Could not complete (for example insufficient funds). |
Poll GET /partner/status?charge_ref=… if a webhook is late; never assume success from the pending response.
Idempotency
Networks time out. If you don't know whether a charge was created, retry with the same idem value: you get the original charge back instead of a second prompt. Use one key per payment attempt, for example order-9-attempt-1.
Dynamic QR (scan to pay)
POST /partner/qr returns a base64 PNG that customers scan in their app. Show it on a screen, a receipt or an invoice.
{ "amount": 100, "kind": "buygoods", "recipient": "400200", "reference": "INV-1001" }kind is buygoods (till), paybill or send (to a phone number). recipient defaults to your own short code.
Till and pay bill (C2B)
Customers can also pay your short code from their own app or USSD. Register where confirmations should go with POST /partner/c2b/register; each payment then arrives as a c2b.confirmation event.
In the sandbox, simulate one:
curl -s https://pesa-bridge.com/api/bridgepay/v1/partner/c2b/simulate \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"msisdn":"254708374149","amount":250,"bill_ref":"ACC-001"}'Invoices
Bill Manager creates invoices with line items and tax. Set "send": true to push a payment prompt to the customer at once, or send later with POST /partner/bills/send.
{
"customer_name": "Jane Doe",
"customer_msisdn": "254708374149",
"tax_pct": 16,
"send": true,
"items": [{ "description": "Consulting", "quantity": 2, "unit_price": 5000 }]
}More ways to get paid
| Endpoint | What it does |
|---|---|
POST /partner/standingorder | Recurring payment from a customer to your short code; the customer authorises it in their app. |
POST /partner/b2b/express | Request payment from another business (till to till). No money moves until they approve. |
POST /partner/loyalty/pay | Accept loyalty points at checkout; you receive the cash value. |
GET /partner/balance | Your collection account balance. |
我们的工程师解答集成问题。把请求参考号发给我们，我们会找到那次调用。
联系支持