Whatsapp Cloud Api + Payment Integration Observations

Implementation observations from a WhatsApp Cloud API pilot in Nigeria, demonstrating conversational food ordering with integrated payment services.

Developer Observations

This repository documents implementation observations from building a small conversational commerce pilot using WhatsApp Cloud APIs and a payment service provider.

The goal of publishing these notes is to share practical developer experiences integrating:

• WhatsApp Cloud API messaging workflows
• catalog-based ordering
• webhook-driven order events
• Nigerian Payment Service Provider (PSP).

The observations in this repository reflect implementation patterns encountered during the pilot and are shared to help developers design similar conversational commerce systems.

---

System Overview

The system, called Jollof Boss, implemented a WhatsApp-native food ordering workflow supporting the full order lifecycle:

Customer → Menu → Order → Payment → Merchant/Customer Notification

Technology Stack

• WhatsApp Cloud APIs: messaging, catalog menus, order events
• Spring Boot backend: workflow orchestration and state management
• Paystack PSP integration: payment authorization and confirmation
• Webhook architecture: event-driven transaction lifecycle

---

Architecture

The system was implemented using an event-driven orchestration model as shown in the architecture diagram below.

---

Observed Transaction Metrics

During the pilot, the backend recorded timestamps across each stage of the workflows (Delivery and Pick-Up).

These metrics are instrumentation observations from a small pilot deployment, not platform benchmarks.

Messaging and Backend Performance

Operation	Typical Duration
WhatsApp message dispatch	1–3 seconds
Backend processing	<15 seconds
Merchant notification after payment	near-instant
Payment processing time (Pickup)	105 seconds
Payment processing time (Delivery)	50 seconds

End-to-End Transaction Time

Order Type	Average Duration
Pickup orders	~132 seconds
Delivery orders	~122 seconds

In both Delivery and Pick-Up workflows, payment completion represented the largest portion of transaction duration, primarily due to user interaction steps such as authentication and payment interface navigation.

---

Key Observations from the Pilot

During implementation of the conversational ordering workflow, three recurring integration patterns were observed:

• Application-defined catalog menus
  Interactive catalog menus require developers to define product sections and identifiers within the application payload.

• Order payloads contain product IDs but not product names
  Order webhook events return productRetailerId values without human-readable product names, requiring additional catalog lookups or local catalog replicas to generate readable confirmations.

• Merchant operational inputs require free-text parsing
  Because WhatsApp Cloud APIs do not currently support structured merchant input fields, values such as delivery fees were collected via formatted free-text messages and parsed by the backend.

These patterns reflect how developers currently coordinate messaging workflows, catalog data, and payment integrations when building conversational commerce systems on WhatsApp Cloud.

Implementation Patterns

The following sections describe the implementation patterns observed during the pilot in more detail.

1. Catalog Menus Are Application-Defined

WhatsApp interactive catalog menus (product_list) require developers to define menu sections in the API payload.

Example request:

{
  "type": "interactive",
  "interactive": {
    "type": "product_list",
    "header": {
      "type": "text",
      "text": "Jollof Boss Menu"
    },
    "body": {
      "text": "Choose a meal"
    },
    "action": {
      "catalog_id": "158747027232639",
      "sections": [
        {
          "title": "Jollof Rice Packs",
          "product_items": [
            { "product_retailer_id": "4ru83njoue" },
            { "product_retailer_id": "motfzzwa0h" }
          ]
        }
      ]
    }
  }
}

This means applications must manage:

• section titles
• product groupings
• product identifiers

---

Possible Direction

One potential improvement would allow merchants to define menu sections directly in Meta Commerce Manager, enabling applications to dynamically retrieve structured catalog layouts instead of composing menus in the application layer with hard-coded sections and product identifiers. Merchants could also mark menu sections as active or out-of-stock without requiring application updates.

---

2. Order Payloads Contain Product IDs but Not Product Names

When a customer places an order, the webhook event returns an Order object which contains productRetailerId, quantity, itemPrice and currency.

Example payload:

{
  "catalogId": "158747027232639",
  "productItems": [
    {
      "productRetailerId": "q44n1fqt6z",
      "quantity": 1,
      "itemPrice": 13000,
      "currency": "NGN"
    }
  ]
}

However, the payload does not include product names to generate readable confirmations for the Merchant and Customer:

1 × 5-Litre Bowl Jollof Rice
1 × Fried Chicken
Total: NGN 17,000

Developers typically handle this in one of two ways:

• Catalog API lookup

  • Resolve each productRetailerId via an additional catalog API call
  • Adds latency and increases the number of API calls per order

• Local catalog cache

  • Maintain a local replica of the WhatsApp catalog
  • Reduces lookup time but introduces catalog synchronization and consistency challenges

---

Possible Direction

Including productName in the order payload could simplify confirmation workflows.

Conceptual example:

{
  "productRetailerId": "q44n1fqt6z",
  "productName": "5-Litre Bowl Jollof Rice",
  "quantity": 1,
  "itemPrice": 13000,
  "currency": "NGN"
}

Benefits:

• fewer catalog lookups
• simpler backend logic
• faster conversational responses

---

3. Merchant Inputs Often Require Free-Text Parsing

In the Delivery workflow, merchants needed to provide a delivery fee, calculated based on the customer's address, before a payment link could be generated.

Because WhatsApp Cloud APIs currently do not support structured merchant input fields, the delivery fee was collected via free-text messages and parsed by the backend.

To minimize ambiguity, an application workaround required merchants to follow a strict message format:

Example message:

DeliveryFee-PhoneNumber = 5000-234XXXXXXXX

Backend workflow:

Merchant message received
        ↓
Validate format
        ↓
Parse delivery fee
        ↓
Generate payment link

This approach introduces several challenges:

• Fragile parsing — free-text inputs are sensitive to formatting errors
• Increased workflow latency — the backend must validate and parse messages before proceeding
• Additional application logic — developers must implement custom validation and parsing rules
• Hard-coded prompts — message formats must remain fixed to ensure reliable parsing

---

Possible Direction

Structured Inputs Similar to CTA Button Templates

Structured template input fields could be implemented similarly to Call-to-Action (CTA) button templates.

Example conceptual template:

{
  "messaging_product": "whatsapp",
  "to": "<merchant_number>",
  "type": "template",
  "template": {
    "name": "request_delivery_fee",
    "language": { "code": "en" }
  },
  "cta_input": {
    "fields": [
      {
        "name": "delivery_fee",
        "label": "Delivery Fee (NGN)",
        "type": "number",
        "required": true
      }
    ]
  }
}

Structured inputs could simplify conversational workflows requiring operational values such as:

• delivery fees
• stock confirmation
• preparation times
• discount values

---

Key Takeaways

From an infrastructure perspective:

• WhatsApp Cloud messaging is reliable
• webhook delivery works well for event-driven systems
• PSP integrations are straightforward

The implementation observations come from application-layer orchestration around:

• catalog menu composition
• order payload resolution
• merchant operational inputs

These patterns are not blockers, but they shape how developers currently design conversational commerce systems on WhatsApp.

---

Conclusion

This pilot illustrates how conversational commerce workflows can be implemented using WhatsApp Cloud APIs and external payment providers.

Messaging delivery, webhook handling, and payment integrations operated reliably in an event-driven architecture. Most engineering effort is centred on coordinating catalog menus, order payloads, merchant inputs, and payment events across systems.

The patterns documented here reflect implementation observations from a small pilot and may help developers design similar conversational commerce applications.

---

Project Context & Further Reading

This repository documents implementation observations from the Jollof Boss conversational commerce pilot.

A broader discussion of the observations and ecosystem implications from this pilot is available in the Techpoint Africa article:

🔗 Jollof Boss Launches WhatsApp–Paystack Pilot Testing Chat Commerce for African SMEs

Feel free to reach out for questions or discussions about the implementation.