SDK Integration

Nkwa Pay provides official SDKs for seamless in-app integration across multiple programming languages. These SDKs offer a convenient wrapper around our API endpoints, making it easier to integrate mobile money payments into your applications. All SDK operations mirror the functionality available in the API reference and the Nkwa Pay dashboard. This guide demonstrates how to install, configure, and use our SDKs to process mobile money transactions in your preferred programming language.

JavaScript
PHP
Python
Java
Go

Install Client

Install the Nkwa Pay JavaScript SDK using npm, pnpm, bun, or yarn:

terminal

# Using npm
$ npm add @nkwa-pay/sdk

# Using pnpm
$ pnpm add @nkwa-pay/sdk

# Using bun
$ bun add @nkwa-pay/sdk

# Using yarn
$ yarn add @nkwa-pay/sdk zod
# Note that Yarn does not install peer dependencies automatically

Configure

Import and initialize the Nkwa Pay client:

example

import { Pay } from "@nkwa-pay/sdk";

// Initialize with your API key
const pay = new Pay({
  apiKeyAuth: "your_api_key",
});

Server Selection

You can specify a custom server URL when initializing the client:

example

// For sandbox environment
const pay = new Pay({
  apiKeyAuth: "your_api_key",
  serverURL: "https://api.sandbox.pay.mynkwa.com",
});

// For production environment
const pay = new Pay({
  apiKeyAuth: "your_production_api_key",
  serverURL: "https://api.pay.mynkwa.com",
});

Collect Payment

To request a payment from a customer:

example

async function collectPayment() {
  try {
    const result = await pay.collect.post({
      requestBody: {
        amount: 1000, // Amount in XAF
        phoneNumber: "237600000000",
        description: "Payment for order #1234"
      }
    });
    
    console.log(result.payment.id); // Use this ID to check payment status later
  } catch (error) {
    console.error(error);
  }
}

Disburse Payment

To send money to a customer:

example

async function disbursePayment() {
  try {
    const result = await pay.disburse.post({
      requestBody: {
        amount: 1000, // Amount in XAF
        phoneNumber: "237600000000",
        description: "Refund for order #1234"
      }
    });
    
    console.log(result.payment.id); // Use this ID to check disbursement status later
  } catch (error) {
    console.error(error);
  }
}

Check Payment Status

To check the status of a payment:

example

async function checkPaymentStatus(paymentId) {
  try {
    const result = await pay.payments.get({
      id: paymentId,
    });
    
    console.log(result.payment.status); // "pending", "successful", or "failed"
  } catch (error) {
    console.error(error);
  }
}

Check MNO Availability

To check the availability of mobile network operators:

example

async function checkAvailability() {
  try {
    const result = await pay.availability.get();
    
    // Check if MTN collections are operational
    const mtnCollections = result.availability.find(a => 
      a.operator === "mtn" && a.operation.type === "collection"
    );
    
    console.log(mtnCollections.operation.status); // "OPERATIONAL" or "SUSPENDED"
  } catch (error) {
    console.error(error);
  }
}

Install Client

Install the Nkwa Pay PHP SDK with Composer:

terminal

$ composer require "nkwa-pay/sdk"

Configure

Import and initialize the Nkwa Pay client:

example

<?php

declare(strict_types=1);
require 'vendor/autoload.php';

use Pay\Pay;

// Initialize client with your API key
$sdk = Pay::builder()
    ->setSecurity('<YOUR_API_KEY_HERE>')
    ->build();

Server Selection

You can specify a custom server URL when initializing the client:

example

<?php

declare(strict_types=1);
require 'vendor/autoload.php';

use Pay\Pay;

// For sandbox environment
$sdk = Pay::builder()
    ->setSecurity('<YOUR_API_KEY_HERE>')
    ->setServerURL('https://api.sandbox.pay.mynkwa.com')
    ->build();

// For production environment
$sdk = Pay::builder()
    ->setSecurity('<YOUR_PRODUCTION_API_KEY>')
    ->setServerURL('https://api.pay.mynkwa.com')
    ->build();

Collect Payment

To request a payment from a customer:

example

try {
    $response = $sdk->collect->post(
        requestBody: [
            'amount' => 1000, // Amount in XAF
            'phoneNumber' => '237600000000',
            'description' => 'Payment for order #1234'
        ]
    );
    
    if ($response->payment !== null) {
        echo "Payment ID: " . $response->payment->id; // Use this ID to check payment status later
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

Disburse Payment

To send money to a customer:

example

try {
    $response = $sdk->disburse->post(
        requestBody: [
            'amount' => 1000, // Amount in XAF
            'phoneNumber' => '237600000000',
            'description' => 'Refund for order #1234'
        ]
    );
    
    if ($response->payment !== null) {
        echo "Disbursement ID: " . $response->payment->id; // Use this ID to check status later
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

Check Payment Status

To check the status of a payment:

example

try {
    $paymentId = 'payment_id_here';
    $response = $sdk->payments->get(
        id: $paymentId
    );
    
    if ($response->payment !== null) {
        echo "Payment status: " . $response->payment->status; // "pending", "successful", or "failed"
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

Check MNO Availability

To check the availability of mobile network operators:

example

try {
    $response = $sdk->availability->get();
    
    if ($response->availability !== null) {
        // Process availability information
        foreach ($response->availability as $provider) {
            echo "Operator: " . $provider->operator . ", ";
            echo "Operation type: " . $provider->operation->type . ", ";
            echo "Status: " . $provider->operation->status . "\n";
        }
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

Install Client

Install the Nkwa Pay Python SDK with pip or poetry:

terminal

# Using pip
$ pip install nkwa-pay-sdk

# Using poetry
$ poetry add nkwa-pay-sdk

Configure

Import and initialize the Nkwa Pay client:

example

from nkwa_pay_sdk import Pay

# Initialize client with your API key
sdk = Pay(
    api_key_auth="your_api_key",
)

Server Selection

You can specify a custom server URL when initializing the client:

example

from nkwa_pay_sdk import Pay

# For sandbox environment
sdk = Pay(
    api_key_auth="your_api_key",
    server_url="https://api.sandbox.pay.mynkwa.com",
)

# For production environment
sdk = Pay(
    api_key_auth="your_production_api_key",
    server_url="https://api.pay.mynkwa.com",
)

Collect Payment

To request a payment from a customer:

example

try:
    response = sdk.collect.post(
        request_body={
            "amount": 1000,  # Amount in XAF
            "phoneNumber": "237600000000",
            "description": "Payment for order #1234"
        }
    )
    
    print(f"Payment ID: {response.payment.id}")  # Use this ID to check payment status later
except Exception as e:
    print(f"Error: {str(e)}")

Disburse Payment

To send money to a customer:

example

try:
    response = sdk.disburse.post(
        request_body={
            "amount": 1000,  # Amount in XAF
            "phoneNumber": "237600000000",
            "description": "Refund for order #1234"
        }
    )
    
    print(f"Disbursement ID: {response.payment.id}")  # Use this ID to check status later
except Exception as e:
    print(f"Error: {str(e)}")

Check Payment Status

To check the status of a payment:

example

try:
    payment_id = "payment_id_here"
    response = sdk.payments.get(
        id=payment_id
    )
    
    print(f"Payment status: {response.payment.status}")  # "pending", "successful", or "failed"
except Exception as e:
    print(f"Error: {str(e)}")

Check MNO Availability

To check the availability of mobile network operators:

example

try:
    response = sdk.availability.get()
    
    # Check if MTN collections are operational
    for provider in response.availability:
        if provider.operator == "mtn" and provider.operation.type == "collection":
            print(f"MTN Collection Status: {provider.operation.status}")
            
except Exception as e:
    print(f"Error: {str(e)}")

Install Client

Add the Nkwa Pay Java SDK to your project:

Maven

example

<dependency>
    <groupId>io.github.nkwa</groupId>
    <artifactId>pay-sdk</artifactId>
    <version>0.1.6</version>
</dependency>

Gradle

example

implementation 'io.github.nkwa:pay-sdk:0.1.6'

Configure

Import and initialize the Nkwa Pay client:

example

package hello.world;

import io.github.nkwa.pay_sdk.Pay;

public class Application {
    public static void main(String[] args) {
        // Initialize client with your API key
        Pay sdk = Pay.builder()
            .apiKeyAuth("your_api_key")
            .build();
    }
}

Server Selection

You can specify a custom server URL when initializing the client:

example

package hello.world;

import io.github.nkwa.pay_sdk.Pay;

public class Application {
    public static void main(String[] args) {
        // For sandbox environment
        Pay sdkSandbox = Pay.builder()
            .serverURL("https://api.sandbox.pay.mynkwa.com")
            .apiKeyAuth("your_api_key")
            .build();
            
        // For production environment
        Pay sdkProduction = Pay.builder()
            .serverURL("https://api.pay.mynkwa.com")
            .apiKeyAuth("your_production_api_key")
            .build();
    }
}

Collect Payment

To request a payment from a customer:

example

import io.github.nkwa.pay_sdk.models.operations.*;
import io.github.nkwa.pay_sdk.models.*;
import java.math.BigInteger;

public void collectPayment() {
    try {
        PostCollectRequest req = new PostCollectRequest();
        PostCollectRequestBody requestBody = new PostCollectRequestBody();
        
        requestBody.setAmount(BigInteger.valueOf(1000)); // Amount in XAF
        requestBody.setPhoneNumber("237600000000");
        requestBody.setDescription("Payment for order #1234");
        
        req.setRequestBody(requestBody);
        
        PostCollectResponse response = sdk.collect.post(req);
        
        if (response.payment != null) {
            System.out.println("Payment ID: " + response.payment.getId()); // Use this ID to check payment status later
        }
    } catch (Exception e) {
        System.err.println("Error: " + e.getMessage());
    }
}

Disburse Payment

To send money to a customer:

example

import io.github.nkwa.pay_sdk.models.operations.*;
import io.github.nkwa.pay_sdk.models.*;
import java.math.BigInteger;

public void disbursePayment() {
    try {
        PostDisburseRequest req = new PostDisburseRequest();
        PostDisburseRequestBody requestBody = new PostDisburseRequestBody();
        
        requestBody.setAmount(BigInteger.valueOf(1000)); // Amount in XAF
        requestBody.setPhoneNumber("237600000000");
        requestBody.setDescription("Refund for order #1234");
        
        req.setRequestBody(requestBody);
        
        PostDisburseResponse response = sdk.disburse.post(req);
        
        if (response.payment != null) {
            System.out.println("Disbursement ID: " + response.payment.getId()); // Use this ID to check status later
        }
    } catch (Exception e) {
        System.err.println("Error: " + e.getMessage());
    }
}

Check Payment Status

To check the status of a payment:

example

import io.github.nkwa.pay_sdk.models.operations.*;
import io.github.nkwa.pay_sdk.models.*;

public void checkPaymentStatus() {
    try {
        String paymentId = "payment_id_here";
        
        GetPaymentsIdRequest req = new GetPaymentsIdRequest();
        req.setId(paymentId);
        
        GetPaymentsIdResponse response = sdk.payments.get(req);
        
        if (response.payment != null) {
            System.out.println("Payment status: " + response.payment.getStatus()); // "pending", "successful", or "failed"
        }
    } catch (Exception e) {
        System.err.println("Error: " + e.getMessage());
    }
}

Check MNO Availability

To check the availability of mobile network operators:

example

import io.github.nkwa.pay_sdk.models.operations.*;
import io.github.nkwa.pay_sdk.models.*;

public void checkAvailability() {
    try {
        GetAvailabilityResponse response = sdk.availability.get();
        
        if (response.availability != null) {
            // Process availability information
            for (Availability provider : response.availability) {
                System.out.println("Operator: " + provider.getOperator() + 
                                   ", Operation: " + provider.getOperation().getType() + 
                                   ", Status: " + provider.getOperation().getStatus());
            }
        }
    } catch (Exception e) {
        System.err.println("Error: " + e.getMessage());
    }
}

Install Client

Install the Nkwa Pay Go SDK with:

terminal

$ go get github.com/nkwa/pay-go

Configure

Import and initialize the Nkwa Pay client:

example

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    
    paygo "github.com/nkwa/pay-go"
)

func main() {
    // Initialize client with your API key
    client := paygo.New(
        paygo.WithSecurity("your_api_key"),
    )
    
    // Now you can use the client to make API calls
}

Server Selection

You can specify a custom server URL when initializing the client:

example

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    
    paygo "github.com/nkwa/pay-go"
)

func main() {
    // For sandbox environment
    sandboxClient := paygo.New(
        paygo.WithSecurity("your_api_key"),
        paygo.WithServerURL("https://api.sandbox.pay.mynkwa.com"),
    )
    
    // For production environment
    productionClient := paygo.New(
        paygo.WithSecurity("your_production_api_key"),
        paygo.WithServerURL("https://api.pay.mynkwa.com"),
    )
}

Collect Payment

To request a payment from a customer:

example

ctx := context.Background()

response, err := client.Payments.Collect(ctx, &paygo.CollectRequest{
    Amount:      1000, // Amount in XAF
    PhoneNumber: "237600000000",
    Description: "Payment for order #1234",
})
if err != nil {
    log.Fatalf("Failed to create payment: %v", err)
}

fmt.Printf("Payment created with ID: %s, status: %s\n", response.Payment.ID, response.Payment.Status)

Disburse Payment

To send money to a customer:

example

ctx := context.Background()

response, err := client.Payments.Disburse(ctx, &paygo.DisburseRequest{
    Amount:      1000, // Amount in XAF
    PhoneNumber: "237600000000",
    Description: "Refund for order #1234",
})
if err != nil {
    log.Fatalf("Failed to create disbursement: %v", err)
}

fmt.Printf("Disbursement created with ID: %s, status: %s\n", response.Payment.ID, response.Payment.Status)

Check Payment Status

To check the status of a payment:

example

ctx := context.Background()

paymentID := "payment_id_here"
response, err := client.Payments.GetByID(ctx, paymentID)
if err != nil {
    log.Fatalf("Failed to get payment: %v", err)
}

fmt.Printf("Payment status: %s\n", response.Payment.Status)

Check MNO Availability

To check the availability of mobile network operators:

example

ctx := context.Background()

response, err := client.Availability.Get(ctx)
if err != nil {
    log.Fatalf("Failed to get availability: %v", err)
}

// Print availability information
for _, provider := range response.Availability {
    fmt.Printf("Operator: %s, Operation Type: %s, Status: %s\n", 
               provider.Operator, provider.Operation.Type, provider.Operation.Status)
}

Error Handling

example

ctx := context.Background()

response, err := client.Payments.GetByID(ctx, "payment_id_here")
if err != nil {
    var httpErr *apierrors.HTTPError
    if errors.As(err, &httpErr) {
        // Handle HTTP errors (like 401, 404, etc.)
        fmt.Printf("HTTP Error: %s\n", httpErr.Error())
        return
    }
    
    var apiErr *apierrors.APIError
    if errors.As(err, &apiErr) {
        // Handle other API errors
        fmt.Printf("API Error: %s\n", apiErr.Error())
        return
    }
    
    // Handle other errors
    fmt.Printf("Unknown error: %s\n", err.Error())
    return
}

// Process successful response
fmt.Printf("Payment status: %s\n", response.Payment.Status)

​SDK Integration

​Install Client

​Configure

​Server Selection

​Collect Payment

​Disburse Payment

​Check Payment Status

​Check MNO Availability

​Install Client

​Configure

​Server Selection

​Collect Payment

​Disburse Payment

​Check Payment Status

​Check MNO Availability

​Install Client

​Configure

​Server Selection

​Collect Payment

​Disburse Payment

​Check Payment Status

​Check MNO Availability

​Install Client

​Maven

​Gradle

​Configure

​Server Selection

​Collect Payment

​Disburse Payment

​Check Payment Status

​Check MNO Availability

​Install Client

​Configure

​Server Selection

​Collect Payment

​Disburse Payment

​Check Payment Status

​Check MNO Availability

​Error Handling

SDK Integration

Install Client

Configure

Server Selection

Collect Payment

Disburse Payment

Check Payment Status

Check MNO Availability

Install Client

Configure

Server Selection

Collect Payment

Disburse Payment

Check Payment Status

Check MNO Availability

Install Client

Configure

Server Selection

Collect Payment

Disburse Payment

Check Payment Status

Check MNO Availability

Install Client

Maven

Gradle

Configure

Server Selection

Collect Payment

Disburse Payment

Check Payment Status

Check MNO Availability

Install Client

Configure

Server Selection

Collect Payment

Disburse Payment

Check Payment Status

Check MNO Availability

Error Handling