# Welcome!

Welcome to Klasha Documentation

### Want to jump right in?

Feeling like an eager beaver? Learn the fastest way to integrate Klasha into your platforms (web/mobile) and start receiving payments seamlessly.

{% content-ref url="/pages/HgjXUrTZdgRWvBg7Sxbv" %}
[Getting Started](/integrating-klasha/getting-started)
{% endcontent-ref %}

### Want to meet other developers integrating Klasha?

Join our Slack developers' community to discuss your Klasha use case with us, get responses to your questions quickly, and meet other developers integrating with Klasha.

{% embed url="<https://join.slack.com/t/klashadev/shared_invite/zt-xnnmdpo0-5Dx6gNuj9b9oiQIuKvqYgw>" %}
Klasha Slack Community
{% endembed %}

### Want to dive deeper?

Explore our services to get an idea of everything possible with Klasha.

{% content-ref url="/pages/y753SE7t2EW1iYldksd6" %}
[Accepting Payments](/accepting-payments/test-payments)
{% endcontent-ref %}


# Getting Started

### 1. Create a Klasha account

To create a free Klasha account, simply visit <https://dashboard.klasha.com/signup>.&#x20;

If you're conducting tests, you can sign up on our DEV environment at [https://dev.dashboard.klasha.com/signup.](https://www.dev.dashboard.klasha.com/signup.)

{% embed url="<https://dashboard.klasha.com/signup>" %}
Klasha Dashboard
{% endembed %}

### 2. Integrate Klasha&#x20;

There are various ways you can integrate Klasha into your platform (web/mobile) to start accepting payments seamlessly.&#x20;

#### Klasha inline&#x20;

The Klasha inline JavaScript method is an easy way to start accepting payments on your web applications.

{% content-ref url="/pages/EQObK7rmhv3GPkAPqNpG" %}
[Klasha Inline](/accepting-payments/klasha-inline)
{% endcontent-ref %}

#### Web SDKs&#x20;

We offer a variety of SDKs to integrate Klasha into your web application, such as Angular, React, Vue 2, and Vue 3.&#x20;

{% content-ref url="/pages/YycQyCAeHYGLXRJLbbf2" %}
[Web SDKs](/plugins-and-sdks/web-sdks)
{% endcontent-ref %}

#### Mobile SDKs&#x20;

We also offer a variety of SDKs to integrate Klasha into your mobile application, such as iOS, Android, Flutter, Ionic, and React Native.&#x20;

{% content-ref url="/pages/OekQSyDnvh4UMD9W85nX" %}
[Mobile SDKs](/plugins-and-sdks/mobile-sdks)
{% endcontent-ref %}

#### Integrate without code&#x20;

Through payment links on your dashboard, Klasha makes it possible to receive payments for products or services directly from your customers with no need for programming or integration. Check out our [Payment Links](broken://pages/f7YvofmomgVAYLSqGf8Q) section for more information and integration guides.


# Prerequisites

Before integrating Klasha, here are a few things you'll need and some information you need to know:

1. **Klasha account.** Create a free Klasha account by visiting <https://dashboard.klasha.com/signup>.

{% embed url="<https://dashboard.klasha.com/signup>" %}
Klasha Dashboard
{% endembed %}

2. **Join our Slack community.** Send us a message on our Slack developers' community channel to discuss your use case with us and get advice on the best integration approach.

{% embed url="<https://join.slack.com/t/klashadev/shared_invite/zt-xnnmdpo0-5Dx6gNuj9b9oiQIuKvqYgw>" %}
Slack
{% endembed %}

## Payment methods we support in each country

<table data-full-width="false"><thead><tr><th width="246.5">  Country</th><th>Payment methods</th></tr></thead><tbody><tr><td>Nigeria (NGN)</td><td>Bank transfer<br>USSD<br>Card<br>Klasha app wallet<br>Klasha business wallet</td></tr><tr><td>South Africa (ZAR)</td><td>Card</td></tr><tr><td>Kenya (KES)</td><td>MPesa<br>Card</td></tr><tr><td>USA (USD)</td><td>Card</td></tr><tr><td>Uganda (UGX)</td><td>Card<br>Mobile money</td></tr><tr><td>Tanzania (TZS)</td><td>Card</td></tr></tbody></table>


# Integration Checklist

This highlights the integration process of Klasha APIs with businesses.

### Process Initialization

* [x] A business entity must have a primary bank account and have its business approved before proceeding further.
* [x] KYC to be completed by the business entity.
* [x] Contract process to be completed by Klasha and the business entity.

### API Integration

* [x] Create a test account on our [sandbox](https://www.dev.dashboard.klasha.com/auth/signup) environment for development and test purposes.
* [x] Inform the Klasha technical support team for approval of the test account.
* [x] Login to your dashboard and retrieve your mechant keys (as shown below)

> Klasha Dashboard → Settings → Generate API Keys

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">

* [x] Proceed with the [apis](https://developers.klasha.com/accepting-payments/payments-api) integration.

### Process Completion

* [x] The business entity informs Klasha the completion status of the api integration.
* [x] Both Klasha and the business entity finalize on other internal agreements if any.
* [x] The business is migrated to a staging or production environment as the case may be and Klasha shares the production api base url with the business entity.
* [x] To conduct a successful integration test, it's crucial to whitelist the IP addresses of your servers making the API calls [here](https://www.dashboard.klasha.com/settings/ip-white-list).
* [x] Final tests of the integrated APIs are conducted end to end in the staging or production environment.
* [x] Go live.


# Wrap Up

Congratulations on integrating the Klasha payment gateway into your platform (web/mobile). You can visit our webhook section (link below) for more information on notifications.

{% content-ref url="/pages/9VPAvrFXWhUcSuJJXBdq" %}
[Webhook](/misc/webhook)
{% endcontent-ref %}


# Introduction

Klasha enables international businesses to sell seamlessly in Africa and accept payments online in different local African currencies.

### Payment collection

Klasha offers a number of payment collection options for business owners:

* **Card payments** - Customers can pay using their debit/credit cards.
* **Bank transfer** (Nigeria) - Customers from Nigeria can pay using the bank transfer payment option.
* **M-Pesa** (Kenya) - Customers from Kenya can make payments seamlessly using M-Pesa.
* **Mobile money** - We offer various mobile money options which customers from Uganda can use.
* **Klasha wallet** - Your customers with a Klasha account can pay from their wallets with ease.
* **USSD** (Nigeria) - Customers from Nigeria can pay using the USSD option by dialing their respective USSD bank codes.

#### Klasha accepts the following currencies (updated regularly):

* NGN
* UGX
* KES
* ZAR
* USD


# Authentication

All our endpoints are secured and requests must be authenticated by passing your merchant public key or Bearer token in the request header.

## Api Key (Public key)

After your account has been approved, you can find your public key on the dashboard (screenshot below). Ensure to include this in all request headers as value for  `x-auth-token`  where it's required.

> Dashboard → Settings → Generate API Keys  → Merchant public key&#x20;

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">

## Bearer Token

The token generated here should be used as a value of the `Authorization` header (Bearer token) for api requests where it is required.

> <mark style="color:yellow;">**POST**</mark> <mark style="color:$primary;">-</mark> <mark style="color:$primary;"></mark><mark style="color:$primary;">`{{env_url}}/auth/account/v2/login`</mark>

#### Request body

| Name                                       | Type   | Description        |
| ------------------------------------------ | ------ | ------------------ |
| username<mark style="color:red;">\*</mark> | String | Your account email |
| password<mark style="color:red;">\*</mark> | String | account password   |

#### Response

{% tabs %}
{% tab title="200" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30"
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "message": "Invalid email or password.",
    "error": "wrong login details",
    "data": null
}
```

{% endtab %}
{% endtabs %}


# Parameters

This page shows the list of template variables used across the documentation and their values.

## List of api variables&#x20;

<table><thead><tr><th width="117.39453125">Name</th><th width="84.421875">Type</th><th>Descriptiom</th><th width="228.56640625">Value</th></tr></thead><tbody><tr><td><em><mark style="color:red;">env_url</mark></em></td><td>String</td><td>Base url for the current environment</td><td>sandbox: <a href="https://dev.kcookery.com">https://dev.kcookery.com</a><br>live: <a href="https://gate.klasapps.com/pay">https://gate.klasapps.com</a></td></tr><tr><td><em><mark style="color:red;">gateway</mark></em></td><td>String</td><td>Supported currencies for card payment as listed <a href="https://developers.klasha.com/integrating-klasha/prerequisites#payment-methods-we-support-in-each-country">here</a> (e.g. NGN, ZAR)</td><td>e.g. NGN, ZAR, USD e.t.c</td></tr><tr><td><em><mark style="color:red;">tx_ref</mark></em></td><td>String</td><td>The unique reference sent during initial payment call, also contained in the successful responses. (should be UUID format or a guaranteed unique value)</td><td>e.g b0c3f173-0954-4124-8480-89352e034974</td></tr></tbody></table>


# Errors

Errors can be seen in the following formats with the 400 HTTP status code:

### Public key error

```json
{
    "status": "error",
    "message": "public key is required",
    "data": null
}
```

### Authorisation error

```json
{
    "status": "error",
    "message": "Authorization required",
    "data": null
}
```

### Bad request error

```json
{
    "status": "Bad Request",
    "message": "Bad Request"
}
```


# Countries & Payment Methods

{% tabs %}
{% tab title="Nigeria" %}

* Card payments
* Bank transfer
* USSD
  {% endtab %}

{% tab title="Kenya" %}

* M-Pesa
* Card payments
* Mobile money
* Wire/Bank transfer
  {% endtab %}

{% tab title="Zambia" %}

* Card payments
* Mobile money
* Wire/Bank transfer
  {% endtab %}

{% tab title="Uganda" %}

* Card payments
* Mobile money
* Wire/Bank transfer
  {% endtab %}

{% tab title="South Africa" %}

* Card payments
* Wire/Bank transfer
  {% endtab %}
  {% endtabs %}

{% tabs %}
{% tab title="Ghana" %}

* Bank transfer
  {% endtab %}

{% tab title="Senegal" %}

* Mobile money
  {% endtab %}

{% tab title="Republic of Congo " %}

* Mobile money
  {% endtab %}

{% tab title="China" %}

* Bank Account (B2B)
* Bank Account (B2C)
* UnionPay
* Alipay
  {% endtab %}
  {% endtabs %}

{% tabs %}
{% tab title="Tanzania" %}

* Card payments
* Mobile money
* Wire/Bank transfer
  {% endtab %}

{% tab title="Sierra Leone" %}

* Mobile money
* Wire/Bank transfer
  {% endtab %}

{% tab title="Côte d'Ivoire (Ivory Coast)" %}

* Mobile money
  {% endtab %}
  {% endtabs %}

{% tabs %}
{% tab title="Democratic Republic of Congo (DRC)" %}

* Mobile money
  {% endtab %}

{% tab title="Rwanda" %}

* Mobile money
  {% endtab %}

{% tab title="Gabon" %}

* Mobile money
  {% endtab %}
  {% endtabs %}

#### WALLET

| Currency | Funding Method                                           |
| -------- | -------------------------------------------------------- |
| NGN      | <p>Virtual account<br>Swap</p>                           |
| KES      | <p>Klasha Bank Account<br>Klasha Pay Methods<br>Swap</p> |
| ZAR      | <p>Klasha Bank Account<br>Klasha Pay Methods<br>Swap</p> |
| USD      | <p>Own IBAN<br>Klasha Pay Methods<br>Swap<br>OTC</p>     |
| ZMW      | <p>Klasha Bank Account<br>Klasha Pay Methods<br>Swap</p> |
| GHS      | Virtual Account                                          |


# Test Payments

You can use the following test cards details to test different payment channels.

## Cards

{% hint style="info" %}
Card expiry date

You can use any date in the future for the expiry date of each card.
{% endhint %}

#### Successful Cards

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td><p><strong>Master Card</strong></p><p>PIN authentication</p></td><td><strong>5531 8866 5214 2950</strong></td><td>Expiry: 09/32<br>CVC: 564<br>PIN: 3310<br>OTP: 12345</td><td></td></tr><tr><td><p><strong>Master Card</strong></p><p>3DS authentication</p></td><td><strong>5438 8980 1456 0229</strong></td><td>Expiry: 10/31<br>CVV: 564<br>PIN: 3310<br>OTP: 12345</td><td></td></tr><tr><td><p>V<strong>isa Card</strong></p><p>3DS authentication</p></td><td><strong>4187 4274 1556 4246</strong></td><td>Expiry: 09/32<br>CVV: 828<br>PIN: 3310<br>OTP: 12345</td><td></td></tr><tr><td><p><strong>Verve</strong> <strong>Card</strong></p><p>Noauth</p></td><td><strong>5061 4601 6697 6054 667</strong></td><td>Expiry: 10/29<br>CVV: 564<br>PIN: 3310</td><td></td></tr><tr><td><p><strong>Visa</strong> <strong>Card</strong></p><p>Address Verification (AVS)</p></td><td><strong>4556 0527 0417 2643</strong></td><td>Expiry: 09/32<br>CVV: 899<br>PIN: 3310<br>OTP: 12345</td><td></td></tr><tr><td>Pre-authentication Test Card</td><td><strong>5377 2836 4507 7450</strong></td><td>Expiry: 09/31<br>CVV: 789<br>PIN: 3310</td><td></td></tr></tbody></table>

#### Mobile Money Test Phone numbers and network

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td>ZMW</td><td>phone: 260973456789<br>network: airtel</td></tr><tr><td>UGX</td><td>phone: 256753456789<br>network: airtel</td></tr><tr><td>SLL</td><td>phone: 23276123456<br>network: orange</td></tr><tr><td>XOF</td><td>phone: 221763456789<br>network: mtn</td></tr><tr><td>RWF</td><td>phone: 250733456789<br>network: airtel</td></tr><tr><td>MWK</td><td>phone: 265993456789<br>network: airtel</td></tr><tr><td>KES</td><td>phone: 254703456789<br>network: mpesa</td></tr><tr><td>CDF</td><td>phone: 243812312332<br>network: vodacom</td></tr><tr><td>CMR</td><td>phone: 237653456789<br>network: mtn</td></tr><tr><td>GHS</td><td>phone: 23354709929220<br>network: airtel</td></tr><tr><td>TZS</td><td>phone: 255712345678<br>network: tigo</td></tr></tbody></table>

#### Failed Cards

<table data-view="cards"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Master Card</strong><br>Declined (Incorrect PIN)</td><td><strong>5399 8346 9789 4723</strong></td><td>Expiry: 09/31<br>CVV: 883<br>PIN: 3310<br>OTP: 123456</td></tr><tr><td><strong>Master Card</strong><br>Card Fraudulent</td><td><strong>5590 1317 4329 4314</strong></td><td>Expiry: 11/32<br>CVV: 887<br>PIN: 3310<br>OTP: 123456</td></tr><tr><td><strong>Master Card</strong><br>Card Declined (Address Verification)</td><td><strong>5143 0105 2233 9965</strong></td><td>Expiry: 08/32<br>CVV: 276<br>PIN: 3310<br>OTP: 3310</td></tr></tbody></table>

#### Errors

<table data-view="cards"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td>Do Not Honour</td><td><strong>5143 0105 2233 9965</strong></td><td>Expiry: 08/31<br>CVV: 276<br>PIN: 3310</td></tr><tr><td>Insufficient funds</td><td><strong>5258 5859 2266 6506</strong></td><td>Expiry: 09/31<br>CVV: 883<br>PIN: 3310<br>OTP: 123456</td></tr></tbody></table>


# Payments API

Summary

This documentation page contains everything you need to know about integrating to Klasha’s Payment Gateway. Once integration is done, you can begin to process payments from anywhere in the world in seconds.

Whilst you start your integration, please remember to reach out to our Compliance team to go through the KYB process and get your business verified. This is a mandatory process before you can start using our production platform.

{% hint style="warning" %}
If you are going to be implementing the direct charge API, you would require additional verification as this is only available to businesses that are PCI-DSS certified.
{% endhint %}

## Payment collection

As a business owner, here is a way we make it possible for you to collect payments from customers all over the world:

* [Card Payments](#card-payments)
* [Bank transfer](#bank-transfer)
* [M-Pesa](#m-pesa)
* [Mobile money](/accepting-payments/payments-api/mobile-money)
* [USSD](/accepting-payments/payments-api/ussd)

In all the following APIs, you can simply substitute the desired currency to the path variable <mark style="color:red;">{{gateway}}</mark>.

### Before you begin

{% hint style="info" %}
Get your API keys

> * Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))
> * Klasha Dashboard, Generate API Keys page
>
> <img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">

{% endhint %}

### Encryption algorithm

We are treating payment data, therefore all requests from merchant to our APIs must be encrypted in line with the industry standard. We make use of the standard 3DES technology with Padding for data encryption.

Below are code snippets for the 3DES encryption in different languages:

{% tabs %}
{% tab title="Java" %}
{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```java
public static String Encrypt3DES(String messageToEncrypt, byte[] secret) throws NoSuchPaddingException, NoSuchAlgorithmException,
            InvalidAlgorithmParameterException, InvalidKeyException, IllegalBlockSizeException, BadPaddingException {
    SecretKeySpec secretKeySpec = new SecretKeySpec(secret, "TripleDES");
    byte[] iv = Arrays.copyOfRange(secret, 0, 8);
    IvParameterSpec ivSpec = new IvParameterSpec(iv);

    Cipher encryptCipher =Cipher.getInstance("TripleDES/CBC/PKCS5Padding");
    encryptCipher.init(Cipher.ENCRYPT_MODE, secretKeySpec, ivSpec);

    byte[] secretMessagesBytes=      messageToEncrypt.getBytes(StandardCharsets.UTF_8);
    byte[] encryptedMessageBytes = encryptCipher.doFinal(secretMessagesBytes);

    return Base64.getEncoder().encodeToString(encryptedMessageBytes);
}
```

{% endcode %}
{% endtab %}

{% tab title="C#" %}
{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```csharp
public static string Encrypt3DES(string message, string secret)
{
    byte[] secretByte = Encoding.UTF8.GetBytes(secret.Trim());

    using (TripleDESCryptoServiceProvider tripleDES = new TripleDESCryptoServiceProvider())
    {
        tripleDES.Key = secretByte;
        byte[] iv = new byte[8];
        Buffer.BlockCopy(secretByte, 0, iv, 0, 8);
        tripleDES.IV = iv;
        tripleDES.Mode = CipherMode.CBC;
        tripleDES.Padding = PaddingMode.PKCS7;

        ICryptoTransform encryptor = tripleDES.CreateEncryptor(tripleDES.Key, tripleDES.IV);

        byte[] messageBytes = Encoding.UTF8.GetBytes(message);
        byte[] encryptedMessageBytes = encryptor.TransformFinalBlock(messageBytes, 0, messageBytes.Length);

        return Convert.ToBase64String(encryptedMessageBytes);
    }
}
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```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()

# Example usgae:
if __name__ == "__main__":
    # key (24 bytes)
    key = b'Use your 24 bytes key here'
    data = "Hello, Klasha!"
    encrypted_text = encrypt_3des(data, key)
    print("Encrypted text:", encrypted_text)
```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}

```
function encrypt3DES($messageToEncrypt, $secret) {
    $iv = substr($secret, 0, 8); // Get the IV (first 8 bytes of the secret key)
    $cipher = "des-ede3-cbc"; // 3DES encryption with CBC mode
    $options = OPENSSL_RAW_DATA;

    // Encrypt the message
    $encryptedMessageBytes = openssl_encrypt($messageToEncrypt, $cipher, $secret, $options, $iv);

    return base64_encode($encryptedMessageBytes);
}
```

{% endtab %}

{% tab title="JavaScript" %}
{% code fullWidth="false" %}

```javascript

// NOTE: You need crypto-js.min.js to use CryptoJS

function encrypt3DES(messageToEncrypt, secret) {
    try {
        if (secret.length < 24) {
            console.error("Secret key must be at least 24 characters long.");
            return;
        }

        // Use the first 24 characters of the secret key for 3DES
        const key = CryptoJS.enc.Utf8.parse(secret.substring(0, 24));

        // Use the first 8 characters of the secret key for the IV
        const iv = CryptoJS.enc.Utf8.parse(secret.substring(0, 8));

        // Encrypt the message
        const encrypted = CryptoJS.TripleDES.encrypt(messageToEncrypt, key, {
            iv: iv,
            mode: CryptoJS.mode.CBC,
            padding: CryptoJS.pad.Pkcs7,
        });

        // Return the Base64-encoded encrypted message
        return encrypted.toString();
    } catch (error) {
        console.error(error);
    }
}

```

{% endcode %}
{% endtab %}

{% tab title="Node.js" %}

```javascript

const crypto = require('crypto');

/**
 * Encrypt a message using 3DES with CBC mode and PKCS5 padding.
 * @param {string} messageToEncrypt - The plaintext message to encrypt.
 * @param {Buffer} secret - The 24-byte secret key.
 * @returns {string} The Base64 encoded encrypted message.
 */
function encrypt3DES(messageToEncrypt, secret) {
    if (secret.length !== 24) {
        throw new Error('Secret must be exactly 24 bytes.');
    }
    // Derive the IV from the first 8 bytes of the secret key
    const iv = secret.slice(0, 8);  // First 8 bytes are used as IV

    // Create cipher
    const cipher = crypto.createCipheriv('des-ede3-cbc', secret, iv);

    // Encrypt the message
    let encrypted = cipher.update(messageToEncrypt, 'utf8', 'base64');
    encrypted += cipher.final('base64');

    return encrypted;
}

// Sample Usage
function testEncrypt3DES() {
    const jsonObject = {
        id: 1,
        name: 'John Doe',
        role: 'Senior Backend Engineer',
        skills: ['Java', 'Node.js', 'AWS']
    };

    // Convert JSON object to string
    const message = JSON.stringify(jsonObject);

    // 24-byte secret key
    const secretKey = '24-byte key'; // replace with your 24-byte encryption key

    console.log('Original JSON Object:', jsonObject);
    console.log('Secret Key (Base64):', secretKey.toString('base64'));

    // Encrypt the JSON string
    const encryptedMessage = encrypt3DES(message, secretKey);
    console.log('Encrypted Message (Base64):', encryptedMessage);
}

testEncrypt3DES();

```

{% endtab %}
{% endtabs %}

## Card payments

To accept a card payment, you need to integrate with the following flow:

{% stepper %}
{% step %}
First, **initiate** the card payment
{% endstep %}

{% step %}
Then **charge** the card
{% endstep %}

{% step %}
And at the end **validate** the payment (optional to provide OTP and/or PIN)
{% endstep %}
{% endstepper %}

{% hint style="info" %}
For all api calls here, you’d need to pass your **public key** as the value for  `x-auth-token` in the request header. See guide [here](https://developers.klasha.com/overview/authentication) on how to retrieve your public key.
{% endhint %}

**Parameter variables**

> see [here](https://developers.klasha.com/overview/parameters) for more explanation on the api parameters

### Initiate card payment

> <mark style="color:yellow;">**`POST`**</mark> - <mark style="color:red;">{{env\_url}}</mark>/pay/aggregators/<mark style="color:red;">{{gateway}}</mark>/card/payment/v2

**Headers**

| Name         | Value                    |
| ------------ | ------------------------ |
| Content-Type | `application/json`       |
| x-auth-token | Your merchant public key |

**Request Body (plain data to be encrypted)**

{% hint style="info" %} <sup>*must be encrypted before sending*</sup>
{% endhint %}

```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": "b4d29429-a569-4eff-a81f-d2947499614a"
}
```

**Request Body (encrypted)**

```json
{
    "message": "encrypted-body"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a",
        "data": {
           "status": "success",
            "message": "Charge authorization data required",
            "meta": {
                "authorization": {
                    "mode": "pin",
                    "fields": [
                        "pin"
                    ]
                }
            }
        }
    }
}
```

{% endtab %}

{% tab title="200" %}

```json
This is for cards that are covered by 3DS flows.
{
    "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a",
    "redirectUrl": "https://coreflutterwavestaging.com/flwmpgs/trxauth?hid=712b85a8542649e68c19b1c80d81aadc",
    "data": {
        "meta": {
            "authorization": {
                "mode": "redirect",
                "redirect": "https://coreflutterwavestaging.com/flwmpgs/trxauth?hid=712b85a8542649e68c19b1c80d81aadc"
            }
        }
    }
}
```

{% endtab %}

{% tab title="200" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a",
        "data": {
           "status": "success",
            "message": "Charge authorization data required",
            "meta": {
                "authorization": {
                    "mode": "avs_noauth",
                    "fields": [
                        "city",
                        "address",
                        "state",
                        "country",
                        "zipcode"
                    ]
                }
            }
        }
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "status": "error",
    "message": "Card number is invalid",
    "data": null,
    "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a"
}
```

{% endtab %}
{% endtabs %}

### Charge card

> <mark style="color:yellow;">**`POST`**</mark> - <mark style="color:red;">{{env\_url}}</mark>/pay/aggregators/<mark style="color:red;">{{gateway}}</mark>/charge/card/v2

**Headers**

| Name           | Value                    |
| -------------- | ------------------------ |
| Content-Type\* | `application/json`       |
| x-auth-token\* | Your merchant public key |

**Request Body (plain data to be encrypted)**

{% hint style="info" %} <sup>*must be encrypted before sending*</sup>
{% endhint %}

{% tabs %}
{% tab title="Mode pin" %}

```json
{
    "mode": "pin",
    "pin": "1111",
    "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a"
}
```

{% endtab %}

{% tab title="Mode avs\_noauth" %}

```json
{
    "mode": "avs_noauth",
    "city": "city",
    "address": "address",
    "state": "state",
    "country": "country",
    "zipcode": "zipcode",
    "tx_ref": "test910-on2007u047e-2910tytrr76"
}
```

{% endtab %}
{% endtabs %}

**Request Body (encrypted)**

```json
{
    "message": "encrypted-body"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
       "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a",
       "message": "Please enter the OTP sent to your mobile number 080****** and email te**@rave**.com",
       "status": "pending"
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "status": "error",
    "message": "Invalid Pin",
    "data": null,
    "tx_ref": "klasha-add-bank-card-odochi_test_test11"
}
```

{% endtab %}
{% endtabs %}

### Validate charge

> <mark style="color:yellow;">**`POST`**</mark> - <mark style="color:red;">{{env\_url}}</mark>/pay/aggregators/<mark style="color:red;">{{gateway}}</mark>/validate/card/v2

**Headers**

| Name         | Value                    |
| ------------ | ------------------------ |
| Content-Type | `application/json`       |
| x-auth-token | Your merchant public key |

**Request Body (plain data to be encrypted)**

{% hint style="info" %} <sup>*must be encrypted before sending*</sup>
{% endhint %}

```json
{
  "otp": "123456",
  "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a",
  "type": "card"
}
```

**Request Body (encrypted)**

```json
{
    "message": "encrypted-body"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
       "tx_ref": "b4d29429-a569-4eff-a81f-d2947499614a",
       "amount": 200.0,
       "processor_response": "successful",
       "message": "Charge validated",
       "status": "successful"
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "status": "error",
    "message": "Invalid OTP",
    "data": null,
    "tx_ref": "klasha-add-bank-card-odochi_test_test11"
}
```

{% endtab %}
{% endtabs %}

## Bank transfer

> <mark style="color:yellow;">**`POST`**</mark> - <mark style="color:red;">{{env\_url}}</mark>/pay/aggregators/<mark style="color:red;">{{gateway}}</mark>/banktransfer/v3

#### Parameter variables

{% hint style="info" %}
see [here](https://developers.klasha.com/overview/parameters) for more explanation on the api parameters
{% endhint %}

**Headers**

| Name         | Value                    |
| ------------ | ------------------------ |
| Content-Type | `application/json`       |
| x-auth-token | Your merchant public key |

**Request Body (plain)**

{% hint style="info" %} <sup>*must be encrypted before sending*</sup>
{% endhint %}

{% tabs %}
{% tab title="NGN" %}

```json
{
   "tx_ref": "67ede7fd-d8b2-4402-88e4-c3596486f3bf",
   "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"
}
```

{% endtab %}

{% tab title="ZAR" %}

```json
{
   "tx_ref": "67ede7fd-d8b2-4402-88e4-c3596486f3bf",
   "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"
}
```

{% endtab %}

{% tab title="GHS" %}

```json
{
   "tx_ref": "67ede7fd-d8b2-4402-88e4-c3596486f3bf",
   "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"
}
```

{% endtab %}
{% endtabs %}

**Request Body (encrypted)**

```json
{
    "message": "encrypted-body"
}
```

**Response**

{% tabs %}
{% tab title="200 (NGN)" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "tx_ref": "67ede7fd-d8b2-4402-88e4-c3596486f3bf",
        "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"
    }
}
```

{% endtab %}

{% tab title="200 (ZAR)" %}

```json
{
    "status": "success",
    "message": "Charge initiated",
    "data": {
        "tx_ref": "t67ede7fd-d8b2-4402-88e4-c3596486f3bf",
        "message": "Transaction in progress",
        "meta": {
            "authorization": {
                "mode": "redirect",
                "redirect": "https://stagingpay.ozow.com/b1c1bb59-bf46-42ee-bc76-ccdf63e3f453/Secure",
                "validate_instructions": ""
            }
        }
    }
}
```

{% endtab %}

{% tab title="GHS" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "tx_ref": "67ede7fd-d8b2-4402-88e4-c3596486f3bf",
        "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"
    }
}
```

{% endtab %}
{% endtabs %}

### M-Pesa

> <mark style="color:yellow;">**`POST`**</mark> - <mark style="color:red;">{{env\_url}}/</mark>pay/aggregators/<mark style="color:red;">{{gateway}}</mark>/card/payment/v2

#### Parameter variables

{% hint style="info" %}
see [here](https://developers.klasha.com/overview/parameters) for more explanation on the api parameters
{% endhint %}

**Headers**

| Name         | Value                    |
| ------------ | ------------------------ |
| Content-Type | `application/json`       |
| x-auth-token | Your merchant public key |

**Request Body (encrypted)**

```json
{
    "message": "encrypted-body"
}
```

**Request Body (plain)**

{% hint style="info" %} <sup>*must be encrypted before sending*</sup>
{% endhint %}

```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": "6b6164f9-8f90-481d-8d4f-d7774e9563aa"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "tx_ref": "6b6164f9-8f90-481d-8d4f-d7774e9563aa",
        "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"
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "tx_ref": "6b6164f9-8f90-481d-8d4f-d7774e9563aa",
    "data": null,
    "message": "Invalid phone number format",
    "status": "error"
}
```

{% endtab %}
{% endtabs %}

### Initiate a refund

> <mark style="color:yellow;">**`POST`**</mark> <mark style="color:red;">{{env\_url}}/</mark>nucleus/refund/initiate/v3

**Headers**

| Name         | Value                    |
| ------------ | ------------------------ |
| Content-Type | `application/json`       |
| x-auth-token | Your merchant public key |

**Request Body (plain)**

{% hint style="info" %} <sup>*must be encrypted before sending*</sup>
{% endhint %}

```json
{
    "txRef": "6b6164f9-8f90-481d-8d4f-d7774e9563aa",
    "amount": 500,
    "refundType": "partial"
}
```

**Request body field description**

<table><thead><tr><th width="138.6328125">Name</th><th width="155.328125">Type</th><th>Description</th></tr></thead><tbody><tr><td>txRef*</td><td>String</td><td>Transaction reference</td></tr><tr><td>refundType*</td><td>String</td><td>Type of refund (must be either <mark style="color:orange;"><strong><code>partial</code></strong></mark> or <mark style="color:orange;"><strong><code>full</code></strong></mark>)</td></tr><tr><td>amount*</td><td>Double</td><td>Amount to be refunded</td></tr></tbody></table>

**Request Body (encrypted)**

```json
{
    "message": "encrypted-body"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "txRef": "6b6164f9-8f90-481d-8d4f-d7774e9563aa",
        "refundTnxId": 12222,
        "businessId": 133,
        "refundedAmount": 500,
        "status": "pending"
    }
}
```

{% endtab %}

{% tab title="400" %}

```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
}
```

{% endtab %}
{% endtabs %}

### Get a refund status

> <mark style="color:green;">**`GET`**</mark> - [<mark style="color:red;">{{env\_url}}</mark>](/overview/parameters)<mark style="color:red;">/</mark>nucleus/refund/status/<mark style="color:red;">{{txRef}}</mark>/v2

Headers

| Name         | Value                    |
| ------------ | ------------------------ |
| Content-Type | `application/json`       |
| x-auth-token | Your merchant public key |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "message": "success",
    "error": null,
    "data": [
        {
            "refundType": "full",
            "txRef": "6b6164f9-8f90-481d-8d4f-d7774e9563aa",
            "refundTnxId": null,
            "businessId": 133,
            "refundedAmount": null,
            "status": "pending"
        }
    ]
}
```

{% endtab %}

{% tab title="400" %}

```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
}
```

{% endtab %}
{% endtabs %}

### Generate a bearer token

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### Exchange rate

> <mark style="color:yellow;">**`POST`**</mark> - [<mark style="color:red;">{{env\_url}}</mark>](/overview/parameters)/nucleus/general/exchange/

Make a POST call to the exchange rate API.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | Bearer "token"     |

**Request Body**

| Name                | Description                |
| ------------------- | -------------------------- |
| sourceCurrency      | currency users will pay in |
| amount              | amount                     |
| destinationCurrency | destination currency       |
| productType         | KLASHA\_PAY (static value) |
| businessId          | your business ID           |

<figure><img src="/files/19JMjRKQLikYPE7uvKU8" alt=""><figcaption></figcaption></figure>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "amount": 1557632.40,
        "rate": 0.000642,
        "buyingRate": 0.000676,
        "destinationCurrency": "NGN",
        "sourceCurrency": "USD",
        "cards": null
    }
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "message": "No exchange found",
    "error": "Not Found",
    "data": null
}
```

{% endtab %}
{% endtabs %}


# Mobile money

Collect payments via our mobile money api

Follow these steps to accept payment using our mobile money API:

* Initiate the Payment via API
* Customer validates OTP on their device(optional)
* Check Status via API

> You would need to pass, as header the `x-auth-token`. This can be obtained from your merchant dashboard → Settings → Generate API keys → **Merchant public key.**

### Coverage

{% hint style="info" %}
The gateway parameter on the request api should be set to anyone of the following currency below for their respective country.
{% endhint %}

<table><thead><tr><th width="207.828125">Country</th><th width="155.953125">Country Code</th><th width="112.48828125">Currency/Gateway</th><th>Network</th></tr></thead><tbody><tr><td>Democratic Republic of the Congo</td><td>COD</td><td>CDF</td><td>vodacom, airtel, orange, mpesa</td></tr><tr><td>Republic of the Congo</td><td>COG</td><td>XAF</td><td>airtel, mtn</td></tr><tr><td>Kenya</td><td>KEN</td><td>KES</td><td>mpesa</td></tr><tr><td>Uganda</td><td>UGA</td><td>UGX</td><td>airtel, mtn</td></tr><tr><td>Senegal</td><td>SEN</td><td>XOF</td><td>free, orange</td></tr><tr><td>Tanzania<mark style="color:red;">*</mark></td><td>TZS</td><td>TZS</td><td>airtel, tigo, halotel </td></tr><tr><td>Ivory Coast (Côte d'Ivoire)</td><td>CIV</td><td>XOF</td><td>mtn, orange</td></tr><tr><td>Rwanda</td><td>RWA</td><td>RWF</td><td>airtel, mtn</td></tr><tr><td>Zambia</td><td>ZMB</td><td>ZMW</td><td>mtn, zamtel</td></tr><tr><td>Sierra Leone</td><td>SLE</td><td>SLE</td><td>orange</td></tr><tr><td>Gabon</td><td>GAB</td><td>XAF</td><td>airtel</td></tr><tr><td>Ghana</td><td>GHS</td><td>GHS</td><td>airtel</td></tr><tr><td>Cameroon</td><td>CMR</td><td>XAF</td><td>mtn, orange</td></tr></tbody></table>

{% hint style="info" %} <sup>*<mark style="color:red;">\*</mark>*</sup><sup>*TZS transactions amount must not have decimals*</sup>
{% endhint %}

### Initiate the Payment

> <mark style="color:yellow;">**POST**</mark> - {{env\_url}}/pay/aggregators/{{gateway}}/mobilemoney/v3

{% hint style="info" %}
**NB**: All requests sent to this api must be encrypted. See encryption algorithm [**here**](/accepting-payments/payments-api#encryption-algorithm)
{% endhint %}

**Headers**

| Name                                           | Value                    |
| ---------------------------------------------- | ------------------------ |
| Content-Type                                   | `application/json`       |
| x-auth-token<mark style="color:red;">\*</mark> | Your merchant public key |

**Params**

{% hint style="info" %}
[See  for details on the url params](#user-content-fn-1)[^1]
{% endhint %}

**Request Body (plain version)**

> * <sup>*The payload must be encrypted before sending*</sup>
> * <sup>*Test phone numbers can be found*</sup> [<sup>*here*</sup>](https://developers.klasha.com/accepting-payments/test-payments#mobile-money-phone-numbers)

```json
{
   "fullname": "Francisca Reuben",
   "email": "fran@matrix.io",
   "phone_number": "260953456700",
   "tx_ref": "de43d7a1-569c-4348-abd8-75246e81d500", // must be UUID generated
   "network": "mtn",
   "description": "payment for airpod",
   "country": "ZMB",
   "amount": "10",
   "currency": "ZMW",
   "rate": "1",
   "paymentType": "woo", // should be left has woo
   "sourceCurrency": "ZMW",
   "sourceAmount": "10",
   "rememberMe": false,
   "productType": "COLLECTION"
}
```

**Request Body (encrypted)**

```json
{
    "message": "encrypted-body"
}
```

**Response**

The customer will need to enter the OTP sent to their provided phone number when the payment is initiated and the message in the response message is "Please enter otp".

{% tabs %}
{% tab title="200 (pending otp)" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "message": "success",
        "error": null,
        "data": {
            "amount": "10",
            "charged_amount": "10",
            "currency": "ZMW",
            "message": "Please enter otp",
            "status": "pending",
            "customer": {
                "country": "ZMB",
                "name": "Francisca Reuben",
                "phone_number": "260763456789",
                "operator": "mtn"
            }
        }
    }
}
```

{% endtab %}

{% tab title="200 (pending)" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "message": "success",
        "error": null,
        "data": {
            "amount": "10",
            "charged_amount": "10",
            "currency": "ZMW",
            "message": "Transaction in progress",
            "status": "pending",
            "customer": {
                "country": "ZMB",
                "name": "Francisca Reuben",
                "phone_number": "260763456789",
                "operator": "mtn"
            }
        }
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "message": "failed",
    "error": "Bad Request",
    "data": {
        "status": "error",
        "error": "failed",
        "message": "Duplicate reference provided"
    }
}
```

{% endtab %}
{% endtabs %}

### Check Status

Use the Transaction status API [here](/misc/transaction-status) to check the status of the transaction by passing your transaction reference as `tnx_ref` in the request body.

[^1]:


# Pay with Capitec Pay

Follow these steps to accept payment using Capitec Pay:

* Initiate
* Validate
* Check Status

### Coverage

The gateway parameter should be set to anyone of the following currencies.

<table><thead><tr><th width="231">Country</th><th>Country Code</th><th>Currency</th><th>gateway</th></tr></thead><tbody><tr><td>South Africa</td><td>ZAF</td><td>ZAR</td><td>ZAR</td></tr></tbody></table>

### Initiate

<mark style="color:green;">`POST`</mark> <mark style="color:red;">{{env\_url}}/</mark>pay/aggregators/<mark style="color:$danger;">{{gateway}}</mark>/bank-wallet-transfer

You would need to pass, as header the `x-auth-token`. This can be obtained from your merchant dashboard → Settings → Generate API keys → **Merchant public key.**

**Headers**

| Name         | Value                    |
| ------------ | ------------------------ |
| Content-Type | `application/json`       |
| x-auth-token | Your merchant public key |

**Request Body (encrypted)**

[**Encryption algorithm here**](/accepting-payments/payments-api#encryption-algorithm)

```json
{
    "message": "encrypted-body"
}
```

**Request Body (plain)**

```json
{
    "fullname": "Francisca Reuben",
    "email": "fran@matrix.io",
    "phone_number": "260953456700",
    "account_number": "260953456700",
    "tx_ref": "de43d7a1-569c-4348-abd8-75246e81d5009",
    "type": "capitec",
    "description": "payment for airpod",
    "country": "ZAF",
    "amount": "10",
    "currency": "ZAR",
    "rate": 1,
    "paymentType": "woo",
    "sourceCurrency": "ZAR",
    "sourceAmount": 10,
    "rememberMe": false,
    "productType": "COLLECTION",
    "redirect_url": "https://validuri.com"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "data": {
        "tx_ref": "de43d7a1-569c-4348-abd8-75246e81d5009",
        "payment_type": "BANK_WALLET_TRANSFER",
        "chargeResponseCode": "pending",
        "charged_amount": 10.0,
        "narration": "Capitec_PAYMENT",
        "currency": "ZAR",
        "message": "Transaction in Progress",
        "status": "pending",
        "customer": {
            "id": 3360279.0,
            "phone_number": "260953456700",
            "name": "Klasha South Africa",
            "email": "ravesb_ccc7ec498d7bb30d9bc2_Jessica@klasha.com",
            "created_at": "2025-09-03T11:12:16.000Z"
        }
    },
    "error": null,
    "status": "success"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "status": "failed",
    "error": "failed",
    "message": "Transaction Reference already exist. Try again in 2 minutes time to use the same ref for a new transaction",
    "tx_ref": "de43d7a1-569c-4348-abd8-75246e81d5009"
}
```

{% endtab %}
{% endtabs %}

### Validate

The customer will need to complete the transaction from the Capitec Pay App.

### Check Status

Click the "Transaction status" link below to check the status of the transaction by passing your tnx\_ref as request body.

[Transaction status](/misc/transaction-status)


# USSD

The Klasha USSD Payment API allows businesses to accept payments via USSD codes, a method especially effective in regions with limited access to the internet.

Follow these steps to accept payment using our USSD API:

* Initiate the USSD Payment
* Steps to Complete Payment
* Check Status

### Coverage

The gateway parameter should be set to anyone of the following currencies below.

<table><thead><tr><th width="231">Country</th><th>Country Code</th><th>Currency</th></tr></thead><tbody><tr><td>Nigeria</td><td>NG</td><td>NGN</td></tr></tbody></table>

### Bank Codes

| **Code** | Bank **Name**       |
| -------- | ------------------- |
| 737      | GTB                 |
| 894      | First Bank          |
| 966      | Zenith Bank         |
| 919      | UBA                 |
| 909      | Stanbic Bank        |
| 5037     | VFD                 |
| 7797     | Rubies (Highstreet) |
| 901      | Access Bank         |
| 822      | Sterling Bank       |
| 7799     | Unity Bank          |
| 7111     | KeyStone Bank       |
| 326      | EcoBank             |
| 945      | Wema Bank           |
| 770      | Fidelity Bank       |
| 329      | FCMB                |
| 745      | Heritage Bank       |
| 826      | Union Bank          |

### Initiate the USSD Payment

> <mark style="color:yellow;">**POST**</mark> - <mark style="color:$primary;">{{env\_url}}/pay/aggregators/{{gateway}}/ussd</mark>

You would need to pass, as header the `x-auth-token`. This can be obtained from your merchant dashboard → Settings → Generate API keys → **Merchant public key.**

**Headers**

| Name         | Value                    |
| ------------ | ------------------------ |
| Content-Type | `application/json`       |
| x-auth-token | Your merchant public key |

**Request Body (encrypted)**

**NB**: Request on this api must be encrypted. See encryption algorithm [**here**](/accepting-payments/payments-api#encryption-algorithm)

```json
{
    "message": "encrypted-body"
}
```

**Request Body (plain version)**

> <sup>*\*must be encrypted before sending*</sup>

```json
{
    "tx_ref": "91a4f37c-61f5-48a6-bef6-ec2ef118615b",
    "account_bank": "329",
    "amount": "3448.28",
    "currency": "NGN",
    "email": "test@dev.com",
    "phone_number": "234888888888",
    "sourceCurrency": "NGN",
    "firstName": "tester",
    "lastName": "one",
    "fullname": "tester one"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "message": "success"
    "data": {
        "payment_type": "USSD",
        "tx_ref": "91a4f37c-61f5-48a6-bef6-ec2ef118615b",
        "chargeResponseCode": "pending",
        "charged_amount": "3448.28",
        "narration": "USSD Payment",
        "status": "pending",
        "ussdString": "*329*000*3668#"
    },
    "status": "success"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "message": "failed",
    "error": "Bad Request",
    "data": "Check your request and try again"
}
```

{% endtab %}
{% endtabs %}

### Steps to Complete Payment

{% stepper %}
{% step %}
**Retrieve the USSD String**

Once the payment is initiated, a unique `ussdString` specific to the bank will be provided in the response.
{% endstep %}

{% step %}
**Dial the USSD Code**

Use the returned `ussdString` to proceed with the transaction. For example, if the string provided is `*329*000*3668#`, dial it on your phone and press the call button.
{% endstep %}

{% step %}
**Follow On-Screen Instructions**

Complete the transaction by following the prompts displayed during the USSD session.
{% endstep %}
{% endstepper %}

### Check Status

Use the Transaction status API [here](/misc/transaction-status) to check the status of the transaction by passing your transaction reference as `tnx_ref` in the request body.


# Payment Link

We can now accept payments through our payment link.

[Dashboard Method](/accepting-payments/payment-link/dashboard)

[API Method](/accepting-payments/payment-link/payment-link-api)


# Dashboard

Collect payments from your customers using payment link.

[One-Time Payment](/features/one-time-payments)

[Recurrent Payment](/features/recurrent-payment)


# Payment Link API

Collect payments from your customers using payment link.

### Summary

The Payment Link API allows merchants to generate payment links for their sub-merchants to easily collect payments. Follow these steps to integrate:

1. Generate a Bearer Token
2. Create a Payment Link
3. Share the Payment Link
4. Monitor Payment Status
5. Fetch payment link transactions via `paylinkId`

{% hint style="info" %}
Before you begin!
{% endhint %}

## Integration steps

## Generate a Bearer Token

Obtain a token by following the authentication guide [here](https://developers.klasha.com/~/revisions/Tw5bfW3awcozGbmqzgEE/overview/authentication). Use this token as your Bearer token in subsequent API calls.

## Create a Payment Link

> <mark style="color:yellow;">**POST**</mark> - <mark style="color:$primary;">`{{env_url}}/merchant/api/v1/paylink/create`</mark>

This api generates a payment link that can be given to your customers to make payments.

**NB**: No need for an encryption of the plain json payload.

#### Headers

| Name          | Value                                                        |
| ------------- | ------------------------------------------------------------ |
| Authorization | Bearer <mark style="color:$primary;">{{token}}</mark>        |
| x-auth-token  | <mark style="color:$primary;">{{MERCHANT PUBLIC KEY}}</mark> |

#### Request Body

| Name                                            | Type    | Description                                                |
| ----------------------------------------------- | ------- | ---------------------------------------------------------- |
| name<mark style="color:red;">\*</mark>          | String  | Sub-Merchant Name                                          |
| subMerchantId<mark style="color:red;">\*</mark> | String  | Sub-Merchant Identification                                |
| description<mark style="color:red;">\*</mark>   | String  | Intending product or service.                              |
| currency<mark style="color:red;">\*</mark>      | String  | NGN                                                        |
| amount<mark style="color:red;">\*</mark>        | Decimal | <p>Amount to accept for the </p><p>product or service.</p> |

See an example of the plain json payload to send.

{% tabs fullWidth="true" %}
{% tab title="Sample Request" %}

```json
{
    "name": "Klash",
    "subMerchantId": "sub-klasha-23456",
    "description": "Payment for 1000 naira purchase",
    "currency": "NGN",
    "amount": 1000
}
```

{% endtab %}
{% endtabs %}

#### Response

{% tabs %}
{% tab title="200: OK" %}

```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"
    }
}
```

{% endtab %}
{% endtabs %}

## Share the Payment Link

Distribute the generated payment link URL to your sub-merchants for them to receive payments. The link directs customers to a payment page (See sample of the page below).

<figure><img src="/files/EJvVEEqA04mOonlSxeiG" alt="" width="563"><figcaption><p>Paylink page for the customer to fill and click Pay with klasha button to proceed.</p></figcaption></figure>

## Monitor Payment Status

We would send payment status updates to your configured webhook URL. Monitor this to track payment outcomes. See webhook details [here](https://developers.klasha.com/~/revisions/ZnKl9fQgoz2UyPgPcwp6/misc/webhook).

## Fetch payment link transactions

> <mark style="color:green;">**GET**</mark> - <mark style="color:$primary;">`{{env_url}}/nucleus/paymentLinkTransaction/id/{{paylinkId}}`</mark>

This api fetches all transactions associated to the `paylinkId` generated above.

#### Headers

| Name                                            | Value                                                     |
| ----------------------------------------------- | --------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | Bearer <mark style="color:red;">`{{token}}`</mark>        |
| x-auth-token<mark style="color:red;">\*</mark>  | <mark style="color:red;">`{{MERCHANT PUBLIC KEY}}`</mark> |

#### Params

| Name                                        | Type   | Description                                  |
| ------------------------------------------- | ------ | -------------------------------------------- |
| paylinkId<mark style="color:red;">\*</mark> | String | paylink id generated while creating the link |

#### Response

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "message": "success",
    "error": null,
    "data": [
        {
            "id": 155,
            "amount": 305.00,
            "currency": "KES",
            "sourceAmount": 305.000000,
            "sourceCurrency": "KES",
            "paymentLinkId": "10df0c84-11ec-434c-9020-33d79c0c7a5a",
            "subMerchantId": "89989aa6-7b59-429b-b855-27c289f02fb0",
            "status": "successful",
            "message": "Transaction Successful",
            "tnxRef": "paylink-87858e5b-8eba-4ebe-8cf4-7883f92c5c10",
            "gateRef": "3378988429",
            "paymentType": "MOBILE_MONEY",
            "customerEmail": "test@example.com"
        },
        {
            "id": 154,
            "amount": 1724.03,
            "currency": "NGN",
            "sourceAmount": 305.000000,
            "sourceCurrency": "KES",
            "paymentLinkId": "10df0c84-11ec-434c-9020-33d79c0c7a5a",
            "subMerchantId": "89989aa6-7b59-429b-b855-27c289f02fb0",
            "status": "failed",
            "message": "payment not authorised",
            "tnxRef": "paylink-bf1e85d5-f6e4-475f-b466-87693311a8c7",
            "gateRef": "",
            "paymentType": "BANK_TRANSFER",
            "customerEmail": "fooboo@test.com"
        }
    ]
}
```

{% endtab %}
{% endtabs %}


# Klasha Inline

Embed Klasha into your website using our inline JavaScript integration.

Take the following steps to integrate the Klasha payment gateway into your website and begin accepting payments from anywhere in the world:

* Embed Klasha JavaScript into the head tag of your HTML code.
* Define a JavaScript function in your script file.

#### Embed Klasha JavaScript into the head tag of your HTML code

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <script type="text/javascript" src="https://js.klasha.com/pay.js"></script>
    <title>Klasha Payment</title>
  </head>

  <body>
    
    <form>
      <input type="button" onclick="payWithKlasha()" value="Pay With Klasha" />
    </form>

    
  </body>
</html>
```

#### Define a JavaScript function in your script file <a href="#defineajavascriptfunction" id="defineajavascriptfunction"></a>

```javascript
<script>
      // Callback for handling transaction status
      const callWhenDone = (data) => {
        if (data.status === "success") {
          console.log("Payment successful", data);
        } else if (data.status === "failed") {
          console.error("Payment failed", data);
        }
      };

      // Payment configuration and initialization
      const payWithKlasha = () => {
        const MERCHANT_KEY = "{{merchantKey}}";
        const AMOUNT = 1;
        const BUSINESS_ID = "{{businessId}}";
        const ENVIRONMENT = true; // true for dev, false for production
        const currency = "{{currency}}";
        const DESTINATION_CURRENCY = "{{destinationCurrency}}";
        const DESCRIPTION = "school fee";

        const paymentKit = {
          tx_ref: "{{paylink_ref}}",
          fullname: "{{fullname}}",
          firstName: "{{firstName}}",
          lastName: "{{lastName}}",
          email: "{{email}}",
          phone_number: "{{phone_number}}",
          businessId: BUSINESS_ID,
          merchantKey: MERCHANT_KEY,
          amount: AMOUNT,
          sourceAmount: "1",
          rate: 1,
        };

        const client = new KlashaClient(
          MERCHANT_KEY,
          BUSINESS_ID,
          AMOUNT,
          DESCRIPTION,
          callWhenDone,
          currency,
          DESTINATION_CURRENCY,
          paymentKit,
          ENVIRONMENT
        );

        client.init();
      };

      document.addEventListener("DOMContentLoaded", payWithKlasha);
    </script>
```

![Pop-up Sample](/files/o2o21ntwJlcgFGicukKL)

#### Callback response

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

With this, other activities like confirming a [Transaction Status](/misc/transaction-status) can be done.

#### Webhook response

If you have Webhook notifications set up on the dashboard, we will send you a transaction response in the format below:

```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"
    }
  }
}
```


# HTML Checkout

Collect payments from your customers using Klasha inline in your HTML file.

Sample implementation:

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <script type="text/javascript" src="https://js.klasha.com/pay.js"></script>
    <title>Klasha Payment</title>
  </head>

  <body>
    <!-- There are two ways to call this script using a click event
    or waiting for the document to load completely. 
    Totally depends on you based on your usecase -->

    <form>
      <input type="button" onclick="payWithKlasha()" value="Pay With Klasha" />
    </form>

    <script>
      // Callback for handling transaction status
      const callWhenDone = (data) => {
        if (data.status === "success") {
          console.log("Payment successful", data);
        } else if (data.status === "failed") {
          console.error("Payment failed", data);
        }
      };

      // Payment configuration and initialization
      const payWithKlasha = () => {
        const MERCHANT_KEY = "{{merchantKey}}";
        const AMOUNT = 1;
        const BUSINESS_ID = "{{businessId}}";
        const ENVIRONMENT = true; // true for dev, false for production
        const currency = "{{currency}}";
        const DESTINATION_CURRENCY = "{{destinationCurrency}}";
        const DESCRIPTION = "school fee";

        const paymentKit = {
          tx_ref: "{{paylink_ref}}",
          fullname: "{{fullname}}",
          firstName: "{{firstName}}",
          lastName: "{{lastName}}",
          email: "{{email}}",
          phone_number: "{{phone_number}}",
          businessId: BUSINESS_ID,
          merchantKey: MERCHANT_KEY,
          amount: AMOUNT,
          sourceAmount: "1",
          rate: 1,
        };

        const client = new KlashaClient(
          MERCHANT_KEY,
          BUSINESS_ID,
          AMOUNT,
          DESCRIPTION,
          callWhenDone,
          currency,
          DESTINATION_CURRENCY,
          paymentKit,
          ENVIRONMENT
        );

        client.init();
      };

      document.addEventListener("DOMContentLoaded", payWithKlasha);
    </script>
  </body>
</html>
```

### klashaClient Parameters

| Name                | Description                                                                                                                                            | Sample                                                              |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| merchantKey         | Merchant Public Key                                                                                                                                    |                                                                     |
| businessId          | Merchant businessId                                                                                                                                    | 12                                                                  |
| amount              | <p>Paying amount.<br>It will be converted to the currency the customer is using if the source currency is different from the transaction currency.</p> | 1                                                                   |
| destinationCurrency | Merchant accepting current                                                                                                                             | USD                                                                 |
| currency            | Customer payment current                                                                                                                               | NGN                                                                 |
| ENVIRONMENT         | Mode to switch between development and production environment                                                                                          | true or false. (set to true in development and false in production) |

{% code title="More explanantion" overflow="wrap" fullWidth="false" %}

```bash
To effectively test a paid or failed transaction, it's important to include the callWhenDone() function in your kit. This function should look similar to the example provided above. It takes an argument that, when logged, will return a status object indicating either an ERROR or a successful transaction. You can then decide how to proceed based on this status.

If the user clicks the close button, the system assumes no action was taken, and it will return an ERROR status.

```

{% endcode %}


# Plugins

Integrate Klasha into your e-commerce platforms with our readymade plugins

Klasha uses the following plugins:

### BigCommerce

BigCommerce is a public technology company that provides a SaaS e-commerce platform. A tutorial on installing the plugin can be found [here](https://support.klasha.com/en/articles/6855267-how-to-integrate-klasha-into-bigcommerce).

### WooCommerce

WooCommerce is an open-source e-commerce plugin, designed for small to large-sized online merchants using WordPress. A tutorial on installing the plugin can be found [here](https://support.klasha.com/en/articles/6855264-how-to-integrate-klasha-into-woocommerce).

### OpenCart

OpenCart is an easy-to-use, powerful, open-source online store management program that can manage multiple online stores from a single back-end. A tutorial on installing the plugin can be found [here](https://support.klasha.com/en/articles/6855278-how-to-integrate-klasha-into-opencart).

### Magento 2

Magento is an open-source e-commerce platform for high GMV merchants. We integrate into both Magento Community and Enterprise. A tutorial on installing the plugin can be found [here](https://support.klasha.com/en/articles/6855322-how-to-integrate-klasha-into-magento-2).

### Ecwid

Ecwid is an e-commerce widget that can seamlessly integrate with whatever platform you already use to promote your business, whether a business website, marketplace, app, or more. A tutorial on installing the plugin can be found [here](https://support.klasha.com/en/articles/6855274-how-to-integrate-klasha-into-ecwid).

### Wix

Wix is a leading cloud-based development platform that makes it easy for everyone to create a beautiful, professional web presence. A tutorial on installing the plugin can be found [here](https://support.klasha.com/en/articles/6855280-how-to-integrate-klasha-into-wix).

### Weebly

Weebly is a free website builder that makes it easy to create a website, blog, or online store. It is an all-in-one powerful e-commerce tool to simplify order management, shipping & payments. A tutorial on installing the plugin can be found [here](https://support.klasha.com/en/articles/6855272-how-to-integrate-klasha-into-weebly).


# Mobile SDKs

Accept payments from your mobile application with Klasha using our mobile SDKs

#### Android SDK

The Klasha Android SDK allows businesses to use Klasha to collect payments within their Android app. Find detailed information on how to integrate Klasha into your Android app [here](https://github.com/klasha-apps/klasha-android).

#### iOS SDK

The Klasha iOS SDK allows businesses to use Klasha to collect payments within their iOS app. Detailed information on how to integrate Klasha into your iOS app can be found in the following resources:

* [Github](https://github.com/klasha-apps/ios)
* [CocoaPods](https://cocoapods.org/pods/klashapay)

#### Flutter SDK

The Klasha Flutter SDK allows businesses to use Klasha to collect payments within their Flutter app. Detailed information on how to integrate Klasha into your website can be found in the following resources:

* [Github](https://github.com/klasha-apps/klasha-flutter)
* [pub.dev](https://pub.dev/packages/klasha_flutter_checkout)

#### Ionic SDK

The Klasha Ionic SDK allows businesses to use Klasha to collect payments within their Ionic app. Detailed information on how to integrate Klasha into your website can be found in the following resources:

* [Github](https://github.com/dansteve/angular-klasha)
* [NPM](https://www.npmjs.com/package/angular-klasha)

**React Native SDK**

The Klasha React Native SDK allows businesses to use Klasha to collect payments within their app. Detailed information on how to integrate Klasha into your website can be found in the following resources:

* [Github](https://github.com/dansteve/react-native-klasha-webview)
* [NPM](https://www.npmjs.com/package/react-native-klasha-webview)


# Web SDKs

Accept payments from your web application with Klasha using our web SDKs

#### Angular SDK

The Klasha Angular SDK allows businesses to use Klasha to collect payments within their websites. Detailed information on how to integrate Klasha into your website can be found in the following resources:

* [Github](https://github.com/dansteve/angular-klasha)
* [NPM](https://www.npmjs.com/package/angular-klasha)

#### React SDK

The Klasha React SDK allows businesses to use Klasha to collect payments within their websites. Detailed information on how to integrate Klasha into your website can be found in the following resources:

* [Github](https://github.com/klasha-apps/klasha-react)
* [NPM](https://www.npmjs.com/package/klasha-pay)

#### Vue SDK

The Klasha Vue SDK allows businesses to use Klasha to collect payments within their websites. Detailed information on how to integrate Klasha into your website can be found in the following resources:

**Vue 2**

* [Github](https://github.com/Dansteve/vue-klasha)
* [NPM](https://www.npmjs.com/package/vue-klasha)

**Vue 3**

* [Github](https://github.com/dansteve/vue3-klasha)
* [NPM](https://www.npmjs.com/package/vue3-klasha)


# Transaction Status

Verify a transaction.

Before giving value for any charge, it's advised to use the transaction status api below to verify the final status of the charge, using the transaction reference supplied during the charge initiation.

When verifying a transaction, the following should be checked:

* Confirm both the value of the payment and the destination currency are correct.
* Confirm the status of the transaction is successful.

### Check transaction status

> <mark style="color:yellow;">**`POST`**</mark> - <mark style="color:$primary;">{{env\_url}}/nucleus/tnx/merchant/status</mark>

#### Request Body

| Name                                     | Type   | Description           |
| ---------------------------------------- | ------ | --------------------- |
| tnxRef<mark style="color:red;">\*</mark> | String | Transaction reference |

```
{
    "tnxRef": "6e003f69-55e3-4117-aa7a-f4259ad227ae"
}
```

#### Response Body

{% tabs %}
{% tab title="200: OK " %}

```jsonl
{
    "txRef": "6e003f69-55e3-4117-aa7a-f4259ad227ae",
    "destinationCurrency": "NGN",
    "sourceAmount": 2500.000000,
    "sourceCurrency": "NGN",
    "status": "successful",
    "destinationAmount": 2500.000000,
    "customer": {
        "id": 6132,
        "name": Demo Tester,
        "email": "test@klasha.com",
        "phone": "09012332122",
        "createdAt": "2022-01-24 13:25:31",
        "updatedAt": "2022-01-24 13:25:31"
    }
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
   "error": "Transaction not found."
}
```

{% endtab %}
{% endtabs %}


# Webhook

Webhook response

If you have webhook notifications set up on your dashboard, we will send you updates for different activities, samples of which can be found below:

####

* [x] Collections

{% tabs %}
{% tab title="charge.completed" %}

```json
{
  "event": "charge.completed",
  "data": {
    "createdAt": "2021-11-18T15:23:16.781",
    "narration": "CARD Transaction ",
    "destinationCurrency": "NGN",
    "sourceAmount": 100,
    "sourceCurrency": "NGN",
    "tnxRef": "6e003f69-55e3-4117-aa7a-f4259ad227ae",
    "status": "successful",
    "destinationAmount": 100,
    "customer": {
      "id": 13,
      "name": "Demo Tester",
      "email": "demo@tester.com",
      "phone": 07000000001,
      "createdAt": "2021-07-20 10:28:43",
      "updatedAt": "2021-07-20 10:28:43"
    }
  }
}
```

{% endtab %}

{% tab title="charge.completed (paylink)" %}

```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"
}
```

{% endtab %}
{% endtabs %}

* [x] Payout

{% tabs %}
{% tab title="payout (successful)" %}

```json
{
  "data": {
    "reference": "kbtr-3857-011-null-166993253331236",
    "createdAt": "2023-03-28T23:01:45.336",
    "amount": 1000,
    "accountName": "Pastor Bright",
    "narration": "certification",
    "name": "Steph and sons",
    "currency": "NGN",
    "bankName": "ACCESS BANK NIGERIA",
    "accountNumber": "0690000032",
    "status": "successful"
  },
  "event": "payout"
}
```

{% endtab %}

{% tab title="payout (failed)" %}

```json
{
  "data": {
    "reference": "kbtr-3857-011-null-166993253331236",
    "createdAt": "2023-03-28T23:01:45.336",
    "amount": 1000,
    "accountName": "Pastor Bright",
    "narration": "certification",
    "name": "Steph and sons",
    "currency": "NGN",
    "bankName": "ACCESS BANK NIGERIA",
    "accountNumber": "0690000032",
    "status": "failed"
  },
  "event": "payout"
}
```

{% endtab %}
{% endtabs %}

* [x] Refund

{% tabs %}
{% tab title="refund.completed (successful)" %}

```json
{
  "event": "refund.completed",
  "data": {
    "createdAt": "2021-11-18T15:23:16.781",
    "refundType": "partial",
    "refundRef": "6b691e37-02ae-4ccc-859d-1d10e53eeabd",
    "amount": 100,
    "completeMessage": "",
    "tnxRef": "6e003f69-55e3-4117-aa7a-f4259ad227ae",
    "status": "successful",
    "customer": {
      "id": 13,
      "name": "Demo Tester",
      "email": "demo@tester.com",
      "phone": 07000000001,
      "createdAt": "2021-07-20 10:28:43",
      "updatedAt": "2021-07-20 10:28:43"
    }
  }
}
```

{% endtab %}

{% tab title="refund.completed (failed)" %}

```json
{
  "event": "refund.completed",
  "data": {
    "createdAt": "2021-11-18T15:23:16.781",
    "refundType": "partial",
    "refundRef": "6b691e37-02ae-4ccc-859d-1d10e53eeabd",
    "amount": 100,
    "completeMessage": "",
    "tnxRef": "6e003f69-55e3-4117-aa7a-f4259ad227ae",
    "status": "failed",
    "customer": {
      "id": 13,
      "name": "Demo Tester",
      "email": "demo@tester.com",
      "phone": 07000000001,
      "createdAt": "2021-07-20 10:28:43",
      "updatedAt": "2021-07-20 10:28:43"
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Resend Webhook

> GET <mark style="color:red;">`{{env_url}}`</mark>`/nucleus/tnx/webhook?reference=`<mark style="color:red;">`{{tx_ref}}`</mark>

This endpoint allows you to resend webhooks from failed sending queues to your server.

You’d need to pass your merchant public key in the request header (`x-auth-token`). This can be obtained from your merchant dashboard → Settings → Generate API keys → **Merchant public key.**

**Headers**

| Name          | Value                                            |
| ------------- | ------------------------------------------------ |
| Content-Type  | `application/json`                               |
| x-auth-token  | merchant public key                              |
| Authorization | Bearer <mark style="color:red;">{{token}}</mark> |

#### Query Params

```json
"tx_ref": the reference used when initiating the transaction
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "message": "webhook sent for reference {{tx_ref}}",
    "error": null,
    "data": null
}
```

{% endtab %}
{% endtabs %}


# API Status

API status updates are available at <https://status.klasha.com/>. Stay informed by subscribing to updates for timely notifications.


# One-time Payments

One-time plans

### Creating a one-time charge payment link

* Login to your dashboard and navigate to Payment Link.
* Click on Create payment link.
* Click on One-time payment.
* When all details are filled in, click on Create link.
* The payment link is created, and you can now share it with your customers.

<figure><img src="/files/XVGHTJosXuEVTzMIOGVX" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/YiUm53DoZ7yZVnRCbSHh" alt=""><figcaption></figcaption></figure>


# Recurrent Payment

Recurrent plans

### Creating a recurrent charge payment link

* Login to your dashboard and navigate to Payment Link.
* Click on Create payment link.
* Click on Recurrent payment.
* When all details are filled in, click on Create link.
* The payment link is created, and you can now share it with your customers.

<figure><img src="/files/6W7xiLsV1MgPrxFvEq3O" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/07s0qI30MQtZL86NqMug" alt=""><figcaption></figcaption></figure>


# Payout

## Summary

Send money locally with Klasha to bank accounts and mobile money wallets in Africa.

### Coverage

* NGN
* [ZAR](/transfers/payout/zar-payout-new-encryption)
* GHS (beta)
* KES (beta)

You can transfer money in four easy steps:

1. Verify the account number
2. Create transfer recipient
3. Initiate a transfer
4. Listen for status.

***

{% hint style="info" %}

### Before you begin!

* [Link](https://api.postman.com/collections/25963887-8947bcfa-aaf7-471a-9df1-18c54dc736ad?access_key=PMAT-01GWN42BNXSAS7WJ7P46PW6B3R) to the Postman collection
* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">

{% endhint %}

<details>

<summary>Generate bearer token</summary>

Using the Token [endpoint](https://developers.klasha.com/~/revisions/UU3P5ANUZVJrY1nR5gP2/overview/token-generation) to generate a bearer token. The token obtained from the api should be passed in the used to authenticate the requests below.

</details>

<details>

<summary>Fetch bank codes</summary>

Use the API below to fetch the available bank codes.

> <mark style="color:blue;">**GET**</mark><mark style="color:blue;">:</mark> {{base\_url}}/wallet/merchant/bank/transfer/request/banks/:currency

```json
{
    "message": "success",
    "error": null,
    "data": [
        {
            "code": "90527",
            "name": " OJOKORO MICROFINANCE BANK"
        },
        ...
        {
            "code": "090384",
            "name": "ZION MFB"
        }
    ]
}
```

</details>

<details>

<summary>Verify account number</summary>

Using the Resolve account number endpoint on the Postman collection [here](https://api.postman.com/collections/8963555-c750eddc-38e9-4866-87ed-c5dc266c25fd?access_key=PMAT-01HZPRY6GFVT9DYGXZYYNM5SS3), verify the account number by making use of the bank codes gotten from here. See an example in the screenshot below

<img src="/files/epvsZyNQCkn9z4Vqhibu" alt="" data-size="original">

</details>

## Generate a transfer reference

It’s a unique reference sent as `requestId` that can be used to uniquely identify a transfer.

#### Initiate a transfer

<details>

<summary>Create payload</summary>

```json
{
	"amount": 1000,
	"country": "NG",
	"currency": "NGN",
	"bankCode": "044",
	"bankName": "Access Bank",
	"accountNumber": "0690000032",
	"accountName": "Pastor Bright",
	"requestId": "kbtr-3857-011-null-166993253334816",
	"description": "certification"
}




Fields specification:

- amount is the amount to payout
- country is the country of the beneficiary
- currency is the currency of payout
- bankcode is the code of the bank which can be gotten by calling the Bank code endpoint
- bankName is the name of the bank
- accountNumber is the beneficiary account number
- accountName is the beneficiary account name
- requestId is the transaction reference
- description is the narration or reason for the payout
```

</details>

* Serialize the payload

#### Encryption Algorithm

You need to encrypt the entire create transfer payload that we specify on the previous point (here). In order to encrypt the body correctly, you’d need the encryptionKey (that you can obtain following this guide here). Find an encryption algorithm code snippet below:

{% tabs %}
{% tab title="Java" %}
{% code overflow="wrap" lineNumbers="true" fullWidth="true" %}

```java
public static String encrypt3DES(String messageToEncrypt, byte[] secret) throws NoSuchPaddingException, NoSuchAlgorithmException,
            InvalidAlgorithmParameterException, InvalidKeyException, IllegalBlockSizeException, BadPaddingException {
    SecretKeySpec secretKeySpec = new SecretKeySpec(secret, "TripleDES");
    byte[] iv = Arrays.copyOfRange(secret, 0, 8);
    IvParameterSpec ivSpec = new IvParameterSpec(iv);

    Cipher encryptCipher = Cipher.getInstance("TripleDES/CBC/PKCS5Padding");
    encryptCipher.init(Cipher.ENCRYPT_MODE, secretKeySpec, ivSpec);

    byte[] secretMessagesBytes = messageToEncrypt.getBytes(StandardCharsets.UTF_8);
    byte[] encryptedMessageBytes = encryptCipher.doFinal(secretMessagesBytes);

    return Base64.getEncoder().encodeToString(encryptedMessageBytes);
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

<details>

<summary>Encrypted Payload</summary>

The result of the encryption of the payload that we specified here have to be used with the Merchant payout endpoint as shown below:

<img src="/files/tvMLOMC8sFUqKLpicoXm" alt="" data-size="original">

</details>

**Merchant Payout request**

## Make a POST call to the Merchant payout request API

> <mark style="color:green;">`POST`</mark> `{{env_url}}/wallet/merchant/{businessId}/bank/transfer/v2/request`

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

## Listen for a status response

When a transfer is initiated, it could take a few seconds or minutes to be processed. This is why we recommend relying on webhooks for verification as opposed to polling.

Once a transfer is processed, we send the final status of the transfer as a POST request to your webhook URL (see [webhook](https://developers.klasha.com/~/revisions/wTs3QfcE0Q2ImN5VimGe/misc/webhook) details here).

### Get wallet balance

To get your wallet balance you would need to make a GET request to the API below:

<mark style="color:green;">`GET`</mark> <mark style="color:red;">{{env\_url}}</mark>/nucleus/business/api/wallets

**Headers**

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

**Response**

{% tabs %}
{% tab title="200" %}

```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"
        }
    ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "message": "`error message",
    "error": "error",
    "data": null
}
```

{% endtab %}
{% endtabs %}

The possible statuses are listed and described in the following table:

| Status                                       | Description                                                                   |
| -------------------------------------------- | ----------------------------------------------------------------------------- |
| <mark style="color:green;">successful</mark> | This is sent when the transfer is successful                                  |
| <mark style="color:red;">failed</mark>       | This is sent when the transfer fails                                          |
| <mark style="color:orange;">pending</mark>   | This transfer is still in progress. Please wait for either success or failed. |

#### Polling transfer statuses

* You can fetch the transfer from the `Find by ref` API on the Postman collection to know the status. See example in the below screenshot.

<figure><img src="/files/JLQofGyjoMn0CFFnc9a3" alt="" width="563"><figcaption></figcaption></figure>

### Source wallet

All transfers would be debited from NGN Wallet balance. Ensure you have sufficient balance before making any transfer request.


# ZAR Payout (new encryption)

### Summary

These APIs are used to initiate a ZAR payout

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

## Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

#### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Get Bank Lists**

## Make a GET call to the Bank List API&#x20;

<mark style="color:blue;">`GET`</mark> `{{env_url}}/wallet/merchant/bank/transfer/request/banks/ZAR`

#### Headers

{% tabs %}
{% tab title="200: OK " %}

```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"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

### **Resolve Bank Account** `(Not Available)`

## Make a POST call to the resolve account API&#x20;

<mark style="color:green;">`POST`</mark> `{{env_url}}/wallet/merchant/bank/transfer/request/resolve/account`

#### Headers

| Key           | Value                |
| ------------- | -------------------- |
| Context-Type  | application/json     |
| Authorization | Bearer \<token here> |
|               |                      |

#### Request Body

| Name                                             | Type   | Description                                                                                                            |
| ------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| bankCode<mark style="color:red;">\*</mark>       |        | 430000                                                                                                                 |
| countryCode<mark style="color:red;">\*</mark>    |        | ZA                                                                                                                     |
| accountNumber<mark style="color:red;">\*</mark>  |        | 0690000032                                                                                                             |
| accountType<mark style="color:red;">\*</mark>    |        | personal                                                                                                               |
| documentType<mark style="color:red;">\*</mark>   | String | Customer’s mode of identity. This could be one of: \[`identityNumber`, `passportNumber`, `businessRegistrationNumber`] |
| businessId<mark style="color:red;">\*</mark>     | String | 133                                                                                                                    |
| documentNumber<mark style="color:red;">\*</mark> | String | 8801235111088                                                                                                          |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "status": true,
    "message": "Personal Account Verification attempted",
    "data": {
        "verified": true,
        "verificationMessage": "Account is verified successfully"
    }
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
This error occurs when the account number cannot be verified
{"error":"Bad request"}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
This error occurs when the right "countryCode" is not passed in
{
    "message": "Operation not allowed.",
    "error": "Operation not allowed",
    "data": null
}
```

{% endtab %}
{% endtabs %}

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/wallet/merchant/{businessId}/bank/transfer/v2/request`

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>SA</td></tr><tr><td>bankCode<mark style="color:red;">*</mark></td><td></td><td>430000</td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Sydney Mark</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>kbtr-3857-011-133-166993253334816</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>ZAR</td></tr><tr><td>bankName<mark style="color:red;">*</mark></td><td>String</td><td>Ubank Ltd</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>0690000032</td></tr><tr><td>mobileNumber<mark style="color:red;">*</mark></td><td>String</td><td>Recipient mobile number</td></tr><tr><td>recipientAddress<mark style="color:red;">*</mark></td><td>String</td><td>Recipient address</td></tr><tr><td>recipientEmail<mark style="color:red;">*</mark></td><td>String</td><td>Recipient email</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "id": 3,
    "amount": 1000,
    "payoutStatus": "PENDING",
    "requestId": "kbtr-3857-011-133-166993253334816",
    "narration": "certification",
    "country": "SA",
    "fee": 25,
    "bankCode": "430000",
    "bankName": "Ubank Ltd",
    "accountNumber": "0690000032",
    "accountName": "Pastor Bright"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "message": "A human readable error message",
    "error": "Bad Request",
    "data": null
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# NGN Payout (new encryption)

### Summary

These APIs are used to initiate a NGN payout

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

## Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

#### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Get Bank Lists**

## Make a GET call to the Bank List API&#x20;

<mark style="color:blue;">`GET`</mark> `{{env_url}}/wallet/merchant/bank/transfer/request/banks/NGN`

#### Headers

{% tabs %}
{% tab title="200: OK " %}

<pre class="language-json"><code class="lang-json">{
    "message": "success",
    "error": null,
    "data": [
<strong>        {
</strong>            "code": "90527",
            "name": " OJOKORO MICROFINANCE BANK"
        },
        {
            "code": "110072",
            "name": "78 FINANCE COMPANY LIMITED"
        },
        {
            "code": "090629",
            "name": "9jaPay Microfinance Bank"
        },
        {
            "code": "120001",
            "name": "9PAYMENT SERVICE BANK"
        }
    ]
}
</code></pre>

{% endtab %}
{% endtabs %}

### **Resolve Bank Account**&#x20;

## Make a POST call to the resolve account API&#x20;

<mark style="color:green;">`POST`</mark> `{{env_url}}/wallet/merchant/bank/transfer/request/resolve/account`

#### Headers

| Key           | Value                |
| ------------- | -------------------- |
| Context-Type  | application/json     |
| Authorization | Bearer \<token here> |
|               |                      |

#### Request Body

| Name                                            | Type | Description |
| ----------------------------------------------- | ---- | ----------- |
| bankCode<mark style="color:red;">\*</mark>      |      | 100004      |
| countryCode<mark style="color:red;">\*</mark>   |      | NG          |
| accountNumber<mark style="color:red;">\*</mark> |      | 9067285661  |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "status": "success",
    "message": "Account details fetched",
    "data": {
        "account_number": "9067777000",
        "account_name": "John Jane Doe"
    }
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
This error occurs when the account number cannot be verified
{
    "status": "error",
    "message": "Account could not be resolved"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
This error occurs when the right "countryCode" is not passed in
{
    "message": "Operation not allowed.",
    "error": "Operation not allowed",
    "data": null
}
```

{% endtab %}
{% endtabs %}

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/wallet/merchant/{businessId}/bank/transfer/v2/request`

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>NG</td></tr><tr><td>bankCode<mark style="color:red;">*</mark></td><td></td><td>10004</td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>1000</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>John Jane Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>kbtr-3857-011-133-166993253334816</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>NGN</td></tr><tr><td>bankName<mark style="color:red;">*</mark></td><td>String</td><td>Opay Limited</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>9067285661</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "id": 3,
    "amount": 1000,
    "payoutStatus": "PENDING",
    "requestId": "kbtr-3857-011-133-166993253334816",
    "narration": "certification",
    "country": "NG",
    "fee": 54,
    "bankCode": "10004",
    "bankName": "Opay Limited",
    "accountNumber": "9067285661",
    "accountName": "John Jane Doe"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "message": "A human readable error message",
    "error": "Bad Request",
    "data": null
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# GHS Payout (new encryption)

### Summary

These APIs are used to initiate a GHS payout

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

## Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

#### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Get Bank Lists**

## Make a GET call to the Bank List API&#x20;

<mark style="color:blue;">`GET`</mark> `{{env_url}}/wallet/merchant/bank/transfer/request/banks/GHS`

#### Headers

{% tabs %}
{% tab title="200: OK " %}

<pre class="language-json"><code class="lang-json">{
    "message": "success",
    "error": null,
    "data": [
<strong>        {
</strong>            "id": 752.0,
            "code": "10550214",
            "name": "The Hongkong and Shanghai Banking Corporation Limited"
        },
        {
            "id": 753.0,
            "code": "11088200",
            "name": "Giro Elszamolasforgalmi Zrt."
        },
        {
            "id": 754.0,
            "code": "11276282",
            "name": "First National Bank Ghana Limited"
        },
        {
            "id": 755.0,
            "code": "11299458",
            "name": "OMNIBANK GHANA LIMITED"
        }
    ]
}
</code></pre>

{% endtab %}
{% endtabs %}

### **Get Bank Codes**

### Make a GET call to the Branch Code API&#x20;

<mark style="color:blue;">`GET`</mark> `{{env_url}}/wallet/merchant/bank/transfer/request/branch-code/{bankid}`

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "message": "success",
    "error": null,
    "data": [
        {
            "id": 2391.0,
            "branch_code": "1812051EPC",
            "branch_name": "1st Natl Bank Ghana Ltd",
            "swift_code": null,
            "bic": null,
            "bank_id": 754.0
        }
    ]
}
```

{% endtab %}
{% endtabs %}

### Get Mobile Money Lists&#x20;

## Make a GET call to the Mobile Money List API&#x20;

<mark style="color:green;">`GET`</mark> `{{env_url}}/wallet/merchant/bank/transfer/request/banks/GHS?type=mobile-money`

#### Headers

#### Response Body

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "message": "success",
    "error": null,
    "data": [
        {
            "code": "MTN",
            "name": "MTN Mobile Money"
        },
        {
            "code": "VODAFONE",
            "name": "Vodafone Mobile Money"
        },
        {
            "code": "AIRTELTIGO",
            "name": "Airtel-Tigo Mobile Money"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

### **Merchant Bank Account Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/wallet/merchant/{businessId}/bank/transfer/v2/request`

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td>String</td><td>GH</td></tr><tr><td>bankCode<mark style="color:red;">*</mark></td><td>String</td><td>10550214</td></tr><tr><td>branchCode<mark style="color:red;">*</mark></td><td>String</td><td>1812062RXQ</td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>1000</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td>String</td><td>John Jane Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>kbtr-3857-011-133-166993253334816</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>GHS</td></tr><tr><td>bankName<mark style="color:red;">*</mark></td><td>String</td><td>The Hongkong and Shanghai Banking Corporation Limited</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>10101010101</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "id": 1205,
    "amount": 100.00,
    "payoutStatus": "PENDING",
    "requestId": "tranf-55b59c78-0093-4c6a-8370-5778c1bde9e3",
    "narration": "GIFT_AND_DONATION",
    "country": "GH",
    "fee": 15.00,
    "bankCode": "10550214",
    "bankName": "The Hongkong and Shanghai Banking Corporation Limited",
    "accountNumber": "10010101011",
    "accountName": "John Jane Doe"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "message": "A human readable error message",
    "error": "Bad Request",
    "data": null
}
```

{% endtab %}
{% endtabs %}

### **Merchant Bank Account Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/wallet/merchant/{businessId}/bank/transfer/v2/request`

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td>String</td><td>GH</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td>String</td><td>MTN</td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>1000</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td>String</td><td>John Jane Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>kbtr-3857-011-133-166993253334816</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>GHS</td></tr><tr><td>bankName<mark style="color:red;">*</mark></td><td>String</td><td>MTN Mobile Money</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>233540105690</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "id": 1206,
    "amount": 100.00,
    "payoutStatus": "PENDING",
    "requestId": "tranf-7956670a-2912-4e74-a54d-ca89c89c7609",
    "narration": "MEDICAL_TREATMENT",
    "country": "GH",
    "fee": 2.50,
    "bankCode": "VODAFONE",
    "bankName": "Vodafone Mobile Money",
    "accountNumber": "233540105690",
    "accountName": "John Jane Doe"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "message": "A human readable error message",
    "error": "Bad Request",
    "data": null
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# KES Payout (new encryption)

### Summary

These APIs are used to initiate a KES payout

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Get Bank Lists**

## Make a GET call to the Bank List API&#x20;

<mark style="color:blue;">`GET`</mark> `{{env_url}}/wallet/merchant/bank/transfer/request/banks/KES?`type=mobile-money

#### Headers

| Key           | Value                |
| ------------- | -------------------- |
| Content-Type  | application/json     |
| Authorization | Bearer \<token here> |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "message": "success",
    "error": null,
    "data": [
        {
            "code": "M-PESA",
            "name": "M-PESA - MOBILE MONEY"
        },
        {
            "code": "AIRTEL",
            "name": "AIRTEL"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

### **Resolve Bank Account** `(Not Available)`

## Make a POST call to the resolve account API&#x20;

<mark style="color:green;">`POST`</mark> `{{env_url}}/wallet/merchant/bank/transfer/request/resolve/account`

#### Headers

| Key           | Value                |
| ------------- | -------------------- |
| Context-Type  | application/json     |
| Authorization | Bearer \<token here> |
|               |                      |

#### Request Body

| Name                                             | Type   | Description                                                                                                            |
| ------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| bankCode<mark style="color:red;">\*</mark>       |        | 430000                                                                                                                 |
| countryCode<mark style="color:red;">\*</mark>    |        | KE                                                                                                                     |
| accountNumber<mark style="color:red;">\*</mark>  |        | 0690000032                                                                                                             |
| accountType<mark style="color:red;">\*</mark>    |        | personal                                                                                                               |
| documentType<mark style="color:red;">\*</mark>   | String | Customer’s mode of identity. This could be one of: \[`identityNumber`, `passportNumber`, `businessRegistrationNumber`] |
| businessId<mark style="color:red;">\*</mark>     | String | 133                                                                                                                    |
| documentNumber<mark style="color:red;">\*</mark> | String | 8801235111088                                                                                                          |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "status": true,
    "message": "Personal Account Verification attempted",
    "data": {
        "verified": true,
        "verificationMessage": "Account is verified successfully"
    }
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
This error occurs when the account number cannot be verified
{"error":"Bad request"}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
This error occurs when the right "countryCode" is not passed in
{
    "message": "Operation not allowed.",
    "error": "Operation not allowed",
    "data": null
}
```

{% endtab %}
{% endtabs %}

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/wallet/merchant/{businessId}/bank/transfer/v2/request`

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>KE</td></tr><tr><td>bankCode<mark style="color:red;">*</mark></td><td></td><td>430000</td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Sydney Mark</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>kbtr-3857-011-133-166993253334816</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>KES</td></tr><tr><td>bankName<mark style="color:red;">*</mark></td><td>String</td><td>Ubank Ltd</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>0690000032</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td>String</td><td>The short code of beneficiary bank account</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "id": 3,
    "amount": 1000,
    "payoutStatus": "PENDING",
    "requestId": "kbtr-3857-011-133-166993253334816",
    "narration": "certification",
    "country": "KE",
    "fee": 25,
    "serviceCode": "009",
    "bankCode": "430000",
    "bankName": "Ubank Ltd",
    "accountNumber": "0690000032",
    "accountName": "Pastor Bright"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "message": "A human readable error message",
    "error": "Bad Request",
    "data": null
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# ZMW Payout (new encryption)

### Summary

These APIs are used to initiate a ZMW payout

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Get Bank Lists**

## Make a GET call to the Bank List API&#x20;

<mark style="color:blue;">`GET`</mark> `{{env_url}}/wallet/merchant/bank/transfer/request/banks/ZMW`

#### Headers

| Key           | Value                |
| ------------- | -------------------- |
| Content-Type  | application/json     |
| Authorization | Bearer \<token here> |

{% tabs %}
{% tab title="200: OK " %}

```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"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/wallet/merchant/{businessId}/bank/transfer/v2/request`

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body (json)

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>ZM</td></tr><tr><td>bankCode<mark style="color:red;">*</mark></td><td></td><td>007</td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>10</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>kbtr-3857-011-133-166993253</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Hair design</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>ZMW</td></tr><tr><td>bankName<mark style="color:red;">*</mark></td><td>String</td><td>Citibank</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>0719593074</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "id": 589,
        "amount": 10.00,
        "payoutStatus": "PENDING",
        "requestId": "kbtr-3857-011-133-166993253",
        "narration": "Hair dressing",
        "country": "ZM",
        "fee": 26.00,
        "bankCode": "007",
        "bankName": "Citibank",
        "accountNumber": "0719593074",
        "accountName": "John Doe"
    }
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "message": "A human readable error message",
    "error": "Bad Request",
    "data": null
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# TZS Payout (new encryption)

### Summary

These APIs are used to initiate a TZS payout

| Momo Network | Service Code |
| ------------ | ------------ |
| Airtel       | AIRTEL\_TZA  |
| Tigo         | TIGO\_TZA    |
| Halotel      | HALOTEL\_TZA |
|              |              |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/wallet/merchant/bank/transfer/request/v2`

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - TZ</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td><p><strong>Allowed Payout types:</strong></p><p><strong>Bank</strong>: TZ-BANK-B2C</p><p><strong>Mobile Money</strong>: TZ-TIGO-B2C or TZ-AIRTEL-B2C</p></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 1000</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference - TZS-payout-3</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - TZS</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's account number - 255713998877</td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
    "country": "TZ",
    "serviceCode": "TZ-TIGO-B2C",
    "amount": 1000,
    "accountName": "John Doe",
    "accountNumber": "255713998877",
    "currency": "TZS",
    "requestId": "TZS-payout-3",
    "description": "Payout",
}
```

{% endtab %}

{% tab title="Second Tab" %}

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "id": 694,
    "amount": 1000.00,
    "payoutStatus": "PENDING",
    "requestId": "TZS-payout-3",
    "narration": "Payout",
    "country": "TZ",
    "fee": 826.00,
    "bankCode": "TZ-TIGO-B2C",
    "bankName": "TZ-TIGO-B2C",
    "accountNumber": "255713998877",
    "accountName": "John Doe"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "message": "A human readable error message",
    "error": "Bad Request",
    "data": null
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# CNY Payout (new encryption)

This documentation provides a comprehensive guide to integrating with Klasha's CNY Payout service. You can use this API to send money to China via various methods, including wallets (Alipay, WeChat),

Summary

Unlock seamless cross-border payments with the Payout API for CNY, enabling businesses/customers to send funds to recipients in China efficiently.

## Integration steps

The integration process involves the following key steps:

* **Generate a Bearer Token:** Authenticate to get your access token.
* **Create a Quotation:** Get a quote for the amount you wish to transfer. This quote will provide the exchange rate, fees, and a unique `quotationId`.
* **Get Bank Codes (for BANK\_ACCOUNT and BANK\_CARD):** Retrieve a list of supported banks and their codes.
* **Upload Attachment (B2B only):** For certain B2B transfers, you may need to upload supporting documents.
* **Initiate a Transfer:** Use the `quotationId` to execute the payout.
* **Listen for Status:** Use webhooks to receive real-time updates on the transaction status.

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

{% hint style="info" %}

### <mark style="color:orange;">Source wallet</mark>

<mark style="color:yellow;">All transfers would be debited from the respective payout currency wallet balance. Ensure you have sufficient balance before making any transfer request.</mark>
{% endhint %}

### Generate a Bearer Token

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### Create a Quote

To begin a transfer, you first need to create a quote. This will lock in the exchange rate and fees for a specific period.\
Payout quotation is created based on the category. Here is the list of categories

| Transfer Type | Service       | Service Code   |
| ------------- | ------------- | -------------- |
| B2C           | BANK\_ACCOUNT | Not applicable |
| B2B           | BANK\_ACCOUNT | Not applicable |
| C2C           | BANK\_ACCOUNT | Not applicable |
| B2B           | BANK\_CARD    | UNIONPAY       |
| C2C           | BANK\_CARD    | UNIONPAY       |
| C2C           | WALLET        | ALIPAY         |

#### Make a POST call to the create quotation API

<mark style="color:blue;">`POST`</mark> `{{env_url}}/wallet/merchant/quotation/v2`

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                |
| ------------- | -------------------- |
| Content-Type  | application/json     |
| Authorization | Bearer \<token here> |
| x-auth-token  | MERCHANT PUBLIC KEY  |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

#### Request body (plain)

{% tabs %}
{% tab title="Wallet - Alipay" %}

```json
{
    "serviceCode": "ALIPAY",
    "service": "WALLET",
    "transferType": "C2C",
    "destinationCurrency": "CNY",
    "sourceCurrency": "USD",
    "fundSource": "CASH",
    "destinationAmount": "10"
}
```

{% endtab %}

{% tab title="Union Pay Card - C2C" %}

```json
{
    "serviceCode": "UNIONPAY",
    "service": "BANK_CARD",
    "transferType": "C2C",
    "destinationCurrency": "CNY",
    "sourceCurrency": "USD",
    "fundSource": "CASH",
    "destinationAmount": "10"
}
```

{% endtab %}

{% tab title="Union Pay Card - B2B" %}

```json
{
    "serviceCode": "UNIONPAY",
    "service": "BANK_CARD",
    "transferType": "B2B",
    "destinationCurrency": "CNY",
    "sourceCurrency": "USD",
    "fundSource": "CASH",
    "destinationAmount": "10"
}
```

{% endtab %}

{% tab title="Bank Account - C2C" %}

```json
{
    "service": "BANK_ACCOUNT",
    "transferType": "C2C",
    "destinationCurrency": "CNY",
    "sourceCurrency": "USD",
    "fundSource": "CASH",
    "destinationAmount": "10"
}
```

{% endtab %}

{% tab title="Bank Account - B2B" %}

```json
{
    "service": "BANK_ACCOUNT",
    "transferType": "B2B",
    "destinationCurrency": "CNY",
    "sourceCurrency": "USD",
    "fundSource": "CASH",
    "destinationAmount": "10"
}
```

{% endtab %}
{% endtabs %}

#### Response

{% tabs %}
{% tab title="200 OK" %}

```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
}
```

{% endtab %}
{% endtabs %}

### **Get Bank Codes**

#### Get Bank codes by BANK\_ACCOUNT

<mark style="color:blue;">`GET`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/banks/CNY

#### Get Bank codes by BANK\_CARD

<mark style="color:blue;">`GET`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/banks/CNY?type=bank\_card

#### Headers

| Key           | Value                |
| ------------- | -------------------- |
| Content-Type  | application/json     |
| Authorization | Bearer \<token here> |

{% tabs %}
{% tab title="200: OK  - By BANK\_ACCOUNT" %}

```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 (中国农业银行)"
        }
   ...]
}    
```

{% endtab %}

{% tab title="200: OK - By BANK\_CARD" %}

```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"
        }
    ...]
}
```

{% endtab %}
{% endtabs %}

### Upload attachment

For B2B transfers, such as `ECOMMERCE` or `GOODS_PURCHASE`, you may need to upload supporting documents like invoices or customs declarations.

Supported Attachment Types

| Values                              |
| ----------------------------------- |
| COMMERCIAL\_DOCUMENTS               |
| LOGISTICS\_DOCUMENTS                |
| LOGISTICS\_COMMUNICATION\_DOCUMENTS |
| CONTRACT\_DOCUMENTS                 |
| ORDER\_DOCUMENTS                    |
| CUSTOMS\_DECLARATION                |
| OTHERS                              |

Make a POST call to upload file&#x20;

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/file

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                 |
| ------------- | --------------------- |
| Context-Type  | multipart/form-data   |
| Authorization | Bearer \<token here>  |
| x-auth-token  | MERCHANT PUBLIC TOKEN |

**Form Data:**

| Key              | Value                | Description                                                       |
| ---------------- | -------------------- | ----------------------------------------------------------------- |
| `file`           | (file)               | The actual file to be uploaded (e.g., `invoice.pdf`, `image.png`) |
| `purpose`        | Order Delivery       | The type of document being uploaded.                              |
| `attachmentType` | CUSTOMS\_DECLARATION | The type of document being uploaded.                              |

#### Response

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

### Initiate a transfer

Once you have a `quotationId` (and a `bankCode` if applicable), you can initiate the transfer. The request body will vary depending on the payout method and transfer type.

#### Make a POST call to the initiate transfer request API

<mark style="color:green;">`POST`</mark> `{{env_url}}`/wallet/merchant/{businessId}/bank/transfer/v2/request

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                |
| ------------- | -------------------- |
| Content-Type  | application/json     |
| x-auth-token  | MERCHANT PUBLIC KEY  |
| Authorization | Bearer \<token here> |

#### ID TYPE

<table data-header-hidden><thead><tr><th></th><th width="326.22265625"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>SENDER/SENDER_BUSINESS ID</strong></td><td><strong>Allowed Types</strong></td><td><strong>Transfer Types</strong></td><td><strong>Services</strong></td></tr><tr><td></td><td>ID_CARD<br>PASSPORT</td><td>C2C / B2C</td><td>BANK_CARD</td></tr><tr><td></td><td><p>ID_CARD</p><p>PASSPORT HONGKONG_ID_CARD</p><p>DRIVER_LICENSE</p><p>HONGKONG_MACAO_TAIWAN_PERMIT</p><p>ALIEN_RESIDENT_PERMIT EMPLOYEE_CARD OTHER</p></td><td>C2C</td><td>BANK_ACCOUNT</td></tr><tr><td></td><td>ID_CARD<br>PASSPORT</td><td>C2C</td><td>WALLET</td></tr><tr><td></td><td><p>BUSINESS_REGISTRATION_CERT</p><p>OTHER</p></td><td>B2C</td><td>BANK_ACCOUNT</td></tr><tr><td></td><td>BUSINESS_REGISTRATION_CERT</td><td>B2B</td><td>BANK_ACCOUNT</td></tr><tr><td></td><td></td><td></td><td></td></tr><tr><td><strong>RECEIVER/RECEIVER_BUSINESS ID</strong></td><td><strong>Allowed Types</strong></td><td><strong>Transfer Types</strong></td><td><strong>Services</strong></td></tr><tr><td></td><td>Receiver ID not compulsory</td><td>C2C / B2C</td><td>BANK_CARD</td></tr><tr><td></td><td>ID_CARD HONGKONG_MACAO_TAIWAN_PERMIT</td><td>C2C</td><td>BANK_ACCOUNT</td></tr><tr><td></td><td>Receiver ID not compulsory</td><td>C2C</td><td>WALLET</td></tr><tr><td></td><td>ID_CARD HONGKONG_MACAO_TAIWAN_PERMIT</td><td>B2C</td><td>BANK_ACCOUNT</td></tr><tr><td></td><td><p>UNIFIED_SOCIAL_CREDIT_ID</p><p>ID_CARD</p></td><td>B2B</td><td>BANK_ACCOUNT</td></tr></tbody></table>

ACCOUNT ID

| Values | **Description**      |
| ------ | -------------------- |
| MOBILE | ALIPAY and WECHATPAY |
| EMAIL  | ALIPAY only          |

#### Relationship

<table><thead><tr><th width="363.3046875">Allowed Values</th><th>Transfer Types</th><th>Services</th></tr></thead><tbody><tr><td>RELATIONSHIP not compulsory</td><td>C2C / B2C </td><td>BANK_CARD</td></tr><tr><td><p>SELF</p><p>SPOUSE</p><p>PARENTS SONS_AND_DAUGHTERS BROTHERS_AND_SISTERS</p><p>GRANDPARENTS</p><p>GRANDPARENTS_IN_LAW GRANDCHILDREN</p><p>MATERNAL_GRANDCHILDREN</p></td><td>C2C</td><td>BANK_ACCOUNT</td></tr><tr><td><p>SPOUSE</p><p>PARENTS</p><p>SONS_AND_DAUGHTERS</p></td><td>C2C</td><td>WALLET</td></tr><tr><td>EMPLOYEE</td><td>B2C</td><td>BANK_ACCOUNT</td></tr><tr><td>RELATIONSHIP not compulsory</td><td>B2B</td><td>BANK_ACCOUNT</td></tr></tbody></table>

#### Account Type

| Values     |
| ---------- |
| INDIVIDUAL |
| COMPANY    |

#### TradeType

| Values |
| ------ |
| GOODS  |

#### Purpose

| Allowed Values                                                                                          | **Transfer Type** | Services                       |
| ------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------ |
| <p>ECOMMERCE</p><p>GOODS\_PURCHASE</p>                                                                  | B2B               | BANK \_ACCOUNT                 |
| <p>SALARY<br>FAMILY\_SUPPORT<br>TRAVEL<br>INSURANCE<br>SERVICE\_CHARGES<br>PATENT\_ROYALTY<br>OTHER</p> | C2C/B2C           | BANK\_CARD                     |
| FAMILY\_SUPPORT                                                                                         | C2C               | <p>BANK\_ACCOUNT<br>WALLET</p> |
| SALARY                                                                                                  | B2C               | BANK\_ACCOUNT                  |

**Supported Product Categories for `GOODS_PURCHASE`**

When the **purpose** is `GOODS_PURCHASE`, you must provide a `productCategory`.&#x20;

The supported values are:&#x20;

`APPAREL`, `BEAUTY_PERSONAL_CARE`, `ELEC_COMPONENTS`, `TOYS_MODELS`, `GARDEN`, `FOOD`, `BOOKS_MEDIA`, `BABY`, `GIFTS_CRAFTS`, `AUTO_ACCESSORIES`, `HOME_GOODS`, `SPORTS_OUTDOORS`, `JEWELRY`, `ENTERTAINMENT`, `MUSICAL_INSTRUMENTS`, `ELECTRONICS`, `ANTIQUES_ART`, `WATCHES_EYEWEAR`, `MECHANICAL_PARTS`.

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

#### Request body (plain)

{% tabs %}
{% tab title="UNION PAY, C2C Card" %}

```json
{
    "bankCode": "01020000",
    "bankName": "Industrial and Commercial bank of China",
    "cardHolderName": "Cui Xia",
    "cardNumber": "6222040000030009",
    "creditAccountCountry": "CN",
    "purpose": "FAMILY_SUPPORT",
    "quotationId": 795,
    "receiverFirstName": "Receiver",
    "receiverLastName": "China",
    "requestId": "China_payout-union-10",
    "senderAddress": {
        "city": "Beijing",
        "countryCode": "CN",
        "postcode": "065001",
        "state": "Heilongjiang",
        "streetAddress": "West Street"
    },
    "senderFirstName": "Sender",
    "senderIdNumber": "1000000000",
    "senderIdType": "ID_CARD",
    "senderLastName": "China",
    "senderNationality": "CN"
}
```

{% endtab %}

{% tab title="UNION PAY, B2B Card" %}

```json
{
    "bankCode": "01020000",
    "bankName": "Industrial and Commercial bank of China",
    "cardHolderName": "Zhang Meizhen",
    "cardNumber": "6222040000030016",
    "creditAccountCountry": "CN",
    "purpose": "FAMILY_SUPPORT",
    "quotationId": 802,
    "receiverFirstName": "Receiver",
    "receiverLastName": "China",
    "requestId": "China_payout-union-b2c-10",
    "senderBusinessAddress": {
        "city": "Beijing",
        "countryCode": "CN",
        "postcode": "065001",
        "state": "Heilongjiang",
        "streetAddress": "West Street"
    },
    "senderBusinessRegisteredName": "KLASHA TECHNOLOGIES LTD",
    "senderFirstName": "Sender",
    "senderIdNumber": "1000000000",
    "senderIdType": "ID_CARDs",
    "senderLastName": "China",
    "senderNationality": "CN"
}
```

{% endtab %}

{% tab title="BANK ACCOUNT, C2C" %}

```json
{
    "accountName": "必须是中文",
    "accountNumber": "6222040000030016",
    "accountType": "INDIVIDUAL",
    "bankCode": "03010000",
    "bankName": "Bank of communications",
    "creditAccountCountry": "CN",
    "purpose": "FAMILY_SUPPORT",
    "quotationId": 794,
    "receiverFirstName": "test",
    "receiverIdNumber": "331081199609218031",
    "receiverIdType": "ID_CARD",
    "receiverLastName": "China",
    "receiverMobileNumber": "+8618612345678",
    "receiverRelationship": "SPOUSE",
    "requestId": "必须是中文-01",
    "senderAddress": {
        "city": "Beijing",
        "countryCode": "CN",
        "postcode": "065001",
        "state": "Heilongjiang",
        "streetAddress": "West Street"
    },
    "senderFirstName": "Sender",
    "senderIdNumber": "331081199609218031",
    "senderIdType": "ID_CARD",
    "senderLastName": "China",
    "senderNationality": "CN"
}
```

{% endtab %}

{% tab title="BANK ACCOUNT, B2C" %}

```json
{
    "accountName": "必须是中文",
    "accountNumber": "6222040000030016",
    "accountType": "INDIVIDUAL",
    "bankCode": "03010000",
    "bankName": "Bank of communications",
    "creditAccountCountry": "CN",
    "purpose": "SALARY",
    "quotationId": 804,
    "receiverFirstName": "test",
    "receiverIdNumber": "331081199609218031",
    "receiverIdType": "ID_CARD",
    "receiverLastName": "China",
    "receiverMobileNumber": "+8613699262597",
    "receiverRelationship": "EMPLOYEE",
    "requestId": "必须是中文-04",
    "senderBusinessAddress": {
        "city": "Beijing",
        "countryCode": "CN",
        "postcode": "065001",
        "state": "Heilongjiang",
        "streetAddress": "West Street"
    },
    "senderBusinessRegisteredName": "KLASHA TECHNOLOGIES LTD",
    "senderBusinessIdNumber": "91510104MA6A3FYD7B",
    "senderBusinessIdType": "BUSINESS_REGISTRATION_CERT"
}
```

{% endtab %}

{% tab title="BANK ACCOUNT, B2B" %}

```json
{
    "accountName": "上海弢汇商务咨询有限公司",
    "accountNumber": "31050161363900000210",
    "accountType": "COMPANY",
    "bankCode": "105100000017",
    "bankName": "Construction Bank of China",
    "creditAccountCountry": "CN",
    "document": {
        "attachments": [
            {
                "fileId": "595"
            }
        ],
        "orderCurrency": "CNY",
        "orderNumber": "001AD#",
        "orderTime": "2025-01-01",
        "products": [
            {
                "name": "FEMALE BAG",
                "quantity": "1",
                "website": "stbc.com"
            }
        ],
        "totalAmount": "100",
        "tradeType": "GOODS"
    },
    "purpose": "ECOMMERCE",
    "quotationId": 4786,
    "receiverBusinessAddress": {
        "city": "Shanghai",
        "countryCode": "CN",
        "postcode": "201599",
        "state": "Shanghai",
        "streetAddress": "Tingwei Highway"
    },
    "receiverBusinessIdNumber": "91310116MA1J9LE95D",
    "receiverBusinessIdType": "UNIFIED_SOCIAL_CREDIT_ID",
    "receiverBusinessMobileNumber": "+8613816932352",
    "receiverBusinessRegisteredName": "上海弢汇商务咨询有限公司",
    "requestId": "6222040000030016-03",
    "senderBusinessAddress": {
        "city": "Lagos",
        "countryCode": "NG",
        "postcode": "50001",
        "state": "Lagos State",
        "streetAddress": "Ligali"
    },
    "senderBusinessRegisteredName": "KLASHA TECHNOLOGIES LTD"
}
```

{% endtab %}

{% tab title="BANK ACCOUNT, B2B" %}

```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",
    "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"
        }
    }
}

```

{% endtab %}

{% tab title="ALIPAY" %}

```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"
}
```

{% endtab %}
{% endtabs %}

Fields specification: C2C, BANK\_CARD

| **Field**              | **Description**                                                                  |
| ---------------------- | -------------------------------------------------------------------------------- |
| `receiverFirstName`    | Receiver first name (必须是中文)                                                      |
| `receiverLastName`     | Receiver last name (必须是中文)                                                       |
| `senderFirstName`      | Sender first name                                                                |
| `senderLastName`       | Sender last name                                                                 |
| `senderNationality`    | Sender nationality                                                               |
| `senderIdType`         | Sender ID type. Please refer to the supported ID type list                       |
| `senderIdNumber`       | Sender ID number                                                                 |
| `senderAddress`        | Sender’s address. Refer to the address object                                    |
| `bankName`             | Name of the bank                                                                 |
| `bankCode`             | Bank ID                                                                          |
| `creditAccountCountry` | Bank’s country                                                                   |
| `cardNumber`           | Card number                                                                      |
| `cardHolderName`       | Name on card                                                                     |
| `quotationId`          | Quotation ID obtained after creating a quotation                                 |
| `purpose`              | Reason for the payout. Please refer to the supported purpose list                |
| `requestId`            | It’s a unique transaction reference will be used to uniquely identify a transfer |

Fields specification: C2C, BANK\_ACCOUNT

| **Field**              | **Description**                                                                  |
| ---------------------- | -------------------------------------------------------------------------------- |
| `receiverFirstName`    | Receiver first name (必须是中文)                                                      |
| `receiverLastName`     | Receiver last name (必须是中文)                                                       |
| `receiverMobileNumber` | Receiver mobile number. Format: +8613699262597                                   |
| `receiverEmail`        | Receiver email                                                                   |
| `receiverRelationship` | Relationship with the receiver                                                   |
| `receiverIdType`       | Receiver ID type. Please refer to the supported ID type list                     |
| `receiverIdNumber`     | Receiver ID number                                                               |
| `senderFirstName`      | Sender first name                                                                |
| `senderLastName`       | Sender last name                                                                 |
| `senderNationality`    | Sender nationality                                                               |
| `senderIdType`         | Sender ID type. Please refer to the supported ID type list                       |
| `senderIdNumber`       | Sender ID number                                                                 |
| `senderAddress`        | Sender address. Refer to the address object                                      |
| `bankName`             | Name of the bank                                                                 |
| `bankCode`             | Bank ID                                                                          |
| `creditAccountCountry` | Credit account bank’s country                                                    |
| `accountNumber`        | Credit account number                                                            |
| `accountName`          | Credit account name (必须是中文)                                                      |
| `accountType`          | Credit account type. Please refer to the supported account type list             |
| `quotationId`          | Quotation ID obtained after creating a quotation                                 |
| `purpose`              | Reason for the payout. Please refer to the supported purpose list                |
| `requestId`            | It’s a unique transaction reference will be used to uniquely identify a transfer |

Fields specification: C2C, WALLET (ALIPAY, WECHATPAY)

| **Field Name**         | **Description**                                                                                                                                                  |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `receiverIdNumber`     | Receive ID number                                                                                                                                                |
| `receiverFirstName`    | Receiver first name (必须是中文)                                                                                                                                      |
| `receiverLastName`     | Receiver last name (必须是中文)                                                                                                                                       |
| `receiverRelationship` | Relationship with the receiver                                                                                                                                   |
| `senderFirstName`      | Sender first name                                                                                                                                                |
| `senderLastName`       | Sender last name                                                                                                                                                 |
| `senderBirthDate`      | Sender date of birth                                                                                                                                             |
| `senderNationality`    | Sender nationality                                                                                                                                               |
| `senderIdType`         | Sender ID type. Please refer to the supported ID type list                                                                                                       |
| `senderIdNumber`       | Sender ID number                                                                                                                                                 |
| `senderAddress`        | Sender address. Refer to the address object                                                                                                                      |
| `creditAccountCountry` | Credit account bank’s country                                                                                                                                    |
| `accountNumber`        | Credit account number - this is either an email or mobile number for ALIPAY or a mobile number for WECHAT PAY. The login account ID to WeChat or Alipay account. |
| `accountId`            | The account ID type of either the WeChat or Alipay account. Please refer to the supported account ID type.                                                       |
| `quotationId`          | Quotation ID obtained after creating a quotation                                                                                                                 |
| `purpose`              | Reason for the payout. Please refer to the supported purpose list                                                                                                |
| `requestId`            | It’s a unique transaction reference will be used to uniquely identify a transfer                                                                                 |

Fields specification: B2B, BANK\_ACCOUNT

| **Field**                        | **Description**                                                                  |
| -------------------------------- | -------------------------------------------------------------------------------- |
| `receiverFirstName`              | Receiver first name (必须是中文)                                                      |
| `receiverLastName`               | Receiver last name (必须是中文)                                                       |
| `receiverBusinessMobileNumber`   | Receiver mobile number. Format: +86 18612345678                                  |
| `receiverEmail`                  | Receiver email                                                                   |
| `receiverBusinessIdType`         | Receiver ID type. Please refer to the supported ID type list                     |
| `receiverBusinessIdNumber`       | Receiver ID number                                                               |
| `receiverBusinessRegisteredName` | Receiver business name. Chinese characters are required if it's in China         |
| `receiverBusinessAddress`        | Receiver business address                                                        |
| `senderFirstName`                | Sender first name                                                                |
| `senderLastName`                 | Sender last name                                                                 |
| `senderBusinessAddress`          | Sender business address. Refer to the address object                             |
| `senderBusinessRegisteredName`   | Sender business name                                                             |
| `bankName`                       | Name of the bank                                                                 |
| `bankCode`                       | Bank ID                                                                          |
| `creditAccountCountry`           | Credit account bank’s country                                                    |
| `accountNumber`                  | Credit account number                                                            |
| `accountName`                    | Credit account name (必须是中文)                                                      |
| `accountType`                    | Credit account type. Please refer to the supported account type list             |
| `quotationId`                    | Klasha quotation ID                                                              |
| `purpose`                        | Reason for the payout. Please refer to the supported purpose list                |
| `requestId`                      | It’s a unique transaction reference will be used to uniquely identify a transfer |
| `document`                       | See: Document                                                                    |

Fields specification: Document

| **Field**       | **Description**                         |
| --------------- | --------------------------------------- |
| `totalAmount`   | Total amount                            |
| `orderNumber`   | Order number                            |
| `orderTime`     | Order time                              |
| `orderCurrency` | Order currency                          |
| `logistics`     | See: Logistics                          |
| `tradeType`     | Please refer to the supported TradeType |
| `products`      | `List<Product>` Product                 |
| `attachments`   | `List<Attachment>` See: Attachment      |

Fields specification: Product

| **Field**  | **Description** |
| ---------- | --------------- |
| `name`     | Product name    |
| `quantity` | Quantity        |

Fields specification: Attachment

| **Field** | **Description** |
| --------- | --------------- |
| `fileId`  | Klasha file ID  |

Fields specification: Logistics

| **Field** | **Description**        |
| --------- | ---------------------- |
| `company` | Logistics company      |
| `orderNo` | Logistics order number |

Fields specification: Address

| **Field**       | **Description**   |
| --------------- | ----------------- |
| `city`          | City              |
| `streetAddress` | Street address    |
| `countryCode`   | Country code      |
| `postcode`      | Postcode          |
| `state`         | Province or state |

#### Response

{% tabs %}
{% tab title="200: OK" %}

```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"
}
```

{% endtab %}
{% endtabs %}

### Listen for a status response

When a transfer is initiated, it could take a few seconds or minutes to be processed. This is why we recommend relying on webhooks for verification as opposed to polling.

Once a transfer is processed, we send the final status of the transfer as a POST request to your webhook URL

{% tabs %}
{% tab title="Successful Webhook" %}

```json
{
  "data": {
    "reference": "kbtr-3857-011-null-166993253331236",
    "createdAt": "2023-03-28T23:01:45.336",
    "amount": 1000,
    "accountName": "Pastor Bright",
    "narration": "certification",
    "name": "Steph and sons",
    "currency": "NGN",
    "bankName": "ACCESS BANK NIGERIA",
    "accountNumber": "0690000032",
    "status": "successful"
  },
  "event": "payout"
}
```

{% endtab %}

{% tab title="Failed Webhook" %}

```json
{
  "data": {
    "reference": "kbtr-3857-011-null-166993253334816",
    "createdAt": "2023-03-28T23:01:45.336",
    "amount": 1000,
    "accountName": "Pastor Bright",
    "narration": "certification",
    "name": "Steph and sons",
    "currency": "NGN",
    "bankName": "ACCESS BANK NIGERIA",
    "accountNumber": "0690000032",
    "status": "failed"
  },
  "event": "payout"
}
```

{% endtab %}
{% endtabs %}

The possible statuses are listed and described in the following table:

| Status                                       | Description                                                                   |
| -------------------------------------------- | ----------------------------------------------------------------------------- |
| <mark style="color:green;">successful</mark> | This is sent when the transfer is successful                                  |
| <mark style="color:red;">failed</mark>       | This is sent when the transfer fails                                          |
| <mark style="color:orange;">pending</mark>   | This transfer is still in progress. Please wait for either success or failed. |

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.

###


# MoMo Payout

## Summary

Send money locally with Klasha to mobile money wallets in Africa.

## Coverage

{% columns %}
{% column %}
[ZMW](/transfers/momo-payout/zmw-new-encryption)

[RWF](/transfers/momo-payout/rwf-new-encryption)

[XAF - Gabon](/transfers/momo-payout/xaf-gabon-new-encryption)

[UGX](/transfers/momo-payout/ugx-new-encryption)

[XOF - Senegal](/transfers/momo-payout/xof-senegal-new-encryption)

[TZS](/transfers/momo-payout/tzs-new-encryption)

{% endcolumn %}

{% column %}
[KES](/transfers/payout/kes-payout-new-encryption)

[SLL](/transfers/momo-payout/sll-new-encryption)

[CDF](/transfers/momo-payout/cdf-democratic-republic-of-the-congo-new-encryption)

[XOF - Ivory Coast](/transfers/momo-payout/xof-ivory-coast-new-encryption)

[XAF - Republic of the Congo](/transfers/momo-payout/xaf-republic-of-the-congo-new-encryption)

[<br>](/transfers/momo-payout/tzs-new-encryption)
{% endcolumn %}
{% endcolumns %}


# ZMW (new encryption)

### Summary

These APIs are used to initiate a ZMW Momo payout

| Momo Network | Service Code   |
| ------------ | -------------- |
| Mtn          | MTN\_MOMO\_ZMB |
| Zamtel       | ZAMTEL\_ZMB    |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td>String</td><td>Country of payout - ZM</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td>String</td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td>String</td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - ZMW</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type<mark style="color:red;">*</mark></td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>payoutType<mark style="color:red;">*</mark></td><td>String</td><td>Allowed value: USD_MOMO</td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "ZM",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "MTN_MOMO_ZMB",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "ZMW",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# RWF (new encryption)

### Summary

These APIs are used to initiate a RWF Momo payout

| Momo Network | Service Code   |
| ------------ | -------------- |
| Mtn          | MTN\_MOMO\_RWA |
| Airtel       | AIRTEL\_RWA    |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - RW</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - RWF</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "RW",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "MTN_MOMO_RWA",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "RWF",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# UGX (new encryption)

### Summary

These APIs are used to initiate a UGX Momo payout

| Momo Network | Service Code      |
| ------------ | ----------------- |
| Mtn          | MTN\_MOMO\_UGA    |
| Airtel       | AIRTEL\_OAPI\_UGA |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - UG</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - UGX</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "UG",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "AIRTEL_OAPI_UGA",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "ZMW",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# GHS (new encryption)

### Summary

These APIs are used to initiate a GHS Momo payout

| Momo Network | Service Code    |
| ------------ | --------------- |
| Mtn          | MTN\_MOMO\_GHA  |
| Vodafone     | VODAFONE\_GHA   |
| Airtel       | AIRTELTIGO\_GHA |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - GH</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - ZMW</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "GH",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "VODAFONE_GHA",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "GHS",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# NGN (new encryption)

### Summary

These APIs are used to initiate a NGN Momo payout

| Momo Network | Service Code   |
| ------------ | -------------- |
| Mtn          | MTN\_MOMO\_NGA |
| Airtel       | AIRTEL\_NGA    |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - NG</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - NGN</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "NG",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "MTN_MOMO_NGA",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "NGN",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# XOF Ivory Coast (new encryption)

### Summary

These APIs are used to initiate a XOF Ivory Coast Momo payout

| Momo Network | Service Code   |
| ------------ | -------------- |
| Mtn          | MTN\_MOMO\_CIV |
| Orange       | ORANGE\_CIV    |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - CI</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - XOF</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "CI",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "ORANGE_CIV",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "XOF",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# XOF Benin (new encryption)

### Summary

These APIs are used to initiate a XOF Benin Momo payout

| Momo Network | Service Code   |
| ------------ | -------------- |
| Mtn          | MTN\_MOMO\_BEN |
| Moov         | MOOV\_BEN      |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - BJ</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - XOF</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "BJ",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "MTN_MOMO_BEN",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "XOF",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# XOF Senegal (new encryption)

### Summary

These APIs are used to initiate a XOF Senegal Momo payout

| Momo Network | Service Code |
| ------------ | ------------ |
| Orange       | ORANGE\_SEN  |
| Free         | FREE\_SEN    |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - SN</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - XOF</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "SN",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "ORANGE_SEN",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "XOF",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# XOF Burkina Faso (new encryption)

### Summary

These APIs are used to initiate a XOF Burkina Faso Momo payout

| Momo Network | Service Code |
| ------------ | ------------ |
| Moov         | MOOV\_BFA    |
| Orange       | ORANGE\_BFA  |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - BF</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - XOF</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "BF",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "ORANGE_BFA",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "XOF",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# XAF Cameroon (new encryption)

### Summary

These APIs are used to initiate a XAF Cameroon Momo payout

| Momo Network | Service Code   |
| ------------ | -------------- |
| Mtn          | MTN\_MOMO\_CMR |
| Orange       | ORANGE\_CMR    |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - CM</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - XAF</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "CM",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "ORANGE_CMR",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "XAF",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

```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"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# XAF Gabon (new encryption)

### Summary

These APIs are used to initiate a XAF Gabon Momo payout

| Momo Network | Service Code |
| ------------ | ------------ |
| Airtel       | AIRTEL\_GAB  |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - GA</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - XAF</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "GA",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "AIRTEL_GAB",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "XAF",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# XAF Republic of the Congo (new encryption)

### Summary

These APIs are used to initiate a XAF Republic of the Congo Momo payout

| Momo Network | Service Code   |
| ------------ | -------------- |
| Mtn          | MTN\_MOMO\_COG |
| Airtel       | AIRTEL\_COG    |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - CG</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - XAF</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "CG",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "MTN_MOMO_COG",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "CDF",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# CDF Democratic Republic of the Congo (new encryption)

### Summary

These APIs are used to initiate a CDF Democratic Republic of the Congo Momo payout

| Momo Network | Service Code        |
| ------------ | ------------------- |
| Orange       | ORANGE\_COD         |
| Airtel       | AIRTEL\_COD         |
| Vodacom      | VODACOM\_MPESA\_COD |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - CD</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - CDF</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "CD",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "AIRTEL_COD",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "CDF",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# TZS (new encryption)

### Summary

These APIs are used to initiate a TZS Momo payout

| Momo Network | Service Code |
| ------------ | ------------ |
| Airtel       | AIRTEL\_TZA  |
| Tigo         | TIGO\_TZA    |
| Halotel      | HALOTEL\_TZA |
|              |              |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - TZ</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - TZS</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "TZ",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "AIRTEL_TZA",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "XOF",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# MWK (new encryption)

### Summary

These APIs are used to initiate a MWK Momo payout

| Momo Network | Service Code |
| ------------ | ------------ |
| Tnm          | TNM\_MWI     |
| Airtel       | AIRTEL\_MWI  |
|              |              |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - MW</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - MWK</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "MW",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "AIRTEL_MWI",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "MWK",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# MZN (new encryption)

### Summary

These APIs are used to initiate a MZN Momo payout

| Momo Network | Service Code |
| ------------ | ------------ |
| Vodacom      | VODACOM\_MOZ |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - MZ</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - MZN</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "MZ",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "VODACOM_MOZ",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "MZN",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# KES (new encryption)

### Summary

These APIs are used to initiate a KES Momo payout

| Momo Network | Service Code |
| ------------ | ------------ |
| Mpesa        | MPESA\_KEN   |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td>String</td><td>Country of payout - KE</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td>String</td><td>Receiver phone Network</td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td>String</td><td>Amount to be sent to receiver</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's Name</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Payout Description </td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout e.g KES</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type<mark style="color:red;">*</mark></td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>payoutType<mark style="color:red;">*</mark></td><td>String</td><td>Allowed value: USD_MOMO</td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "KE",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "MPESA_KEN",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "KES",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# SLL (new encryption)

### Summary

These APIs are used to initiate a SLL Momo payout

| Momo Network | Service Code |
| ------------ | ------------ |
| Orange       | ORANGE\_SLE  |

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

### Integration steps

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api#encryption-algorithm)

### **Merchant Payout request**

## Make a POST call to the Merchant payout request API

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/v3?encryption=NEW

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| Content-Type  | application/json         |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

**Request body (plain)**

#### Request Body

<table><thead><tr><th width="264">Name</th><th width="160">Type</th><th>Description</th></tr></thead><tbody><tr><td>country<mark style="color:red;">*</mark></td><td></td><td>Country of payout - SL</td></tr><tr><td>serviceCode<mark style="color:red;">*</mark></td><td></td><td></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td></td><td>Amount - 100</td></tr><tr><td>accountName<mark style="color:red;">*</mark></td><td></td><td>Receiver's Name - John Doe</td></tr><tr><td>requestId<mark style="color:red;">*</mark></td><td>String</td><td>Unique request's reference</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>Merchant's description - Payout</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Currency of payout - SLL</td></tr><tr><td>accountNumber<mark style="color:red;">*</mark></td><td>String</td><td>Receiver's phone number - 260973456789</td></tr><tr><td>type</td><td>String</td><td>Allowed value: mobile_money</td></tr><tr><td>walletId</td><td>Integer</td><td>Business wallet ID</td></tr><tr><td>payoutType</td><td>String</td><td>Allowed value: USD_MOMO</td></tr><tr><td>debitAmount</td><td>String</td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="Plain Request" %}

```json
{
  "country": "SL",
  "amount": "100",
  "accountName": "test sample",
  "serviceCode": "ORANGE_SLE",
  "requestId": "tranf-36ac6398-fa2c-407d-84c5-c40c91091a98",
  "description": "none for now",
  "currency": "SLL",
  "accountNumber": "260973456789",
  "type": "mobile_money",
  "debitAmount": "10",
  "walletId": 12,
  "payoutType": "USD_MOMO"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    "status": "error",
    "message": "Unable process payout. Contact support"
}
```

{% endtab %}
{% endtabs %}

### **Query payout status**

Make a [call](/transfers/payout#polling-transfer-statuses) to fetch status of initiated payouts.


# Klasha Wire API

### Summary

Give merchants the ability to send out funds from their collection balance via API using our internal Klasha rates.

**Coverage**

See all available currencies[ here](/transfers/currency-coverage)

You can transfer money in four easy steps:

1. Generate a bearer token
2. Create a beneficiary
3. Generate a quote for the beneficiary
4. Initiate a payment

{% hint style="info" %}
Before you begin!

* [Link](https://api.postman.com/collections/25963887-51087ebf-1aa8-4573-9259-9965bf043717?access_key=PMAT-01HF4CJMVK7BG3QSRHYH1CKE6E) to the Postman collection
* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

<details>

<summary>Encryption Algorithm</summary>

You need to encrypt the entire create transfer payload that we specify on the previous point (here). In order to encrypt the body correctly, you’d need the encryptionKey (that you can obtain following this guide here). We also provided an example in Java of the encryption algorithm in order to help you.

```java
public static String encryptCBC(String stringToEncrypt, String encryptionkey) {
    try {
        SecureRandom sr = new SecureRandom();
        byte[] salt = new byte[8];
        sr.nextBytes(salt);
        final byte[][] keyAndIV =GenerateKeyAndIV(32, 16, 1, salt, password.getBytes(StandardCharsets.UTF_8),
                MessageDigest.getInstance("MD5"));
        Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
        cipher.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(keyAndIV[0], "AES"), new IvParameterSpec(keyAndIV[1]));
        byte[] encryptedData = cipher.doFinal(stringToEncrypt.getBytes(StandardCharsets.UTF_8));
        byte[] prefixAndSaltAndEncryptedData = new byte[16 + encryptedData.length];
        // Copy prefix (0-th to 7-th bytes)
        System.arraycopy("Salted__".getBytes(StandardCharsets.UTF_8), 0, prefixAndSaltAndEncryptedData, 0, 8);
        // Copy salt (8-th to 15-th bytes)
        System.arraycopy(salt, 0, prefixAndSaltAndEncryptedData, 8, 8);
        // Copy encrypted data (16-th byte and onwards)
        System.arraycopy(encryptedData, 0, prefixAndSaltAndEncryptedData, 16, encryptedData.length);
        return Base64.getEncoder().encodeToString(prefixAndSaltAndEncryptedData);
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}




public static byte[][] GenerateKeyAndIV(int keyLength, int ivLength, int iterations, byte[] salt, byte[] password, MessageDigest md) {

    int digestLength = md.getDigestLength();
    int requiredLength = (keyLength + ivLength + digestLength - 1) / digestLength * digestLength;
    byte[] generatedData = new byte[requiredLength];
    int generatedLength = 0;

    try {
        md.reset();

        // Repeat process until sufficient data has been generated
        while (generatedLength < keyLength + ivLength) {

            // Digest data (last digest if available, password data, salt if available)
            if (generatedLength > 0)
                md.update(generatedData, generatedLength - digestLength, digestLength);
            md.update(password);
            if (salt != null)
                md.update(salt, 0, 8);
            md.digest(generatedData, generatedLength, digestLength);

            // additional rounds
            for (int i = 1; i < iterations; i++) {
                md.update(generatedData, generatedLength, digestLength);
                md.digest(generatedData, generatedLength, digestLength);
            }

            generatedLength += digestLength;
        }

        // Copy key and IV into separate byte arrays
        byte[][] result = new byte[2][];
        result[0] = Arrays.copyOfRange(generatedData, 0, keyLength);
        if (ivLength > 0)
            result[1] = Arrays.copyOfRange(generatedData, keyLength, keyLength + ivLength);

        return result;

    } catch (DigestException e) {
        throw new RuntimeException(e);

    } finally {
        // Clean out temporary data
        Arrays.fill(generatedData, (byte) 0);
    }
}


```

</details>

### Integration step

**Generate a bearer token**

Using the Token endpoint on the Postman collection, the token can be obtained from the headers under the header name: <mark style="color:red;">token</mark>

<mark style="color:green;">`POST`</mark> `{{env_url}}/auth/account/v2/login`

#### Request Body

| Name                                       | Type     | Description |
| ------------------------------------------ | -------- | ----------- |
| username<mark style="color:red;">\*</mark> | username |             |
| password<mark style="color:red;">\*</mark> | password |             |

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}
{% endtabs %}

**Create a beneficiary**

## Make a POST call to the Create Merchant Beneficiary API to create your beneficiary

<mark style="color:green;">`POST`</mark> `{{env_url}}/merchant/merchantbeneficiary/create`

Make a <mark style="color:green;">POST</mark> call to the Create Merchant Beneficiary API to create your beneficiary. See an  example of the payload you need to encrypt and send in order to create a beneficiary

The encrypted JSON body for the request can be found in the Postman [link](https://api.postman.com/collections/25963887-51087ebf-1aa8-4573-9259-9965bf043717?access_key=PMAT-01HF4CJMVK7BG3QSRHYH1CKE6E).

You’d need to pass, as header the `x-auth-token`. This can be obtained from your merchant dashboard → Settings → Generate API keys → **Merchant public key.**

#### Headers

| Name                                            | Value               |
| ----------------------------------------------- | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | Bearer {{token}}    |
| x-auth-token                                    | MERCHANT PUBLIC KEY |

#### Request Body

| Name                                                 | Type | Description              |
| ---------------------------------------------------- | ---- | ------------------------ |
| accountNumber<mark style="color:red;">\*</mark>      |      | 1234567890               |
| bankName<mark style="color:red;">\*</mark>           |      | Bank Name                |
| bankAddress<mark style="color:red;">\*</mark>        |      | Bank Address             |
| beneficiaryName<mark style="color:red;">\*</mark>    |      | Beneficiary Name         |
| beneficiaryAddress<mark style="color:red;">\*</mark> |      | Beneficiary Address      |
| country<mark style="color:red;">\*</mark>            |      | Country Name             |
| countryCode<mark style="color:red;">\*</mark>        |      | US                       |
| currency<mark style="color:red;">\*</mark>           |      | USD                      |
| phone<mark style="color:red;">\*</mark>              |      | phone number             |
| swiftCode<mark style="color:red;">\*</mark>          |      | SWFT1234                 |
| narration<mark style="color:red;">\*</mark>          |      | clothes                  |
| email<mark style="color:red;">\*</mark>              |      | <your.email@example.com> |
| routingNumber<mark style="color:red;">\*</mark>      |      | 12345                    |
| iban<mark style="color:red;">\*</mark>               |      | 045                      |

{% tabs %}
{% tab title="Encrypted Request " %}

```json
{
  "message": "encrypted request"
}
```

{% endtab %}

{% tab title="201: Created " %}

```json
Response
{
    "message": "success",
    "error": null,
    "data": {
        "accountNumber": "1234567890",
        "bankName": "Bank Name",
        "token": "d95a6930-233f-4699-a11f-0d1337a34cce",
        "beneficiaryName": "Beneficiary Name",
        "id": 345
    }
}
```

{% endtab %}
{% endtabs %}

**Generate a quote**

## Make a POST call to the Create Quote API to generate your quote

<mark style="color:green;">`POST`</mark> `{{env_url}}/wallet/wire/generate/quote`

Make a POST call to the Create Quote API to generate your quote. See an example of the payload you need to encrypt and send in order to generate your quote.

The encrypted JSON body for the request can be found in the Postman [link](https://api.postman.com/collections/25963887-51087ebf-1aa8-4573-9259-9965bf043717?access_key=PMAT-01HF4CJMVK7BG3QSRHYH1CKE6E) as well as other APIs.

You’d need to pass, as header the `x-auth-token`. This can be obtained from your merchant dashboard → Settings → Generate API keys → **Merchant public key.**

#### Headers

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

#### Request Body

| Name                                                  | Type | Description                                       |
| ----------------------------------------------------- | ---- | ------------------------------------------------- |
| sourceCurrency<mark style="color:red;">\*</mark>      |      | NGN                                               |
| destinationCurrency<mark style="color:red;">\*</mark> |      | USD                                               |
| beneficiary<mark style="color:red;">\*</mark>         |      | beneficiar87954c4f-736a-4e09-b588-76ab9c13bafeyId |
| destinationAmount<mark style="color:red;">\*</mark>   |      | 1000.00                                           |

{% tabs %}
{% tab title="Encrypted Request" %}

```json
{
  "message": "encrypted request"
}
```

{% endtab %}

{% tab title="201: Created " %}

```json
Response
{
    "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"
    }
}
```

{% endtab %}
{% endtabs %}

**Initiate a payment**

## Make a POST call to the Initiate Payment API&#x20;

<mark style="color:green;">`POST`</mark> `{{env_url}}/wallet/wire/initiate`

Make a POST call to the Initiate Payment API to convert your quote into an initialised payment.&#x20;

See an example of the payload you need to encrypt and send in order to generate your quote.

The encrypted JSON body for the request can be found in the Postman [link](https://api.postman.com/collections/25963887-51087ebf-1aa8-4573-9259-9965bf043717?access_key=PMAT-01HF4CJMVK7BG3QSRHYH1CKE6E) as well as other APIs

You’d need to pass, as header the `x-auth-token`. This can be obtained from your merchant dashboard → Settings → Generate API keys → **Merchant public key.**

#### Headers

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

#### Request Body

| Name                                          | Type | Description                                     |
| --------------------------------------------- | ---- | ----------------------------------------------- |
| quoteToken<mark style="color:red;">\*</mark>  |      | 842dcd42-8f95-4a3b-a5f3-07a3d0416119            |
| beneficiary<mark style="color:red;">\*</mark> |      | 87954c4f-736a-4e09-b588-76ab9c13bafe            |
| narration<mark style="color:red;">\*</mark>   |      | School fees                                     |
| invoiceUrl<mark style="color:red;">\*</mark>  |      | [www.invoiceURL.com](http://www.invoiceURL.com) |

{% tabs %}
{% tab title="Encrypted Request" %}

```json
{
  "message": "encrypted request"
}
```

{% endtab %}

{% tab title="201: Created " %}

```json
Response
{
    "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"
    }
}
```

{% endtab %}
{% endtabs %}

**Fetch all your payments**

## Make a GET call to the Fetch All API

<mark style="color:blue;">`GET`</mark> `{{env_url}}/wallet/wire/fetch/all`

Make a GET call to the Fetch All API to retrieve all your previously initiated wire payments.

The URL can be found in the Postman [link](https://api.postman.com/collections/25963887-51087ebf-1aa8-4573-9259-9965bf043717?access_key=PMAT-01HF4CJMVK7BG3QSRHYH1CKE6E) well as other APIs

You’d need to pass, as header the `x-auth-token`. This can be obtained from your merchant dashboard → Settings → Generate API keys → **Merchant public key.**

#### Headers

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

{% tabs %}
{% tab title="200: OK " %}

```json
Response
{
    "message": "success",
    "error": null,
    "data": [
         {
            "id": 46,
            "sourceCurrency": "NGN",
            "sourceAmount": 1628664.50,
            "destinationCurrency": "USD",
            "destinationAmount": 1000.00,
            "narration": "Test",
            "destinationFees": 27.50,
            "sourceFees": 44788.27,
            "rate": 0.000614,
            "klashaWireStatus": "PENDING",
            "transactionReference": "KWire-296aac06-f425-4d43-9e4c-611247959a88",
            "merchantBeneficiary": "e0595f0b-16b4-4b62-a317-fa00af40a7ec",
            "quoteToken": "71a6aff6-5c23-41e3-8b85-6918cf92ead6",
            "createdAt": "2024-07-09T19:00:52.218",
            "updatedAt": "2024-07-09T19:02:14.863"
        },
        {
            "id": 60,
            "sourceCurrency": "NGN",
            "sourceAmount": 1631321.37,
            "destinationCurrency": "USD",
            "destinationAmount": 1000.00,
            "narration": "Test",
            "destinationFees": 27.50,
            "sourceFees": 44861.34,
            "rate": 0.000613,
            "klashaWireStatus": "PENDING",
            "transactionReference": "KWire-bae3f6dc-aaec-4e6a-a963-cffe1a3899c5",
            "merchantBeneficiary": "633b70a6-da15-4bc5-b0ec-1eda041245e2",
            "quoteToken": "dbd4e976-ad5e-4555-aee5-d4afa59849c5",
            "createdAt": "2024-07-11T14:40:11.91",
            "updatedAt": "2024-07-11T14:41:29.237"
        }
     ...
    ]
}
```

{% endtab %}
{% endtabs %}

**Fetch a single payment by reference**

## Fetch by reference API to retrieve all your previously initiated wire payments.

<mark style="color:blue;">`GET`</mark> `{{env_url}}/wallet/wire/fetch/by/reference/<ref>`

Make a GET call to the Fetch by reference API to retrieve all your previously initiated wire payments.

The URL can be found in the Postman [link ](https://api.postman.com/collections/25963887-51087ebf-1aa8-4573-9259-9965bf043717?access_key=PMAT-01HF4CJMVK7BG3QSRHYH1CKE6E)well as other APIs

You’d need to pass the `transactionReference` you obtained when you initiated the payment, as a path variable.

You’d need to pass, as header the `x-auth-token`. This can be obtained from your merchant dashboard → Settings → Generate API keys → **Merchant public key.**

#### Headers

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

{% tabs %}
{% tab title="200: OK " %}

```json
Response
{
    "message": "success",
    "error": null,
    "data": {
            "id": 46,
            "sourceCurrency": "NGN",
            "sourceAmount": 1628664.50,
            "destinationCurrency": "USD",
            "destinationAmount": 1000.00,
            "narration": "Test",
            "destinationFees": 27.50,
            "sourceFees": 44788.27,
            "rate": 0.000614,
            "klashaWireStatus": "PENDING",
            "transactionReference": "KWire-296aac06-f425-4d43-9e4c-611247959a88",
            "merchantBeneficiary": "e0595f0b-16b4-4b62-a317-fa00af40a7ec",
            "quoteToken": "71a6aff6-5c23-41e3-8b85-6918cf92ead6",
            "createdAt": "2024-07-09T19:00:52.218",
            "updatedAt": "2024-07-09T19:02:14.863"
    }
}
```

{% endtab %}
{% endtabs %}

&#x20;

{% hint style="info" %}
Notes

Klasha Wire Statuses

When you generate a quote and initiate a payment, one of the field in the response body is <mark style="color:red;">`klashaWireStatus`</mark>, here you can find all the possible cases and explanation:

* <mark style="color:orange;">PENDING</mark>: this is the status when a payment just get initialised through the API. This is not a final status.
* <mark style="color:yellow;">PROCESSING</mark>: this is when Klasha is actually processing the payment itself. This is not a final status.
* <mark style="color:green;">SUCCESSFUL</mark>: the klasha wire payment was executed successfully. Final status.
* <mark style="color:red;">CANCELLED</mark>: The payment has been cancelled from the Klasha finance/operation team, in result of previous communication with the merchant. Final status.
* <mark style="color:red;">FAILED</mark>: the initiated wire payments failed to be executed. Final status.
  {% endhint %}

**Quote expiry logic**

After you proceeded generating your quote, you can now convert that quote into an initiated payment.

The initiation would be successful if the quote is NOT expired.

A quote does not expire because of time but just if the rate in our system changed.

{% hint style="info" %}
**Example**

&#x20;If you generate a quote on 1st Oct at 11am and at 3pm the rate changes, you can convert your quote into a initiated payment until 2:59:59pm. Right after, then the rate get updated at 3pm, you won’t be able to initiate a payment with that quote and you’d have to generate a new quote.
{% endhint %}

In case you try to initiate a payment with an expired quote, you’d have a Bad Request response with the the following body:

```json
{
    "message": "Quote has expired or does not exist!",
    "error": "QuoteNotFoundException",
    "data": null
}
```


# Swap API

Our Swap API give merchants the ability to swap funds between their wallets via API using our internal Klasha rates.

### Integration step

You can swap money in three easy steps:

1. Generate a bearer token (see [authentication](https://developers.klasha.com/~/revisions/9BaXSBqKHuDCUL5Mcat0/overview/authentication))
2. Generate a quote for the swap
3. Confirm swap

{% hint style="info" %}
All requests sent to these APIs must be encrypted. The encryption Algorithm can be gotten [here](https://developers.klasha.com/transfers/klasha-wire-api#encryption-algorithm)
{% endhint %}

### **Generate a bearer token**

Use the authentication API [here](https://developers.klasha.com/~/revisions/9BaXSBqKHuDCUL5Mcat0/overview/authentication) to generate a bearer token and set your `Authorization` header to the token obtained.

You’d also need to set your public key as header the `x-auth-token`. This can be obtained from your merchant dashboard → Settings → Generate API keys → **Merchant public key.**

In summary, the request headers of all the requests sent to the APIs below should contain the data specified below;

| Name          | Value               | Description                                 |
| ------------- | ------------------- | ------------------------------------------- |
| Authorization | Bearer {{token}}    | token generated from the authentication API |
| x-auth-token  | MERCHANT PUBLIC KEY | public key retrieved from the dashboard     |

### **Generate a quote**

> <mark style="color:yellow;">**POST**</mark> - <mark style="color:$primary;">{{env\_url}}/wallet/swap/generate/quote</mark>

Call the Create Quote API to generate your quote. See an example of the payload you need to encrypt and send in order to generate your quote.

The encrypted JSON body for the request can be found in the Postman [link](https://api.postman.com/collections/8963555-81a5d469-e054-4630-b7af-827b6d261eef?access_key=PMAT-01J546H4YV5MTX9ZDYTMET8VG7) as well as other APIs.

#### Headers&#x20;

> As specified above

#### Request Body (plain)

| Name                                                  | Type   | Description                                                                                                                  |
| ----------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| sourceCurrency<mark style="color:red;">\*</mark>      | String | Example: NGN                                                                                                                 |
| destinationCurrency<mark style="color:red;">\*</mark> | String | Example: USD                                                                                                                 |
| destinationAmount                                     | String | Amount received by the recipient. Example: 1000.00                                                                           |
| sourceAmount<mark style="color:red;">\*</mark>        | String | Amount sent from the sender. Example: 100.00                                                                                 |
| mode                                                  | String | When the mode is set to "SOURCE", the system will utilize the `sourceAmount`, making the `destinationAmount` field optional. |

#### Request Body (encrypted)

{% tabs %}
{% tab title="Encrypted Request" %}

```json
{
  "message": "encrypted request"
}
```

{% endtab %}
{% endtabs %}

#### Response

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "id": 1,
        "sourceCurrency": "NGN",
        "sourceAmount": 1697792.87,
        "destinationCurrency": "USD",
        "destinationAmount": 1000,
        "destinationFees": 20,
        "sourceFees": 33955.86,
        "rate": 0.000589,
        "transactionStatus": "PENDING",
        "transactionReference": "swap-9b1e2c71-43a2-490b-a0be-e4a0337d0911",
        "quoteToken": "97f20109-54e8-4861-ba12-0ea7d32351e9",
        "createdAt": "2024-08-07T18:56:28.633",
        "updatedAt": "2024-08-07T18:56:28.633"
    }
}
```

{% endtab %}
{% endtabs %}

### **Confirm swap**

> <mark style="color:yellow;">**POST**</mark> - <mark style="color:$primary;">{{env\_url}}/wallet/swap/initiate</mark>

Call the Confirm swap API to convert your quote into wallet swap transaction.&#x20;

See an example of the payload you need to encrypt and send in order to generate your quote.

The encrypted JSON body for the request can be found in the Postman [link](https://api.postman.com/collections/8963555-81a5d469-e054-4630-b7af-827b6d261eef?access_key=PMAT-01J546H4YV5MTX9ZDYTMET8VG7) as well as other APIs

#### Headers

> As specified above

#### Request Body

| Name                                         | Type   | Description                                          |
| -------------------------------------------- | ------ | ---------------------------------------------------- |
| quoteToken<mark style="color:red;">\*</mark> | String | quote token return from the generate quote API above |

{% tabs %}
{% tab title="Encrypted Request" %}

```json
{
  "message": "encrypted request"
}
```

{% endtab %}

{% tab title="200: OK" %}

```json
Response
{
    "message": "success",
    "error": null,
    "data": {
        "id": 1,
        "sourceCurrency": "NGN",
        "sourceAmount": 1697792.87,
        "destinationCurrency": "USD",
        "destinationAmount": 1000,
        "destinationFees": 20,
        "sourceFees": 33955.86,
        "rate": 0.000589,
        "transactionStatus": "SUCCESSFUL",
        "transactionReference": "swap-9b1e2c71-43a2-490b-a0be-e4a0337d0911",
        "quoteToken": "97f20109-54e8-4861-ba12-0ea7d32351e9",
        "createdAt": "2024-08-07T18:56:28.633",
        "updatedAt": "2024-08-07T18:58:38.426"
    }
}
```

{% endtab %}
{% endtabs %}

### **Fetch all your payments**

> <mark style="color:green;">**GET**</mark> - <mark style="color:$primary;">{{env\_url}}/wallet/swap/fetch/by/reference/{{transactionReference}}</mark>

Call this API to retrieve a swap transaction associated to a swap reference

You’d need to pass the `transactionReference` you obtained when you initiated the swap, as a path variable.

#### Headers

> As specified above

#### Response

{% tabs %}
{% tab title="200: OK " %}

```json
Response
{
    "message": "success",
    "error": null,
    "data": {
        "id": 1,
        "sourceCurrency": "NGN",
        "sourceAmount": 1697792.87,
        "destinationCurrency": "USD",
        "destinationAmount": 1000,
        "destinationFees": 20,
        "sourceFees": 33955.86,
        "rate": 0.000589,
        "transactionStatus": "SUCCESSFUL",
        "transactionReference": "swap-9b1e2c71-43a2-490b-a0be-e4a0337d0911",
        "quoteToken": "97f20109-54e8-4861-ba12-0ea7d32351e9",
        "createdAt": "2024-08-07T18:56:28.633",
        "updatedAt": "2024-08-07T18:58:38.426"
    }
}
```

{% endtab %}
{% endtabs %}

### **Fetch a single payment by quote token**

> <mark style="color:green;">**GET**</mark> - <mark style="color:$primary;">{{env\_url}}/wallet/swap/fetch/by/token/{{quoteToken}}</mark>

Make a call to this API to retrieve all your previously initiated quoted swaps.

You’d need to pass the `quoteToken` you obtained when you initiated the swap, as a path variable.

#### Headers

> As specified above

#### **Response**

{% tabs %}
{% tab title="200: OK " %}

```json
Response
{
    "message": "success",
    "error": null,
    "data": {
        "id": 1,
        "sourceCurrency": "NGN",
        "sourceAmount": 1697792.87,
        "destinationCurrency": "USD",
        "destinationAmount": 1000,
        "destinationFees": 20,
        "sourceFees": 33955.86,
        "rate": 0.000589,
        "transactionStatus": "SUCCESSFUL",
        "transactionReference": "swap-9b1e2c71-43a2-490b-a0be-e4a0337d0911",
        "quoteToken": "97f20109-54e8-4861-ba12-0ea7d32351e9",
        "createdAt": "2024-08-07T18:56:28.633",
        "updatedAt": "2024-08-07T18:58:38.426"
    }
}
```

{% endtab %}
{% endtabs %}

&#x20;

{% hint style="info" %}
Notes

Klasha Swap Statuses

When you generate a quote and confirm the swap, one of the field in the response body is <mark style="color:red;">`transactionStatus`</mark>, here you can find all the possible cases and explanation:

* <mark style="color:orange;">PENDING</mark>: this is the status when a swap gets initialised through the API. This is not a final status.
* <mark style="color:green;">SUCCESSFUL</mark>: the swap was executed successfully. Final status.
* <mark style="color:red;">CANCELLED</mark>: The swap has been cancelled from the Klasha finance/operation team, in result of previous communication with the merchant. Final status.
* <mark style="color:red;">FAILED</mark>: the initiated swap failed to be executed. Final status.
  {% endhint %}

**Quote expiry logic**

After you proceeded generating your quote, you can now convert that quote to confirm a swap transactions.

The confirmation would be successful if the quote is <mark style="color:red;">NOT</mark> expired.

A quote does not expire because of time but just if the rate in our system changed.

{% hint style="info" %}
**Example**

&#x20;If you generate a quote on 1st Oct at 11am and at 3pm the rate changes, you can convert your quote into a initiated payment until 2:59:59pm. Right after, then the rate get updated at 3pm, you won’t be able to confirm the swap with that quote and you’d have to generate a new quote.
{% endhint %}

In case you try to initiate a payment with an expired quote, you’d have a Bad Request response with the the following body:

{% tabs %}
{% tab title="400" %}

```json
{
    "message": "Rate has changed!",
    "error": "RateChangeException",
    "data": null
}
```

{% endtab %}
{% endtabs %}


# Currency Coverage

| Destination Country            | Available Currency |
| ------------------------------ | ------------------ |
| Angola                         | USD                |
| Anguilla                       | USD                |
| Antigua & Barbuda              | USD                |
| Argentina                      | USD                |
| Armenia                        | USD                |
| Aruba                          | USD                |
| Australia                      | AUD/USD            |
| Austria                        | EUR/USD            |
| Bahrain                        | USD                |
| Belgium                        | EUR/GBP/USD        |
| Belize                         | USD                |
| Benin                          | USD/XOF            |
| Bermuda                        | USD                |
| Bosnia and Herzegovina         | USD                |
| Brunei Darussalam              | USD                |
| Bulgaria                       | USD                |
| Burkina Faso                   | USD                |
| Cameroon                       | USD/XAF            |
| Canada                         | CAD/USD            |
| Chad                           | USD/XAF            |
| Chile                          | USD                |
| China                          | CNY/USD            |
| Colombia                       | USD                |
| Congo                          | USD                |
| Cook Islands                   | USD                |
| Costa Rica                     | USD                |
| Croatia                        | USD                |
| Curacao                        | USD                |
| Czech Republic                 | EUR                |
| Denmark                        | EUR/USD            |
| Djibouti                       | USD                |
| Dominica                       | USD                |
| Egypt                          | USD                |
| El Salvador                    | USD                |
| Equatorial Guinea              | USD                |
| Estonia                        | USD                |
| Ethiopia                       | ETB                |
| Fiji                           | USD                |
| Finland                        | EUR/USD            |
| France                         | EUR/GBP/USD        |
| French Guiana                  | USD                |
| French Polynesia               | USD                |
| Gabon                          | USD/XAF            |
| Gambia                         | USD                |
| Georgia                        | USD                |
| Germany                        | EUR/GBP/USD        |
| Ghana                          | GHS/NGN/USD        |
| Gibraltar                      | USD                |
| Greece                         | EUR                |
| Greenland                      | USD                |
| Grenada                        | USD                |
| Guadaloupe                     | USD                |
| Guernsey                       | USD                |
| Honduras                       | USD                |
| Hong Kong                      | HKD/USD            |
| Hungary                        | USD                |
| India                          | INR/USD            |
| Ireland                        | EUR/USD            |
| Italy                          | EUR                |
| Jamaica                        | USD                |
| Japan                          | JPY                |
| Jersey                         | USD                |
| Kazakhstan                     | USD                |
| Kenya                          | KES/USD            |
| Kiribati                       | USD                |
| Kosovo                         | USD                |
| Kyrgyzstan                     | USD                |
| Lesotho                        | USD                |
| Liechtenstein                  | USD                |
| Macao                          | USD                |
| Macedonia                      | USD                |
| Madagascar                     | USD                |
| Malawi                         | USD                |
| Malaysia                       | USD                |
| Malta                          | EUR/USD            |
| Mauritius                      | USD                |
| Mexico                         | USD                |
| Moldova                        | USD                |
| Monaco                         | USD                |
| Mongolia                       | USD                |
| Montenegro                     | USD                |
| Montserrat                     | USD                |
| Morocco                        | USD                |
| Namibia                        | USD                |
| Nepal                          | USD                |
| Netherlands                    | EUR/USD            |
| New Caledonia                  | USD                |
| Nigeria                        | NGN/USD            |
| Norway                         | EUR                |
| Pakistan                       | USD                |
| Palestine                      | USD                |
| Papua New Guinea               | USD                |
| Paraguay                       | USD                |
| Peru                           | USD                |
| Philippines                    | USD                |
| Poland                         | EUR/USD            |
| Portugal                       | EUR/GBP/USD        |
| Romania                        | EUR/USD            |
| Rwanda                         | USD                |
| Saint Lucia                    | USD                |
| Saint Vincent & The Grenadines | USD                |
| Senegal                        | USD                |
| Serbia                         | USD                |
| Seychelles                     | USD                |
| Sierra Leone                   | SLL/USD            |
| Singapore                      | USD                |
| Slovakia                       | USD                |
| Slovenia                       | USD                |
| Solomon Islands                | USD                |
| South Africa                   | ZAR/USD            |
| South Korea                    | USD                |
| Spain                          | EUR/GBP/USD        |
| Suriname                       | USD                |
| Swaziland                      | USD                |
| Sweden                         | EUR/USD            |
| Switzerland                    | CHF/EUR/GBP/USD    |
| Tanzania                       | TZS/USD            |
| Thailand                       | USD                |
| The British Virgin Islands     | USD                |
| The Republic of Congo          | XAF                |
| Timor-Leste                    | USD                |
| Togo                           | USD                |
| Tunisia                        | USD                |
| Turkey                         | TRY/USD            |
| Turks & Caicos                 | USD                |
| Uganda                         | UGX/USD            |
| United Arab Emirates           | AED/USD            |
| United Kingdom                 | GBP/USD            |
| United States                  | USD                |
| Uruguay                        | USD                |
| Vietnam                        | USD                |
| Zambia                         | USD/ZMW            |


# Stablecoin Wallets, Swaps and Payouts

Use Klasha's stablecoin APIs to provision business wallet addresses, price and initiate stablecoin payouts, and quote and confirm stablecoin swaps.

### Integration steps

* provision a business stablecoin wallet and fetch its deposit addresses
* validate a destination wallet address and fetch fees before you send
* initiate a business stablecoin payout and track it to completion
* generate a swap quote and confirm it to move between fiat and stablecoins, or between `USDT` and `USDC`

### Coverage

**Supported stablecoins**

* `USDT`
* `USDC`

**Supported networks**

* `ERC20`
* `TRC20`
* `BEP20`

### Before you begin

1. Create and verify your Klasha account.
2. Generate your merchant public key from the dashboard.
3. Generate a bearer token from the authentication API.
4. Retrieve your merchant encryption key. Some endpoints below require an encrypted `message` payload; others accept plain JSON — check each endpoint's **Request body** section before integrating.

{% hint style="info" %}
Encryption requirements vary per endpoint in this flow. Wallet creation/lookup and `v2/create-payout` accept plain JSON; `create-payout` (v1), `create-swap`, and `confirm-swap` require an encrypted `message` body using your merchant encryption key. The encryption algorithm can be gotten here.
{% endhint %}

### Generate a bearer token

Use the authentication API here to generate a bearer token and set your `Authorization` header to the token obtained. Most requests below also require the headers listed here.

| Header          | Value                                                           |
| --------------- | --------------------------------------------------------------- |
| `Authorization` | `Bearer {{token}}`                                              |
| `x-auth-token`  | Your merchant public key — required on business (B2B) endpoints |
| `Content-Type`  | `application/json`                                              |

### Create a stablecoin wallet

Create a stablecoin wallet for a business and provision network-specific deposit addresses.

> **POST** `{{env_url}}/wallet/stable-coin/create-wallet`

**Request body**

| Name             | Type   | Description                                                       |
| ---------------- | ------ | ----------------------------------------------------------------- |
| `businessId`\*   | Number | Klasha business ID.                                               |
| `currencyCode`\* | String | `USDT` or `USDC`. If omitted, Klasha provisions both stablecoins. |

**Example request**

```json
{
  "businessId": 12345,
  "currencyCode": "USDT"
}
```

**Example response**

```json
{
  "message": "success",
  "error": null,
  "data": [
    {
      "id": 91,
      "walletId": 501,
      "businessId": 12345,
      "userId": null,
      "currency": "USDT",
      "network": "ERC20",
      "address": "0x8d7f..."
    },
    {
      "id": 92,
      "walletId": 501,
      "businessId": 12345,
      "userId": null,
      "currency": "USDT",
      "network": "TRC20",
      "address": "TXYZ..."
    },
    {
      "id": 93,
      "walletId": 501,
      "businessId": 12345,
      "userId": null,
      "currency": "USDT",
      "network": "BEP20",
      "address": "0x4ac2..."
    }
  ]
}
```

**Notes**

* If the wallet already exists, the API returns the existing addresses and only creates missing networks.

### Get a business stablecoin wallet

Fetch previously provisioned addresses for a business wallet.

> **GET** `{{env_url}}/wallet/stable-coin/get-wallet?currency={{currency}}`

**Query params**

| Name         | Type   | Description      |
| ------------ | ------ | ---------------- |
| `currency`\* | String | `USDT` or `USDC` |

**Example response**

```json
{
  "message": "success",
  "error": null,
  "data": [
    {
      "id": 91,
      "walletId": 501,
      "businessId": 12345,
      "userId": null,
      "currency": "USDT",
      "network": "TRC20",
      "address": "TXYZ..."
    }
  ]
}
```

### Validate a destination wallet address

Validate a destination address before you initiate a payout. This endpoint is shared across B2B and B2C integrations.

> **POST** `{{env_url}}/wallet/stable-coin/validate-address`

**Request body**

| Name         | Type   | Description                  |
| ------------ | ------ | ---------------------------- |
| `currency`\* | String | `USDT` or `USDC`             |
| `network`\*  | String | `ERC20`, `TRC20`, or `BEP20` |
| `address`\*  | String | Wallet address to validate   |

**Example request**

```json
{
  "currency": "USDT",
  "network": "TRC20",
  "address": "TXYZ1234567890"
}
```

### Get stablecoin fees

Retrieve the pricing Klasha will apply to stablecoin receive, payout, and swap flows. This endpoint is also shared across B2B and B2C integrations.

> **GET** `{{env_url}}/wallet/stable-coin/fees?currency={{currency}}&amount={{amount}}&flow={{flow}}&network={{network}}`

**Query params**

| Name         | Type   | Description                                                                                                                                                         |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `currency`\* | String | `USDT` or `USDC`                                                                                                                                                    |
| `amount`\*   | String | Amount to price                                                                                                                                                     |
| `flow`       | String | Defaults to `payout`. Supported values: `receive` (aliases: `topup`, `deposit`), `send` (aliases: `payout`, `transfer`), `fiat-to-stablecoin`, `stablecoin-to-fiat` |
| `network`    | String | Recommended for payout pricing — fees can be network-specific                                                                                                       |

**Example response**

```json
{
  "message": "success",
  "error": null,
  "data": {
    "currency": "USDT",
    "flow": "send",
    "amount": 100.00,
    "fee": 1.00,
    "totalDebit": 101.00
  }
}
```

**Notes**

* `totalDebit` is the full amount debited from the wallet for a payout.
* `fiat-to-stablecoin` and `stablecoin-to-fiat` are priced with the same swap fee — only the label differs by direction.

### B2B stablecoin payout

Use this flow to send `USDT` or `USDC` from a business wallet to an external wallet address.

**Integration steps**

1. Validate the destination address.
2. Fetch the expected fee.
3. Initiate the payout.
4. Track status via your webhook, or query by `requestId`.

#### Initiate a payout

Encrypted request version:

> **POST** `{{env_url}}/wallet/stable-coin/create-payout`

Plain JSON version:

> **POST** `{{env_url}}/wallet/stable-coin/v2/create-payout`

**Request body** (plain payload shown; the encrypted variant sends this same payload as an encrypted `message` string)

| Name                         | Type   | Description                                                                                                         |
| ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `currency`\*                 | String | `USDT` or `USDC`                                                                                                    |
| `amount`\*                   | String | Amount to send                                                                                                      |
| `narration`\*                | String | Payout description                                                                                                  |
| `requestId`\*                | String | Unique payout reference. Re-sending the same `requestId` returns the existing payout instead of creating a new one. |
| `walletDestinationAddress`\* | String | Recipient stablecoin address                                                                                        |
| `network`                    | String | `ERC20`, `TRC20`, or `BEP20`. Strongly recommended for routing and fee calculation.                                 |

**Example request (v2, plain JSON)**

```json
{
  "currency": "USDT",
  "amount": "100.00",
  "narration": "Vendor settlement",
  "requestId": "scp-20260722-0001",
  "walletDestinationAddress": "TXYZ1234567890",
  "network": "TRC20"
}
```

**Example response**

```json
{
  "amount": 100.00,
  "fee": 1.00,
  "narration": "Vendor settlement",
  "payoutStatus": "PENDING",
  "requestId": "scp-20260722-0001",
  "transactionReference": null,
  "providerReference": null,
  "failureReason": null,
  "walletDestinationAddress": "TXYZ1234567890",
  "createdAt": "2026-07-22 14:10:00",
  "updatedAt": "2026-07-22 14:10:00"
}
```

**Notes**

* Klasha validates wallet balance before debit and returns an error if `amount + fee` exceeds the available balance.
* The initial response is an accepted payout request, not a final result — provider completion happens asynchronously and is delivered to your configured webhook URL.
* `payoutStatus` moves through `PENDING` → `IN_PROGRESS` → a terminal state (`SUCCESSFUL`, `FAILED`, `CANCELLED`, or `REVERSED`). Your webhook fires on the terminal states.

{% hint style="warning" %}
Polling payout status by `requestId` is not fully reliable in the current environment. We recommend relying on the `create-payout` response plus your webhook events for payout status, rather than the query-by-reference endpoint below, until this is confirmed stable.
{% endhint %}

#### Query a payout

Fetch the current state of a previously created stablecoin payout.

> **POST** `{{env_url}}/wallet/stable-coin/get-payout?requestId={{requestId}}`

**Query params**

| Name          | Type   | Description                                           |
| ------------- | ------ | ----------------------------------------------------- |
| `requestId`\* | String | The same `requestId` used when the payout was created |

### B2B stablecoin swap

Use this flow to:

* swap fiat to stablecoin
* swap stablecoin to fiat
* swap `USDT` to `USDC`
* swap `USDC` to `USDT`

#### Generate a quote

> **POST** `{{env_url}}/wallet/stable-coin/create-swap`

This endpoint expects an encrypted `message` body. The plain payload before encryption looks like this:

| Name                    | Type   | Description                                    |
| ----------------------- | ------ | ---------------------------------------------- |
| `sourceCurrency`\*      | String | Wallet currency to debit                       |
| `destinationCurrency`\* | String | Wallet currency to credit                      |
| `sourceAmount`          | String | Amount to debit when `mode` is `SOURCE`        |
| `destinationAmount`     | String | Amount to receive when `mode` is `DESTINATION` |
| `mode`\*                | String | `SOURCE` or `DESTINATION`                      |

**Example plain quote payload**

```json
{
  "sourceCurrency": "NGN",
  "destinationCurrency": "USDT",
  "sourceAmount": "100000.00",
  "mode": "SOURCE"
}
```

**Example quote response**

```json
{
  "message": "success",
  "error": null,
  "data": {
    "id": 81,
    "sourceCurrency": "NGN",
    "sourceAmount": 100000.000000,
    "destinationCurrency": "USDT",
    "destinationAmount": 99.700000,
    "destinationFees": 0.000000,
    "sourceFees": 0.000000,
    "rate": 0.000997,
    "transactionStatus": "PENDING",
    "transactionReference": "swap-7bc0d94d-7b7f-4f0b-b1bc-3c7f8d9f4d21",
    "quoteToken": "4a66fe86-d8e1-49ef-9b8b-0f07c7888f0e",
    "createdAt": "2026-07-22T14:22:00",
    "updatedAt": "2026-07-22T14:22:00"
  }
}
```

#### Confirm a swap

> **POST** `{{env_url}}/wallet/stable-coin/confirm-swap`

This endpoint also expects an encrypted `message` body.

**Request body**

| Name           | Type   | Description                           |
| -------------- | ------ | ------------------------------------- |
| `quoteToken`\* | String | Quote token returned by the quote API |

**Example plain request**

```json
{
  "quoteToken": "4a66fe86-d8e1-49ef-9b8b-0f07c7888f0e"
}
```

**Notes**

* Transaction status values: `PENDING`, `PROCESSING`, `SUCCESSFUL`, `FAILED`, `CANCELLED`, `REVERSED`, `PENDING_REVERSAL`.
* A quote becomes unusable once it has been consumed by a successful confirm, or if the market rate has moved since the quote was generated — confirm will return a rate-changed error in that case. Quotes do not expire on a fixed timer.
* Generate a fresh quote via **Generate a quote** if a confirm attempt fails due to a rate change.

#### Query a swap

Fetch a swap by reference.

> **POST** `{{env_url}}/wallet/stable-coin/get-swap`

**Request body**

| Name          | Type   | Description                                                |
| ------------- | ------ | ---------------------------------------------------------- |
| `requestId`\* | String | Use the `transactionReference` returned from the quote API |

**Example request**

```json
{
  "requestId": "swap-7bc0d94d-7b7f-4f0b-b1bc-3c7f8d9f4d21"
}
```


# Virtual Account Creation

Create Virtual Accounts (VA) on demand, receive funds from customers via these accounts and get notification on its usage.

## Summary

Our Virtual Accounts service lets you create Nigerian account number for your customers which allow your customers to receive payment from their customers.

When you create a VA for a customer, all bank transfers to that account will automatically be recorded as transactions from that customer and displayed on your dashboard.

### Coverage

| Country | currency |
| ------- | -------- |
| Nigeria | NGN      |
| Ghana   | GHS      |

#### Integration steps

You can generate a VA and start receiving money in 3 easy steps:

{% stepper %}
{% step %}
Prepare and encrypt the payload (fields include: first name, last name, currency and email)
{% endstep %}

{% step %}
Initiate VA creation
{% endstep %}

{% step %}
Get instant response
{% endstep %}
{% endstepper %}

***

## Create a virtual account

> <mark style="color:yellow;">**POST**</mark>  - <mark style="color:$primary;">`{{env_url}}/wallet/virtual/v3/business/create/account`</mark>

Encrypt the plain request using the encryption algorithm specified [here](https://developers.klasha.com/accepting-payments/payments-api#java). Then send the encrypted data as the request body as shown below.&#x20;

#### Headers

{% hint style="info" %}
You are required to set the *x-auth-token* and *Authorization* values in the request headers.
{% endhint %}

| Key                                             | Value                                                                                                                        |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| x-auth-token<mark style="color:red;">\*</mark>  | Your merchant public key                                                                                                     |
| Authorization<mark style="color:red;">\*</mark> | Bearer \<token> ([generated here](https://developers.klasha.com/~/revisions/6QchOxP4kiu4Tx13lWtV/overview/token-generation)) |

#### Request to be encrypted (plain)

{% tabs %}
{% tab title="Individual" %}

```json
{
   "firstName": "John",
   "lastName": "Doe",
   "currency": "NGN",
   "email": "test@klasha.com"
}
```

{% endtab %}

{% tab title="Business" %}

```json
{
   "currency": "NGN",
   "email": "test@klasha.com"
}
```

{% endtab %}
{% endtabs %}

| Name                                       | Type   | Description                                                          |
| ------------------------------------------ | ------ | -------------------------------------------------------------------- |
| currency<mark style="color:red;">\*</mark> | String | must be one of the supported currencies in the [coverage](#coverage) |
| email<mark style="color:red;">\*</mark>    | String | email to be linked to the VA                                         |

#### **Final Request Body (encrypted)**

```json
{
   "message": "encrypted-message"
}
```

{% hint style="info" %}
The encrypted payload must be used with the create virtual account endpoint as seen above.
{% endhint %}

#### Response

When you create a Virtual Account (VA), please allow a few seconds for processing. The `accountName` will be the `first` and `last name` for a personal account, or the business name for a corporate account. Below are sample responses;

{% tabs %}
{% tab title="200: OK (NGN) " %}

```json
{
    "id": 1,
    "accountNumber": "8571529225",
    "bankName": "WEMA BANK",
    "orderRef": "HsKRPDlemp7XBKvgO1HE",
    "txRef": "klasha-virtual-account-banktransfer-Business owner-999",
    "flwRef": "URF_vK8el9541NEy0j66imFD",
    "currency": "NGN",
    "businessId": 999,
    "bankCode": "120937",
    "enabled": true,
    "accountName": "Business owner",
    "email": "test@business.com",
    "createdAt": "2025-09-29 13:32:59",
    "updatedAt": "2025-09-29 13:32:59"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```json
{
    "message": "There is no identity available for this bvn.",
    "error": "Operation not allowed"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```json
{
    "message": "Bvn name mismatch.",
    "error": "Operation not allowed"
}
```

{% endtab %}
{% endtabs %}

## Requery VA

> <mark style="color:green;">**GET**</mark> - <mark style="color:$primary;">`{{env_url}}/wallet/virtual/v2/account/{{email}}`</mark>

In case of network downtime or failures during VA creation, the virtual account can be re-queried with the user’s email. This can be fetched using the email specified during the initial VA creation.

#### Headers

| Key                                                 | Value           |
| --------------------------------------------------- | --------------- |
| Authorization<mark style="color:$danger;">\*</mark> | Bearer \<token> |

{% tabs %}
{% tab title="200: OK " %}

```json
[
    {
        "accountNumber": "8571529225",
        "bankName": "WEMA BANK",
        "orderRef": "HsKRPDlemp7XBKvgO1HE",
        "txRef": "klasha-virtual-account-banktransfer-Business owner-999",
        "flwRef": "URF_vK8el9541NEy0j66imFD",
        "businessId": 999,
        "enabled": true,
        "accountName": "Business Owner",
        "email": "test@business.com",
        "createdAt": "2023-07-04 17:02:59",
        "updatedAt": "2023-07-04 17:02:59"
    }
]
```

{% endtab %}
{% endtabs %}

## VA Transactions notification

When payments are received in the VA, we would send a webhook with the details of the transaction to your callback URL. (see webhook details [here](https://developers.klasha.com/~/revisions/H5FGFkMO860BT4FVTiB5/misc/webhook))

## Polling transaction status

> <mark style="color:yellow;">**POST**</mark> - <mark style="color:$primary;">`{{env_url}}/nucleus/tnx/collection/status`</mark>

To know the status of a transaction, you can fetch the transaction using the Transaction Status API on the Postman collection. Make use of the session id received from the bank. See an example below:

#### Request Body

| Name                                      | Type   | Description                                                      |
| ----------------------------------------- | ------ | ---------------------------------------------------------------- |
| gateRef<mark style="color:red;">\*</mark> | String | session id received from the bank (e.g. 10043509483902847574822) |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "destinationCurrency": "NGN",
    "sourceAmount": 2500.000000,
    "sourceCurrency": "NGN",
    "status": "successful",
    "destinationAmount": 2500.000000,
    "customer": {
        "id": 53603,
        "name": "Last Name",
        "email": "test@steph.com",
        "phone": null,
        "createdAt": "2023-07-04 20:11:05",
        "updatedAt": "2023-07-04 20:11:05"
    }
}
```

{% endtab %}
{% endtabs %}


# VA balance and statement

### Summary

These APIs give Klasha’s merchants the ability to retrieve the balance of their Virtual Account as well as the statement of their transactions.

### API specifications

**Before you begin!**

{% stepper %}
{% step %}
**Generate a bearer token**

Use the token request [endpoint](https://developers.klasha.com/~/revisions/LgPYv1wt83TA5LzyGVuI/overview/token-generation) to generate a bearer token and pass in the header of the api calls below.
{% endstep %}

{% step %}
**Retrieve your merchant public key**

Find your keys on the Klasha dashboard → Settings → Generate API keys → Merchant public key (as shown below).&#x20;

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endstep %}
{% endstepper %}

## Get Virtual Account Balance

> <mark style="color:blue;">**GET**</mark> - <mark style="color:$primary;">`{{env_url}}/nucleus/virtual/account/collections/business/`</mark>

NB: You’d need to pass your merchant public key in the header as the x-auth-token and bearer token as the Authorization.

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| x-auth-token<mark style="color:red;">\*</mark>  | String | merchant public key |
| Authorization<mark style="color:red;">\*</mark> | String | bearer \<token>     |

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

```json
{
    "message": "A human readable error message",
    "error": "Bad Request",
    "data": null
}
```

{% endtab %}
{% endtabs %}

## Retrieve Transaction Statements

> <mark style="color:yellow;">**POST**</mark> - <mark style="color:$primary;">`{{env_url}}/nucleus/tnx/paginated/filter/v2`</mark>

NB: You’d need to pass the merchant public key in the header as the x-auth-token.

#### Headers

| Name                                           | Type   | Description         |
| ---------------------------------------------- | ------ | ------------------- |
| x-auth-token<mark style="color:red;">\*</mark> | String | merchant public key |

#### Request Body

* The request body can be a combination of the filters below (all or just 1 or 2)
* When you send an empty request body, you get all your transactions.

| Name     | Type   | Description                  |
| -------- | ------ | ---------------------------- |
| currency | String | transaction currency         |
| status   | String | transaction status           |
| tnxRef   | String | unique transaction reference |

{% tabs %}
{% tab title="200: OK " %}
{% code overflow="wrap" %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "pageNo": 1,
        "totalPages": 1,
        "totalCount": 1,
        "transactions": [
            {
                "transaction": {
                    "status": "successful",
                    "virtualAccountNumber": "000000001",
                    "email": "tester@email.com",
                    "currency": "NGN",
                    "tnxRef": "e7ef0a9a-8898-4850-9290-2b28ece057fe",
                    "sourceCurrency": "NGN",
                    "paymentType": "BANK_TRANSFER",
                    "channel": "woo",
                    "previousBalance": 1003.02,
                    "amountCredited": 100,
                    "amountCollected": 200,
                    "newBalance": 1103.02,
                    "settledCurrency": "NGN",
                    "createdAt": "2023-01-01 01:01:00",
                    "payerDetails": {
                        "bank": "Wema Bank",
                        "accountName": "Tester Demo",
                        "accountNumber": "0000000022"
                    }
                }
            }
        ]
    }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}


# Business Identification Service

## Overview

The Business Identification Service allows merchants to create a 3-character BIN (Business Identification Number). This BIN is used to identify merchant funds and transactions, ensuring that funds are accurately allocated to the merchant’s wallet from the pool. Merchants can also issue unique client references for better reconciliation and tracking.

Once a merchant has generated a BIN, they can create unique client references for their customers. The format for client references is:

* Client reference must start with the merchant BIN
* Maximum size: 8 characters
* Must be alphanumeric and uppercase

Merchants must instruct their clients to always include the reference in the narration/description field when sending funds to the provided account to ensure proper identification and crediting.

### Available currencies

* KES (Kenyan Shilling)
* ZMW (Zambian Kwacha)
* ZAR (South African Rand)
* XOF (<mark style="color:orange;">beta</mark>)

#### Integration steps

You can generate a BIN and start receiving money in 3 easy steps:

1. Prepare payload
2. Initiate BIN creation
3. Get instant response

{% hint style="info" %}

### Before you begin!

* [Link](https://api.postman.com/collections/8963555-635c3c8e-26bf-4ac0-aa04-6aa500691ef5?access_key=PMAT-01J8096AHFACTFV95C58XNJ2GV) to the Postman collection
* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))
* Klasha Dashboard, Generate API Keys page

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication)
{% endcontent-ref %}

### Initiate BIN creation

## Generate BIN

<mark style="color:green;">`POST`</mark>  <mark style="color:red;">{{env\_url}}</mark>/nucleus/foreign-funding/bins?businessId=<mark style="color:red;">{{businessId}}</mark>

You are required to set the x-auth-token and Authorization in the headers.

#### Headers

| Key           | Value                    |
| ------------- | ------------------------ |
| x-auth-token  | Your merchant public key |
| Authorization | Bearer \<token here>     |

**Request Param**

```json
businessId:{{businessId}}
```

{% tabs %}
{% tab title="200: Ok" %}

```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"
    }
}
```

{% endtab %}

{% tab title="400: Bad request" %}

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

{% endtab %}
{% endtabs %}

## Get bank account details

<mark style="color:blue;">`GET`</mark> <mark style="color:red;">{{env\_url}}</mark>/nucleus/foreign-funding/accounts?currency=<mark style="color:red;">{{currency}}</mark>\&businessId=<mark style="color:red;">{{businessId}}</mark>

Fetch the bank account details to share with your customers to proceed with funding with narration starting with your generated BIN.

#### Headers

| Key           | Value                |
| ------------- | -------------------- |
| Authorization | Bearer \<token here> |

{% tabs %}
{% tab title="200: Ok " %}

```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"
        }
    ]
}
```

{% endtab %}

{% tab title="400: Bad request" %}

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

{% endtab %}
{% endtabs %}

## Get transaction status

<mark style="color:blue;">`GET`</mark> <mark style="color:red;">{{env\_url}}</mark>/nucleus/foreign-funding/transactions/<mark style="color:red;">{{reference}}</mark>

Fetch transaction status using reference/narration shared to your customers.

#### Headers

| Key           | Value                |
| ------------- | -------------------- |
| Authorization | Bearer \<token here> |

{% tabs %}
{% tab title="200: Ok " %}

```json
{
    "message": "success",
    "error": null,
    "data": {
        "id": 24,
        "businessId": 133,
        "walletTransactionId": 12102,
        "amount": 2000.00,
        "fee": 2.00,
        "rate": "1",
        "type": "BANK_TRANSFER",
        "clientReference": "WZ0-CVDSDWEWERFEWRWRWEED",
        "currency": "KES",
        "narration": "MOB2/UTU/From JANET WAMBUI KIRAGU/WZ0-CVDSDWEWERFEWRWRWEED",
        "status": "SUCCESSFUL",
        "uploadedBy": "stephen@klasha.com",
        "senderAccountNumber": "N/A",
        "senderAccountName": "From JANET WAMBUI KIRAGU",
        "senderBankName": "N/A",
        "batchId": "KFF-4109fad5-e2ca-4e2e-99c3-6cd865a8c68b",
        "isSettled": true,
        "dateOnStatement": "2024-08-20",
        "createdAt": "2024-09-13 13:54:27",
        "updatedAt": "2024-09-13 13:54:27"
    }
}
```

{% endtab %}

{% tab title="400: Bad request" %}

```json
{
    "message": "No transaction found for clientReference 34",
    "error": "NOT_FOUND",
    "data": null
}
```

{% endtab %}
{% endtabs %}

## Retrieve BIN

<mark style="color:blue;">`GET`</mark> <mark style="color:red;">{{env\_url}}</mark>/nucleus/foreign-funding/bins/<mark style="color:red;">{{businessId}}</mark>

Get your bin using your business id.

| Key           | Value                |
| ------------- | -------------------- |
| Authorization | Bearer \<token-here> |

{% tabs %}
{% tab title="200: OK" %}

```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"
    }
}
```

{% endtab %}

{% tab title="400 : Bad Request" %}

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

{% endtab %}
{% endtabs %}