Receive payments

1. Reseller-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.

For easier reconciliations, Tanda handles the Mobile Money accountReference in a special way. The accountReference is built from the reseller's wallet A/c number and the customer's phone number using the format {resellerWallerAccout}{accountNumber}. The calling code is stripped from the accountNumber prior.

Expected command ID

• CustomerPayment

Expected Service Provider ID(s)

• MPESA
• AIRTELMONEY

Expected request parameters

• amount (Transaction Amount)
• accountNumber (Customer's mobile number)
• merchantWallet (Merchant Collection Wallet Number issued by Tanda. This parameter is Optional)

Expected result parameters

• transactionRef (Reference number generated by the MMO)

2. Customer-initiated Customer Payment

2.1. Mobile money transfer

There is going to be a time when Reseller-initiated Customer Payment won't be suitable due to technical or business reasons. In that case, the customer will need:

• Business number (Shared by Tanda)
• Account Number is generated by joining the following:
  • your merchant account number.
  • letters IO.
  • a customer identifier from your system.
    For instance, if your merchant account number = 123456 and the customer identifier from your system is = ABCDEF, then the MoMo Account Number will be 123456IOABCDEF. ABCDEF will be assigned to the customer.number sent to your registered IPN endpoint.

2.2. Bank transfer

Customers can also pay by transferring funds from their bank account to a Tanda-provided and managed bank account. This is only possible via the following channels:

2.2.1. Pesalink

The customer must follow the steps below to achieve a seamless payment experience:

2.2.1.1. Send to our NCBA bank account

• Log in to your m-banking platform
• Send money via Pesalink to Dukapay Ltd NCBA bank account 3739470045
• Use your merchant account number followed by letters IO and a customer identifier from your system as the Pesalink narration e.g. if your merchant account number = 123456 and the customer identifier from your system is = ABCDEF, then the Pesalink narration will be 123456IOABCDEF. ABCDEF will be assigned to the customer.number sent to your registered IPN endpoint.
• The merchant wallet number can be found on the Reseller portal
• Balances are updated in about 0 - 45 mins

IPN

An IPN is a payment notification that Tanda sends to a merchant whenever a customer pays the merchant. Only Customer-initiated Customer Payments receive the IPN. The results of a Reseller-initiated Customer Payment are POSTed to the resultUrl specified during request initiation.

Configure your preferred IPN URL and Basic Auth username and password from the Tanda Reseller Portal. All Customer-initiated customer payments will be POSTed to that callback URL.

📘

Secure your callback URL using Basic Auth. The username and password are configured from the Tanda Reseller Portal

The configured callback URL MUST:

• Accept POST HTTP requests
• Accept application/json Content-Type
• Be publicly accessible

The IPN request body should have the following JSON format:

{
  "wallet": {
    "id": {collectionsWalletId},
    "account": {collectionsWalletAccountNumber},
    "actual": {collectionsWalletActualBalance},
    "available": {collectionsWalleAvailableBalance},
    "currency": "KES"
  },
  "customer": {
    "account": {customerIdentifier},
    "name": {customerName}
  },
  "transaction": {
    "id": {transactionId},
    "amount": {amount},
    "currency": "KES",
    "channel": {collectionChannel},
    "type": {D/W},
    "reference": {reference},
    "timestamp": "yyyy-MM-dd'T'HH:mm:ssZ"
  }
}