Initialise Transaction

The Transactions API allows you create and manage collections.

Initialise Transaction

To Initialise a transaction, you'll need to pass information such as email, amount, transaction reference and local currency, email and amount required. For Transactions like this where merchant expects us to settle in a foreign currency Kyshi use's the best rate to process the said transaction

Payment Details

FieldData typeRequiredDescription
amountintegerYesThe amount merchant offers their service.
emailstringYesCustomer email address
phoneNumberstringNoCustomer phone number
referencestringNoUnique transaction reference as generated by the merchant
localCurrencystringNoThe currency in which the customer should be charged. The ISO 4217 currency code
redirectUrlstringNoFully qualified url. Use this to override the callback url provided on the dashboard for this transaction. You would be redirected to this url after transaction is completed
channelsarrayNoAn array of payment channels to control what you want to make available to the user to make a payment with. Available channels include: ["card", "mobileMoney", "bankTransfer"]

Initiate Payment

After collecting the necessary payment details for the transaction. Make a POST request to our initialize endpoint.

Note : Before making a post request, the secret key should be specified in the header.

-H "x-api-key: your_secret_key".

If the API call is successful, Kyshi returns the following response:

    "email": "[email protected]",
    "amount": 2,
    "localCurrency": "NGN",
    "reference": "KYSHI-DEMO-1111112",
    "feeBearer": "MERCHANT", // MERCHANT || CUSTOMER
    "taxChargeable": "INCLUSIVE", // INCLUSIVE || EXCLUSIVE
    "channels": ["mobileMoney"],
    "redirectUrl": ""
"status": true,
"code": 201,
"message": "Success",
"data": {
    "authorizationUrl": "",
    "accessCode": "",
    "reference": "KYSHI-1292018922",
    "rate": 10.1

Receive and validate webhook notification

Listen for webhook events. We will send a notification to your webhook URL that indicates the status of the collection. Read our guide on securing and validating the webhook notification on your end.

Note: We will only send you a webhook when the transaction is successful

  "event": "successful", 
  "data": {
    "reference": "6df5910e1bdde31abf",
    "amount": 500.00,
    "customer": {
       "id": "",
       "firstName": "John",
       "email": "[email protected]", 
       "phone": null 
    "authorization": { 
       "authorizationCode": "my_reference",
       "cardType": "",
       "brand": "Visa",
       "last4": "", 
       "bin": "", 
       "expMonth": "", 
       "expYear": "" 
    "log": {},
    "meta": {
        "localCurrency": "NGN",
        "localAmount": 500.00,
        "feeBreakdown": {
          "vat": 0,
          "fee": 10.0,