Unofficial Rust SDK for the Chapa API

A type-safe, async Rust SDK for the Chapa Payment API.

⚠️ Pre-release Notice

chapa-rust is currently in active development (v0.1.0). While stable enough for testing and sandbox use, the public API may change before v1.0.0.

Table of Contents

1. Setup
2. Usage
3. Contribution
4. License

Setup

Getting Started

chapa-rust is an asynchronous, type-safe Rust SDK for the Chapa Payment API.
It allows developers to easily integrate Chapa’s payment, transfer, and verification services in their Rust projects.

⚠️ Note: This is a pre-release version (v0.1.0-alpha.1) and is currently distributed directly via Git.
The API may still change slightly before the stable v1.0.0 release.

---

Installation

Add chapa-rust as a dependency in your project’s Cargo.toml.

Option 1 — Use the main branch (latest stable development)

[dependencies]
chapa-rust = { git = "https://github.com/Chapa-Et/chapa-rust.git", branch = "main" }

Option 2 — Use the development branch (latest experimental features)

[dependencies]
chapa-rust = { git = "https://github.com/Chapa-Et/chapa-rust.git", branch = "develop" }

Once added, run:

cargo build

Configuration

The first step is to set up an account on Chapa's homepage. Once you're done, you should have public and secret API keys available to you. Copy your secret key and paste it into a .env file in the same directory as your Rust project.

CHAPA_API_PUBLIC_KEY=<API_KEY>

Note: The CHAPA_API_PUBLIC_KEY is required for the SDK to function.

Usage

You can refer to the examples folder for a comprehensive treatment of each Chapa API operation.

In this section, we will look at the transaction operation.

Initialize Transaction

Initializing a transaction requires an input argument formatted according to the InitializeOption struct you imported during setup:

pub struct InitializeOptions {
    /// The first name of the customer.
    pub first_name: Option<String>,
    /// The last name of the customer.
    pub last_name: Option<String>,
    /// The email address of the customer.
    pub email: Option<String>,
    /// The phone number of the customer.
    pub phone_number: Option<String>,
    /// The currency for the transaction (e.g., "ETB", "USD").
    pub currency: String,
    /// The amount to be charged in the transaction.
    pub amount: String,
    /// A unique reference for the transaction.
    pub tx_ref: String,
    /// An optional callback URL for transaction updates.
    pub callback_url: Option<String>,
    /// An optional return URL for redirecting after payment.
    pub return_url: Option<String>,
    /// Customization options for the payment interface.
    pub customization: Option<Customization>,
    /// Additional metadata to be associated with the transaction.
    pub meta: serde_json::Value,
}

Notice the optional fields. Here's a simple example:

    let test_transaction = InitializeOptions {
        amount: "150".to_string(),
        currency: String::from("USD"),
        email: Some(String::from("[email protected]")),
        first_name: Some(String::from("John")),
        last_name: Some(String::from("Doe")),
        tx_ref: String::from("mail_order_injera"),
        ..Default::default()
    };

Under the hood, this is a POST request to the Chapa API. It also does the work of serializing the Transaction struct and deserializing the response to an InitializeResponse object for you.

use chapa_rust::{
    client::ChapaClient,
    config::ChapaConfigBuilder,
    models::payment::{Customization, InitializeOptions},
};
#[tokio::main]
async fn main() {
    // load environment variables
    dotenvy::dotenv().ok();
    // initialize a chapa client
    let config = ChapaConfigBuilder::new().build().unwrap();
    let mut client = ChapaClient::from_config(config).unwrap();

    let tx_ref = String::from("mail_order_injera");
    let test_transaction = InitializeOptions {
        amount: "150".to_string(),
        currency: String::from("USD"),
        email: Some(String::from("[email protected]")),
        first_name: Some(String::from("John")),
        last_name: Some(String::from("Doe")),
        tx_ref: tx_ref.clone(),
        customization: Some(Customization {
            title: Some("Injera Purchase".to_string()),
            description: Some("Order 1234 - 5kg of Injera".to_string()),
            logo: Some("https://example.com/logo.png".to_string()),
        }),
        ..Default::default()
    };

    let init_success = client.initialize_transaction(test_transaction).await;
    match init_success {
        Ok(resp) => println!("{:#?}", resp),
        Err(e) => eprintln!("{:#?}", e),
    }
}

You can expect a similar response in the following format to be printed to the terminal.

{
   "message": "Hosted Link",
   "status": "success",
   "data": {
   "checkout_url": "https://checkout.chapa.co/checkout/payment/V38JyhpTygC9QimkJrdful9oEjih0heIv53eJ1MsJS6xG"
    }
}

Using the tx_ref we used in the InitializeOption struct, you can request to verify the transaction using the client.verify_transaction(tx_ref) method. Refer to the examples folder for more.

Contribution

If you find a bug or have any suggestions, please feel free to open an issue or a pull request.

License

This open source library is under the terms of the MIT license.