Create a payment link for a specific customer. Kyshi creates a pending transaction and returns a link URL your customer can use to pay.

-H "x-api-key: your_secret_key"

POST {{host}}/v1/pay/initialize

Request Body

Field	Data Type	Required	Description
customer	object	Yes	Customer details. `email` is required; `firstName`, `lastName`, and `phoneNumber` are recommended.
expiresAt	string	Yes	ISO 8601 expiry date/time for the link.
localCurrency	string	Yes	Customer payment currency. Supported collection currencies: `NGN`, `KES`, `ZAR`, `GHS`, `XOF`, `USD`.
description	string	Yes	Description shown for the payment.
metadata	array	Yes	Line items. Each item requires `name`, `amount`, and `quantity`. `amount` is in your settlement currency.
feeBearer	string	No	`MERCHANT` or `CUSTOMER`. Defaults to your business setting or `CUSTOMER`.
taxChargeable	string	No	`INCLUSIVE` or `EXCLUSIVE`. Defaults to your business setting or `EXCLUSIVE`.
taxEnabled	boolean	No	Enables provider automatic tax where supported, mainly Stripe.

{
  "customer": {
    "email": "[email protected]",
    "firstName": "Ada",
    "lastName": "Okafor"
  },
  "expiresAt": "2026-06-01T23:59:59Z",
  "localCurrency": "NGN",
  "description": "Invoice #10001",
  "metadata": [
    {
      "name": "Website design",
      "amount": 100,
      "quantity": 1
    }
  ],
  "feeBearer": "CUSTOMER",
  "taxChargeable": "EXCLUSIVE",
  "taxEnabled": true
}

{
  "status": true,
  "message": "Success",
  "code": 201,
  "data": {
    "reference": "KYSHI-1778623597453",
    "status": "PENDING",
    "paymentLink": {
      "id": "f6cbda33-1a40-4f2e-a211-fd87bd86cc4a",
      "code": "PLK_abc123",
      "url": "https://pay.kyshi.co/PLK_abc123",
      "expiresAt": "2026-06-01T23:59:59.000Z"
    },
    "amount": {
      "value": 155000,
      "currency": "NGN"
    }
  }
}

Notes

Metadata item amounts are sent in major settlement currency units.
Kyshi stores item amounts internally in minor units.
The returned amount.value is the local customer-facing amount after FX conversion.