feat: added support for the subaccounts api route

morukele · morukele · commit 7ed60e5afd1c · 2025-08-29T12:58:31.000+02:00
diff --git a/README.md b/README.md
@@ -20,7 +20,7 @@ The client currently covers the following section of the API, and the sections t
 - [x] Customers
 - [x] Dedicated Virtual Account
 - [x] Apple Pay
-- [ ] Subaccounts
+- [x] Subaccounts
 - [ ] Plans
 - [ ] Subscriptions
 - [ ] Transfer Recipients
diff --git a/src/endpoints/apple_pay.rs b/src/endpoints/apple_pay.rs
@@ -1,7 +1,7 @@
 //! Apple Pay
 //! THe Apple Pay API allows you register your application's top-level domain or subdomain.
 
-use super::BASE_URL;
+use super::PAYSTACK_BASE_URL;
 use crate::{ApplePayResponseData, HttpClient, PaystackAPIError, PaystackResult};
 use serde_json::json;
 use std::{marker::PhantomData, sync::Arc};
@@ -27,7 +27,7 @@ impl<T: HttpClient + Default> ApplePayEndpoints<T> {
     /// # Returns
     /// A new ApplePayEndpoints instance
     pub fn new(key: Arc<String>, http: Arc<T>) -> ApplePayEndpoints<T> {
-        let base_url = format!("{}/apple-pay/domain", BASE_URL);
+        let base_url = format!("{}/apple-pay/domain", PAYSTACK_BASE_URL);
         ApplePayEndpoints {
             key: key.to_string(),
             base_url,
diff --git a/src/endpoints/customers.rs b/src/endpoints/customers.rs
@@ -2,7 +2,7 @@
 //! =========
 //! Thse Customers API allows you to create and maange customers on your integration
 
-use super::BASE_URL;
+use super::PAYSTACK_BASE_URL;
 use crate::{
     CreateCustomerRequest, CustomerResponseData, HttpClient, PaystackAPIError, PaystackResult,
     Response, RiskAction, UpdateCustomerRequest, ValidateCustomerRequest,
@@ -31,7 +31,7 @@ impl<T: HttpClient + Default> CustomersEndpoints<T> {
     /// # Returns
     /// A new CustomersEndpoints instance
     pub fn new(key: Arc<String>, http: Arc<T>) -> CustomersEndpoints<T> {
-        let base_url = format!("{}/customer", BASE_URL);
+        let base_url = format!("{}/customer", PAYSTACK_BASE_URL);
         CustomersEndpoints {
             key: key.to_string(),
             base_url,
diff --git a/src/endpoints/dedicated_virtual_account.rs b/src/endpoints/dedicated_virtual_account.rs
@@ -2,7 +2,7 @@
 //! =========================
 //! The Dedicated Virtual Account API enables Nigerian and Ghanaian merchants to manage unique payment accounts of their customers.
 
-use super::BASE_URL;
+use super::PAYSTACK_BASE_URL;
 use crate::{
     BankProviderData, DedicatedVirtualAccountRequest, DedicatedVirtualAccountResponseData,
     HttpClient, ListDedicatedAccountFilter, PaystackAPIError, PaystackResult, Response,
@@ -29,7 +29,7 @@ impl<T: HttpClient + Default> DedicatedVirtualAccountEndpoints<T> {
     /// # Returns
     /// A new DedicatedVirtualAccountEndpoints instance
     pub fn new(key: Arc<String>, http: Arc<T>) -> DedicatedVirtualAccountEndpoints<T> {
-        let base_url = format!("{}/dedicated_account", BASE_URL);
+        let base_url = format!("{}/dedicated_account", PAYSTACK_BASE_URL);
         DedicatedVirtualAccountEndpoints {
             key: key.to_string(),
             base_url,
diff --git a/src/endpoints/mod.rs b/src/endpoints/mod.rs
@@ -18,4 +18,4 @@ pub use transaction_split::*;
 pub use virtual_terminal::*;
 
 // Const for the base url, since it is used multiple times
-pub const BASE_URL: &str = "https://api.paystack.co";
+pub const PAYSTACK_BASE_URL: &str = "https://api.paystack.co";
diff --git a/src/endpoints/subaccount.rs b/src/endpoints/subaccount.rs
@@ -3,9 +3,9 @@
 //! The Subaccounts API allows you to create and manage subaccounts on your integration.
 //! Subaccounts can be used to split payment between two accounts (your main account and a subaccount).
 
-use super::BASE_URL;
+use super::PAYSTACK_BASE_URL;
 use crate::{
-    HttpClient, PaystackAPIError, PaystackResult, Response, SubaccountRequest,
+    CreateSubaccountRequest, HttpClient, PaystackAPIError, PaystackResult, Response,
     SubaccountsResponseData,
 };
 use std::sync::Arc;
@@ -31,7 +31,7 @@ impl<T: HttpClient + Default> SubaccountEndpoints<T> {
     /// # Returns
     /// A new SubaccountEndpoints instance
     pub fn new(key: Arc<String>, http: Arc<T>) -> SubaccountEndpoints<T> {
-        let base_url = format!("{}/subaccount", BASE_URL);
+        let base_url = format!("{}/subaccount", PAYSTACK_BASE_URL);
         SubaccountEndpoints {
             key: key.to_string(),
             base_url,
@@ -43,13 +43,13 @@ impl<T: HttpClient + Default> SubaccountEndpoints<T> {
     ///
     /// # Arguments
     /// * `subaccount_request` - The request data to create the subaccount.
-    ///   It should be created with the `SubaccountRequestBuilder` struct.
+    ///   It should be created with the `CreateSubaccountRequestBuilder` struct.
     ///
     /// # Returns
     /// A Result containing the subaccount response data or an error
     pub async fn create_subaccount(
         &self,
-        subaccount_request: SubaccountRequest,
+        subaccount_request: CreateSubaccountRequest,
     ) -> PaystackResult<SubaccountsResponseData> {
         let url = &self.base_url;
         let body = serde_json::to_value(subaccount_request)
@@ -80,6 +80,76 @@ impl<T: HttpClient + Default> SubaccountEndpoints<T> {
         page: Option<u32>,
     ) -> PaystackResult<Vec<SubaccountsResponseData>> {
         let url = self.base_url.to_string();
-        todo!()
+
+        let per_page = per_page.unwrap_or(50).to_string();
+        let page = page.unwrap_or(1).to_string();
+        let query = vec![("perPage", per_page.as_str()), ("page", page.as_str())];
+
+        let response = self
+            .http
+            .get(&url, &self.key, Some(&query))
+            .await
+            .map_err(|e| PaystackAPIError::Subaccount(e.to_string()))?;
+
+        let parsed_response: Response<Vec<SubaccountsResponseData>> =
+            serde_json::from_str(&response)
+                .map_err(|e| PaystackAPIError::Subaccount(e.to_string()))?;
+
+        Ok(parsed_response)
+    }
+
+    /// Get the details of a subaccount on your integration
+    ///
+    /// # Arguments
+    /// * `id_or_code` - The subaccount ID or code you want to fetch
+    ///
+    /// # Returns
+    /// A Result containing the details of the subaccount or an error.
+    pub async fn fetch_subaccount(
+        &self,
+        id_or_code: String,
+    ) -> PaystackResult<SubaccountsResponseData> {
+        let url = format!("{}/{}", self.base_url, id_or_code);
+
+        let response = self
+            .http
+            .get(&url, &self.key, None)
+            .await
+            .map_err(|e| PaystackAPIError::Subaccount(e.to_string()))?;
+
+        let parsed_response: Response<SubaccountsResponseData> = serde_json::from_str(&response)
+            .map_err(|e| PaystackAPIError::Subaccount(e.to_string()))?;
+
+        Ok(parsed_response)
+    }
+
+    /// Update a subaccount details in your integration
+    ///
+    /// # Arguments
+    /// * `id_or_code` - Subaccount's ID or code
+    /// * `update_request` - The request data to update the subaccount.
+    ///   It should be created with the `CreateSubaccountRequestBuilder` struct.
+    ///
+    /// # Returns
+    /// A Result containing the updated subaccount response data or an error
+    pub async fn update_subaccount(
+        &self,
+        id_or_code: String,
+        update_request: CreateSubaccountRequest,
+    ) -> PaystackResult<SubaccountsResponseData> {
+        let url = format!("{}/{}", self.base_url, id_or_code);
+        let body = serde_json::to_value(update_request)
+            .map_err(|e| PaystackAPIError::Subaccount(e.to_string()))?;
+
+        let response = self
+            .http
+            .put(&url, &self.key, &body)
+            .await
+            .map_err(|e| PaystackAPIError::Subaccount(e.to_string()))?;
+
+        let parsed_response: Response<SubaccountsResponseData> = serde_json::from_str(&response)
+            .map_err(|e| PaystackAPIError::Subaccount(e.to_string()))?;
+
+        Ok(parsed_response)
     }
 }
diff --git a/src/endpoints/terminal.rs b/src/endpoints/terminal.rs
@@ -9,7 +9,7 @@ use crate::{
 };
 use std::{marker::PhantomData, sync::Arc};
 
-use super::BASE_URL;
+use super::PAYSTACK_BASE_URL;
 
 /// A struct to hold all the functions of the terminal API endpoint
 #[derive(Debug, Clone)]
@@ -32,7 +32,7 @@ impl<T: HttpClient + Default> TerminalEndpoints<T> {
     /// # Returns
     /// A new TerminalEndpoints instance
     pub fn new(key: Arc<String>, http: Arc<T>) -> TerminalEndpoints<T> {
-        let base_url = format!("{}/terminal", BASE_URL);
+        let base_url = format!("{}/terminal", PAYSTACK_BASE_URL);
         TerminalEndpoints {
             key: key.to_string(),
             base_url,
diff --git a/src/endpoints/transaction.rs b/src/endpoints/transaction.rs
@@ -2,7 +2,7 @@
 //! =============
 //! The Transaction route allows to create and manage payments on your integration.
 
-use super::BASE_URL;
+use super::PAYSTACK_BASE_URL;
 use crate::{
     ChargeRequest, ChargeResponseData, Currency, ExportTransactionData, HttpClient,
     PartialDebitTransactionRequest, PaystackAPIError, PaystackResult, Response, Status,
@@ -32,7 +32,7 @@ impl<T: HttpClient + Default> TransactionEndpoints<T> {
     /// # Returns
     /// A new TransactionEndpoints instance
     pub fn new(key: Arc<String>, http: Arc<T>) -> TransactionEndpoints<T> {
-        let base_url = format!("{}/transaction", BASE_URL);
+        let base_url = format!("{}/transaction", PAYSTACK_BASE_URL);
         TransactionEndpoints {
             key: key.to_string(),
             base_url,
diff --git a/src/endpoints/transaction_split.rs b/src/endpoints/transaction_split.rs
@@ -3,7 +3,7 @@
 //! The Transaction Splits API enables merchants split the settlement for a
 //! transaction across their payout account, and one or more subaccounts.
 
-use super::BASE_URL;
+use super::PAYSTACK_BASE_URL;
 use crate::{
     DeleteSubAccountBody, HttpClient, PaystackAPIError, PaystackResult, Response, SubaccountBody,
     TransactionSplitRequest, TransactionSplitResponseData, UpdateTransactionSplitRequest,
@@ -31,7 +31,7 @@ impl<T: HttpClient + Default> TransactionSplitEndpoints<T> {
     /// # Returns
     /// A new TransactionSplitEndpoints instance
     pub fn new(key: Arc<String>, http: Arc<T>) -> TransactionSplitEndpoints<T> {
-        let base_url = format!("{}/split", BASE_URL);
+        let base_url = format!("{}/split", PAYSTACK_BASE_URL);
         TransactionSplitEndpoints {
             key: key.to_string(),
             base_url,
diff --git a/src/endpoints/virtual_terminal.rs b/src/endpoints/virtual_terminal.rs
@@ -2,7 +2,7 @@
 //! ================
 //! The Virtual Terminal API allows you to accept in-person payments without a POS device.
 
-use super::BASE_URL;
+use super::PAYSTACK_BASE_URL;
 use crate::{
     DestinationRequest, DestinationResponse, HttpClient, PaystackAPIError, PaystackResult,
     Response, TransactionSplitResponseData, VirtualTerminalRequestData,
@@ -31,7 +31,7 @@ impl<T: HttpClient + Default> VirtualTerminalEndpoints<T> {
     /// # Returns
     /// A new VirtualTerminalEndpoints instance
     pub fn new(key: Arc<String>, http: Arc<T>) -> VirtualTerminalEndpoints<T> {
-        let base_url = format!("{}/virtual_terminal", BASE_URL);
+        let base_url = format!("{}/virtual_terminal", PAYSTACK_BASE_URL);
         VirtualTerminalEndpoints {
             key: key.to_string(),
             base_url,
diff --git a/src/models/subaccount_models.rs b/src/models/subaccount_models.rs
@@ -2,40 +2,54 @@
 //! ==============
 //! This file contains the models for working with the subaccounts endpoint.
 
+use super::Currency;
+use crate::utils::bool_from_int_or_bool;
 use derive_builder::Builder;
 use serde::{Deserialize, Serialize};
 
-use super::Currency;
-
 /// This struct is used to create the body for creating a subaccount on your integration.
 /// Use the `SubaccountRequestBuilder` to create this object.
 #[derive(Serialize, Debug, Builder, Default)]
-pub struct SubaccountRequest {
+pub struct CreateSubaccountRequest {
     /// Name of business for subaccount
-    business_name: String,
+    #[builder(setter(strip_option), default)]
+    #[serde(skip_serializing_if = "Option::is_none")]
+    business_name: Option<String>,
     /// Bank Code for the bank.
     /// You can get the list of Bank Codes by calling the List Banks endpoint.
-    settlement_bank: String,
+    #[builder(setter(strip_option), default)]
+    #[serde(skip_serializing_if = "Option::is_none")]
+    settlement_bank: Option<String>,
     /// Bank Account Number
-    account_number: String,
+    #[builder(setter(strip_option), default)]
+    #[serde(skip_serializing_if = "Option::is_none")]
+    account_number: Option<String>,
     /// The default percentage charged when receiving on behalf of this subaccount
-    percentage_charge: f32,
+    #[builder(setter(strip_option), default)]
+    #[serde(skip_serializing_if = "Option::is_none")]
+    percentage_charge: Option<f32>,
     /// A description for this subaccount
-    description: String,
+    #[builder(setter(strip_option), default)]
+    #[serde(skip_serializing_if = "Option::is_none")]
+    description: Option<String>,
     /// A contact email for the subaccount
     #[builder(setter(strip_option), default)]
+    #[serde(skip_serializing_if = "Option::is_none")]
     primary_contact_email: Option<String>,
     /// A name for the contact person for this subaccount
     #[builder(setter(strip_option), default)]
+    #[serde(skip_serializing_if = "Option::is_none")]
     primary_contact_name: Option<String>,
     /// A phone number to call for this subaccount
     #[builder(setter(strip_option), default)]
+    #[serde(skip_serializing_if = "Option::is_none")]
     primary_contact_phone: Option<String>,
     /// Stringified JSON object.
     /// Add a custom_fields attribute which has an array of objects if you would like the fields to be
     /// added to your transaction when displayed on the dashboard.
     /// Sample: {"custom_fields":[{"display_name":"Cart ID","variable_name": "cart_id","value": "8393"}]}
     #[builder(setter(strip_option), default)]
+    #[serde(skip_serializing_if = "Option::is_none")]
     metadata: Option<String>,
 }
 
@@ -94,6 +108,7 @@ pub struct SubaccountsResponseData {
     /// Currency of the subaccount
     pub currency: Option<Currency>,
     /// If the account is active or not, should be 1 for active and 0 for inactive
+    #[serde(default, deserialize_with = "bool_from_int_or_bool")]
     pub active: Option<bool>,
     /// Settlement schedule of subaccount.
     pub settlement_schedule: Option<String>,
@@ -105,17 +120,8 @@ pub struct SubaccountsResponseData {
     /// Last update time of subaccount.
     #[serde(rename = "updatedAt")]
     pub updated_at: Option<String>,
-}
-
-/// Represents the JSON response for fetch subaccount.
-#[derive(Debug, Deserialize, Serialize, Default)]
-pub struct FetchSubaccountResponse {
-    /// The status of the JSON response.
-    pub status: bool,
-    /// The message associated with the JSON response.
-    pub message: String,
-    /// Fetch Subaccount response data.
-    pub data: SubaccountsResponseData,
+    pub product: Option<String>,
+    pub managed_by_integration: Option<u32>,
 }
 
 /// This struct is used to create the body for deleting a subaccount on your integration.
diff --git a/src/models/transaction_split_models.rs b/src/models/transaction_split_models.rs
@@ -44,6 +44,7 @@ pub struct TransactionSplitResponseData {
     /// The split code of the percentage split.
     pub split_code: String,
     /// Indicates whether the percentage split is active or not.
+    #[serde(default)]
     pub active: Option<bool>,
     /// The bearer type of the percentage split.
     pub bearer_type: String,
diff --git a/src/utils.rs b/src/utils.rs
@@ -1,4 +1,6 @@
 use serde::de::Error;
+use serde::{Deserialize, Deserializer};
+use serde_json::Value;
 use std::fmt::Formatter;
 use std::str::FromStr;
 
@@ -152,3 +154,22 @@ where
 
     deserializer.deserialize_option(OptionStringOrNumberVisitor)
 }
+
+pub fn bool_from_int_or_bool<'de, D>(deserializer: D) -> Result<Option<bool>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let v: Option<Value> = Option::deserialize(deserializer)?;
+    match v {
+        Some(Value::Bool(b)) => Ok(Some(b)),
+        Some(Value::Number(n)) => {
+            if let Some(i) = n.as_i64() {
+                Ok(Some(i != 0))
+            } else {
+                Err(serde::de::Error::custom("Invalid number for bool"))
+            }
+        }
+        Some(Value::Null) | None => Ok(None),
+        _ => Err(serde::de::Error::custom("Expected bool or int")),
+    }
+}
diff --git a/tests/api/main.rs b/tests/api/main.rs
@@ -3,6 +3,7 @@ pub mod charge;
 pub mod customer;
 pub mod dedicated_virtual_account;
 pub mod helpers;
+pub mod subaccount;
 pub mod terminal;
 pub mod transaction;
 pub mod transaction_split;
diff --git a/tests/api/subaccount.rs b/tests/api/subaccount.rs
diff --git a/tests/api/transaction_split.rs b/tests/api/transaction_split.rs
