P
Welcome, Phineas
Signed in as phin254

    APIs

    Customer To Business Register URL

Customer To Business Register URL
Register validation and confirmation URLs on M-Pesa
POSThttps://sandbox.safaricom.co.ke/mpesa/c2b/v1/registerurl

Register URL API works hand in hand with Customer to Business (C2B) APIs and allows receiving payment notifications to your paybill. This API enables you to register the callback URLs via which you shall receive notifications for payments to your pay bill/till number.

There are two URLs required for Register URL API: Validation URL and Confirmation URL.

Validation URL: This is the URL that is only used when a Merchant (Partner) requires to validate the details of the payment before accepting. For example, a bank would want to verify if an account number exists in their platform before accepting a payment from the customer.

Confirmation URL:  This is the URL that receives payment notification once payment has been completed successfully on M-PESA.

NB: C2B Transaction Validation is an optional feature that needs to be activated on M-Pesa, the owner of the shortcode needs to make this request for activation by emailing us at apisupport@safaricom.co.ke or M-pesabusiness@safaricom.co.ke  if they need their transactions validated before execution.


 

The above chart, explains how URLs are registered to send requests and receive responses.
Flowchart of the C2B process

The process is explained below:

    Payment request to a pay bill by a customer from their phone.
    M-PESA receives requests and validates them internally
    M-Pesa then checks if External Validation has been activated for the paybill.
    If External Validation is enabled:
        M-PESA first sends a Validation request to the Validation URL registered in the system by the integrated partner with the payment details.
        The integrated partner system validates the request and sends an appropriate response to M-PESA. This response must be received within a given period or M-Pesa marks the partner endpoint as unreachable. The response informs M-Pesa to either complete or cancel the payment:
        M-Pesa receives the response and processes the transaction accordingly:
        As explained in item 6 below, If you had registered a default action value to complete the transaction, M-PESA sends a Confirmation request to your Confirmation URL with the details of the completed transaction. The transaction is then complete. Thus you shall receive two API calls on your system.
        If you had registered cancelled as the default action, M-Pesa simply cancels the transaction and no other request is sent. The transaction is then complete
    If External Validation is disabled, M-Pesa automatically completes the transaction, and if the transaction is a success, M-Pesa sends a Confirmation request to the Confirmation URL registered in the system. This is the only API call you shall receive on your end.
    If External Validation is enabled, but for some reason, M-Pesa could not reach your endpoint to validate the transaction within the stipulated time period (usually < 8 seconds from the moment the request leaves M-PESA), or no response was received by the time M-PESA terminates the request, it checks on the default action value saved during registration of the URLs. If the default action was set to Completed, M-PESA automatically completes the transaction and also tries to send a Confirmation request to your other endpoint. If the default action was set to Cancelled, M-Pesa simply cancels the transaction and no Confirmation callbacks are sent. The transaction is then complete.
    If no URLs are registered in the system, M-PESA automatically completes the request.
    M-PESA then sends an SMS notification to both the customer and the paybill owner with the results of the transaction as usual.
    When external notifications fail to be sent, you can use Pull transaction API for reconciliation or check on the M-PESA Org portal https://org.ke.m-pesa.com/login.action and cross-check against received callbacks. The portal has all the payments ever made available, whether you received the callback or not.

URL Requirements

    Use publicly available (Internet-accessible) IP addresses or domain names.
    All Production URLs must be HTTPS, on Sandbox you're allowed to simulate using HTTP.
    Avoid using keywords such as M-PESA, M-Pesa, M-Pesa, Safaricom, exe, exec, cmd, SQL, query, or any of their variants in either upper or lower cases in your URLs.
    Do not use public URL testers e.g. ngrok, mockbin, or requestbin, especially on production, they are also usually blocked by the API. Use your own application URLs and do not make them public or share them with any of your peers.

NB:

On the sandbox, you are free to register your URLs multiple times or even overwrite the existing ones. In the production environment, this is a one-time API call that registers your validation and confirmation URLs to have them changed you can delete them on the URL management tab under self-service and re-register using register URL API, you can also email us at apisupport@safaricom.co.ke for assistance.

As you set up the default value, the words “Cancelled/Completed” must be in sentence case and well-spelled.
Request Body
{    
   "ShortCode": "601426",
   "ResponseType":"[Cancelled/Completed]",
   "ConfirmationURL":"[confirmation URL]",
   "ValidationURL":"[validation URL]"
}
Request Parameter Definition

Name
	

Description
	

Type
	

Sample Values

Validation URL
	

This is the URL that receives the validation request from the API upon payment submission. The validation URL is only called if the external validation on the registered shortcode is enabled. (By default External Validation is disabled).
	

URL
	

https://ip or domain:port/path

ConfirmationURL
	

This is the URL that receives the confirmation request from API upon payment completion.
	

URL
	

https://ip or domain:port/path

ResponseType
	

This parameter specifies what is to happen if for any reason the validation URL is not reachable. Note that, this is the default action value that determines what M-PESA will do in the scenario that your endpoint is unreachable or is unable to respond on time. Only two values are allowed: Completed or Cancelled. Completed means M-PESA will automatically complete your transaction, whereas Cancelled means M-PESA will automatically cancel the transaction, in the event M-PESA is unable to reach your Validation URL.
	

String
	

- Canceled
- Completed


Shortcode
	

Usually, a unique number is tagged to an M-PESA pay bill/till number of the organization.
	

Numeric
	

123456
Response Body
{
    "OriginatorCoversationID": "7619-37765134-1",
    "ResponseCode": "0",
    "ResponseDescription": "success"
}
Response Parameters Definition

Name
	

Description
	

Type
	

Sample Values

OriginatorCoversationID
	

This is a global unique identifier for the transaction request returned by the API proxy upon successful request submission.
	

Alpha-numeric
	

An alpha-numeric string of fewer than 20 characters

ResponseCode
	

It indicates whether Mobile Money accepts the request or not.
	

Alpha-numeric
	

0

ResponseDescription
	

This is the status of the request.
	

String
	

Success


NB: Before any API request register URL is included, you will require authorization by generating an access token from the authorization API to allow you successfully make an API call.

Once you’ve registered URLs as explained above, C2B API payment transaction is initiated by the customer when they are paying. You can use the simulator to have an overview of how the request looks. You don’t need to develop anything on your side for this part.


Upon successful payment, we post the payment details to your confirmation and validation URLs as explained in the resulting body below;
Result Body

Validation Request

The validation request is received only by partners who have the External Validation feature enabled on their PayBill or BuyGoods (Till Number) and require validating a payment before M-PESA completes the transaction. You will first receive a validation request to validate on your Validation URL.


The Confirmation and Validation result posted on your URLs after payment will have the structure below:
{    
   "TransactionType": "Pay Bill",
   "TransID":"RKTQDM7W6S",
   "TransTime":"20191122063845",
   "TransAmount":"10"
   "BusinessShortCode": "600638",
   "BillRefNumber":"invoice008",
   "InvoiceNumber":"",
   "OrgAccountBalance":""
   "ThirdPartyTransID": "",
   "MSISDN":"25470****149",
   "FirstName":"John",
   "MiddleName":""
   "LastName":"Doe"
}


Validation Response

After receiving the validation request, you are required to process it and respond to the API call and inform M-PESA either to accept or reject the payment. To accept, you send the below JSON making sure the value of ResultCode is 0 (zero), but the value of ResultDesc is Accepted.
{    
   "ResultCode": "0",
   "ResultDesc": "Accepted",
}


To reject a transaction, you send the same JSON above, but with the ResultCode set as C2B00011 (or any other value from the error table below), BUT NOT 0. The ResultDesc should be set as Rejected as shown below:
{    
   "ResultCode": "C2B00011",
   "ResultDesc": "Rejected",
}


Result Error Codes

ResultCode
	

ResultDesc

C2B00011
	

Invalid MSISDN

C2B00012
	

Invalid Account Number

C2B00013
	

Invalid Amount

C2B00014
	

Invalid KYC Details

C2B00015
	

Invalid Shortcode

C2B00016
	

Other Error
Results Parameter Definition

Name
	

Description
	

Type
	

Sample Values

TransactionType
	

The transaction type specified during the payment request.
	

String
	

Buy Goods or Pay Bill

TransID
	

This is the unique M-Pesa transaction ID for every payment request. This is sent to both the call-back messages and a confirmation SMS sent to the customer.
	

Alpha-numeric
	

LHG31AA5TX

TransTime
	

This is the Timestamp of the transaction, normally in the format of YEAR+MONTH+DATE+HOUR+MINUTE+SECOND (YYYYMMDDHHMMSS) Each part should be at least two digits apart from the year which takes four digits.
	

Time
	

YYYYMMDDHHmmss e.g. 20170813154301

TransAmount
	

This is the amount transacted (normally a numeric value), money that the customer pays to the Shortcode. Only whole numbers are supported.
	

Numeric
	

100

BusinessShortCode
	

This is the organization's shortcode (Paybill or Buygoods - a 5 to 6-digit account number) used to identify an organization and receive the transaction.
	

String
	

Shortcode (5 to 6 digits) e.g. 654321

BillRefNumber
	

This is the account number for which the customer is making the payment. This is only applicable to Customer PayBill Transactions
	

String
	

An alpha-numeric value of up to 20 characters.

OrgAccountBalance
	

The current utility account balance of the payment-receiving organization shortcode. For validation requests, this field is usually blank whereas, for the confirmation message, the value represents the new balance after the payment has been received.
	

Decimal
	

30671

ThirdPartyTransID
	

This is a transaction ID that the partner can use to identify the transaction. When a validation request is sent, the partner can respond with ThirdPartyTransID and this will be sent back with the Confirmation notification
	

String
	

1234567890

MSISDN
	

This is a masked mobile number of the customer making the payment.
	

Numeric
	

25470****149

FirstName
	

The customer's first name is as per the M-Pesa register. This parameter can be empty.
	

String
	

John

MiddleName
	

The customer's middle name is as per the M-Pesa register. This parameter can be empty.
	

String
	Doe


LastName
	

The customer's last name is as per the M-Pesa register. This parameter can be empty.
	

String
	




NB: Data minimization is a requirement from the data protection office not to share customers’ personal information without their consent.

Validation Response - Expected from your validation URL.

Name
	

Description
	

Type

ResultCode
	

A code indicating whether to complete the transaction. 0(Zero) always means complete. Other values mean canceling the transaction, which also determines the customer notification SMS type.
	

Alpha-numeric

ResultDesc
	

Short validation result description
	

String

ThirdPartyTransID
	

An optional value that can be used to identify the payment during a confirmation callback. If a value is set, it would be passed back in a confirmation callback.
	

String


Confirmation acknowledgment - Expected from your Confirmation URL.

Name
	

Description
	

Type

ResultCode
	

A code indicating the receipt status of the confirmation callback. Always 0(zero).
	

Number

ResultDesc
	

A short confirmation receipt description. Usually “Success”.
	

String


Customer To Business Register URL
4:52:48 am
Simulator
Use this simulator to invoke requests to the API
​
Select or search one of your apps
​
Business Short Code *
​
Amount *
​
MSISDN (Phone No) *
254
​
Command ID *
CustomerPayBillOnline
​
Bill Reference Number *
Account Number of Organization
9 / 20
