Receive payments

Merchant initiated customer payment

This is one of the 2 ways a reseller can receive cash from their customers. In the Mobile Money space, this is achieved through USSD push or STK push. The customer receives a prompt to enter their mobile money account PIN.

This acts as consent and completes the transaction by transfering e-value from the customer's wallet to a business short code (Paybill) or to a merchant short code (Till). The Tanda I/O RESTful API supports this channel natively.

Path: /io/v3/organizations/{organizationId}/request

Method: POST

CommandId: CustomerToMerchantMobileMoneyPayment

Use the following for testing

organizationId: a353acfa-5340-49ac-8f7c-2f807a87fc2f

shortCode: 746312

Body

Parameter	Description	Mandatory
commandId	Specifies the command to be executed, in this case, CustomerToMerchantMobileMoneyPayment	Yes
serviceProviderId	Specifies the service provider for the mobile money payment, Supported service providers are:- MPESA - AIRTELMONEY	Yes
reference	A unique reference for the transaction. It should be between 8-16 alphanumeric characters	Yes
request	Object array containing additional request details	Yes

Request parameters

Parameter	Description	Mandatory
amount	The amount of money in Ksh.	Yes
shortCode	Uniquely identifies an entity making a request. This is issued by Tanda	Yes
accountNumber	Mobile phone number	Yes
narration	Description of the payment.	Yes
ipnUrl	URL to receive Instant payment notifications.	Yes

Example request

{
  "commandId": "CustomerToMerchantMobileMoneyPayment",
  "serviceProviderId": "MPESA",
  "reference":"REFEBC1234",
  "request": [
    {
        "id": "amount",
        "value": "2",
        "label": "Amount"
    },{
        "id": "narration",
        "value": "Payment via Till",
        "label": "Narration"
    },
    {
        "id": "ipnUrl",
        "value": "https://tanda-tills-ipn.free.beeceptor.com",
        "label": "Notification URL"
    },{
         "id": "shortCode",
        "value": "746312",
        "label": "Short code"
    },{
         "id": "accountNumber",
        "value": "25470000000",
        "label": "Phone number"
    }
  ]
}

Sample response

{
    "trackingId": "b5b47bd2-c1da-4b8a-b0de-ffb4ec474bff",
    "reference": "QBQIGRH1",
    "status": "P202000",
    "message": "Successful. Request accepted for processing. You'll be notified by Tanda shortly"
}