Integration Guides

Tutorials

Connecting a Bank Account

A step-by-step guide to authenticate and link a bank account to a fintech app using the Auth API.

1. Collect Credentials: Prompt the user for their bank_id, username, and password.
2. Authenticate: Send a POST request to /v1/auth with the credentials.
3. Handle Response: Store the access_token and account_id securely for future API calls.
4. Error Handling: Handle 401 Unauthorized or 400 Bad Request errors by prompting the user to verify their credentials.

Building a Payment App

Use the Payments API to enable transfers in your app.

1. Gather Payment Details: Collect account_id, amount, recipient_account, and reference from the user.
2. Initiate Payment: Send a POST request to /v1/payments with the payment details and the Authorization header.
3. Confirm Success: Display a confirmation to the user upon a successful response.
4. Handle Errors: Implement retry logic for transient errors and display user-friendly error messages.

Creating a Budgeting App

Use the Transactions and Balance APIs to build a budgeting app for tracking spending.

1. Fetch Balance: Query /v1/balance with the account_id to display the current balance.
2. Retrieve Transactions: Use /v1/transactions with account_id, start_date, and end_date to fetch transaction history.
3. Analyze Data: Calculate spending patterns and categorize transactions for budgeting insights.
4. Update UI: Refresh the app’s dashboard with the latest balance and transaction data.

Code Samples

Python: Fetching Transactions

import requests
 
url = "https://api.birr-connect.com/v1/transactions"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"account_id": "acc123", "start_date": "2025-01-01"}
 
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}")

JavaScript: Initiating a Payment

const axios = require("axios");
 
const initiatePayment = async () => {
  try {
    const response = await axios.post(
      "https://api.birr-connect.com/v1/payments",
      {
        account_id: "acc123",
        amount: 1000.0,
        recipient_account: "acc789",
        reference: "Invoice #123",
      },
      { headers: { Authorization: "Bearer YOUR_API_KEY" } }
    );
    console.log(response.data);
  } catch (error) {
    console.error("Payment failed:", error.response.data);
  }
};
 
initiatePayment();

Webhooks

Setting Up Webhooks

Configure webhooks to receive real-time updates for events like new transactions or payment confirmations.

1. Register Webhook: Provide a secure HTTPS endpoint to the platform’s webhook configuration.
2. Handle Payloads: Parse incoming webhook payloads to update your app’s state.
3. Acknowledge Receipt: Respond with a 200 OK status to confirm receipt.

Example Webhook Payload:

{
  "event": "transaction.created",
  "account_id": "acc123",
  "transaction_id": "txn456",
  "amount": 5000.0,
  "currency": "ETB",
  "timestamp": "2025-04-24T10:00:00Z"
}

Security Tips

• Verify Signatures: Use the provided webhook signature to validate the authenticity of incoming requests.
• Secure Endpoint: Ensure your webhook endpoint uses HTTPS and is protected against unauthorized access.
• Log Events: Maintain logs of webhook events for debugging and auditing purposes.

Compliance Guide

Adhering to Ethiopian Regulations

Comply with the National Bank of Ethiopia’s open banking rules.

• Obtain Licenses: Ensure your app is licensed to operate as a fintech service in Ethiopia.
• Audit Trails: Maintain detailed logs of API interactions for regulatory audits.

Implementing User Consent Flows

• Explicit Consent: Prompt users to approve data sharing before accessing their bank account data.
• Clear Disclosure: Inform users about what data is accessed and how it will be used.
• Revoke Access: Provide an option for users to revoke consent and unlink their accounts.

Data Security

• Encryption: Use AES-256 for data at rest and TLS for data in transit.
• Secure Storage: Store sensitive data like access_token in a secure vault.
• Regular Audits: Conduct security audits to identify and mitigate vulnerabilities.