API Reference

Overview

Detailed documentation for all API endpoints, organized by functionality.

Core APIs

Auth API

Endpoint: `POST /v1/auth`

Description: Authenticate a user’s bank account.

Parameters:

Name	Type	Description
`bank_id`	String	The ID of the bank
`username`	String	User’s account username
`password`	String	User’s account password

Example Response:

{
  "access_token": "xyz789",
  "account_id": "acc123",
  "expires_in": 3600
}

Error Codes:

401 Unauthorized
400 Bad Request

Transactions API

Endpoint: `GET /v1/transactions`

Description: Retrieve transaction history for an account.

Parameters:

Name	Type	Description
`account_id`	String	The account ID
`start_date`	String	Start date (YYYY-MM-DD)
`end_date`	String	End date (YYYY-MM-DD)
`limit`	Number	Maximum number of transactions

Example Request:

curl -X GET "https://api.birr-connect.com/v1/transactions?account_id=acc123&start_date=2025-01-01" \
-H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "transactions": [
    {
      "transaction_id": "txn456",
      "amount": 5000.0,
      "currency": "ETB",
      "date": "2025-01-02",
      "description": "Payment to Merchant"
    }
  ],
  "pagination": {
    "next_page": null,
    "total": 1
  }
}

Balance API

Endpoint: `GET /v1/balance`

Description: Check the current balance of an account.

Parameters:

Name	Type	Description
`account_id`	String	The account ID

Example Response:

{
  "account_id": "acc123",
  "balance": 25000.0,
  "currency": "ETB",
  "last_updated": "2025-04-24T10:00:00Z"
}

Payments API

Endpoint: `POST /v1/payments`

Description: Initiate a payment or transfer.

Parameters:

Name	Type	Description
`account_id`	String	The sender’s account ID
`amount`	Number	Payment amount
`recipient_account`	String	The recipient’s account ID
`reference`	String	Payment reference (e.g., Invoice)

Example Request:

curl -X POST https://api.birr-connect.com/v1/payments \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"account_id": "acc123", "amount": 1000.00, "recipient_account": "acc789", "reference": "Invoice #123"}'

Identity API

Endpoint: `GET /v1/identity`

Description: Verify user identity for KYC compliance.

Parameters:

Name	Type	Description
`account_id`	String	The account ID

Example Response:

{
  "account_id": "acc123",
  "name": "Abebe Kebede",
  "national_id": "ETH123456789",
  "verified": true
}

Error Handling

Common Error Codes:

429 Rate Limit Exceeded
500 Internal Server Error

Recommendations:

Implement retries with exponential backoff for transient errors.
Monitor error responses to handle rate limits gracefully.

Rate Limits

Default Limits:

Sandbox: 1000 requests/hour
Production: 5000 requests/hour

Enterprise Clients:

Contact support to request higher limits for enterprise use cases.

API Reference

On this page