Payments

Pay Built-In Functions

The pay BIF is available on a persistent object instance representing the payment sender, and takes three parameters:

1. payment recipient
2. currency code
3. payment amount

Both the payer and payee needs to have an identifier. Depending on the Helium configuration for payments in the app this can either be a so called "MSISDN" or a mobile number attribute on both the payer and payee objects.

farmerPurchase.paymentId = farmer.pay(shop, "KES", farmerPurchase.finalCost);

The pay function returns a uuid that represents the internal Helium id for the payment. This, along with the @OnPaymentStatusUpdate annotation, can be used to track the payment status in the app.

The payWithRef BIF is useful for adding a reference to the Helium core app's payments view. It has two additional parameters:

4. payment reference
5. message string (omit message by providing an empty string)

farmerPurchase.paymentId = farmer.payWithRef(
    shop, "KES", farmerPurchase.finalCost, farmerPurchase._id,
    Strings:concat(shop.name, " - ", shop.shopCode)
);

@OnPaymentUpdate Annotation for Payment Callback Functions 

Helium processes payments asynchronously. This means that a result of a call to the pay function will not be immediately available.

Helium provides a mechanism whereby an app function can be declared as a callback that will be invoked once Helium has an update on the payment status. This is implemented by means of the @OnPaymentUpdate annotation. Such a callback for payments made without an additional reference is included in the app in the PaymentCallback unit under the services folder:

@OnPaymentUpdate
void paymentUpdate(uuid id, PAYMENT_STATUS status, string message){
     
    // Find the associated purchase based on the internal Helium payment ID
    // Ids should be unique so we are only expecting one purchase in the resulting collection
    FarmerPurchase[] farmerPurchases = FarmerPurchase:equals(paymentId, id);
     
    if(farmerPurchases.length() >= 0) {
        FarmerPurchase farmerPurchase = farmerPurchases.first();
         
        // Update the payment status maintained on the farmer purchase
        farmerPurchase.paymentStatus = status;
         
        // Record the time stamp of the update
        farmerPurchase.paymentStatusUpdatedOn = Mez:now();
    }
}

or payments that were made with an additional reference we can change the function signature as follows:

@OnPaymentUpdate
void paymentUpdateWithRef(uuid id, string reference, PAYMENT_STATUS status, string message){
.
.
}

A summary of the possible PAYMENT_STATUS statuses and their meanings follow below.

Additional Mentions and References

• Lesson 12: Payments, Widget Visiblity#PayBuilt-InFunctions
• Lesson 12: Payments, Widget Visiblity#%40OnPaymentUpdateAnnotationforPaymentCallbackFunctions
• Quick Reference#PersistentEntityBIFs
• Quick Reference#FunctionAnnotations