> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mynkwa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK

> Integrate Nkwa Pay seamlessly into your applications with our official SDKs for multiple programming languages

# 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](/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.

<Tabs>
  <Tab title="JavaScript">
    ### Install Client

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

    ```bash terminal theme={null}
    # 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:

    ```javascript example theme={null}
    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:

    ```javascript example theme={null}
    // 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:

    ```javascript example theme={null}
    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:

    ```javascript example theme={null}
    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:

    ```javascript example theme={null}
    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:

    ```javascript example theme={null}
    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);
      }
    }
    ```
  </Tab>

  <Tab title="PHP">
    ### Install Client

    Install the Nkwa Pay PHP SDK with Composer:

    ```bash terminal theme={null}
    $ composer require "nkwa-pay/sdk"
    ```

    ### Configure

    Import and initialize the Nkwa Pay client:

    ```php example theme={null}
    <?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:

    ```php example theme={null}
    <?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:

    ```php example theme={null}
    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:

    ```php example theme={null}
    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:

    ```php example theme={null}
    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:

    ```php example theme={null}
    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();
    }
    ```
  </Tab>

  <Tab title="Python">
    ### Install Client

    Install the Nkwa Pay Python SDK with pip or poetry:

    ```bash terminal theme={null}
    # Using pip
    $ pip install nkwa-pay-sdk

    # Using poetry
    $ poetry add nkwa-pay-sdk
    ```

    ### Configure

    Import and initialize the Nkwa Pay client:

    ```python example theme={null}
    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:

    ```python example theme={null}
    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:

    ```python example theme={null}
    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:

    ```python example theme={null}
    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:

    ```python example theme={null}
    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:

    ```python example theme={null}
    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)}")
    ```
  </Tab>

  <Tab title="Java">
    ### Install Client

    Add the Nkwa Pay Java SDK to your project:

    #### Maven

    ```xml example theme={null}
    <dependency>
        <groupId>io.github.nkwa</groupId>
        <artifactId>pay-sdk</artifactId>
        <version>0.1.6</version>
    </dependency>
    ```

    #### Gradle

    ```groovy example theme={null}
    implementation 'io.github.nkwa:pay-sdk:0.1.6'
    ```

    ### Configure

    Import and initialize the Nkwa Pay client:

    ```java example theme={null}
    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:

    ```java example theme={null}
    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:

    ```java example theme={null}
    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:

    ```java example theme={null}
    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:

    ```java example theme={null}
    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:

    ```java example theme={null}
    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());
        }
    }
    ```
  </Tab>

  <Tab title="Go">
    ### Install Client

    Install the Nkwa Pay Go SDK with:

    ```bash terminal theme={null}
    $ go get github.com/nkwa/pay-go
    ```

    ### Configure

    Import and initialize the Nkwa Pay client:

    ```go example theme={null}
    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:

    ```go example theme={null}
    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:

    ```go example theme={null}
    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:

    ```go example theme={null}
    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:

    ```go example theme={null}
    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:

    ```go example theme={null}
    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

    ```go example theme={null}
    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)
    ```
  </Tab>
</Tabs>