pixcli
API Reference

pix-provider

Provider trait for PSP abstraction

The pix-provider crate defines the PixProvider trait — the abstraction layer that allows pixcli to work with any Pix payment service provider (PSP).

[dependencies]
pix-provider = "0.1"

The PixProvider Trait

use async_trait::async_trait;
use pix_provider::*;

#[async_trait]
pub trait PixProvider: Send + Sync {
    /// Get account balance.
    async fn get_balance(&self) -> Result<Balance, ProviderError>;

    /// Create a new immediate charge.
    async fn create_charge(&self, request: ChargeRequest) -> Result<Charge, ProviderError>;

    /// Get a charge by TxID.
    async fn get_charge(&self, txid: &str) -> Result<Charge, ProviderError>;

    /// List charges within a time range.
    async fn list_charges(&self, filter: TransactionFilter) -> Result<Vec<Charge>, ProviderError>;

    /// List received Pix transactions.
    async fn list_pix(&self, filter: TransactionFilter) -> Result<Vec<PixTransaction>, ProviderError>;

    /// Get a Pix transaction by E2E ID.
    async fn get_pix(&self, e2eid: &str) -> Result<PixTransaction, ProviderError>;

    /// Register a webhook for a Pix key.
    async fn register_webhook(&self, key: &str, url: &str) -> Result<(), ProviderError>;

    /// Get the registered webhook for a Pix key.
    async fn get_webhook(&self, key: &str) -> Result<Webhook, ProviderError>;

    /// Remove the webhook for a Pix key.
    async fn remove_webhook(&self, key: &str) -> Result<(), ProviderError>;
}

Implementing a Custom Provider

To add support for a new PSP (e.g., Banco do Brasil, Itaú), implement the PixProvider trait:

use async_trait::async_trait;
use pix_provider::*;

pub struct MyBankProvider {
    api_key: String,
    base_url: String,
}

#[async_trait]
impl PixProvider for MyBankProvider {
    async fn get_balance(&self) -> Result<Balance, ProviderError> {
        // Call your bank's API
        let response = reqwest::get(&format!("{}/balance", self.base_url))
            .await
            .map_err(|e| ProviderError::Network(e.to_string()))?;

        // Parse response
        let data: serde_json::Value = response.json().await
            .map_err(|e| ProviderError::Parse(e.to_string()))?;

        Ok(Balance {
            available: data["available"].as_str().unwrap_or("0").to_string(),
        })
    }

    async fn create_charge(&self, request: ChargeRequest) -> Result<Charge, ProviderError> {
        // Implement charge creation for your bank
        todo!()
    }

    // ... implement remaining methods
}

Built-in Providers

EfiProvider

The pix-efi crate provides the EfiClient which implements PixProvider for the Efí (Gerencianet) API. This is currently the only built-in provider.

use pix_efi::{EfiClient, EfiConfig};

let config = EfiConfig { /* ... */ };
let provider: Box<dyn PixProvider> = Box::new(EfiClient::new(config)?);

// Use through the trait
let balance = provider.get_balance().await?;

Core Types

Balance

pub struct Balance {
    pub available: String,
}

ChargeRequest

pub struct ChargeRequest {
    pub amount: String,
    pub pix_key: String,
    pub description: Option<String>,
    pub expiration: Option<u32>,
    pub debtor: Option<Debtor>,
    pub txid: Option<String>,
}

Charge

pub struct Charge {
    pub txid: String,
    pub status: String,
    pub amount: String,
    pub pix_key: String,
    pub description: Option<String>,
    pub brcode: Option<String>,
    pub created_at: String,
    pub expiration: Option<u32>,
}

PixTransaction

pub struct PixTransaction {
    pub e2eid: String,
    pub amount: String,
    pub timestamp: String,
    pub payer_name: Option<String>,
    pub payer_doc: Option<String>,
    pub txid: Option<String>,
    pub info: Option<String>,
}

ProviderError

pub enum ProviderError {
    Auth(String),
    Network(String),
    Api { status: u16, message: String },
    Parse(String),
    NotFound(String),
    Other(String),
}

Full API Documentation

For the complete auto-generated API reference, see docs.rs/pix-provider.

On this page