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)

2. Generate a quote for the swap

3. Confirm swap

All requests sent to these APIs must be encrypted. The encryption Algorithm can be gotten here

Generate a bearer token

Use the authentication API here 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

POST - {{env_url}}/wallet/swap/generate/quote

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 as well as other APIs.

Headers

As specified above

Request Body (plain)

Name	Type	Description
sourceCurrency*	String	Example: NGN
destinationCurrency*	String	Example: USD
destinationAmount	String	Amount received by the recipient. Example: 1000.00
sourceAmount*	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)

Encrypted Request

{
  "message": "encrypted request"
}

Response

200: OK

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

Confirm swap

POST - {{env_url}}/wallet/swap/initiate

Call the Confirm swap API to convert your quote into wallet swap transaction.

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 as well as other APIs

Headers

As specified above

Request Body

Name	Type	Description
quoteToken*	String	quote token return from the generate quote API above

Encrypted Request

{
  "message": "encrypted request"
}

200: OK

Fetch all your payments

GET - {{env_url}}/wallet/swap/fetch/by/reference/{{transactionReference}}

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

200: OK

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

Fetch a single payment by quote token

GET - {{env_url}}/wallet/swap/fetch/by/token/{{quoteToken}}

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

200: OK

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

Notes

Klasha Swap Statuses

When you generate a quote and confirm the swap, one of the field in the response body is transactionStatus, here you can find all the possible cases and explanation:

• PENDING: this is the status when a swap gets initialised through the API. This is not a final status.

• SUCCESSFUL: the swap was executed successfully. Final status.

• CANCELLED: The swap has been cancelled from the Klasha finance/operation team, in result of previous communication with the merchant. Final status.

• FAILED: the initiated swap failed to be executed. Final status.

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 NOT expired.

A quote does not expire because of time but just if the rate in our system changed.

Example

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.

In case you try to initiate a payment with an expired quote, you’d have a Bad Request response with the the following body:

400

{
    "message": "Rate has changed!",
    "error": "RateChangeException",
    "data": null
}