App Payment Configuration Support Request

Owned by Jacques Marais
Last updated: Mar 19, 2021

In order to configure an app for payments the following details need to be specified in your support request:

  1. The Helium server where the app is located.
  2. The unique identifier (UUID) of your app. If you are unsure how to obtain the app id for your app, please consult the documentation here.
  3. The M-Pesa account number also known as the shortcode. Only applicable to the old Safaricom KE and Vodacom TZ payment drivers.
  4. In the case of the new Vodafone driver the API key that is generated from the online portal.
  5. All objects that are involved in payments. In other words the objects that represent entities making payments and receiving payments in the app. In the example shown in Lesson 12 of the tutorial, the objects are Farmer and Shop. For each object the following should also be specified:
    • The field on the object that is to be used as an M-Pesa identifier
    • The type of M-Pesa identifier that is represented by the field mentioned above. This can, for example, be an MSISDN (such as a mobile number) or a Short Code / till number.

If there are multiple accounts being used in your app, please also specify the following in addition to the above items:

  1. The M-Pesa account number also known as the shortcode for all accounts (Only relevant to the old Safaricom KE and Vodacom TZ payment drivers).
  2. A field on one of the payment objects or an object related to a payment object that represents an account to be used.
  3. The values used to represent accounts on the field mentioned above, can be arbitrary, but a mapping also needs to be specified that maps possible values of this field with actual accounts represented by the account number specified in point 1 of this section.


Configuring apps for M-pesa payments is a complex topic. To assist with the understanding of this please see the two examples shown in the sections that follow. Once you have made the request, you will be asked to specify the initiator user name and password for each M-Pesa account. Although these credentials should not be included in the original request, it is very important that they are generated before the initial request is made. This is essential in order for the request to be serviced as fast as possible.

Once the content of your request has been finalised it can be sent using the following channels:

  • For internal Mezzanine developers, create a JIRA ticket on the HE project. The ticket type should be "Support Request".
  • For external PaaS client developers, send an e-mail with your request to Mezzanine Support at support@mezzanineware.com.



Example 1: Single M-Pesa Account


Pay Built-In Function Usage

UUID makePayment(Payer payer, Payee payee, int value) {
	UUID paymentId = payer.pay(payee, "KES", value);
	return paymentId;
}


Relevant Model

persistent object Payer {
	string name;
	string description;
	string mobileNumber;
}
persistent object Payee {
	string name;
	string description;
	string mobileNumber;
}


Request Example

Good day,

I would like to request that my app with appId a3515db6-ed0b-5b04-be1a-41f22e27d15a on the server located at https://some-server.mezzaninewe.com be configured for payments with the following details:

M-Pesa account number (shortcode): 111222


Relevent data model objects and fields:

Object: Payer

M-Pesa Identifier field: mobileNumber

M-Pesa Identifier type: MSISDN


Object: Payee

M-Pesa Identifier field: mobileNumber

M-Pesa Identifier type: MSISDN




Example 2: Mutiple M-Pesa Accounts


Pay Built-In Function Usage

UUID makePayment(Payer payer, Payee payee, int value) {
	UUID paymentId = payer.pay(payee, "KES", value);
	return paymentId;
}


Relevant Model

persistent object Branch {
	string branchName;
}
persistent object Payer {
	string name;
	string description;
	string mobileNumber;
 
	@ManyToOne
	Branch branch via payers;
}
persistent object Payee {
	string name;
	string description;
	string mobileNumber;
}


Request Example

Good day,

I would like to request that my app with appId a3515db6-ed0b-5b04-be1a-41f22e27d15a on the server located at https://some-server.mezzaninewe.com be configured for payments with the following details:

M-Pesa account numbers (shortcode): 111222, 111333, 111444


Relevent data model objects and fields:

Object: Payer

M-Pesa Identifier field: mobileNumber

M-Pesa Identifier type: MSISDN


Object: Payee

M-Pesa Identifier field: mobileNumber

M-Pesa Identifier type: MSISDN


The M-Pesa branch to use with a payment can be referenced from the Payer objects as follows:

payer.branch.branchName

and can have the following values:

BranchOne

BranchTwo

BranchThree


These branches are mapped to the available M-Pesa accounts as follows:

BranchOne: 111222

BranchTwo: 111333

BranchThree: 111444