LogoLogo
  • Welcome!
  • Integrating Klasha
    • Getting Started
    • Prerequisites
    • Integration Checklist
    • Wrap Up
  • Overview
    • Introduction
    • Parameters
    • Token Generation
    • Errors
    • Countries & Payment Methods
  • Accepting Payments
    • Test Payments
    • Payments API
      • Mobile money
      • USSD
    • Payment Link
      • Dashboard
      • Payment Link API
    • Klasha Inline
    • HTML Checkout
  • PLUGINS AND SDKS
    • Plugins
    • Mobile SDKs
    • Web SDKs
  • MISC
    • Transaction Status
    • Webhook
    • API Status
  • Features
    • One-time Payments
    • Recurrent Payment
  • Transfers
    • Payout
      • ZAR Payout(new encryption)
      • KES Payout(new encryption)
      • ZMW Payout(new encryption)
      • TZS Payout(new encryption)
      • CNY Payout(new encryption)
    • Klasha Wire API
    • Swap API
    • Currency Coverage
  • Bank Account Collection
    • Virtual Account Creation
    • VA balance and statement
    • Business Identification Service
Powered by GitBook
On this page
  • Summary
  • Integration step
  • Make a POST call to the Create Quote API to generate your swap quote
  • Make a POST call to the Confirm swap API
  • Make a GET call to the Fetch by swap reference API
  • Fetch by token API to retrieve all your previously initiated quoted swaps.
  1. Transfers

Swap API

PreviousKlasha Wire APINextCurrency Coverage

Last updated 9 months ago

Summary

Give merchants the ability to swap funds between their wallets via API using our internal Klasha rates.

You can swap money in three easy steps:

  1. Generate a bearer token

  2. Generate a quote for the swap

  3. Confirm swap

Before you begin!

  • to the Postman collection

  • Find your keys on the Klasha Dashboard → Settings → Generate API Keys ()

Encryption Algorithm can be gotten

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: token

POST {{env_url}}/auth/account/v2/login

Request Body

Name
Type
Description

username*

username

password*

password

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

Generate a quote

Make a POST call to the Create Quote API to generate your swap quote

POST {{env_url}}/wallet/swap/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.

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*

String

NGN

destinationCurrency*

String

USD

destinationAmount*

1000.00

{
  "message": "encrypted request"
}
{
    "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

Make a POST call to the Confirm swap API

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

Make a POST call to 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.

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*

String

97f20109-54e8-4861-ba12-0ea7d32351e9

{
  "message": "encrypted request"
}
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 all your payments

Make a GET call to the Fetch by swap reference API

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

Make a GET call to the Fetch by swap reference to retrieve a swap transaction.

You’d need to pass the transactionReference you obtained when you initiated the swap, 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

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

Fetch by token API to retrieve all your previously initiated quoted swaps.

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

Make a GET call to the Fetch by token 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.

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

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:

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

The encrypted JSON body for the request can be found in the Postman as well as other APIs.

The encrypted JSON body for the request can be found in the Postman as well as other APIs

link
link
Link
here
here