API Documentation

Introduction

Badala provides your e-commerce store with REST API endpoints to complete checkout transactions.

For testing, you can use your Badala API test details provided on your business account dashboard.

Base URL

Not a developer?

Use our alternative plugins to get started with Badala without writing code.

Authentication

All API requests require your API key for authentication. You can find your API key in your business dashboard.

Include your API key in the request body:

{
  "api_key": "your-api-key-here"
}

For Escrow API endpoints, use JWT Bearer token authentication:

Authorization: Bearer <your-jwt-token>

Make a Payment

Enable your customers to checkout with Badala by sending a JSON object and handling the response.

POST

Request Parameters

Example Request

{
  "id": "#1878567",
  "api_key": "your-api-key",
  "type": "payment",
  "currency": "R",
  "total_amount": 290.50,
  "items": "Bucket hat, Sleeve less Tee",
  "return_method": "GET",
  "return_url": "https://your-domain.com/handle/response/"
}

Success Response

{
  "id": "#1878567",
  "success": true,
  "message": "Initiating payment request successful",
  "datetime": "2020-10-22T20:13:08.958619Z",
  "complete_payment_url": "https://badala.co.za/api/payment/T29vaE0Nso/",
  "status_code": 200
}

Refunds

Process refunds for completed transactions.

POST

Request Parameters

Example Request

{
  "id": "#1878567",
  "api_key": "your-api-key",
  "type": "refund",
  "currency": "R",
  "total_amount": 290.50,
  "reason": "Clothes didn't fit"
}

Escrow API Overview

The Badala Escrow API enables secure payment processing between buyers and sellers. Funds are held safely in escrow until the transaction is completed, protecting both parties.

How Escrow Works

1. Create: Merchant creates an escrow account for an order
2. Fund: Customer funds the escrow (via Paystack, Ozow, or wallet)
3. Activate: Escrow becomes active once funded
4. Release: Funds are released to merchant after order fulfillment

Base URL

Escrow Statuses

Create Escrow Account

Create a new escrow account for a transaction between a buyer and seller.

POST

Request Parameters

Example Request

{
  "payer_id": "550e8400-e29b-41d4-a716-446655440000",
  "payee_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "amount": "250.00",
  "currency": "ZAR",
  "external_transaction_id": "ORDER-2024-001234"
}

Success Response

{
  "account_number": "ESC87654321",
  "status": "created",
  "amount": "250.00",
  "currency": "ZAR",
  "expires_at": "2024-01-22T10:30:00Z"
}

Fund Escrow

Fund an existing escrow account using various payment methods.

POST

Request Parameters

Release Funds

Release escrow funds to the seller after transaction completion.

POST

Request Parameters

Check Escrow Status

Retrieve the current status and details of an escrow account.

GET

Response

{
  "account_number": "ESC87654321",
  "status": "funded",
  "amount": "250.00",
  "funded_amount": "250.00",
  "currency": "ZAR",
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-01-22T10:30:00Z"
}

Cancel Escrow

Cancel an escrow and refund funds to the buyer.

POST

Request Parameters

HTTP Status Codes

Badala uses conventional HTTP response codes to indicate success or failure of API requests.