Transactions

Initialize transaction

Changed on Nov 3, 2026

Creates a pending transaction and returns a hosted checkout URL. A 201 means the request was accepted, not that the customer has paid: verify before releasing value.

post/v1/transactions/initialize

Request

Base URL
https://api.kyshi.co
Auth
API key in header x-api-key
TypeScript
https://skmtc.dev/kyshi/apis/kyshi-mor-public-api/docs/v1/transactions/initialize/post.ts
A function with typed inputs. Its response is checked against the schema.

Request body

emailstring required

firstNamestring required

lastNamestring required

phoneNumberstring required

localCurrency'NGN' | 'KES' | 'ZAR' | 'GHS' | 'XOF' | 'USD' required

referencestring required

channelsstring[] required

amountnumber required

amountCurrency'settlement' | 'local'

How to interpret 'amount'. Defaults to 'settlement' for backward compatibility.

metadataobject required

redirectUrlstring required

feeBearer'MERCHANT' | 'CUSTOMER' required

taxChargeable'INCLUSIVE' | 'EXCLUSIVE' required

chargeType'BANK_TRANSFER' required

expiresAtstring required

Example request

{
  "email": "dom@yopmail.com",
  "firstName": "Dom",
  "lastName": "Aba",
  "phoneNumber": "2250734567890",
  "localCurrency": "XOF",
  "reference": "ORDER-100045",
  "channels": [
    "mobile_money"
  ],
  "amount": 1000,
  "amountCurrency": "local",
  "metadata": {
    "orderId": "ORDER-100045",
    "source": "checkout"
  },
  "redirectUrl": "https://merchant.example.com/payments/return",
  "feeBearer": "CUSTOMER",
  "taxChargeable": "EXCLUSIVE",
  "chargeType": "BANK_TRANSFER",
  "expiresAt": "2026-09-30T23:59:59Z"
}

Response

Success.

statusboolean required

true on success.

messagestring required

codenumber required

Mirrors the HTTP status code.

Example response

{
  "status": true,
  "message": "Success",
  "code": 200,
  "data": {}
}

Changes

Nov 3, 20264aed77604588 Revision changes
- breaking
  added the new required request property
- breaking
  added the new required request property
- breaking
  the request property became required
- breaking
  the request property became required
- breaking
  the request property became required
- breaking
  the request property became required
- breaking
  the request property became required
- breaking
  the request property became required
- breaking
  the request property became required
- breaking
  the request property became required
- breaking
  the request property became required
- info
  the endpoint scheme security ApiKeyAuth was added to the API
- info
  the request property format was generalized from email to no format
- info
  added subschema #2 to the response body allOf list for the response status
- info
  removed from the response body allOf list for the response status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status

Operation history