Initialize a card or supported checkout payment for a customer. Kyshi creates a pending transaction and returns the provider checkout details your customer should use to complete payment.

-H "x-api-key: your_secret_key"

POST {{host}}/v1/transactions/initialize

Request Body

Field	Data Type	Required	Description
email	string	Yes	Customer email address.
amount	number	Yes	Amount to charge. Minimum is `1`.
localCurrency	string	Yes	Customer payment currency. Supported collection currencies: `NGN`, `KES`, `ZAR`, `GHS`, `XOF`, `USD`.
amountCurrency	string	No	How to interpret `amount`. Use `settlement` when amount is in your settlement currency, or `local` when amount is already in `localCurrency`. Defaults to `settlement`.
firstName	string	No	Customer first name.
lastName	string	No	Customer last name.
phoneNumber	string	No	Customer phone number.
reference	string	No	Your unique transaction reference. If omitted, Kyshi generates one.
channels	array	No	Provider-supported payment channels. Example: `["card"]`.
metadata	object	No	Extra data to attach to the transaction.
redirectUrl	string	No	URL to redirect the customer after checkout.
feeBearer	string	No	Who pays fees. Allowed values: `MERCHANT`, `CUSTOMER`.
taxChargeable	string	No	Tax behavior. Allowed values: `INCLUSIVE`, `EXCLUSIVE`.

Currency And Amounts

Amounts are sent in major currency units. For example, 1000 means 1000 NGN, 1000 GHS, or 1000 KES.

If your settlement currency differs from localCurrency, Kyshi uses the latest configured FX rate. With amountCurrency: "settlement", Kyshi converts the settlement amount into the customer local amount. With amountCurrency: "local", Kyshi treats amount as the exact customer-facing amount.

{
  "email": "[email protected]",
  "firstName": "Ada",
  "lastName": "Okafor",
  "amount": 1000,
  "localCurrency": "NGN",
  "amountCurrency": "local",
  "reference": "ORDER-10001",
  "channels": ["card"],
  "redirectUrl": "https://merchant.example.com/payments/callback",
  "metadata": {
    "orderId": "10001"
  },
  "feeBearer": "MERCHANT",
  "taxChargeable": "EXCLUSIVE"
}

{
  "status": true,
  "message": "Success",
  "code": 201,
  "data": {
    "authorizationUrl": "https://checkout.example.com/pay/abc123",
    "accessCode": "abc123",
    "reference": "ORDER-10001",
    "rate": 1,
    "feeBreakdown": {
      "fee": 10,
      "vat": 0,
      "processorFee": 0,
      "allInclusiveKyshiFee": 10,
      "stampDuty": 0,
      "others": {},
      "totalFees": 10
    }
  }
}