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

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/integration

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