Initialise Payment Link

To initialise a payment link, you’ll need to pass information such as customer details, items to be paid for, local currency, expiry date and a description.

For payment links where settlement happens in a foreign currency, Kyshi uses the best available rate at the time of creation to process the transaction.

Payment Link Details

Field	Data Type	Required	Description
customer.email	string	Yes	Customer email address
customer.firstName	string	No	Customer first name
customer.lastName	string	No	Customer last name
metadata[].name	string	Yes	Item name
metadata[].amount	integer	Yes	Item amount
metadata[].quantity	integer	Yes	Item quantity
localCurrency	string	Yes	Currency the customer will be charged in (ISO 4217)
expiresAt	string (ISO date)	Yes	Expiry date/time for the payment link
description	string	No	Description for the payment
feeBearer	string	No	Determines who bears the transaction fees (CUSTOMER or MERCHANT). Default is CUSTOMER
taxChargeable	string	No	Specifies whether tax is included in or added to the amount (INCLUSIVE or EXCLUSIVE). Default is EXCLUSIVE

Create Payment Link

After collecting the required details, make a POST request to the initialise endpoint.

Note: Before making a request, your API key must be specified in the request header.

-H "x-api-key: your_secret_key"

{{host}}/v1/pay/initialize

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

{
  "customer": {
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe"
  },
  "metadata": [
    {
      "name": "Book",
      "amount": 500,
      "quantity": 1
    }
  ],
  "localCurrency": "KES",
  "expiresAt": "2026-02-04T01:35:04Z",
  "description": "Book purchase"
}

{
  "status": true,
  "code": 201,
  "message": "Success",
  "data": {
    "reference": "KYSHI-1770114609126",
    "status": "PENDING",
    "paymentLink": {
      "id": "09930725-2fb3-473a-978d-e395de858c04",
      "code": "1lPxay18RMZWCMo",
      "url": "https://merchant.kyshi.co/payment/1lPxay18RMZWCMo",
      "expiresAt": "2026-02-04T01:35:04.000Z"
    },
    "amount": {
      "value": 74205,
      "currency": "KES"
    }
  }
}

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