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

Field	Data type	Required	Description
amount	integer	Yes	Amount to charge for the service. This is interpreted based on amountCurrency .
amountCurrency	string	No	Determines what currency amount is in. Use local to mean the customer’s local currency (GHS, NGN, KES, XOF). Use settlement to mean the merchant’s settlement currency (USD, EUR etc).
email	string	Yes	Customer email address
phoneNumber	string	No	Customer phone number
reference	string	No	Unique transaction reference as generated by the merchant
localCurrency	string	No	The currency in which the customer should be charged. The ISO 4217 currency code e.g. KES, GHS, XOF, NGN.
redirectUrl	string	No	Fully 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
channels	array	No	An 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".

{{host}}/v1/transactions/initialize

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

{
    "email": "[email protected]",
    "amount": 2,
    "amountCurrency": "local",
    "localCurrency": "NGN",
    "reference": "KYSHI-DEMO-1111112",
    "feeBearer": "MERCHANT", // MERCHANT || CUSTOMER
    "taxChargeable": "INCLUSIVE", // INCLUSIVE || EXCLUSIVE
    "channels": ["mobileMoney"],
    "redirectUrl": "https://web.facebook.com"
}

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