Transaction API

Create, retrieve, search, and manage transactions

The Transaction API allows you to create and manage transactions programmatically. All transaction endpoints require the X-API-Key header for authentication.

📝 Transaction Status Lifecycle:

Transactions in the BessaPay API follow this lifecycle:

PENDING - Initial state when transaction is created
PROCESSING - Payment is being processed
COMPLETED - Payment was successful
FAILED - Payment failed or was rejected
CANCELLED - Transaction was cancelled by merchant or user
EXPIRED - Transaction expired due to inactivity

Available Endpoints

POST/api/v1/integration/transactions/create

Create a new transaction via API integration.

Authentication

API Key required in X-API-Key header

Query Parameters

Parameter	Type	Required	Description
environment	string	Optional	Optional environment to use (TEST or LIVE). If not specified, the system will resolve the environment based on other factors.

Request Body

1{
2  "merchantId": "mer_12345abcde",
3  "amount": 1000,
4  "currency": "KES",
5  "reference": "order-123456",
6  "customer": {
7    "name": "John Doe",
8    "email": "john@example.com",
9    "phone": "+254712345678"
10  },
11  "callbackUrl": "https://your-app.com/callbacks/bessapay",
12  "returnUrl": "https://your-app.com/return",
13  "cancelUrl": "https://your-app.com/cancel",
14  "timeoutUrl": "https://your-app.com/timeout"
15}

Response

1{
2  "transaction": {
3    "id": "txn_1J3F9KHGKm7Zf",
4    "merchantId": "mer_12345abcde",
5    "amount": 1000,
6    "currency": "KES",
7    "reference": "order-123456",
8    "transactionStatus": "PENDING",
9    "paymentStatus": "PENDING",
10    "paymentUrl": "https://pay.bessapay.com/checkout/txn_1J3F9KHGKm7Zf",
11    "createdAt": "2023-06-01T12:00:00Z",
12    "environment": "TEST"
13  }
14}

Notes

Authentication requires a valid API key in the X-API-Key header
The merchant must have the appropriate permissions
The environment can be specified via query parameter, header, or domain
All transactions created will inherit the environment setting

GET/api/v1/integration/transactions/{transactionId}

Retrieve details of an existing transaction.

Authentication

API Key required in X-API-Key header

Path Parameters

Parameter	Type	Required	Description
transactionId	string	Required	The ID of the transaction to retrieve

Query Parameters

Parameter	Type	Required	Description
merchantId	string	Required	The ID of the merchant who owns the transaction
environment	string	Optional	Optional environment to filter by (TEST or LIVE)

Response

1{
2  "transaction": {
3    "id": "txn_1J3F9KHGKm7Zf",
4    "merchantId": "mer_12345abcde",
5    "amount": 1000,
6    "currency": "KES",
7    "reference": "order-123456",
8    "transactionStatus": "COMPLETED",
9    "paymentStatus": "COMPLETED",
10    "createdAt": "2023-06-01T12:00:00Z",
11    "updatedAt": "2023-06-01T12:05:00Z",
12    "environment": "TEST"
13  }
14}

Notes

Authentication requires a valid API key in the X-API-Key header
The API key must belong to the specified merchant
The transaction must be in the specified environment
If no transaction is found in the specified environment, a 400 error is returned

POST/api/v1/integration/transactions/search

Search for transactions with various filters.

Authentication

API Key required in X-API-Key header

Query Parameters

Parameter	Type	Required	Description
environment	string	Optional	Optional environment to filter by (TEST or LIVE)

Request Body

1{
2  "merchantId": "mer_12345abcde",
3  "page": 0,
4  "size": 10,
5  "sort": "createdAt,desc",
6  "searchCriteria": [
7    {
8      "key": "transactionStatus",
9      "operation": "eq",
10      "value": "COMPLETED"
11    },
12    {
13      "key": "createdAt",
14      "operation": "gt",
15      "value": "2023-01-01T00:00:00Z"
16    }
17  ]
18}

Response

1{
2  "transactions": [
3    {
4      "id": "txn_1J3F9KHGKm7Zf",
5      "merchantId": "mer_12345abcde",
6      "amount": 1000,
7      "currency": "KES",
8      "reference": "order-123456",
9      "transactionStatus": "COMPLETED",
10      "paymentStatus": "COMPLETED",
11      "createdAt": "2023-06-01T12:00:00Z",
12      "environment": "TEST"
13    }
14  ],
15  "totalElements": 1,
16  "totalPages": 1,
17  "currentPage": 0,
18  "size": 10
19}

Notes

Authentication requires a valid API key in the X-API-Key header
The API key must belong to the specified merchant
The environment filter is automatically applied based on the resolved environment
The search automatically filters for the specified environment

POST/api/v1/integration/transactions/{transactionId}/cancel

Cancel a pending transaction.

Authentication

API Key required in X-API-Key header

Path Parameters

Parameter	Type	Required	Description
transactionId	string	Required	The ID of the transaction to cancel

Query Parameters

Parameter	Type	Required	Description
merchantId	string	Required	The ID of the merchant who owns the transaction
environment	string	Optional	Optional environment to filter by (TEST or LIVE)

Response

1{
2  "transaction": {
3    "id": "txn_1J3F9KHGKm7Zf",
4    "merchantId": "mer_12345abcde",
5    "amount": 1000,
6    "currency": "KES",
7    "reference": "order-123456",
8    "transactionStatus": "FAILED",
9    "paymentStatus": "FAILED",
10    "createdAt": "2023-06-01T12:00:00Z",
11    "updatedAt": "2023-06-01T12:10:00Z",
12    "environment": "TEST"
13  }
14}

Notes

Authentication requires a valid API key in the X-API-Key header
The API key must belong to the specified merchant
Only transactions with PENDING status can be cancelled
The transaction must be in the specified environment
After cancellation, the transaction status will be set to FAILED