### Klasha Transfer Response Example

Source: https://developers.klasha.com/transfers/payout/cny-payout-new-encryption

This is an example of a successful response when initiating a transfer or uploading a file with the Klasha API, showing the returned ID, purpose, and attachment type.

```JSON
{
    "id": 628,
    "purpose": "Order Delivery",
    "attachmentType": "CUSTOMS_DECLARATION"
}
```

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

### Klasha Callback Response Example

Source: https://developers.klasha.com/accepting-payments/klasha-inline

This is an example of a callback response from Klasha after a transaction. It provides details about the transaction amount, currency, and status.

```json
{
   "amount": 560,
   "currency": "NGN",
   "status": "successful",
   "tnxRef": "tnxRef"
}
```

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

### Create Payment Link Response - Klasha API

Source: https://developers.klasha.com/accepting-payments/payment-link/payment-link-api

Example of a successful response after creating a payment link, providing the unique paylinkId, the payment URL, and the business ID.

```JSON
{
    "message": "success",
    "error": null,
    "data": {
        "paylinkId": "b8d0aab0-5974-45a6-ae4a-8b6d519b4da2",
        "paylinkUrl": "https://dev.d2qotb20wbiarg.amplifyapp.com/?token=b8d0aab0-5974-45a6-ae4a-8b6d519b4da2",
        "businessId": "111"
    }
}
```

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

### Create Quotation API Response

Source: https://developers.klasha.com/transfers/payout/cny-payout-new-encryption

Example response from the create quotation API, detailing the transaction details including source and destination amounts, exchange rate, fees, and expiration.

```json
{
    "id": 472,
    "sourceAmount": 9.40,
    "sourceCurrency": "USD",
    "destinationAmount": 70.00,
    "destinationCurrency": "CNY",
    "fxRate": 7.44,
    "fee": 6.00,
    "expiration": 1734490800000,
    "reference": "f7c32b34-ec79-4de2-ae8a-42529",
    "expired": false
}
```

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

### Login Response - Klasha API

Source: https://developers.klasha.com/accepting-payments/payment-link/payment-link-api

Example of a successful response when generating a bearer token, containing the authentication token.

```JSON
{
    "message": "success",
    "error": null,
    "data": {
        "token": "This is your token"
    }
}
```

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

### Klasha Webhook Response Example

Source: https://developers.klasha.com/accepting-payments/klasha-inline

This example demonstrates the structure of a webhook response from Klasha for a completed charge. It includes event details, transaction data, customer information, and status.

```json
{
  "event": "charge.completed",
  "data": {
    "createdAt": "2021-11-18T15:23:16.781",
    "narration": "CARD Transaction ",
    "destinationCurrency": "NGN",
    "sourceAmount": 1,
    "sourceCurrency": "USD",
    "tnxRef": "tnxRef",
    "status": "successful",
    "destinationAmount": 560,
    "customer": {
      "id": 13,
      "name": "Klasha",
      "email": "test@klasha.com",
      "phone": "09012332122",
      "createdAt": "2021-07-20 10:28:43",
      "updatedAt": "2021-07-20 10:28:43"
    }
  }
}
```

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

### Klasha Initiate Transfer Request API

Source: https://developers.klasha.com/transfers/payout/cny-payout-new-encryption

This section details how to initiate a bank transfer using the Klasha API. It specifies the endpoint, required headers (including 'x-auth-token'), and provides an example of an encrypted request body.

```HTTP
POST {{env_url}}/wallet/merchant/{businessId}/bank/transfer/v2/request

Headers:
Content-Type: application/json
x-auth-token: MERCHANT PUBLIC KEY
Authorization: Bearer <token here>

Request body (encrypted):
{
  "message": "encrypted-request-body"
}
```

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

### BIN Not Found Response

Source: https://developers.klasha.com/bank-account-collection/business-identification-service

Example response indicating that BIN data was not found for the specified business ID.

```json
{
    "message": "Bin data not found for business 1",
    "error": "NOT_FOUND",
    "data": null
}
```

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

### Successful BIN Generation Response

Source: https://developers.klasha.com/bank-account-collection/business-identification-service

Example of a successful response when a BIN is generated, including the BIN, business ID, and creation timestamps.

```json
{
    "message": "success",
    "error": null,
    "data": {
        "id": 4,
        "bin": "DL0",
        "businessId": 3,
        "createdAt": "2024-09-17 14:38:28",
        "updatedAt": "2024-09-17 14:38:28"
    }
}
```

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

### Get Bank Lists Response

Source: https://developers.klasha.com/transfers/payout/zmw-payout-new-encryption

Example JSON response for the Get Bank Lists API, containing a list of banks with their codes and names.

```json
{
    "message": "success",
    "error": null,
    "data": [
        {
            "code": "002",
            "name": "Absa Bank"
        },
        {
            "code": "003",
            "name": "Access Bank"
        },
        {
            "code": "005",
            "name": "Atlas Mara"
        },
        {
            "code": "006",
            "name": "Bank of China"
        },
        {
            "code": "007",
            "name": "Citibank"
        },
        {
            "code": "008",
            "name": "Ecobank"
        },
        {
            "code": "010",
            "name": "Indo Zambia Bank"
        },
        {
            "code": "011",
            "name": "Investrust Bank"
        },
        {
            "code": "012",
            "name": "First Alliance Bank"
        },
        {
            "code": "013",
            "name": "First Capital"
        },
        {
            "code": "014",
            "name": "FNB"
        },
        {
            "code": "016",
            "name": "Stanbic Bank"
        },
        {
            "code": "017",
            "name": "Standard Chartered Bank"
        },
        {
            "code": "022",
            "name": "United Bank for Africa"
        },
        {
            "code": "023",
            "name": "Zanaco"
        },
        {
            "code": "025",
            "name": "ZICB"
        }
    ]
}
```

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

### Wallet Balance Success Response

Source: https://developers.klasha.com/transfers/payout

Example of a successful response when fetching the wallet balance, showing currency, balances, and wallet details.

```JSON
{
    "message": "success",
    "error": null,
    "data": [
        {
            "id": 66,
            "currency": "NGN",
            "ledgerBalance": 100.0,
            "availableBalance": 100.0,
            "walletType": "BUSINESS",
            "businessId": 3,
            "createdAt": "2023-12-19 14:54:49",
            "updatedAt": "2023-12-19 14:54:49"
        }
    ]
}
```

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

### Payment Status Webhook - Klasha API

Source: https://developers.klasha.com/accepting-payments/payment-link/payment-link-api

Example of a webhook payload received from Klasha indicating the status of a payment, including transaction details and customer information.

```JSON
{
    "data": {
        "createdAt": "2024-08-21T12:03:46.728",
        "subMerchantId": "sub-merchant_12",
        "paylinkId": "8406d382-8443-4c65-aaf2-6dc3721c85b4",
        "narration": "Business wallet popup payment",
        "destinationCurrency": "NGN",
        "sourceAmount": 1500.00,
        "sourceCurrency": "NGN",
        "tnxRef": "paylink-f66b115c-4733-4b2c-88f9-085517c1dba7",
        "status": "successful",
        "destinationAmount": 1500.0,
        "customer": {
            "id": 13,
            "name": "Steph Oj",
            "email": "stephen@klasha.com",
            "phone": null,
            "createdAt": "2021-07-20T10:28:43.820",
            "updatedAt": "2021-07-20T10:28:43.820"
        }
    },
    "event": "charge.completed"
}
```

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

### BIN Already Issued Response

Source: https://developers.klasha.com/bank-account-collection/business-identification-service

Example response indicating that a BIN has already been issued for the business.

```json
{
    "message": "Business has already been issued a bin",
    "error": "Bad Request",
    "data": null
}
```

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

### Klasha Payout Response Example

Source: https://developers.klasha.com/transfers/payout/cny-payout-new-encryption

This JSON object represents a successful payout response from the Klasha API, including details like payout status, request ID, bank information, and account details.

```JSON
{
    "id": 1,
    "amount": 70.00,
    "payoutStatus": "PENDING",
    "requestId": "ed5fa-a33ed-fc4dc",
    "narration": "GOODS_PURCHASE",
    "country": "CN",
    "fee": 6.00,
    "bankCode": "03010000",
    "bankName": "Bank of communications",
    "accountNumber": "10000000000",
    "accountName": "Test Flow"
}
```

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

### Successful BIN Retrieval Response

Source: https://developers.klasha.com/bank-account-collection/business-identification-service

Example of a successful response when retrieving a BIN using the business ID.

```json
{
    "message": "success",
    "error": null,
    "data": {
        "id": 3,
        "bin": "WZ0",
        "businessId": 133,
        "createdAt": "2024-08-12 15:11:39",
        "updatedAt": "2024-08-12 15:11:39"
    }
}
```

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

### Successful Bank Account Details Response

Source: https://developers.klasha.com/bank-account-collection/business-identification-service

Example response showing bank account details for a currency, including account number, name, bank name, and location.

```json
{
    "message": "success",
    "error": null,
    "data": [
        {
            "id": 1,
            "businessId": 176,
            "accountNumber": "0011223344",
            "accountName": "Klasha Ke",
            "bankName": "FBN ltd",
            "currency": "KES",
            "location": "Kenya",
            "isLocationDefault": true,
            "createdAt": "2024-08-09 11:28:13",
            "updatedAt": "2024-08-09 11:28:13"
        }
    ]
}
```

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

### Retrieve BIN (GET)

Source: https://developers.klasha.com/bank-account-collection/business-identification-service

Fetches the BIN associated with a given business ID. Requires an `Authorization` header with a Bearer token.

```HTTP
GET {{env_url}}/nucleus/foreign-funding/bins/{{businessId}}

Headers:
Key
Value
Authorization
Bearer <token-here>
```

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

### No Accounts Available Response

Source: https://developers.klasha.com/bank-account-collection/business-identification-service

Example response when no bank accounts are available for the specified currency.

```json
{
    "message": "No accounts available for the specified currency USD",
    "error": "NOT_FOUND",
    "data": null
}
```

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

### Successful Payout Response (JSON)

Source: https://developers.klasha.com/transfers/momo-payout/xaf-cameroon-new-encryption

Example of a successful response (200 OK) after initiating a merchant payout request, detailing payout information.

```json
{
    "id": 10,
    "amount": 100.00,
    "payoutStatus": "PENDING",
    "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
    "narration": "none for now",
    "country": "CM",
    "fee": 2.00,
    "bankCode": "ORANGE_CMR",
    "bankName": "ORANGE_CMR",
    "accountNumber": "260973456789",
    "accountName": "test sample"
}
```

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

### POST /pay/aggregators/{{gateway}}/card/payment/v2

Source: https://developers.klasha.com/accepting-payments/payments-api

Processes a payment via M-Pesa. Requires an x-auth-token in the header and provides request body and response examples for successful and failed transactions.

```APIDOC
## POST /pay/aggregators/{{gateway}}/card/payment/v2

### Description
Processes a payment via M-Pesa. Requires an x-auth-token in the header and provides request body and response examples for successful and failed transactions.

### Method
POST

### Endpoint
`{{env_url}}/pay/aggregators/{{gateway}}/card/payment/v2`

### Parameters
#### Path Parameters
- **gateway** (string) - Required - The payment gateway (e.g., KES for M-Pesa).

#### Headers
- **Content-Type** (string) - `application/json`
- **x-auth-token** (string) - Required - Your merchant public key.

#### Request Body
- **currency** (string) - Required - The currency of the transaction (e.g., KES).
- **country** (string) - Required - The country code (e.g., KE).
- **amount** (string) - Required - The payment amount.
- **rate** (number) - Required - The exchange rate.
- **paymentType** (string) - Optional - The payment type (e.g., 'woo').
- **sourceCurrency** (string) - Optional - The source currency.
- **sourceAmount** (number) - Optional - The source amount.
- **rememberMe** (boolean) - Optional - Whether to remember the user.
- **option** (string) - Required - The payment option (e.g., 'mpesa').
- **phone_number** (string) - Required - Customer's phone number.
- **email** (string) - Required - Customer's email address.
- **fullname** (string) - Required - Customer's full name.
- **tx_ref** (string) - Required - Transaction reference ID.

### Request Example
```json
{
   "currency": "KES",
   "country": "KE",
   "amount": "10",
   "rate": 680,
   "paymentType": "woo",
   "sourceCurrency": "KES",
   "sourceAmount": 10,
   "rememberMe": true,
   "option": "mpesa",
   "phone_number": "+254710000000",
   "email": "email@klasha.com",
   "fullname": "John Doe",
   "tx_ref": "test910-on2007u047e-291076"
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the status of the operation.
- **error** (object|null) - Contains error details if any.
- **data** (object) - Contains transaction details.
  - **tx_ref** (string) - Transaction reference ID.
  - **data** (object) - Nested data object with transaction information.
    - **amount** (string) - The transaction amount.
    - **charged_amount** (string) - The charged amount.
    - **currency** (string) - The transaction currency.
    - **customer** (object) - Customer details.
      - **name** (string) - Customer's name.
      - **phone_number** (string) - Customer's phone number.
      - **email** (string) - Customer's email address.
    - **status** (string) - The status of the transaction (e.g., 'pending').
  - **message** (string) - Status message for the transaction.
  - **status** (string) - Overall status of the transaction.

#### Error Response (400)
- **tx_ref** (string) - Transaction reference ID.
- **data** (null) - No data returned in case of an error.
- **message** (string) - Error message (e.g., "Invalid phone number format").
- **status** (string) - Indicates an error status.

### Response Example (Success)
```json
{
    "message": "success",
    "error": null,
    "data": {
        "tx_ref": "test910-on2007u047e-291076",
        "data": {
            "amount": "10",
            "charged_amount": "10",
            "currency": "KES",
            "customer": {
                "name": "John Doe",
                "phone_number": "+254710000000",
                "email": "email@klasha.com"
            },
            "status": "pending"
        },
        "message": "Transaction in progress",
        "status": "pending"
    }
}
```

### Response Example (Error)
```json
{
    "tx_ref": "test910-on2007u047e-mcnvmlbhgmjfo",
    "data": null,
    "message": "Invalid phone number format",
    "status": "error"
}
```
```

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

### React SDK Integration

Source: https://developers.klasha.com/plugins-and-sdks/web-sdks

Use the Klasha React SDK to enable payment collection within your React-based websites. Detailed integration guides are available on GitHub and NPM.

```JavaScript
// Example usage for React SDK (conceptual)
// Import Klasha component or hook
// Configure Klasha with your public key
// Render payment component or call payment function
```

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

### Initiate Virtual Account Creation Request

Source: https://developers.klasha.com/bank-account-collection

This code snippet demonstrates how to structure the POST request to initiate virtual account creation. It includes the endpoint, required headers (x-auth-token and Authorization), and the encrypted message in the request body.

```http
POST {{env_url}}/wallet/virtual/v3/business/create/account

Headers:
x-auth-token: Your merchant public key
Authorization: Bearer <token here>

**Request Body (encrypted)**
```
{
   "message": "encrypted-message"
}
```
```

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

### Initiate Card Payment

Source: https://developers.klasha.com/accepting-payments/payments-api

Initiates a card payment process. Requires authentication via an x-auth-token.

```APIDOC
## POST /pay/aggregators/{{gateway}}/card/payment/v2

### Description
Initiates a card payment transaction. This is the first step in the card payment flow, followed by charging and validating the card.

### Method
POST

### Endpoint
`{{env_url}}/pay/aggregators/{{gateway}}/card/payment/v2`

### Parameters
#### Headers
*   **Content-Type** (string) - Required - `application/json`
*   **x-auth-token** (string) - Required - Your merchant public key, obtained from your merchant dashboard.
```

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

### Get Bank Account Details (GET)

Source: https://developers.klasha.com/bank-account-collection/business-identification-service

Fetches bank account details for a specified currency and business ID. These details are shared with customers for funding, requiring the narration to start with the merchant's BIN.

```HTTP
GET {{env_url}}/nucleus/foreign-funding/accounts?currency={{currency}}&businessId={{businessId}}

Headers:
Key
Value
Authorization
Bearer <token here>
```

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

### Get Wallet Balance API Request

Source: https://developers.klasha.com/transfers

This snippet shows how to make a GET request to the Klasha API to retrieve the wallet balance. It includes the necessary endpoint, headers (Content-Type, Authorization, x-auth-token), and example success and error responses.

```bash
GET {{env_url}}/nucleus/business/api/wallets
Headers:
Content-Type: application/json
Authorization: Bearer <token>
x-auth-token: <public key>
```

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

### Klasha Wire Payment Initiation Response

Source: https://developers.klasha.com/transfers/klasha-wire-api

Example response after initiating a wire payment. It confirms the transaction details, including amounts, fees, status, and unique identifiers like transaction reference and quote token.

```json
{
    "message": "success",
    "error": null,
    "data": {
        "id": 5,
        "sourceCurrency": "NGN",
        "sourceAmount": 575338.5,
        "destinationCurrency": "USD",
        "destinationAmount": 1000,
        "narration": "School fees",
        "destinationFees": 27.5,
        "sourceFees": 15821.81,
        "rate": 575.3385,
        "klashaWireStatus": "PENDING",
        "transactionReference": "KWire-32f1d4c6-4560-4033-8cf6-713d405ec10d",
        "merchantBeneficiary": "7ed8d2e3-8709-4202-8842-7757946ee194",
        "quoteToken": "1c8eaf0d-3490-4774-ae86-7443e4f93557",
        "createdAt": "2023-10-26T12:44:37.355",
        "updatedAt": "2023-10-26T12:45:27.243"
    }
}
```

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

### Klasha Wire Quote Response

Source: https://developers.klasha.com/transfers/klasha-wire-api

Example response from the Create Quote API, confirming the quote generation. Includes details like source and destination amounts, fees, exchange rate, and status.

```json
{
    "message": "success",
    "error": null,
    "data": {
        "id": 1,
        "sourceCurrency": "NGN",
        "sourceAmount": 575338.5,
        "destinationCurrency": "USD",
        "destinationAmount": 1000,
        "destinationFees": 27.5,
        "sourceFees": 15821.808749999998,
        "rate": 575.3385,
        "klashaWireStatus": "PENDING",
        "merchantBeneficiary": "87954c4f-736a-4e09-b588-76ab9c13bafe",
        "quoteToken": "842dcd42-8f95-4a3b-a5f3-07a3d0416119",
        "createdAt": "2023-10-09T13:11:29.478",
        "updatedAt": "2023-10-09T13:11:29.478"
    }
}
```

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

### Virtual Account Balance Response

Source: https://developers.klasha.com/bank-account-collection/va-balance-and-statement

Example JSON response for the Get Virtual Account Balance API, showing the settlement and collection balances.

```JSON
{
    "message": "success",
    "error": null,
    "data": {
        "virtualAccountCollectionSettlement": 100.00,
        "virtualAccountCollectionsBalance": 200.00
    }
}
```

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

### Fetch Payment Link Transactions - Klasha API

Source: https://developers.klasha.com/accepting-payments/payment-link/payment-link-api

Retrieve payment link transactions by making a GET request using the `paylinkId`. Ensure to include authorization headers.

```HTTP
GET {{env_url}}/nucleus/paymentLinkTransaction/id/{{paylinkId}}
```

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

### Klasha API: C2C Bank Transfer (CNY)

Source: https://developers.klasha.com/transfers/payout/cny-payout-new-encryption

Example JSON payload for a C2C bank transfer within China, specifying sender and receiver details, bank information, and transaction purpose.

```JSON
{
    "accountName": "上海弢汇商务咨询有限公司",
    "accountNumber": "31050161363900000210",
    "accountType": "COMPANY",
    "bankCode": "105100000017",
    "bankName": "中国建设银行",
    "creditAccountCountry": "CN",
    "purpose": "GOODS_PURCHASE",
    "quotationId": 4852,
    "receiverBusinessIdNumber": "91310116MA1J9LE95D",
    "receiverBusinessIdType": "UNIFIED_SOCIAL_CREDIT_ID",
    "receiverBusinessMobileNumber": "+8613816932352",
    "receiverBusinessRegisteredName": "上海弢汇商务咨询有限公司",
    "receiverBusinessAddress": {
        "city": "Shanghai",
        "streetAddress": "Tingwei Highway",
        "countryCode": "CN",
        "postcode": "201599",
        "state": "Shanghai"
    },
    "requestId": "6222040000030016-06",
    "senderBusinessAddress": {
        "city": "Lagos",
        "streetAddress": "Ligali",
        "countryCode": "NG",
        "postcode": "50001",
        "state": "Lagos State"
    },
    "senderBusinessRegisteredName": "KLASHA TECHNOLOGIES LTD",
    "message": "bypass",
    "document": {
        "totalAmount": "100",
        "attachments": [
            {
                "fileId": "628"
            }
        ],
        "orderNumber": "001AD#",
        "orderTime": "2025-01-01",
        "orderCurrency": "CNY",
        "tradeType": "GENERAL_GOODS",
        "products": [
            {
                "name": "FEMALE BAG",
                "quantity": "1",
                "productCategory": "APPAREL"
            }
        ],
        "paymentType": "COLLECT",
        "customs": {
            "customsDecNo": "00112345666"
        },
        "logistics": {
            "company": "GIG",
            "orderNo": "001AD#",
            "shipDate": "2025-04-27"
        }
    }
}
```

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

### Initiate Payment Request Body (Plain)

Source: https://developers.klasha.com/accepting-payments/payments-api

The plain request body for initiating a payment, including card details, currency, amount, and customer information. This is used to start a transaction before charging.

```json
{
    "card_number": "507850785078507812",
    "card_holder_name": "John Doe",
    "cvv": "081",
    "expiry_month": "05",
    "expiry_year": "25",
    "currency": "NGN",
    "country": "NG",
    "amount": "200",
    "rate": 1,
    "paymentType": "woo",
    "sourceCurrency": "NGN",
    "sourceAmount": 200,
    "rememberMe": true,
    "phone_number": "080344006699",
    "email": "email@klasha.com",
    "fullname": "John Doe",
    "tx_ref": "test910-on2007u047e-2910tytrr76"
}
```

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

### Klasha API: C2C Family Support (CN)

Source: https://developers.klasha.com/transfers/payout/cny-payout-new-encryption

Example JSON payload for a C2C transfer within China for family support, including sender's passport details and receiver's name.

```JSON
{
    "senderAddress": {
        "city": "Beijing",
        "streetAddress": "Beijing",
        "countryCode": "CN",
        "postcode": "100001",
        "state": "Beijing"
    },
    "senderFirstName": "Chin",
    "senderLastName": "Yung",
    "senderNationality": "CN",
    "senderIdNumber": "B12507200",
    "senderBirthDate": "1991-09-26",
    "senderIdType": "PASSPORT",
    "purpose": "FAMILY_SUPPORT",
    "creditAccountCountry": "CN",
    "receiverLastName": "Fan",
    "receiverIdNumber": "B12507200",
    "receiverFirstName": "Jing",
    "requestId": "d99c0f80-301e-4938-9f79-d9753",
    "quotationId": 728,
    "accountNumber": "8613699262597",
    "accountId": "MOBILE",
    "receiverRelationship": "SELF"
}
```

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

### Initiate Klasha Wire Payment

Source: https://developers.klasha.com/transfers/klasha-wire-api

Initiates a wire payment by converting a quote into a payment. This POST request requires a quote token, beneficiary ID, narration, and an invoice URL. Similar to quote generation, the request body must be encrypted and include the 'x-auth-token' header.

```http
POST {{env_url}}/wallet/wire/initiate

Headers:
Name: Value
Authorization: Bearer {{token}}
x-auth-token: MERCHANT PUBLIC KEY

Request Body:
Name: Type: Description
quoteToken*: 842dcd42-8f95-4a3b-a5f3-07a3d0416119
beneficiary*: 87954c4f-736a-4e09-b588-76ab9c13bafe
narration*: School fees
invoiceUrl*: www.invoiceURL.com
```

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

### Get Bank Codes by Account Type in JSON

Source: https://developers.klasha.com/transfers/payout/cny-payout-new-encryption

Retrieves a list of bank codes and their corresponding names. The API supports filtering by account type, specifically 'BANK_ACCOUNT' or 'bank_card'. The response is in JSON format and includes a 'data' array with 'code' and 'name' fields for each bank.

```JSON
{
    "message": "success",
    "error": null,
    "data": [
        {
            "code": "403100000004",
            "name": "Postal Savings Bank of China (中国邮政储蓄银行)"
        },
        {
            "code": "102100099996",
            "name": "Industrial and Commercial Bank of China (中国工商银行)"
        },
        {
            "code": "103100000026",
            "name": "Agricultural Bank of China (中国农业银行)"
        }
   ...]
}
```

```JSON
{
    "message": "success",
    "error": null,
    "data": [
        {
            "code": "03010000",
            "name": "Bank of Communications"
        },
        {
            "code": "01040000",
            "name": "Bank of China"
        },
        {
            "code": "03033320",
            "name": "Guang Da Bank"
        },
        {
            "code": "14505800",
            "name": "GuangDong Rural Credit Bank"
        }
    ...]
}
```

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

### Klasha API Response Example (JSON)

Source: https://developers.klasha.com/bank-account-collection/virtual-account-creation

This code snippet shows a typical successful response from the Klasha API, detailing account information for a payment transaction. It includes details like account number, bank name, and transaction references.

```json
[
    {
        "accountNumber": "8573777620",
        "bankName": "WEMA BANK",
        "orderRef": "HsKRPDlemp7XBKvgO1HE",
        "txRef": "klasha-fund-wallet-banktransfer-steph-AJDcN6app",
        "flwRef": "URF_1Qw8TF2ZN1KkIdsqyHYI",
        "businessId": 5,
        "enabled": true,
        "accountName": "Forrest Green",
        "email": "test@klasha.com",
        "createdAt": "2023-07-04 17:02:59",
        "updatedAt": "2023-07-04 17:02:59"
    }
]
```

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

### Initiate Refund

Source: https://developers.klasha.com/accepting-payments/payments-api

Initiates a refund for a given transaction. Requires an x-auth-token in the header and can accept an encrypted or plain request body.

```APIDOC
## POST /nucleus/refund/initiate/v3

### Description
Initiates a refund for a transaction.

### Method
POST

### Endpoint
{{env_url}}/nucleus/refund/initiate/v3

### Headers
- **Content-Type** (string) - Required - `application/json`
- **x-auth-token** (string) - Required - Your merchant public key

### Request Body (plain)
- **txRef** (string) - Required - Transaction reference
- **refundType** (string) - Required - `partial` or `full`
- **amount** (integer) - Required - Refund amount

### Request Example
```json
{
    "txRef": "txRef",
    "amount": 500,
    "refundType": "partial"
}
```

### Response
#### Success Response (200)
- **message** (string) - Success message
- **error** (null) - Error object (null on success)
- **data** (object) - Refund details
  - **txRef** (string) - Transaction reference
  - **refundTnxId** (integer) - Refund transaction ID
  - **businessId** (integer) - Business ID
  - **refundedAmount** (integer) - Amount refunded
  - **status** (string) - Refund status

#### Response Example (Success)
```json
{
    "message": "success",
    "error": null,
    "data": {
        "txRef": "txRef",
        "refundTnxId": 12222,
        "businessId": 133,
        "refundedAmount": 500,
        "status": "pending"
    }
}
```

#### Error Response (400)
- **message** (string) - Error message
- **error** (string) - Error type (e.g., "Bad Request")
- **data** (null)

#### Response Example (Error)
```json
{
    "message": "Given final block not properly padded. Such issues can arise if a bad key is used during decryption.",
    "error": "Bad Request",
    "data": null
}
```
```

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

### Get Wallet Balance

Source: https://developers.klasha.com/transfers/payout

Retrieve the current wallet balance by making a GET request to the specified API endpoint. Requires authentication headers.

```HTTP
GET {{env_url}}/nucleus/business/api/wallets

**Headers**
Name
Value
Content-Type
`application/json`
Authorization
`Bearer <token>`
x-auth-token
`<public key>`
```

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

### Get Transaction Status (GET)

Source: https://developers.klasha.com/bank-account-collection/business-identification-service

Retrieves the status of a transaction using a client reference or narration. Requires the `Authorization` header with a Bearer token.

```HTTP
GET {{env_url}}/nucleus/foreign-funding/transactions/{{reference}}

Headers:
Key
Value
Authorization
Bearer <token here>
```

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

### Get ZAR Bank Lists

Source: https://developers.klasha.com/transfers/payout/zar-payout-new-encryption

Fetches a list of South African banks supported for ZAR payouts. Requires a GET request to the specified endpoint.

```HTTP
GET {{env_url}}/wallet/merchant/bank/transfer/request/banks/ZAR
```

```JSON
{
    "message": "success",
    "error": null,
    "data": [
        {
            "id": 420.0,
            "code": "FNB",
            "name": "First National Bank"
        },
        {
            "id": 421.0,
            "code": "NedBank",
            "name": "Nedbank Limited"
        },
        {
            "id": 1798.0,
            "code": "ABSA",
            "name": "ABSA"
        }
    ]
}
```

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

### POST /pay/aggregators/{{gateway}}/banktransfer/v3

Source: https://developers.klasha.com/accepting-payments/payments-api

Initiates a bank transfer payment through a specified gateway. Requires an x-auth-token in the header and provides request body examples for NGN, ZAR, and GHS currencies.

```APIDOC
## POST /pay/aggregators/{{gateway}}/banktransfer/v3

### Description
Initiates a bank transfer payment through a specified gateway. Requires an x-auth-token in the header and provides request body examples for NGN, ZAR, and GHS currencies.

### Method
POST

### Endpoint
`{{env_url}}/pay/aggregators/{{gateway}}/banktransfer/v3`

### Parameters
#### Path Parameters
- **gateway** (string) - Required - The payment gateway (e.g., NGN, ZAR, GHS).

#### Headers
- **Content-Type** (string) - `application/json`
- **x-auth-token** (string) - Required - Your merchant public key.

#### Request Body (plain)
- **tx_ref** (string) - Required - Transaction reference ID.
- **amount** (string) - Required - The payment amount.
- **email** (string) - Required - Customer's email address.
- **phone_number** (string) - Required - Customer's phone number.
- **currency** (string) - Required - The currency of the transaction (e.g., NGN, ZAR, GHS).
- **narration** (string) - Optional - A description for the transaction.
- **rate** (number) - Optional - The exchange rate.
- **paymentType** (string) - Optional - The payment type (e.g., 'woo').
- **productType** (string) - Optional - The product type (e.g., 'COLLECTION').
- **sourceCurrency** (string) - Optional - The source currency.
- **sourceAmount** (number) - Optional - The source amount.
- **fullname** (string) - Optional - The customer's full name.
- **redirect_url** (string) - Optional - URL to redirect after payment (for ZAR and GHS).

### Request Example (NGN)
```json
{
   "tx_ref": "MC-15856767458ffdgddfefhqweert",
   "amount": "500",
   "email": "email@gmail.com",
   "phone_number": "054709929220",
   "currency": "NGN",
   "narration": "A payment",
   "rate": 1.0,
   "paymentType": "woo",
   "productType": "COLLECTION",
   "sourceCurrency": "NGN",
   "sourceAmount": 500,
   "fullname": "Test"
}
```

### Request Example (ZAR)
```json
{
   "tx_ref": "test-15856767458ffdgddfefhqweert",
   "amount": "500",
   "email": "email@gmail.com",
   "phone_number": "054709929220",
   "currency": "ZAR",
   "narration": "A payment",
   "rate": 1.0,
   "redirect_url": "merchant_url",
   "paymentType": "woo",
   "productType": "COLLECTION",
   "sourceCurrency": "ZAR",
   "sourceAmount": 500,
   "fullname": "Test"
}
```

### Request Example (GHS)
```json
{
   "tx_ref": "test-15856767458ffdgddfefhqweerf",
   "amount": "500",
   "email": "email@gmail.com",
   "phone_number": "054709929220",
   "currency": "GHS",
   "narration": "A payment",
   "rate": 1.0,
   "redirect_url": "merchant_url",
   "paymentType": "woo",
   "productType": "COLLECTION",
   "sourceCurrency": "GHS",
   "sourceAmount": 500,
   "fullname": "Test"
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the status of the operation.
- **error** (object|null) - Contains error details if any.
- **data** (object) - Contains transaction details.
  - **tx_ref** (string) - Transaction reference ID.
  - **message** (string) - Status message for the transaction.
  - **status** (string) - Overall status of the transaction.
  - **meta** (object) - Metadata related to the transaction.
    - **authorization** (object) - Authorization details.
      - **mode** (string) - The authorization mode (e.g., 'banktransfer', 'redirect').
      - **transfer_note** (string) - Note for bank transfer payments.
      - **transfer_amount** (number) - The amount to be transferred.
      - **transfer_bank** (string) - The bank for transfer.
      - **account_expiration** (string) - Account expiration time.
      - **transfer_account** (string) - The account number for transfer.
      - **redirect** (string) - Redirect URL for certain payment types.
      - **validate_instructions** (string) - Instructions for validation.

### Response Example (NGN)
```json
{
    "message": "success",
    "error": null,
    "data": {
        "tx_ref": "MC-15856767458ffdgddfefhqweert",
        "meta": {
            "authorization": {
                "mode": "banktransfer",
                "transfer_note": "Please make a bank transfer to Klasha - Collection",
                "transfer_amount": 500.0,
                "transfer_bank": "WEMA BANK",
                "account_expiration": "2024-05-23T13:55:13.105",
                "transfer_account": "8574551243"
            }
        },
        "message": "Charge initiated",
        "status": "success"
    }
}
```

### Response Example (ZAR)
```json
{
    "status": "success",
    "message": "Charge initiated",
    "data": {
        "tx_ref": "test_xfer_29071707",
        "message": "Transaction in progress",
        "meta": {
            "authorization": {
                "mode": "redirect",
                "redirect": "https://stagingpay.ozow.com/b1c1bb59-bf46-42ee-bc76-ccdf63e3f453/Secure",
                "validate_instructions": ""
            }
        }
    }
}
```

### Response Example (GHS)
```json
{
    "message": "success",
    "error": null,
    "data": {
        "tx_ref": "test-15856767458ffdgddfefhqweerf",
        "message": "Charge initiated",
        "meta": {
            "authorization": {
                "transfer_account": "7003000100286",
                "transfer_bank": "Affinity",
                "account_expiration": "2025-06-11 12:12:13 PM",
                "transfer_note": "Mock note",
                "transfer_amount": "500.00",
                "mode": "banktransfer"
            }
        },
        "status": "success"
    }
}
```
```

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

### Webhook Transaction Response Example

Source: https://developers.klasha.com/misc/webhook

This snippet shows a sample JSON response received when a transaction is completed via Klasha's webhook notifications. It includes details about the event, transaction status, amounts, currencies, and customer information.

```JSON
{
  "event": "charge.completed",
  "data": {
    "createdAt": "2021-11-18T15:23:16.781",
    "narration": "CARD Transaction ",
    "destinationCurrency": "NGN",
    "sourceAmount": 0.0023,
    "sourceCurrency": "USD",
    "tnxRef": "test910-on2007u047e-errrtd",
    "status": "successful",
    "destinationAmount": 1,
    "customer": {
      "id": 13,
      "name": "Steph Oj",
      "email": "stephen@klasha.com",
      "phone": null,
      "createdAt": "2021-07-20 10:28:43",
      "updatedAt": "2021-07-20 10:28:43"
    }
  }
}
```

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

### 3DES Encryption (Python)

Source: https://developers.klasha.com/accepting-payments/payments-api

Encrypts data using the 3DES algorithm in CBC mode with PKCS5 padding. Requires the `pyDes` library. The function takes the data string and a key string, encrypts the data, and returns the Base64 encoded result. Ensure `pyDes` is installed via `pip install pyDes`.

```Python
#Ensure you have the pyDes library installed (pip install pyDes)

from pyDes import triple_des, PAD_PKCS5, CBC
import base64

def encrypt_3des(data, key):
    des = triple_des(key, CBC, pad=None, padmode=PAD_PKCS5)

    encrypted_data = des.encrypt(data)
   
    return base64.b64encode(encrypted_data).decode()

```