Collection Post Request

You can make the payment using any of the URLs below

Live

POST  https://kitegateway.com/v1/collections/request-to-pay

Sandbox

POST  https://sandbox.kitegateway.com/v1/collections/request-to-pay

Headers

Request Headers

Header	Value	Required
Content-Type	application/json	YES
Accept	application/json	YES
Authorization	JWT ***	YES

Request

Request Body

Parameter	Type	Description	Required
currency	string	The medium of exchange for goods and services. e.g USD, UGX, KES In case the currency is different from the merchant wallet where the money is supposed to go, the funds will be exchanged based on the market rate	YES
amount	double	2 decimal places	YES
payment_method	string	The means through which the money will be transacted. MOBILE_MONEY, CARD, BANK, CRYPTO	YES
account_number	string	The unique identifier on the providers' network where the money will originate from. For mobile money ie if the payment_method isMOBILE_MONEY, you should provide an internationally formatted phone_number i.e 2567041111111	Not Required for CARD
merchant_reference	string	The UNIQUE Identification for a transaction generated by your merchant application	YES, UUID4 9 to 36 character
narration	string	A brief description of the transaction	required, 9 to 64 characters max
redirect_url	string	When a payment is initiated, sometimes a payment link is returned in the response if the payment must be completed by the customer via the payment_url The payment methods that return a payment_url link include, online banking methods, visa 3d So the redirect_url is used to redirect the customer after payment has been completed or canceled via the payment_url	Required for BANK, CARD and CRYPTO collections.
account_name	string	The name of your customer who is making the payment request	Required for CARD
account_email	string	The email of your customer who is making the request	Required for CARD

Response

Response body

Parameters	Type	Description
request_amount	double	Amount requested for collection
request_currency	string	The currency of the requested amount
account_amount	double	The converted amount from request_currency to wallet_currency at market rate.
account_currency	string	The wallet currency where the amount paid by the customer will be deposited. The currency of the amount paid by the customer is determined by the provider used to pay.
transaction_fee	double	This is the fee charged based on the paid amount.
total_credit	double	This is the amount less the transaction_fee deposited in your account wallet
merchant_reference	string	This is the reference that was specified at the start of the transaction
kitegateway_reference	string	This is the unique id of the transaction on the Kitegateway network. You are advised to store it because it is used to track transaction-related queries.
transaction_status	string	The stage of the transaction
customer_charged	boolean	It indicates whether if the merchant customer was charged instead
payment_url	string	Optional The URL where the customer is redirected to complete the payment. It's only returned if the payment has to be completed from a web browser.
instructions	string	Optional It contains instructions that advise the customer about what they should next. It is always present on mobile money transactions and requests that do not contain payment_url. We recommend that you display the instructions to the customer

Sample Request

{ 
    "currency": "USD", // OR KES or TZS or RWF or USD or EUR ..etc
    "amount": 200,
    "account_number": "256775123123",
    "payment_method": "CARD", // OR CARD or BANK or CRYPTO, 
    "merchant_reference": "Your unique payment reference", 
    "narration": "Reason for payment",
    "redirect_url": "optional.For payments completed via payment_url ",
    "account_name": "Ankunda Ruth",
    "account_email": "[e-mail]"
}

Sample Response

{
  "code": 200,
  "status": "accepted",
  "message": "Transaction Initiated",
  "data": {
    "id": "8823887277266266662662662",
    "request_amount": 20000,
    "request_currency": "UGX",
    "account_amount": 20000,
    "account_currency": "UGX",
    "transaction_fee": 3000,
    "total_credit": 15000,
    "merchant_reference": "3CC383-3A673-8392-AF883-99AKJ",
    "kitegateway_reference": "WPC405GZM1G5JXGA71IK",
    "transaction_status": "PENDING",
    "transaction_type": "collection",
    "message": "Transaction started",
    "account_name": "Ankunda Ruth",
    "account_email": "[e-mail]",
    "customer_charged": false,
    "payment_url": "Exists if web browser shold be used to complete payments",
    "instructions": [
      {
        "step": "1",
        "description": "Ensure that you have enough money on your Airtel Money account"
      },
      {
        "step": "2",
        "description": "When the USSD screen appears with the specified amount, approve the payment"
      }
    ]
  }
}

Sample IPN

{
    "id": "888237273723723772377232323",
    "request_amount": 20000,
    "request_currency": "UGX",
    "account_amount": 20000,
    "account_currency": "UGX",
    "transaction_fee": 3000,
    "total_credit": 15000,
    "customer_charged": false,
    "merchant_reference": "3CC383-3A673-8392-AF883-99AKJ",
    "kitegateway_reference": "KG405GZM1G5JXGA71IK",
    "transaction_status": "COMPLETED",
    "transaction_type": "collection",
    "message": "Transaction Completed Successfully",
    "account_name": "Ankunda Ruth",
    "account_email": "[e-mail]",
    "institution_name": "Optional eg: Aritel Money Uganda"
}