Getting Started

Account Setup

To begin using the Ethiopian Platform API, follow these steps to set up a developer account:

1. Sign Up:
   • Visit the developer portal at https://api.birr-connect.com/portal.
   • Register with your email, name, and app details to create a developer account.
2. Verify Identity:
   • Submit KYC documentation, including business registration for fintech companies, to comply with Ethiopian regulations.
   • Provide proof of identity (e.g., national ID) and business details (e.g., tax ID) as prompted.
3. Await Approval:
   • Account verification typically takes 2-5 business days. You’ll receive a confirmation email once approved.

Sandbox Access

Test your integration in a free sandbox environment with mock data:

1. Generate Sandbox API Keys:

   • Register for sandbox access using the following API call:

     curl -X POST https://api.birr-connect.com/v1/sandbox/register \
     -H "Content-Type: application/json" \
     -d '{"email": "developer@example.com", "app_name": "MyFintech"}'

   • Receive a sandbox API key via email or the developer portal.

2. Explore Mock Data:

   • The sandbox includes mock bank accounts, transactions, and balances for testing.
   • Example mock account: bank_id: bank123, username: test_user, password: test_pass.

First API Call

Authenticate a bank account in the sandbox with this quick tutorial:

Request:

curl -X POST https://api.birr-connect.com/v1/auth \
-H "Authorization: Bearer YOUR_SANDBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"bank_id": "bank123", "username": "test_user", "password": "test_pass"}'

Expected Response:

{
  "access_token": "abc123",
  "account_id": "acc123",
  "status": "success"
}

Next Steps:

• Store the access_token securely and use it for subsequent API calls.
• Handle errors like 401 Unauthorized by verifying credentials.

API Authentication

The platform uses OAuth 2.0 for secure API access:

• How It Works:

  • Authenticate via /v1/auth to obtain an access_token.
  • Include the token in the Authorization: Bearer YOUR_TOKEN header for all API requests.
  • Tokens expire after a set period (e.g., 3600 seconds). Renew using the same /v1/auth endpoint.

• Managing and Rotating API Keys:

  • Store API keys in environment variables or a secure vault, never in source code.
  • Rotate keys regularly via the developer portal: https://api.birr-connect.com/portal.
  • Invalidate old keys immediately if a security breach is suspected.