C2B

Also called the Register URL API. Safaricom describes it as enabling merchants to receive real-time notifications for payments made to their Pay Bill or Till number.

Endpoint

https://sandbox.safaricom.co.ke/mpesa/c2b/v2/registerurl

OverviewCopy Anchor Link

Funds move from a customer's M-PESA wallet to a merchant's short code, triggered from SIM Toolkit, the M-PESA app, the Safaricom app, USSD, the NI Push API, or the Dynamic QR Code API. This API registers two callback URLs against your short code:

• Validation URL, called only if you've had External Validation enabled on your short code (off by default), giving you a chance to accept or reject a payment before it completes, for example by checking an account number.
• Confirmation URL, called after a payment has completed successfully.

How it worksCopy Anchor Link

For transactions where a callback never lands, Safaricom points to the Pull Transactions API or the M-PESA Organization Portal as the fallback.

URL requirementsCopy Anchor Link

• Publicly reachable IP address or domain name.
• HTTPS required in production; HTTP is allowed in sandbox.
• Avoid the words M-PESA, Safaricom, exe, exec, cmd, sql, query (or variants) anywhere in the URL.
• Don't use public URL testers such as ngrok, mockbin, or requestbin in production; these are typically blocked by the gateway.

PrerequisitesCopy Anchor Link

• Daraja account and sandbox app, with a Consumer Key and Consumer Secret.
• Test data from the simulator section for sandbox testing.
• A live Pay Bill or Till number with Business Admin/Manager operators created, for Go Live.
• An access token from the Authorization API.

Registering URLsCopy Anchor Link

RequestCopy Anchor Link

{
  "ShortCode": "600984",
  "ResponseType": "Either Cancelled or Completed",
  "ConfirmationURL": "your confirmation URL",
  "ValidationURL": "your validation URL"
}

ResponseCopy Anchor Link

{
  "OriginatorCoversationID": "6e86-45dd-91ac-fd5d4178ab523408729",
  "ResponseCode": "0",
  "ResponseDescription": "Success"
}

Once URLs are registered, no further development is needed on your side to trigger a payment during testing: use the simulator to preview what an incoming payment looks like.

Simulating a transactionCopy Anchor Link

RequestCopy Anchor Link

{
  "ShortCode": 600984,
  "CommandID": "Either CustomerBuyGoodsOnline or CustomerPayBillOnline",
  "Amount": 1,
  "Msisdn": 254708374149,
  "BillRefNumber": "Account reference for Customer paybills and null for customer buy goods"
}

ResponseCopy Anchor Link

{
  "OriginatorCoversationID": "53e3-4aa8-9fe0-8fb5e4092cdd3405976",
  "ResponseCode": "0",
  "ResponseDescription": "Accept the service request successfully."
}

Callback payloadsCopy Anchor Link

Validation requestCopy Anchor Link

Only sent to partners who have External Validation enabled.

{
  "TransactionType": "Pay Bill",
  "TransID": "RKL51ZDR4F",
  "TransTime": "20231121121325",
  "TransAmount": "5.00",
  "BusinessShortCode": "600966",
  "BillRefNumber": "Sample Transaction",
  "InvoiceNumber": "",
  "OrgAccountBalance": "25.00",
  "ThirdPartyTransID": "",
  "MSISDN": "2547 ***** 126",
  "FirstName": "NICHOLAS",
  "MiddleName": "",
  "LastName": ""
}

Accepting or rejecting a validation requestCopy Anchor Link

To accept, respond with ResultCode 0 and ResultDesc Accepted:

{ "ResultCode": "0", "ResultDesc": "Accepted" }

To reject, use any non-zero code from the table below and set ResultDesc to Rejected:

{ "ResultCode": "C2B00011", "ResultDesc": "Rejected" }

Error codesCopy Anchor Link

TestingCopy Anchor Link

Daraja Simulator: create a test app with the C2B product attached, register your URLs, then simulate with CustomerPayBillOnline or CustomerBuyGoodsOnline.

Postman: generate a token from https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials, then call the sandbox endpoint above. A ready-made Postman collection is available from the portal once logged in.

Go LiveCopy Anchor Link

Attach the integration to a live Pay Bill or Till, using a short code, organization name, and M-PESA admin/manager username. See Organization Portal & Go Live for creating those operators. Once approved, production endpoints are emailed to the developer on the account.

FAQsCopy Anchor Link