API Reference

Authentication

The BessaPay API uses API keys to authenticate requests. You can view and manage your API keys in the BessaPay Dashboard.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Authentication Example

1# Example API request with API key
2curl https://api.bessapay.net/api/v1/integration/transactions/create \
3  -H "X-API-Key: your_api_key_here"

Environment Types

The API supports two environments: TEST and LIVE. These can be specified in multiple ways.

Merchant Environments

Merchants can be configured in either LIVE or TEST mode:

LIVE - For production use with real transactions. Live merchants can create both LIVE and TEST API keys.
TEST - For testing and development. Test merchants can only create TEST API keys, and all transactions will be marked as test transactions.

API Key Environments

Each API key has its own environment setting:

LIVE API Keys - Used for processing real transactions with actual funds.
TEST API Keys - Used for development and testing without affecting real balances. All transactions created with test API keys will be automatically purged after 30 days.

Environment Resolution

There are multiple ways to specify which environment you want to use:

1. Query Parameter

Add the environment query parameter to any request:

Query Parameter Example

1# Requesting resources in TEST environment
2curl https://api.semuni.com/api/v1/integration/transactions \
3  -H "X-API-Key: your_api_key_here" \
4  ?environment=TEST

2. Request Header

Set the X-Environment header in your requests:

Request Header Example

1# Requesting resources in TEST environment
2curl https://api.semuni.com/api/v1/integration/transactions \
3  -H "X-API-Key: your_api_key_here" \
4  -H "X-Environment: TEST"

3. Domain-based Selection

Use environment-specific domains:

api.semuni.com - LIVE environment (default)
test-api.semuni.com - TEST environment

4. Default Environment

If none of the above methods are used, the system will use the merchant's configured default environment.

💡 Priority Order:

When multiple environment selection methods are used, they are evaluated in this order:

Query parameter
Domain-based selection
Request header
Merchant default environment

Important Note:

TEST merchants can only create test API keys

Important Note:

All test transactions are automatically purged after 30 days

Important Note:

Live and test environments are completely separate

Error Handling

The API uses RFC-9457 Problem Details for HTTP APIs to provide standardized error responses. All errors follow a consistent format, making it easier to handle errors in your applications.

For detailed information on error types, formats, and handling best practices, see ourError Reference.

Example Error Response

1{
2"type": "https://bessapay.net/errors/validation-error",
3"title": "Validation Error",
4"status": 422,
5"detail": "The request contains invalid fields",
6"instance": "/api/transactions",
7"errorCode": "INVALID_INPUT",
8"timestamp": "2023-06-15T10:15:30Z",
9"validationErrors": [
10  {
11    "field": "amount", 
12    "message": "must be greater than zero"
13  }
14]
15}

API Resources

Transactions

Create, retrieve, search, and manage transactions.

• Create transactions
• Check transaction status
• Search transactions
• Cancel pending transactions

View Transaction API →

Webhooks

Receive real-time updates about your transactions.

• Webhook signatures
• Event types
• Webhook security
• Best practices

View Webhooks Documentation →