Appearance

Hubtel Callback ​

The Hubtel Callback solution consists of a callback receiver API and a callback sender consumer. These components work together to handle callbacks efficiently and effectively.

Hubtel Callback Receiver Api ​

The Hubtel Callback Receiver API allows you to securely set up and expose an API project for receiving callbacks into your system. This API ensures the isolation of the callback endpoint, providing enhanced security. Our infrastructure will set up an instance of this API for your project with the necessary configuration. The API receives callbacks on configured endpoints and writes them to configured topics.

Hubtel Callback API
An overview of how the callback API Works

Setting up a callback ​

To set up a callback, follow these steps:

  1. Use the existing build pipeline for this API to generate release artifacts.
  2. Have your Product Reliability Engineer (PRE) create a new release pipeline that references the build outputs of the build pipeline.
  3. Configure the appropriate callback endpoint as required by your project and deploy the instance of the API with the help of your PRE.
  4. Configure your consumer to listen on the configured topic and receive the callback data into your system, also with the assistance of your PRE.

Callback API Configuration ​

The key sections to configure for Hubtel Callback API are the EndpointConfiguration and KafkaProducerConfig Sections.

json
"EndpointConfiguration": {
    "DefaultProducerTopic": "hubtel.receivemoney.callbackreceived.default",
    "EndpointDefinitions": [
        {
            "UrlPath": "voda-receive-money/{name}/callback",
            "HttpMethod": "POST", // "GET", "PUT", "PATCH"
            "ProducerTopic": "hubtel.receivemoney.callbackreceived.vodafonegh1"
        },
        {
            "UrlPath": "mtn-receive-money/callback",
            "HttpMethod": "PUT",
            "ProducerTopic": "hubtel.receivemoney.callbackreceived.mthgn"
        },
        {
            "UrlPath": "airteltigo-receive-money/callback",
            "HttpMethod": "GET",
            "ProducerTopic": "hubtel.receivemoney.callbackreceived.airteltigo"
        },
        {
            "UrlPath": "cybersourceproxy/callback",
            "HttpMethod": "POST",
            "ProducerTopic": "hubtel.receivemoney.card.cybersource.callback_received"
        }
    ]
},
"KafkaProducerConfig": {
    "Hosts": [
        {
            "Alias": "default",
            "BootstrapServers": "kafka:9092"
        }
    ]
}

The following is the configuration for the Hubtel Callback API:

EndpointConfiguration:

  • DefaultProducerTopic: Specifies the default topic for receiving callback data.
  • EndpointDefinitions: Contains a list of endpoint configurations for different callback scenarios. Each configuration includes the UrlPath, HttpMethod, and ProducerTopic.
    • UrlPath: voda-receive-money/{name}/callback
      • Specifies the URL path for the callback endpoint. The {name} part is a placeholder for a dynamic segment in the URL.
    • HttpMethod: POST
      • Indicates that this endpoint accepts HTTP POST requests. Other possible methods (commented out) include GET, PUT, and PATCH.
    • ProducerTopic: hubtel.receivemoney.callbackreceived.vodafonegh1
      • Defines the topic name for which the received request should be produced to

KafkaProducerConfig:

  • Hosts: Specifies the Kafka server configuration, including the Alias and BootstrapServers.

Callback Kafka Message ​

json
{
    "RequestBody": {
        "ResponseCode": "0000",
        "Data": {
            "PaymentDate": "2024-06-21T18:27:05.9268916Z",
            "TransactionId": "xxxx",
            "ExternalTransactionId": "xxxxx",
            "OrderId": "xxxx",
            "Description": "You have paid GHS15.00",
            "ClientReference": "xxxx",
            "Amount": 15.0,
            "AmountDebited": 0.0,
            "Charges": 0.22
        },
        "Message": "success",
        "Code": 0,
        "SubCode": 0,
        "Errors": null
    },
    "QueryParams":  {
        "userId": "xxxxx",
        "districtId": "xxxxx"
    },
    "RouteParams": {
        "meterId": "xxxxx",
        "walletId": "xxxxx"
    }
}

The Callback Kafka Message your consumer will receive is made up of 3 major fields:

  • RequestBody: contains the payload received in the callback request.
  • QueryParams: contains the URL query params sent with the callback request.
  • RouteParams: contains the URL route params sent with the callback request.

Developing against Hubtel Callback API ​

To develop against Hubtel callback API, you can login into Hubtel's Github Docker Registry and pull the latest image with the following command:

bash
docker pull ghcr.io/hubtel/hubtel-callback-receiver-api:latest