OneKhusa

https://docs.onekhusa.com/
Admin
OneKhusa is a secure payment gateway that enables merchants, PSPs, and organizations to send and...
Tokens:136,903
Snippets:824
Trust Score:4.8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Get Payment SDK Example

Source: https://docs.onekhusa.com/sdk/csharp-sdk/accept-payment/get-payment

This example demonstrates how to retrieve payment details using the `GetPaymentAsync` method. It includes handling both successful responses and errors.

```APIDOC
## Get Payment

### Description
Retrieves a collection transaction (payment) performed by the customer.

### Method
`GetPaymentAsync`

### Parameters
#### Request Body
- **MerchantAccountNumber** (int) - Required - The merchant's account number.
- **TransactionReferenceNumber** (string) - Required - The reference number of the transaction.

### Request Example
```csharp
var request = new GetPaymentRequest
{
    MerchantAccountNumber = 12345678,
    TransactionReferenceNumber = "260219DXQ5FB"
};
```

### Response
#### Success Response (200)
- **Data** (GetPaymentResponse) - Contains the payment details.
  - **SourceAccountNumber** (string)
  - **SourceCustomerName** (string)
  - **SourceReferenceNumber** (string)
  - **SourceCurrencyCode** (string)
  - **BeneficiaryAccountNumber** (string)
  - **BeneficiaryName** (string)
  - **BeneficiaryCurrencyCode** (string)
  - **ConnectorName** (string)
  - **AmountSent** (decimal)
  - **AmountReceived** (decimal)
  - **TransactionFee** (decimal)
  - **TransactionDescription** (string)
  - **TransactionDate** (DateTime)
  - **TransactionReferenceNumber** (string)
  - **TransactionStatusCode** (int)
  - **TransactionStatusName** (string)
  - **TransactionTypeName** (string)
  - **ValueDate** (DateTime)

#### Error Response
- **Error** (OneKhusaError) - Contains error details if the request fails.
  - **Type** (string)
  - **Title** (string)
  - **Detail** (string)
  - **ErrorCode** (string)
  - **Status** (int)
  - **Instance** (string)
  - **Errors** (List<string>)

### Response Example (Success)
```csharp
// Assuming response.IsSuccess is true and response.Data is not null
Console.WriteLine($"SourceAccountNumber: {response.Data.Source.AccountNumber}");
// ... other fields
```

### Response Example (Error)
```csharp
// Assuming response.IsSuccess is false
Console.WriteLine($"Type: {response.Error?.Type}");
// ... other error fields
```
```

--------------------------------

### Example Success Response for Get Webhook

Source: https://docs.onekhusa.com/api-reference/webhooks/getwebhook

This is an example of a successful response when retrieving webhook details. It includes information such as the webhook ID, callback URL, and creation details.

```json
{
  "merchantAccountNumber": 35253486,
  "webhookId": 1,
  "eventCode": "payment.success",
  "eventName": "Payment Success Notification",
  "callbackUrl": "https://merchant.example.com/webhooks/payment",
  "webhookSignature": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
  "dateCreated": "2024-01-15T10:30:00Z",
  "createdBy": "admin@example.com",
  "dateModified": "2024-01-16T14:20:00Z",
  "modifiedBy": "user@example.com"
}
```

--------------------------------

### Install OneKhusa.SDK via Package Manager Console

Source: https://docs.onekhusa.com/sdk/csharp-sdk/installation

Use the `Install-Package` command in Visual Studio's Package Manager Console to install the SDK.

```powershell
Install-Package OneKhusa.SDK
```

--------------------------------

### Example Success Response for Get Webhooks

Source: https://docs.onekhusa.com/api-reference/webhooks/getwebhooks

This JSON structure represents a successful response when retrieving webhook configurations. It includes details for each configured webhook.

```json
[
  {
    "merchantAccountNumber": 35253486,
    "webhookId": 1,
    "eventCode": "payment.success",
    "eventName": "Payment Success Notification",
    "callbackUrl": "https://merchant.example.com/webhooks/payment",
    "webhookSignature": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
    "dateCreated": "2024-01-15T10:30:00Z",
    "createdBy": "user@example.com",
    "dateModified": "2024-01-16T14:20:00Z",
    "modifiedBy": "admin@example.com"
  },
  {
    "merchantAccountNumber": 35253486,
    "webhookId": 2,
    "eventCode": "payout.success",
    "eventName": "Successful Disbursement (Payout)",
    "callbackUrl": "https://merchant.example.com/webhooks/payout",
    "webhookSignature": "z6y5x4w3v2u1t0s9r8q7p6o5n4m3l2k1j0i9h8g7f6e5d4c3b2a1",
    "dateCreated": "2024-01-20T09:15:00Z",
    "createdBy": "admin@example.com",
    "dateModified": null,
    "modifiedBy": null
  }
]
```

--------------------------------

### Example Idempotency Keys

Source: https://docs.onekhusa.com/api-reference/get-started/idempotency

Examples of valid idempotency keys that can be used in the request header. These follow the recommended patterns and meet the specified requirements.

```text
X-Idempotency-Key: 12345678-019b51ad-44fb-73f9-bd09-334479d7ce63
```

```text
X-Idempotency-Key: 12345678-batchdis-0701206165430-615272500126
```

--------------------------------

### Connector Response Example

Source: https://docs.onekhusa.com/api-reference/connectors/getAll

Example of a successful response when retrieving connector information. Includes details such as connector ID, name, description, channel information, and active status.

```json
[
  {
    "connectorId": 769375,
    "connectorName": "Airtel Money",
    "connectorCode": "EEE",
    "connectorDescription": "The mobile money operator supports the processing of disbursement and collection transactions",
    "channelName": "Mobile Network Operator",
    "channelCode": "M",
    "switchMerchantId": "5554",
    "logoBase64": "iVBORw0KGgoAAAANSUh....",
    "logoFormat": "image/png",
    "isActive": false
  },
  {
    "connectorId": 769356,
    "connectorName": "FDH Bank Limited",
    "connectorCode": "FDH",
    "connectorDescription": "The bank supports the processing of disbursement and collection transactions",
    "channelName": "Bank",
    "channelCode": "B",
    "switchMerchantId": "FDHMW2233",
    "logoBase64": "iVBORw0KGgoAAAANSUhE...",
    "logoFormat": "image/png",
    "isActive": true
  }
]
```

--------------------------------

### Get Webhook Details

Source: https://docs.onekhusa.com/api-reference/webhooks/getwebhook

This example demonstrates how to retrieve webhook details using the API. It includes the necessary headers and a JSON payload with merchant account number and event code.

```APIDOC
## POST /merchants/webhooks/get

### Description
Retrieves the details of a specific webhook subscription for a merchant.

### Method
POST

### Endpoint
/merchants/webhooks/get

### Headers
- **Authorization** (string) - Required - Bearer authentication header of the form `Bearer Token`.
- **Accept-Language** (string) - Optional - Preferred language for the response. Defaults to `en`.

### Request Body
- **merchantAccountNumber** (integer) - Required - The unique identifier of the merchant account. Must be between 10000000 and 99999999.
- **eventCode** (string) - Required - The event code of the webhook subscription to retrieve.

### Request Example
```json
{
  "merchantAccountNumber": 35253486,
  "eventCode": "payment.success"
}
```

### Response
#### Success Response (200)
- **merchantAccountNumber** (integer) - The unique identifier of the merchant account.
- **webhookId** (integer<int64>) - The unique identifier of the webhook.
- **eventCode** (string) - The event code that triggers the webhook.
- **eventName** (string) - A description of the event.
- **callbackUrl** (string<uri>) - The URL that receives webhook notifications.
- **webhookSignature** (string) - The signature used to verify the authenticity of webhook notifications.
- **dateCreated** (string<date-time>) - The date and time when the webhook was created (ISO 8601).
- **createdBy** (string) - The username or identifier of the user who created the webhook.
- **dateModified** (string<date-time> | null) - The date and time when the webhook was last modified (ISO 8601).
- **modifiedBy** (string | null) - The username or identifier of the user who last modified the webhook.

#### Response Example
```json
{
  "merchantAccountNumber": 35253486,
  "webhookId": 1,
  "eventCode": "payment.success",
  "eventName": "Payment Success Notification",
  "callbackUrl": "https://merchant.example.com/webhooks/payment",
  "webhookSignature": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
  "dateCreated": "2024-01-15T10:30:00Z",
  "createdBy": "admin@example.com",
  "dateModified": "2024-01-16T14:20:00Z",
  "modifiedBy": "user@example.com"
}
```
```

--------------------------------

### Success Response Example

Source: https://docs.onekhusa.com/api-reference/merchants/getAuthLevels

This is an example of a successful response (200 OK) when retrieving merchant authorization levels. It lists each level with its number and name.

```json
[
  {
    "levelNumber": 1,
    "levelName": "Initiator Only"
  },
  {
    "levelNumber": 2,
    "levelName": "Initiator -> Approver"
  },
  {
    "levelNumber": 3,
    "levelName": "Initiator -> Reviewer -> Approver"
  }
]
```

--------------------------------

### Get Batches Request Example

Source: https://docs.onekhusa.com/api-reference/disbursements/batch-getBatches

Use this cURL command to send a POST request to the Get Batches endpoint. Ensure you replace 'your-jwt-token' with your actual authentication token. The request body specifies filtering and pagination parameters.

```curl
curl -X 'POST' \
  'https://api.onekhusa.com/sandbox/v1/disbursements/batch/getBatches' \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer your-jwt-token' \
  --header 'Accept-Language: en' \
  -d '{ \
  "merchantAccountNumber": 12345678, \
  "batchDate": "2025-09-26", \
  "pageNumber": 1, \
  "numberOfReturnedRows": 20, \
  "isIncremental": true, \
  "searchBy": "CapturedBy": 
  "searchText": "j1LgGY" \
}'
```

--------------------------------

### Response Body Example

Source: https://docs.onekhusa.com/api-reference/users/get-users

This is an example of a successful response when retrieving merchant users. It includes details such as user ID, name, email, phone number, status, and timestamps.

```JSON
[
  {
    "userId": "user-id-456",
    "firstName": "Jane",
    "lastName": "Smith",
    "emailAddress": "jane.smith@example.com",
    "phoneNumber": "0881234567",
    "isEmailConfirmed": true,
    "roleName": "Merchant Administrator",
    "statusCode": "A",
    "statusName": "Active",
    "capturedBy": "admin@example.com",
    "dateCaptured": "2025-11-13T07:25:46.877Z",
    "modifiedBy": "user@example.com",
    "dateModified": "2025-11-13T07:25:46.877Z"
  },
  {
    "userId": "user-id-123",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "john.doe@example.com",
    "phoneNumber": "0881234567",
    "isEmailConfirmed": true,
    "roleName": "Merchant Administrator",
    "statusCode": "A",
    "statusName": "Active",
    "capturedBy": "admin@example.com",
    "dateCaptured": "2025-11-01T10:30:00.000Z",
    "modifiedBy": "admin@example.com",
    "dateModified": "2025-11-03T09:15:00.000Z"
  }
]
```

--------------------------------

### Successful Response Example

Source: https://docs.onekhusa.com/api-reference/disbursements/batch-getTransactions

This is an example of a successful response when retrieving batch transactions. It includes details for each transaction within the specified batch.

```JSON
{
  "message": [
    {
      "batchNumber": 123456,
      "transactionReferenceNumber": "250926JL5ZRO",
      "beneficiaryName": "JOHN PHIRI",
      "connectorName": "National Bank of Malawi",
      "beneficiaryAccountNumber": "002125456",
      "transactionDescription": "MTUKULA PAKHOMO FOR APR2025",
      "transactionAmount": 50000.00,
      "transactionStatusCode": "S",
      "transactionStatusName": "Successful",
      "currencyCode": "MWK"
    },
    {
      "batchNumber": 123456,
      "transactionReferenceNumber": "25092631JFIW",
      "beneficiaryName": "SUSAN KAPONDA",
      "connectorName": "National Bank of Malawi",
      "beneficiaryAccountNumber": "002125457",
      "transactionDescription": "MTUKULA PAKHOMO FOR APR2025",
      "transactionAmount": 50000.00,
      "transactionStatusCode": "S",
      "transactionStatusName": "Successful",
      "currencyCode": "MWK"
    }
  ]
}
```

--------------------------------

### Success Response Example

Source: https://docs.onekhusa.com/api-reference/General/currencies

This is an example of a successful response when retrieving currency data. The response is a JSON array of currency objects, each containing a currency code and name.

```json
[
  {
    "currencyCode": "MWK",
    "currencyName": "Malawian Kwacha"
  }
]
```

--------------------------------

### Get Connectors Summary (cURL)

Source: https://docs.onekhusa.com/api-reference/connectors/getConnectorsSummary

Use this cURL command to make a GET request to the API to retrieve a summary of all connectors. Ensure you replace 'your-jwt-token' with your actual authentication token.

```bash
curl -X GET "https://api.onekhusa.com/sandbox/v1/api/core/Connectors/GetSummary" \
  --header "Authorization: Bearer your-jwt-token"
```

--------------------------------

### Get All Currencies (cURL)

Source: https://docs.onekhusa.com/api-reference/General/currencies

Use this cURL command to make a GET request to the currencies endpoint. Ensure you replace `<token>` with your actual access token.

```bash
curl --request GET \
  --url https://api.onekhusa.com/sandbox/v1/core/currencies/GetAll \
  --header 'Authorization: Bearer <token>'
```

--------------------------------

### Transaction Charges Response Example

Source: https://docs.onekhusa.com/api-reference/merchants/getAllTransactionCharges

This is an example of the JSON response you will receive when successfully retrieving transaction charges. It details fees for different transaction types.

```json
[
  {
    "merchantAccountNumber": 12445132,
    "transactionType": "Account To Merchant",
    "currencyCode": "MWK",
    "convenienceFee": 0.00,
    "transactionFeeTag": "P",
    "transactionFee": 1.00,
    "governmentLevyFeeTagCode": "F",
    "governmentLevyFeeAmount": 0.00,
    "vatPercentage": 0.00,
    "merchantFeeTag": "P",
    "merchantFee": 0.00
  },
  {
    "merchantAccountNumber": 12445132,
    "transactionType": "Merchant To Account",
    "currencyCode": "MWK",
    "convenienceFee": 700.00,
    "transactionFeeTag": "P",
    "transactionFee": 1.00,
    "governmentLevyFeeTagCode": "P",
    "governmentLevyFeeAmount": 0.05,
    "vatPercentage": 17.50,
    "merchantFeeTag": "P",
    "merchantFee": 0.00
  },
  {
    "merchantAccountNumber": 12445132,
    "transactionType": "Marchant To Mobile Wallet",
    "currencyCode": "MWK",
    "convenienceFee": 200.00,
    "transactionFeeTag": "P",
    "transactionFee": 1.00,
    "governmentLevyFeeTagCode": "P",
    "governmentLevyFeeAmount": 0.05,
    "vatPercentage": 17.50,
    "merchantFeeTag": "P",
    "merchantFee": 0.00
  },
  {
    "merchantAccountNumber": 12445132,
    "transactionType": "Mobile Wallet To Merchant",
    "currencyCode": "MWK",
    "convenienceFee": 0.00,
    "transactionFeeTag": "P",
    "transactionFee": 1.00,
    "governmentLevyFeeTagCode": "F",
    "governmentLevyFeeAmount": 0.00,
    "vatPercentage": 0.00,
    "merchantFeeTag": "P",
    "merchantFee": 0.00
  },
  {
    "merchantAccountNumber": 12445132,
    "transactionType": "Revenue To Bank Account",
    "currencyCode": "MWK",
    "convenienceFee": 700.00,
    "transactionFeeTag": "P",
    "transactionFee": 0.00,
    "governmentLevyFeeTagCode": "F",
    "governmentLevyFeeAmount": 0.00,
    "vatPercentage": 0.00,
    "merchantFeeTag": "P",
    "merchantFee": 0.00
  }
]
```

--------------------------------

### Get All Bank Accounts (cURL)

Source: https://docs.onekhusa.com/api-reference/merchants/getAllBankAccounts

Use this cURL command to make a GET request to retrieve all bank accounts for a merchant. Ensure you replace `<token>` with your actual access token.

```bash
curl --request GET \
  --url https://api.onekhusa.com/sandbox/v1/merchants/bankAccounts/getAll \
  --header 'Authorization: Bearer <token>'
```

--------------------------------

### Get Connectors Summary

Source: https://docs.onekhusa.com/api-reference/connectors/getConnectorsSummary

Fetches a list of all available payment connectors.

```APIDOC
## GET /core/Connectors/GetSummary

### Description
Retrieves a summary of all available payment connectors, including their status and details.

### Method
GET

### Endpoint
/core/Connectors/GetSummary

### Parameters
#### Query Parameters
- **Accept-Language** (string) - Optional - Preferred language for the response. Defaults to 'en'.

#### Headers
- **Authorization** (string) - Required - Bearer authentication header of the form `Bearer Token`, where `accessToken` is the access token used to authenticate the request.

### Response
#### Success Response (200)
- **connectorName** (string) - Required - The name of the payment connector.
- **connectorId** (integer) - Required - Unique identifier for the connector.
- **isActive** (boolean) - Required - Indicates if the connector is currently active.
- **channelCode** (string) - Required - Code identifying the payment channel.
- **connectorCode** (string) - Required - Unique code for the connector.

#### Response Example
```json
[
  {
    "connectorName": "Airtel Money",
    "connectorId": 123456,
    "isActive": true,
    "channelCode": "M",
    "connectorCode": "EEE"
  },
  {
    "connectorName": "FDH Bank Limited",
    "connectorId": 234567,
    "isActive": true,
    "channelCode": "B",
    "connectorCode": "FDH"
  }
]
```
```

--------------------------------

### Initialize OneKhusa Client and Create Payout

Source: https://docs.onekhusa.com/sdk/get-started/introduction

Demonstrates how to initialize the OneKhusa client with sandbox credentials and create a single disbursement payout. Ensure you replace placeholder API keys and account details with your actual sandbox or production credentials.

```csharp
using Microsoft.Extensions.Logging;
using OneKhusa.SDK;
using OneKhusa.SDK.Models.Configurations;
using OneKhusa.SDK.Models.Shared;
using OneKhusa.SDK.Models.Transactions.SingleDisbursements;

using var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddConsole().SetMinimumLevel(LogLevel.Debug);
});

OneKhusaClient client = new OneKhusaClient(new OneKhusaOptions
{
    ApiKey = "sandbox_1x6PM1KqFUtTwNo32...",
    ApiSecret = "UhWS5DmJfDUFi0OoJAGLzp3c...",
    MerchantAccountNumber = 12345678,
    OrganisationId = "ORG123456789"
}, loggerFactory);

OneKhusaResponse<CreatePayoutResponse> response = await client
    .Transactions
    .SingleDisbursements
    .CreatePayoutAsync(new CreatePayoutRequest
   {
      TransactionAmount = 50000.00,
      BeneficiaryName = "JOE DOE",
      SourceReferenceNumber = "QWSFCTXF882",
      BeneficiaryAccountNumber = "3333888800",
      ConnectorId = 221300,
      MerchantAccountNumber = 12345678,
      TransactionDescription = "MEEETING ALLOWANCE PAYMENT",
      CapturedBy = "joe.doe@example.com",
   });

```

--------------------------------

### Add OneKhusa.SDK via .NET CLI

Source: https://docs.onekhusa.com/sdk/csharp-sdk/installation

Use the `dotnet add package` command in your project's terminal to add the SDK as a dependency.

```bash
dotnet add package OneKhusa.SDK
```

--------------------------------

### Get Batches Success Response Example

Source: https://docs.onekhusa.com/api-reference/disbursements/batch-getBatches

This is an example of a successful response (200 OK) when retrieving disbursement batches. It returns an array of batch objects, each containing details like batch number, status, and transaction count.

```json
[
  {
    "batchNumber": 2024001,
    "capturedBy": "johndoe@example.com",
    "dateCaptured": "2024-01-15",
    "batchStatusCode": "A",
    "batchStatusDescription": "Approved",
    "processDate": "2024-01-15",
    "isBatchScheduled": false,
    "numberOfTransactions": 100
  }
]
```

--------------------------------

### Get Transactions Response (JSON)

Source: https://docs.onekhusa.com/api-reference/collections/get-transactions

This is an example of a successful response (200 OK) from the Get Transactions API. It returns an array of transaction objects, each containing details such as customer name, connector, amount, currency, status, reference number, and date.

```json
[
  {
    "sourceCustomerName": "Joe Doe",
    "connectorName": "Airtel Money",
    "transactionAmount": 75000,
    "transactionFee": 1000,
    "currencyCode": "MWK",
    "transactionStatusCode": "S",
    "transactionStatusName": "Success",
    "transactionReferenceNumber": "D250713MGGGY",
    "transactionDate": "2024-01-15T10:30:00Z"
  },
  {
    "sourceCustomerName": "Grace Banda",
    "connectorName": "Airtel Money",
    "transactionAmount": 75000,
    "transactionFee": 1000,
    "currencyCode": "MWK",
    "transactionStatusCode": "S",
    "transactionStatusName": "Success",
    "transactionReferenceNumber": "B250713MGRTW",
    "transactionDate": "2024-01-15T09:15:00Z"
  }
]
```

--------------------------------

### Manually Instantiate OneKhusa Client

Source: https://docs.onekhusa.com/sdk/csharp-sdk/client-configuration

Create a `OneKhusaClient` instance manually using the configured options. This method is recommended for console applications. It's crucial to instantiate the client once and reuse it for all subsequent API calls to ensure efficient resource management.

```csharp
var client = new OneKhusaClient(options);
```

--------------------------------

### Get Transaction Success Response (200 OK)

Source: https://docs.onekhusa.com/api-reference/collections/get-transaction

This is an example of a successful response when retrieving transaction details. It includes information about the beneficiary, source, and the transaction itself.

```json
{
  "beneficiary": {
    "accountNumber": 12346198,
    "accountName": "MERCHANT SANDBOX",
    "amountReceived": 49500,
    "currencyCode": "MWK"
  },
  "source": {
    "accountNumber": "5271306",
    "customerName": "ANGEL BAULENI",
    "amountSent": 50000,
    "currencyCode": "MWK",
    "sourceReferenceNumber": "JF260209114N",
    "connectorId": 212188,
    "connectorName": "National Bank of Malawi"
  },
  "transaction": {
    "transactionReferenceNumber": "CBPC73IQ5U2E",
    "transactionFee": 500,
    "transactionDescription": "Fake Merchant Account Topup",
    "transactionDate": "2026-02-09T15:12:52.8020476+02:00",
    "valueDate": "2026-02-09T15:12:52.8020476+02:00",
    "transactionCode": "BAM",
    "transactionTypeName": "Account To Merchant",
    "transactionStatusCode": "S",
    "transactionStatusName": "Success",
    "bridgeReferenceNumber": "019c4288-9342-7ebd-a947-6d97d4da77ed",
    "responseCode": "S100",
    "responseMessage": "Successful transaction"
  }
}
```

--------------------------------

### Get Batch Transactions

Source: https://docs.onekhusa.com/sdk/csharp-sdk/batch-disbursements/get-batch-transactions

This C# code example demonstrates how to retrieve batch transactions for a given merchant account and batch number using the OneKhusa SDK.

```APIDOC
## Get Batch Transactions

### Description
Retrieves the posted merchant batch transactions.

### Method Signature
`OneKhusaResponse<List<GetBatchTransactionsResponse>> GetBatchTransactionsAsync(GetBatchTransactionsRequest request)`

### Parameters
#### Request Body
- **request** (GetBatchTransactionsRequest) - Required - An object containing the merchant account number and batch number.
  - **MerchantAccountNumber** (long) - Required - The account number of the merchant.
  - **BatchNumber** (long) - Required - The batch number to retrieve transactions for.

### Response
#### Success Response (200)
- **Data** (List<GetBatchTransactionsResponse>) - A list of batch transaction details.
  - **BatchNumber** (long) - The batch number.
  - **TransactionReferenceNumber** (string) - The reference number of the transaction.
  - **TransactionDescription** (string) - The description of the transaction.
  - **ConnectorName** (string) - The name of the connector used.
  - **CurrencyCode** (string) - The currency code of the transaction.
  - **TransactionAmount** (decimal) - The amount of the transaction.
  - **TransactionStatusCode** (int) - The status code of the transaction.
  - **TransactionStatusName** (string) - The status name of the transaction.

#### Error Response
- **Error** (OneKhusaError) - An object containing error details if the request fails.
  - **Type** (string) - The type of error.
  - **Title** (string) - The title of the error.
  - **Detail** (string) - A detailed description of the error.
  - **ErrorCode** (string) - The specific error code.
  - **Status** (int) - The HTTP status code.
  - **Instance** (string) - The URI that identifies the occurrence of the error.
  - **Errors** (List<string>) - A list of additional errors.
```

--------------------------------

### Initialize OneKhusa Client with Dependency Injection

Source: https://docs.onekhusa.com/sdk/csharp-sdk/client-configuration

Register the OneKhusa client service using dependency injection in your `Program.cs`. This is recommended for web applications and APIs as it manages connection pooling and logging automatically.

```csharp
using OneKhusa.SDK.Extensions;

//code omitted for brevity
builder.Services.AddOneKhusaClient(options =>
{
    options.ApiKey = "your_api_key";
    options.ApiSecret = "your_api_secret";
    options.OrganisationId = "ORG123456789";
    options.MerchantAccountNumber = 12345678;
    options.IsSandbox = true;
});
```

--------------------------------

### Retrieve All Supported Currencies

Source: https://docs.onekhusa.com/sdk/csharp-sdk/static-mentainance/currencies/get-currencies

This C# code example demonstrates how to call the GetCurrenciesAsync method to retrieve a list of all supported currencies and print their codes and names. It also shows how to handle potential errors.

```APIDOC
## Retrieve All Supported Currencies

### Description
This method retrieves all supported currencies on our payment gateway.

### Method
```csharp
GetCurrenciesAsync()
```

### Parameters
This method does not take any parameters.

### Response
#### Success Response
Returns a `OneKhusaResponse` object containing a list of `GetCurrenciesResponse` objects. Each `GetCurrenciesResponse` object contains `CurrencyCode` and `CurrencyName`.

#### Error Response
Returns a `OneKhusaResponse` object with an `Error` property if the request fails. The `Error` object is RFC7807 compliant and may contain fields like `Type`, `Title`, `Detail`, `ErrorCode`, `Status`, `Instance`, and `Errors`.

### Request Example
```csharp
using OneKhusa.SDK;
using OneKhusa.SDK.Models.StaticMaintenance.Currencies;

// Assuming 'client' is an initialized OneKhusaClient instance
OneKhusaResponse<List<GetCurrenciesResponse>> response = await client.StaticMaintenance.Currencies.GetCurrenciesAsync();

if (response.IsSuccess && response.Data != null)
{
    foreach (var currency in response.Data)
    {
        Console.WriteLine($"CurrencyCode: {currency.CurrencyCode}; CurrencyName: {currency.CurrencyName}");
    }
}
else
{
    Console.WriteLine($"Error Type: {response.Error?.Type}");
    Console.WriteLine($"Error Title: {response.Error?.Title}");
    Console.WriteLine($"Error Detail: {response.Error?.Detail}");
    Console.WriteLine($"Error Code: {response.Error?.ErrorCode}");
    Console.WriteLine($"Error Status: {response.Error?.Status}");
    Console.WriteLine($"Error Instance: {response.Error?.Instance}");
    Console.WriteLine($"Errors: {string.Join(";", response.Error?.Errors ?? [])}");
}
```
```

--------------------------------

### Reference OneKhusa.SDK in C# Code

Source: https://docs.onekhusa.com/sdk/csharp-sdk/installation

After installation, use the `using` directive to reference the SDK in your C# code.

```csharp
using OneKhusa.SDK;
```

--------------------------------

### Successful Response for Get Merchant Claims

Source: https://docs.onekhusa.com/api-reference/users/get-users-claims

This is an example of a successful 200 OK response, detailing the claims returned for a merchant user. Claims include account name, status, level, and role information.

```json
[
  {
    "claimType": "MerchantAccountName",
    "claimValue": "Acme Corporation"
  },
  {
    "claimType": "MerchantStatusCode",
    "claimValue": "A"
  },
  {
    "claimType": "LevelNumber",
    "claimValue": 1
  },
  {
    "claimType": "LevelName",
    "claimValue": "Level 1 Merchant"
  },
  {
    "claimType": "MerchantAccountNumber",
    "claimValue": "35253486"
  },
  {
    "claimType": "OrganisationId",
    "claimValue": "FYH0NTVW0DXK"
  },
  {
    "claimType": "OrganisationTypeCode",
    "claimValue": "MER"
  },
  {
    "claimType": "Role",
    "claimValue": "BO_OPR"
  }
]
```

--------------------------------

### Get All Bank Accounts Response (JSON)

Source: https://docs.onekhusa.com/api-reference/merchants/getAllBankAccounts

This is an example of a successful JSON response when retrieving all bank accounts for a merchant. It lists account details including account number, connector information, and creation/modification timestamps.

```json
[
  {
    "merchantAccountNumber": 35253486,
    "accountId": 1,
    "accountName": "Test Account 1",
    "accountNumber": "114453647",
    "connectorId": 550044,
    "connectorName": "National Bank of Malawi",
    "isActive": true,
    "dateCreated": "2024-01-15T10:30:00Z",
    "dateCaptured": "2024-01-15T10:30:00Z",
    "capturedBy": "admin@example.com",
    "dateModified": "2024-01-16T14:20:00Z",
    "modifiedBy": "user@example.com"
  },
  {
    "merchantAccountNumber": 35253486,
    "accountId": 2,
    "accountName": "Test Account 2",
    "accountNumber": "3114453648",
    "connectorId": 666473,
    "connectorName": "FDH Bank Limited",
    "isActive": false,
    "dateCreated": "2024-01-20T09:15:00Z",
    "dateCaptured": "2024-01-20T09:15:00Z",
    "capturedBy": "admin@example.com",
    "dateModified": null,
    "modifiedBy": null
  }
]
```

--------------------------------

### Upload Batch File using SDK

Source: https://docs.onekhusa.com/sdk/csharp-sdk/batch-disbursements/upload-batchfile

This code example demonstrates how to upload a batch disbursement file using the OneKhusa SDK. It shows how to instantiate the request, set necessary parameters, and handle both successful responses and errors.

```APIDOC
## Upload Batch File

### Description
Uploads batch disbursement transactions using Microsoft Excel (.xlsx) or CSV files.

### Method
`UploadFileAsync`

### Parameters
#### Request Body
- **MerchantAccountNumber** (int) - Required - The merchant's account number.
- **ContentType** (string) - Required - The type of the file content (e.g., `ContentTypes.MicrosoftExcel`).
- **IsBatchScheduled** (bool) - Required - Indicates if the batch is scheduled.
- **FileContent** (byte[]) - Required - The content of the file to upload.
- **CapturedBy** (string) - Required - The email address of the user capturing the batch.
- **IdempotencyKey** (string) - Optional - A custom idempotency key.
- **ScheduledDate** (DateTime) - Optional - The date to schedule the batch if `IsBatchScheduled` is true.

### Request Example
```csharp
using OneKhusa.SDK;
using OneKhusa.SDK.Models.Transactions.BatchDisbursements;
using OneKhusa.SDK.Models.Constants.Shared;

// ... other using statements and setup ...

OneKhusaResponse<UploadBatchFileResponse> response = await client
    .Transactions
    .BatchDisbursements
    .UploadFileAsync(new UploadBatchFileRequest
    {
        MerchantAccountNumber = 12345678,
        ContentType = ContentTypes.MicrosoftExcel,
        IsBatchScheduled = false,
        FileContent = File.ReadAllBytes(@"file-directory\batch_payouts.xlsx"),
        CapturedBy = "joe.doe@example.com"
    });
```

### Response
#### Success Response (200)
- **MerchantAccountNumber** (long) - The merchant's account number.
- **BatchNumber** (long) - The unique identifier for the batch.
- **BatchStatusCode** (string) - The status code of the batch.

#### Response Example
```json
{
  "MerchantAccountNumber": 12345678,
  "BatchNumber": 987654321,
  "BatchStatusCode": "PENDING"
}
```

#### Error Response
- **Type** (string) - The type of the error.
- **Title** (string) - The title of the error.
- **Detail** (string) - A detailed description of the error.
- **ErrorCode** (string) - The specific error code.
- **Status** (int) - The HTTP status code.
- **Instance** (string) - The URI that identifies the occurrence of the error.
- **Errors** (List<string>) - A list of specific field errors.

#### Error Response Example
```json
{
  "Type": "https://tools.ietf.org/html/rfc7807",
  "Title": "Validation Error",
  "Detail": "One or more validation errors occurred.",
  "ErrorCode": "VALIDATION_ERROR",
  "Status": 400,
  "Instance": "/transactions/batch-disbursements/upload",
  "Errors": ["MerchantAccountNumber is required."]
}
```

### Notes
- This method accepts custom idempotency keys. If not specified, one will be generated.
- To schedule a batch, set `IsBatchScheduled` to `true` and provide a `ScheduledDate`.
- For large files, use a streaming approach to prevent API request timeouts.
```

--------------------------------

### Disbursement Webhook Payload Examples

Source: https://docs.onekhusa.com/api-reference/webhooks/disbursementwebhook

Example JSON payloads for different disbursement transaction statuses: Success, Failed, and Reversed Payouts.

```APIDOC
## Disbursement Webhook Payload Examples

### Success Payout
```json
{
  "beneficiaryAccountNumber": "1234567890",
  "beneficiaryAccountName": "John Doe",
  "beneficiaryInstitution": "National Bank of Malawi",
  "transactionReferenceNumber": "251105812UIK",
  "transactionDescription": "Salary Payment",
  "transactionCode": "MBA",
  "transactionAmount": 1000.50,
  "transactionFee": 10.00,
  "transactionDate": "2024-01-15T09:00:00Z",
  "processedDate": "2024-01-15T10:30:00Z",
  "transactionStatusCode": "S",
  "responseCode": "S100",
  "connectorId": 223758
}
```

### Failed Payout
```json
{
  "beneficiaryAccountNumber": "1234567890",
  "beneficiaryAccountName": "John Doe",
  "beneficiaryInstitution": "National Bank of Malawi",
  "transactionReferenceNumber": "251105812HMM",
  "transactionDescription": "Salary Payment",
  "transactionCode": "MBA",
  "transactionAmount": 1000.50,
  "transactionFee": 10.00,
  "transactionDate": "2024-01-15T09:00:00Z",
  "processedDate": "2024-01-15T11:00:00Z",
  "transactionStatusCode": "F",
  "responseCode": "E999",
  "connectorId": 224545
}
```

### Reversed Payout
```json
{
  "beneficiaryAccountNumber": "1234567890",
  "beneficiaryAccountName": "John Doe",
  "beneficiaryInstitution": "National Bank of Malawi",
  "transactionReferenceNumber": "251605812HKL",
  "transactionDescription": "Salary Payment for January",
  "transactionCode": "MMW",
  "transactionAmount": 1000.50,
  "transactionFee": 10.00,
  "transactionDate": "2024-01-15T09:00:00Z",
  "processedDate": "2024-01-15T10:30:00Z",
  "transactionStatusCode": "R",
  "responseCode": "S100",
  "connectorId": 221478
}
```
```

--------------------------------

### Get Merchant Bank Account

Source: https://docs.onekhusa.com/api-reference/merchants/getBankAccount

This snippet shows how to retrieve a merchant's bank account details using the GET method.

```APIDOC
## GET /merchants/bankAccounts/get

### Description
Retrieves the details of a specific merchant bank account.

### Method
GET

### Endpoint
/merchants/bankAccounts/get

### Query Parameters
- **AccountId** (integer) - Required - The unique identifier of the bank account.

### Headers
- **Authorization** (string) - Required - Bearer authentication header of the form `Bearer Token`.
- **Accept-Language** (string) - Optional - Preferred language for the response. Defaults to 'en'.

### Response
#### Success Response (200)
- **merchantAccountNumber** (integer) - The unique identifier of the merchant account.
- **accountId** (integer) - The unique identifier of the bank account.
- **accountName** (string) - The name of the bank account.
- **accountNumber** (string) - The bank account number.
- **connectorId** (integer) - The unique identifier of the connector/payment provider.
- **connectorName** (string) - The name of the payment connector.
- **isActive** (boolean) - Indicates whether the bank account is currently active.
- **dateCreated** (string<date-time>) - The date and time when the bank account was created (ISO 8601).
- **dateCaptured** (string<date-time>) - The date and time when the bank account details were captured (ISO 8601).
- **capturedBy** (string<email>) - The email of the user who captured the account.
- **dateModified** (string<date-time> | null) - The date and time when the bank account was last modified (ISO 8601).
- **modifiedBy** (string | null) - The username or identifier of the user who last modified the account.

### Request Example
```curl
curl -X GET "https://api.onekhusa.com/sandbox/v1/merchants/bankAccounts/get?AccountId=1" \
  --header "Authorization: Bearer your-jwt-token" \
  --header "accept: application/json" \
  --header "Accept-Language: en"
```

### Response Example
```json
{
  "merchantAccountNumber": 35253486,
  "accountId": 12,
  "accountName": "Test Account",
  "accountNumber": "114453647",
  "connectorId": 550044,
  "connectorName": "National Bank of Malawi",
  "isActive": true,
  "dateCreated": "2024-01-15T10:30:00Z",
  "dateCaptured": "2024-01-15T10:30:00Z",
  "capturedBy": "admin@example.com",
  "dateModified": "2024-01-16T14:20:00Z",
  "modifiedBy": "user@example.com"
}
```
```

--------------------------------

### Get All Connectors

Source: https://docs.onekhusa.com/api-reference/connectors/getAll

Retrieves a list of all available connectors. Requires Bearer token authentication and specifies the desired language for the response.

```bash
curl -X GET "https://api.onekhusa.com/sandbox/v1/core/connectors/GetAll" \
  --header "Authorization: Bearer your-jwt-token" \
  --header "accept: application/json" \
  --header "Accept-Language: en"
```

--------------------------------

### Connectors Summary Response

Source: https://docs.onekhusa.com/api-reference/connectors/getConnectorsSummary

This is an example of a successful JSON response when retrieving the connectors summary. It lists each connector with its details.

```json
[
  {
    "connectorName": "Airtel Money",
    "connectorId": 123456,
    "isActive": true,
    "channelCode": "M",
    "connectorCode": "EEE"
  },
  {
    "connectorName": "FDH Bank Limited",
    "connectorId": 234567,
    "isActive": true,
    "channelCode": "B",
    "connectorCode": "FDH"
  }
]
```

--------------------------------

### Fee Calculation Response (JSON)

Source: https://docs.onekhusa.com/api-reference/merchants/fee-calculation

This is a sample successful response (200 OK) for a fee calculation request. It details various fee components, including currency, amounts, VAT, and the net fee.

```json
{
  "currencyCode": "MWK",
  "transactionAmount": 100000,
  "convenienceFeeAmount": 700,
  "transactionFeeAmount": 1000,
  "merchantFeeAmount": 0,
  "governmentLevyFeeAmount": 50,
  "totalFeeBeforeVat": 1750,
  "vatAmount": 306.25,
  "netFeeAmount": 2056.25
}
```

--------------------------------

### Configure OneKhusa Client Options

Source: https://docs.onekhusa.com/sdk/csharp-sdk/client-configuration

Define your merchant API credentials and other configuration settings for the OneKhusa client. The `IsSandbox` option defaults to `true` and can be omitted if using the sandbox environment. `ApiVersion` defaults to `v1`.

```csharp
using OneKhusa.SDK;
using OneKhusa.SDK.Models.Configurations;
var options = new OneKhusaOptions
{
    ApiKey = "your_api_key",
    ApiSecret = "your_api_secret",
    OrganisationId = "ORG123456789",
    MerchantAccountNumber = 12345678,
    IsSandbox = true
};
```
Tokens:
Raw