WhatsApp Cloud Api + Payment Integration Observations

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

Conversational commerce is already common in markets where messaging apps function as digital storefronts. In Nigeria, WhatsApp often serves as the primary channel through which small businesses interact with customers, share menus, and coordinate orders. However, unlike markets such as Brazil and India, where payments are natively integrated into WhatsApp, Nigerian businesses typically rely on third-party Payment Service Providers (PSPs). This separation requires developers to orchestrate messaging workflows, payment initiation, and transaction confirmations across multiple systems.

To explore how these systems interact in practice and serve our customers, we built a small pilot application called Jollof Boss — a WhatsApp-native food ordering service built with WhatsApp Cloud APIs and integrated with a Nigerian PSP (Paystack). The pilot instrumented the full order-to-payment lifecycle across pickup and delivery workflows, allowing us to observe latency, workflow coordination, and integration patterns between messaging infrastructure and payment services.

This article shares technical observations from that pilot, focusing on developer implementation patterns encountered when integrating WhatsApp Cloud messaging workflows, catalog-based ordering, webhook-driven order events, and external payment providers. The goal is to provide practical insights that may help developers design similar conversational commerce systems.

System Overview

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

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

The architecture connects messaging infrastructure with payment processing while keeping the entire experience within the WhatsApp conversation.

Technology Stack

The pilot was implemented using the following components:

1. WhatsApp Cloud APIs: messaging, catalog menus, order events
2. Spring Boot Backend: workflow orchestration and state management
3. Paystack PSP integration: payment authorization and confirmation
4. Webhook Architecture: event-driven transaction lifecycle

Architecture

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

Source: ChatGPT

Observed Transaction Metrics

During the pilot deployment, the backend recorded timestamps across each stage of the ordering workflow.

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

source: ChatGPT

Across both workflows, payment completion represented the largest portion of transaction time. Most of this delay was attributable to user interaction steps such as authentication and payment interface navigation.

Key Implementation Observations

During the development of the conversational ordering workflow, several recurring integration patterns emerged.

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

1. Catalog Menus Are Application-Defined

Interactive catalog menus using the WhatsApp product_list message type require developers to define menu sections and product identifiers directly within 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" }
          ]
        }
      ]
    }
  }
}

In practice, applications become responsible for managing:

• menu section structure
• product groupings
• product identifiers

This often leads developers to maintain local representations of the catalog in order to compose menus dynamically.

Possible Direction

One potential improvement would allow merchants to define menu sections directly in Meta Commerce Manager, enabling applications to retrieve structured catalog layouts dynamically instead of composing menus in the application layer with hard-coded sections and product identifiers.

Merchants could also mark 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, WhatsApp sends an order webhook event containing product identifiers, quantities, and prices.

Example payload:

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

However, the payload does not include human-readable product names.

To generate readable confirmations, such as:

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

Applications typically resolve product names through one of two ways:

Catalog API lookups resolving each productRetailerId through additional API calls or

Local catalog caches for maintaining a synchronized local copy of the catalog.

Both approaches introduce additional complexity in the application layer.

Possible Direction

Including product names directly in the order payload could simplify order confirmation workflows.

Example:

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

This could reduce catalog lookup requests, backend orchestration logic and response latency in conversational workflows

3. Merchant Inputs Often Require Free-Text Parsing

Some conversational workflows require merchants to provide operational values before payment can proceed. In the delivery workflow, the merchant needed to provide a delivery fee based on the customer’s location.

Since WhatsApp Cloud APIs currently do not support structured merchant input fields, the pilot collected this value through formatted free-text messages.

Example format:

DeliveryFee-PhoneNumber = 5000-234XXXXXXXX

Backend workflow:

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

While effective, this approach introduces:

• fragile parsing logic
• strict message formatting requirements
• additional backend validation logic

Possible Direction

Structured input fields similar to a Call-To-Action (CTA) Button interactive template could simplify operational workflows that require merchant-provided values.

Conceptual example:

{
  "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 support workflows requiring operational values such as:

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

Final Thoughts

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

Messaging delivery, webhook handling, and payment integrations operated reliably within an event-driven architecture.

The primary engineering effort centred on coordinating messaging events, catalog data, merchant inputs, and payment lifecycle events across systems. These patterns are not blockers, but they shape how developers currently design conversational commerce systems on WhatsApp.

The implementation observations documented here reflect a small pilot deployment but highlight patterns developers may encounter when building conversational commerce systems on WhatsApp.

Project Context & Further Reading

This project forms part of the Jollof Boss conversational commerce pilot.

A broader discussion of the ecosystem implications is available in the Techpoint Africa article.

These observations are also published in the **GitHub repository README** for developers who prefer reviewing them in a repository format.