KotaniPay API-v2 Documentation (0.1.0)

Download OpenAPI specification:Download

Authorization

Client login

Clients who received their api-credentials can use this endpoint to login. They will then receive an access-token that will allow them to access all the endpoints within the API.

Request Body schema: application/json
phoneNumber
required
string

The phoneNumber used by the partner during registration

countryCode
required
string

The residence country of the partner i.e KEN/GH

password
required
string

The password used by the partner during signup

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "countryCode": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "status": 201,
  • "accessToken": "string"
}

Binance

Create Order

This endpoint is used to create an order and generate a checkout link or a qr code that will be used to pay for the order created.

Authorizations:
bearerAuth
Request Body schema: application/json
amount
required
integer
Default: 10
goodsName
required
string
goodsDetail
required
string
currency
required
string

Currencies currently accepted are BUSD and USDT

returnUrl
required
string

The URL to redirect to when the payment is successful

cancelUrl
required
string

The URL to redirect to when payment is failed

Responses

Request samples

Content type
application/json
{
  • "amount": 10,
  • "goodsName": "string",
  • "goodsDetail": "string",
  • "currency": "string",
  • "returnUrl": "string",
  • "cancelUrl": "string"
}

Response samples

Content type
application/json
{
  • "result": { }
}

Close Order

This endpoint is used to close an order generated before it has been paid. Please not that an order will be automatically closed after 1 hour if the order is not paid.

Authorizations:
bearerAuth
Request Body schema: application/json
prepayId
required
string

Responses

Request samples

Content type
application/json
{
  • "prepayId": "string"
}

Response samples

Content type
application/json
{
  • "result": { }
}

Query Order

This endpoint is used to query an order generated to view its current status. Although this is can be used to do a payout, the payout is initiated immediately after a payput is successfull.

Authorizations:
bearerAuth
Request Body schema: application/json
prepayId
required
string

Responses

Request samples

Content type
application/json
{
  • "prepayId": "string"
}

Response samples

Content type
application/json
{
  • "result": { }
}

Celo

Buy Celo cUSD

This endpoint is used by partners who have API credentials and desire to purchase Celo stablecoins. The phone numbers are used to verify the existence of the user with their wallet address and is also used to purchase Celo tokens.

Authorizations:
bearerAuth
Request Body schema: application/json
phoneNumber
required
string
celoAmount
required
string

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "celoAmount": "string"
}

Response samples

Content type
application/json
{
  • "status": 201,
  • "details": { }
}

Send cUSD to Mpesa

This end point sends converted stablecoins that are onchain into fiat via mobile money. (Mpesa)

Authorizations:
bearerAuth
Request Body schema: application/json
phoneNumber
required
string

Phone number of the recipient

txhash
required
string

The transactionHash of the USD tokens sent to Kotani Escrow wallet

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "txhash": "string"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "desc": "string",
  • "cusdDetails": {
    }
}

Fiat-Fiat

Deposit fiat

This end point places a request to authorize sending of a certain amount to their mobile money wallet through a specified phone number . The funds are retrieved from the mobile money wallet and sent to Kotani Pay’s
main wallet which the user can use for different reasons such as converting to stablecoin and sending it to another via the onchain network.
N/B: Kindly note that all callback urls are required to start with a protocol, i.e 'https'/'http'

Authorizations:
bearerAuth
Request Body schema: application/json
amount
required
integer
Default: 10
phoneNumber
required
string
Default: "254*********"
callback
string
externalId
string

Responses

Request samples

Content type
application/json
{
  • "amount": 10,
  • "phoneNumber": "254*********",
  • "callback": "string",
  • "externalId": "string"
}

Response samples

Content type
application/json
{
  • "result": { }
}

Deposit fiat with an accepted quote

This end point places a request to authorize sending of a certain amount that was approved in a previous quote to their mobile money wallet through a specified phone number . The funds are retrieved from the mobile money wallet and sent to Kotani Pay’s
main wallet which the user can use for different reasons such as converting to stablecoin and sending it to another via the onchain network.
N/B: Kindly note that all callback urls are required to start with a protocol, i.e 'https'/'http'

Authorizations:
bearerAuth
Request Body schema: application/json
acceptedQuoteId
required
string
Default: "hiwurhr"
phoneNumber
required
string
Default: "254*********"
callback
string
externalId
string

Responses

Request samples

Content type
application/json
{
  • "acceptedQuoteId": "hiwurhr",
  • "phoneNumber": "254*********",
  • "callback": "string",
  • "externalId": "string"
}

Response samples

Content type
application/json
{
  • "result": { }
}

Get transaction status using requestId

This endpoint is used by users and partners to inquire the status of a transaction; whether it failed or was successful. The requestId is retrieved from the response of a transaction that already occurred.

Authorizations:
bearerAuth
path Parameters
requestId
required
any

Responses

Response samples

Content type
application/json
{
  • "result": { }
}

Get transaction status using externalId

This endpoint is used when a partner or a user wants to inquire on a single transaction. The externalId containing the response is retrieved from a transaction that already happened.

Authorizations:
bearerAuth
path Parameters
externalId
required
any
query Parameters
transactionalType
required
string

Transaction type could be either Collections or Payouts

Responses

Response samples

Content type
application/json
{
  • "result": { }
}

Withdraw fiat through mobile money

This endpoint is used by a partner to withdraw fiat via mobile money. A partner transacting onchain may disburse the funds to their customers by hitting the withdrawal endpoint which will allow the converted funds to be sent directly to the recipients.

Authorizations:
bearerAuth
Request Body schema: application/json
amount
required
integer
Default: 20
phoneNumber
required
string
Default: 254722222222
callback
string
externalId
string

Responses

Request samples

Content type
application/json
{
  • "amount": 20,
  • "phoneNumber": 254722222222,
  • "callback": "string",
  • "externalId": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "phoneNumber": "string",
  • "message": "string",
  • "amount": "string",
  • "externalId": "string"
}

Get all transactions

Get all transactions made by a partner including those done during depositing fiat through mobile money, or those done by withdrawing fiat through mobile money.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "transactionType": "string",
  • "limit": "string",
  • "orderBy": "string"
}

Transact using payBill

This endpoint is used by a partner who desires to pay a business or a merchant for goods sold via paybill. This endpoint is currently only used in Kenya Kindly note that all transactions done through paybill number are subjected to incur a transactional fee that varies per the amount transacted.

Authorizations:
bearerAuth
Request Body schema: application/json
merchantNumber
required
string
accountNumber
required
string
amount
required
string
callback
string

Responses

Request samples

Content type
application/json
{
  • "merchantNumber": "string",
  • "accountNumber": "string",
  • "amount": "string",
  • "callback": "string"
}

Response samples

Content type
application/json
{
  • "result": { }
}

Pay using a tillNumber

This endpoint is used by a partner who desires to pay a business or a merchant for goods sold via till number. This endpoint is currently only used in Kenya Transactions done through a till number are free of charge.

Authorizations:
bearerAuth
Request Body schema: application/json
merchantTill
required
string
amount
required
string
callback
string

Responses

Request samples

Content type
application/json
{
  • "merchantTill": "string",
  • "amount": "string",
  • "callback": "string"
}

Response samples

Content type
application/json
{
  • "result": { }
}

Withdraw fiat through the bank

This endpoint is used by a partner to withdraw fiat to a bank account A partner transacting onchain may disburse the funds to their customers by hitting the withdrawal endpoint which will allow the converted funds to be sent directly to the recipients' bank accounts.

Supported Banks
Name Code
Kenya Commercial Bank 01
Standard Chartered 02
Absa Bank Kenya 03
Ncba Bank Kenya 07
Prime Bank 10
Cooperative Bank 11
National Bank of Kenya 12 12
Citibank N.A Kenya 16
Middle East Bank Kenya 18
Bank of Africa Kenya 19
Credit Bank Limited 25
CFC Stanbic Kenya 31
Paramount Bank 50
Jamii Bora Bank 51
Guaranty Trust Bank 53
Guardian Bank 55
I&M Bank 57
Diamond Trust Bank 63
Sidian Bank 66
Equity Bank Kenya 68
Family Bank Limited 70
Gulf African Bank 72
First Community Bank 74
Kenya Women's Finance Trust 78

Authorizations:
bearerAuth
Request Body schema: application/json
amount
required
integer
Default: 20
accountNumber
required
string
Default: 123456789
accountName
required
string
Default: "Jane Doe"

The user's bank account name

serviceProviderId
required
string

The serviceProviderId is the BankCode of the accepted banks. See the table above

callback
string
externalId
string

Responses

Request samples

Content type
application/json
{
  • "amount": 20,
  • "accountNumber": 123456789,
  • "accountName": "Jane Doe",
  • "serviceProviderId": "string",
  • "callback": "string",
  • "externalId": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "accountNumber": "string",
  • "accountName": "string",
  • "serviceProviderId": "string",
  • "message": "string",
  • "amount": "string",
  • "externalId": "string"
}

Fiat Connect

Fiat Connect Client login

Log in with a SIWE message and get a session cookie

Request Body schema: application/json
message
required
string

The plaintext SIWE message

signature
required
string

An EIP-191 (for EOA) or EIP-1271 (for contract-owned accounts) signature for the SIWE message

Responses

Request samples

Content type
application/json
{
  • "message": "string",
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "error": "InvalidSignature"
}

Create Fiat Connect api-credentials

Regeister Fiat Connect client Webhooks and get API key Credentials

Request Body schema: application/json
webhook
required
string
Default: "string"

Responses

Request samples

Content type
application/json
{
  • "webhook": "string"
}

Response samples

Content type
application/json
{
  • "apiKey": "string",
  • "webhook": "string",
  • "webhookSecret": "string"
}

Get the server's current time

Responses

Response samples

Content type
application/json
{
  • "time": "string"
}

Retrieve a quote for a transfer from fiat to crypto

The endpoint is used to create quotes for transfers from fiat to crypto

Request Body schema: application/json
cryptoType
required
string
fiatAmount
required
string
fiatType
required
string
country
required
string

Responses

Request samples

Content type
application/json
{
  • "cryptoType": "string",
  • "fiatAmount": "string",
  • "fiatType": "string",
  • "country": "string"
}

Response samples

Content type
application/json
{
  • "quote": { },
  • "kyc": { },
  • "fiatAccount": { }
}

Retrieve a quote for a transfer from crypto to fiat

The endpoint is used to create quotes for transfers from crypto to fiat

Request Body schema: application/json
cryptoType
required
string
cryptoAmount
required
string
fiatType
required
string
country
required
string

Responses

Request samples

Content type
application/json
{
  • "cryptoType": "string",
  • "cryptoAmount": "string",
  • "fiatType": "string",
  • "country": "string"
}

Response samples

Content type
application/json
{
  • "quote": { },
  • "kyc": { },
  • "fiatAccount": { }
}

Provide KYC data of a particular schema to the server

The endpoint is used to create KYC info for a particular user

Authorizations:
None
Request Body schema: application/json
firstName
required
string
lastName
required
string
phoneNumber
required
string
localCurrency
required
string
celoPublicAddress
required
string
address
required
object
dateOfBirth
required
object

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "phoneNumber": "string",
  • "localCurrency": "string",
  • "celoPublicAddress": "string",
  • "address": { },
  • "dateOfBirth": { }
}

Response samples

Content type
application/json
{
  • "kycStatus": "KycApproved",
  • "kycData": { }
}

Query the status of a KYC verification for a specific schema type

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "kycStatus": "string",
  • "data": { }
}

Delete a KYC record for a particular KYC schema

Authorizations:
None

Responses

Response samples

Content type
application/json
{ }

Provide fiat account data of a particular schema to the server

The endpoint is used to create fiat accounts used for transfers

Authorizations:
None
Request Body schema: application/json
fiatAccountSchema
required
string
data
required
object

Responses

Request samples

Content type
application/json
{
  • "fiatAccountSchema": "string",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "fiatAccountId": "string",
  • "accountName": "string",
  • "institutionName": "string",
  • "fiatAccountType": "string",
  • "fiatAccountSchema": "string"
}

Query for all fiat accounts on file for a user

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "additionalProp1": [ ],
  • "additionalProp2": [ ]
}

Delete fiat account information for a particular user

Authorizations:
None
path Parameters
fiatAccountId
required
any

The id of the fiat account being deleted

Responses

Response samples

Content type
application/json
{ }

Initiate a new transfer from fiat to crypto

The endpoint is used to initiate a new transfer from fiat to crypto

Authorizations:
NoneNone
header Parameters
Idempotency-Key
required
any

An idempotency key generated by the client

Request Body schema: application/json
fiatAccountId
required
string
quoteId
required
string

Responses

Request samples

Content type
application/json
{
  • "fiatAccountId": "string",
  • "quoteId": "string"
}

Response samples

Content type
application/json
{
  • "transferId": "string",
  • "transferStatus": "TransferStarted",
  • "transferAddress": "string"
}

Initiate a new transfer from crypto to fiat

The endpoint is used to initiate a new transfer from crypto to fiat

Authorizations:
NoneNone
header Parameters
Idempotency-Key
required
any

An idempotency key generated by the client

Request Body schema: application/json
fiatAccountId
required
string
quoteId
required
string

Responses

Request samples

Content type
application/json
{
  • "fiatAccountId": "string",
  • "quoteId": "string"
}

Response samples

Content type
application/json
{
  • "transferId": "string",
  • "transferStatus": "TransferStarted",
  • "transferAddress": "string"
}

Check the status of a transfer

Authorizations:
None
path Parameters
transferId
required
any

The id of the tranfer being requested

Responses

Response samples

Content type
application/json
{
  • "status": "TransferStarted",
  • "transferType": "string",
  • "fiatType": "string",
  • "cryptoType": "string",
  • "amountProvided": "string",
  • "amountReceived": "string",
  • "fee": "string",
  • "fiatAccountId": "string",
  • "transferId": "string",
  • "transferAddress": "string"
}

Health Endpoint Checker

checks if the API is up and running

checks if the API is up and running

Responses

KYC

Create a user

This endpoint creates an account for a user who will be able to use a chain for their own transactions.

Authorizations:
bearerAuth
Request Body schema: application/json
phoneNumber
required
string

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string"
}

Response samples

Content type
application/json
{
  • "userId": "string"
}

Verify a user

This endpoint is used to check whether a user exists in the system, and if their details have been verified.

Authorizations:
bearerAuth
Request Body schema: application/json
phoneNumber
required
string

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Update user details

The endpoint is used to gather more details about a user. The details are used to verify the identity of the user which will help to prevent fraud in the form of fake profiles or stolen identities.

Authorizations:
bearerAuth
Request Body schema: application/json
phoneNumber
required
string

Phone number used when user was being created

lastname
required
string

User's last name

firstname
required
string

User's first name

email
required
string

User's email address

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "lastname": "string",
  • "firstname": "string",
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "desc": "string",
  • "details": { }
}

Get all user details by phoneNumber

This is an internal API endpoint that is used to retrieve the details of a single user using their phone number.

Authorizations:
bearerAuth
Request Body schema: application/json
phoneNumber
required
string

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string"
}

Response samples

Content type
application/json
{
  • "userRecord": { }
}

Get all user account details

This is an internal endpoint that is used to retrieve the details of all the users present in the system.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": { }
}

Get user phoneNumber by their onchain address

This is an internal APIused to find the onchain address of a user using their phone number.

Authorizations:
bearerAuth
Request Body schema: application/json
publicAddress
required
string

Responses

Request samples

Content type
application/json
{
  • "publicAddress": "string"
}

Response samples

Content type
application/json
{
  • "phoneNumber": "string"
}

OnChain

Get account balance

Get user account balance on the onchain. This endpoint only requires the phone number of the user which is linked to their address. The retrieved address will then be used to check their balance in the network.

Authorizations:
bearerAuth
Request Body schema: application/json
phoneNumber
required
string

PhoneNumber used to transact on chain

chain
required
string

The onchain network a user uses. Can either be tron, arbitrum, celo, avalanche, or stellar

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "chain": "string"
}

Response samples

Content type
application/json
{
  • "status": 201,
  • "address": "string",
  • "balance": {
    }
}

Get Escrow transaction rates

Get Escrow transaction rates for all related USD stablecoins

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "escrowAddress": "string",
  • "conversionRate": {
    }
}

Stellar CashIn/ CashOut

Fiat cashout

This endpoint is used by a client who desires to convert their Stellar USDC to fiat currency and send it to a recipient via mobile money. The endpoint currently only supports the sending of funds to Kenya and Ghanaian recipients.

Authorizations:
bearerAuth
path Parameters
countryCode
required
string

Country codes supported include KE (Kenya) and GH (Ghana)

Request Body schema: application/json
phoneNumber
required
string
Default: 254712345678
txHash
required
string
callback
string
name
string
email
string
description
string

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": 254712345678,
  • "txHash": "string",
  • "callback": "string",
  • "name": "string",
  • "email": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{ }

Quotes in/out

Get cash in quote

Get user a quote on how much a recipient will get if you deposit a certain amount of fiat.

Authorizations:
bearerAuth
Request Body schema: application/json
fiatAmount
required
string

The amount a user desires to deposit

currency
required
string

The currency of the fiat to be deposited

cryptoType
required
string

The type of crypto the fiat will be converted to

Responses

Request samples

Content type
application/json
{
  • "fiatAmount": "string",
  • "currency": "string",
  • "cryptoType": "string"
}

Response samples

Content type
application/json
{ }

Get cash out quote

Get user a quote on how much a recipient will get if you desire to send a certain amount of crypto.

Authorizations:
bearerAuth
Request Body schema: application/json
cryptoAmount
required
string

The amount of crypto a user desires to send

currency
required
string

The currency of the fiat to be received by the recipient

cryptoType
required
string

The type of crypto the user intends to send

Responses

Request samples

Content type
application/json
{
  • "cryptoAmount": "string",
  • "currency": "string",
  • "cryptoType": "string"
}

Response samples

Content type
application/json
{ }

Accept quote in

Accept a quote in

Authorizations:
bearerAuth
Request Body schema: application/json
quoteId
required
string

The quoteId of the placed quote

Responses

Request samples

Content type
application/json
{
  • "quoteId": "string"
}

Response samples

Content type
application/json
{ }

Accept quote out

Accept a quote out

Authorizations:
bearerAuth
Request Body schema: application/json
quoteId
required
string

The quoteId of the placed quote

Responses

Request samples

Content type
application/json
{
  • "quoteId": "string"
}

Response samples

Content type
application/json
{ }

Tron CashIn / CashOut

Convert USDT on Tron to Mobile Money

This endpoint is used by a client who desires to convert their TRON USDT to fiat currency and send it to a recipient via mobile money. The endpoint currently only supports the sending of funds to Kenya and Ghanaian recipients.

Authorizations:
bearerAuth
path Parameters
countryCode
required
string

Country codes supported include KE (Kenya) and GH (Ghana)

Request Body schema: application/json
phoneNumber
required
string
txHash
required
string
callback
string
name
string
email
string

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "txHash": "string",
  • "callback": "string",
  • "name": "string",
  • "email": "string"
}

Response samples

Content type
application/json
{ }

Convert Mobile Money to USDT on TRON

This endpoint is used by a client who desires to convert their mobile money(FIAT) to TRON USDT. The endpoint currently only supports phone numbers in Kenya(+254).

Authorizations:
bearerAuth
path Parameters
countryCode
required
string

Country codes supported include KE (Kenya) and GH (Ghana)

UBI

Claim UBI funds

This endpoint can only be accessed by UBI beneficiaries through the USSD code and is used to request and affirm that the beneficiary is the rightful owner of the funds sent to their addresses.

Authorizations:
bearerAuth
Request Body schema: application/json
phoneNumber
required
string
programId
required
string

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "programId": "string"
}

Response samples

Content type
application/json
{
  • "status": 201,
  • "desc": "string",
  • "txid": "string"
}

Check if user is UBI beneficiary

This endpoint is used by existing Kotani Pay users to inquire if they are UBI beneficiaries.

Authorizations:
bearerAuth
Request Body schema: application/json
phoneNumber
required
string
programId
required
string

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "programId": "string"
}

Response samples

Content type
application/json
{
  • "status": 201,
  • "desc": "string",
  • "result": { }
}

Set user as UBI beneficiary

This endpoint is used by UBI partners who want to add beneficiaries to their program.

Authorizations:
bearerAuth
Request Body schema: application/json
phoneNumber
required
string
programId
required
string

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "programId": "string"
}

Response samples

Content type
application/json
{
  • "desc": "string",
  • "result": { }
}