# Home Welcome to the **Kitegateway** APIs! You can use our APIs to send and receive money, through major mobile money providers, visa and banks. Kitegateway API is fully based on [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) API (Application Programming Interfaces). This implies that the API uses standard HTTP verbs which are understood by most HTTP clients. You can view code examples in the dark area, and you can switch the programming language of the examples with the tabs. Kitegateway API is a payment platform powerhouse. Behind these APIs is a software layer connecting and optimising payments services around the world to allow businesses to send and receive money, globally. # Introduction We assign an account manage who set ups your account at [https://kitegateway.com ](https://kitegateway.com/). Our team will get back to you within 24 hours. If you have a merchant account already, go to the next step and sign in . Once you sign in, you can now create a business account. You can then select an business merchant so that you manage its users, mids and charge configurations. To make a payment request, you will generate your business account [`API KEY`](/dashboard/api-credentials#api_key) and [`API SECRET`](/dashboard/api-credentials#api_secret)from you business account profile page {% hint style="warning" %} Protect your `API KEY` and `API SECRET` at all times including but not limited to avoiding saving them to source code repositories. {% endhint %} You can always re-generate the `API KEY` and `API SECRET` if compromised or need to change it. In as much as you can test on the sandbox as you wish, once you are ready to go into production contact us to inform us that you are ready. We shall go through your sandbox test cases to confirm that every use case has been covered and do other background checks to make sure that you are fully set. This is to get your admin user account and business accounts verified. Once verified then you can start to receive and send payments for that particular merchant account. # Request/Response Format The default response format is JSON. Requests with a message-body use plain JSON to set or update resource attributes. Successful requests will return a `200 OK` HTTP status. Some general information about responses: * Dates are returned in ISO8601 format: `YYYY-MM-DDTHH:MM:SS` * Resource IDs are returned as integers. * Any decimal monetary amount, such as prices or totals, will be returned as strings with two decimal places. * Other amounts, such as item counts, are returned as integers. * Blank fields are generally included as `null` or \`empty string\` instead of being omitted. # Errors Occasionally you might encounter errors when accessing the REST API. There are four possible types: | Error Code | Error Type | | --------------------------- | ---------------------------------------------------------- | | `400 Bad Request` | Invalid request, e.g. using an unsupported HTTP method | | `401 Unauthorized` | Authentication or permission error, e.g. incorrect API-KEY | | `404 Not Found` | Requests to resources that don't exist or are missing | | `500 Internal Server Error` | Server error | > Kitegateway REST API error example: ```javascript { "code": "kitegateway_rest_term_invalid", "status": "indicate if request was successfull", "message": "Resource doesn't exist.", "data": { "...": ... } } ``` Errors return both an appropriate HTTP status code and response object which contains a `code`, `message`, `status` and `data` attribute. # Parameters Almost all endpoints accept optional parameters which can be passed as a HTTP query string parameter, e.g. `GET /collections?status=completed`. All parameters are documented along each endpoint. # Pagination Requests that return multiple items will be paginated to 10 items by default. This default can be changed by the site administrator by changing the `posts_per_page` option. Alternatively the items per page can be specified with the `?per_page` parameter: `GET /collections?per_page=15` You can specify further pages with the `?page` parameter: `GET /collections?page=2` You may also specify the offset from the first resource using the `?offset` parameter: `GET /collections?offset=5` Page number is 1-based and omitting the `?page` parameter will return the first page. The total number of resources and pages are always included in the `X-PH-Total` and `X-PH-TotalPages` HTTP headers. #### Link Header Pagination info is included in the [Link Header](http://tools.ietf.org/html/rfc5988). It's recommended that you follow these values instead of building your own URLs where possible. ``` Link: ; rel="next", ; rel="last"` ``` The possible `rel` values are: | Value | Description | | ------- | -------------------------------------------------------- | | `next` | Shows the URL of the immediate next page of results. | | `last` | Shows the URL of the last page of results. | | `first` | Shows the URL of the first page of results. | | `prev` | Shows the URL of the immediate previous page of results. | # Registration 1\. Normally you submit your details to us via other channels of communication established or via email. {% hint style="danger" %} Email {% endhint %} 2\. You will be required to submit the different relevant KYC documents. These documents are required by our legal to ascertain your business authenticity. Some times we are acting as intermediaries for payment service providers or fintechs and in that we create accounts as authorised. 3\. We use your details to set up the main admin account that you can use to sign in to start to explore our platform. 4\. If everything is okay with the submitted KYC, it should take two (2) business days to verify your account 5\. You can go ahead to create a business account # Environments Once you are on the dashboard. You can sign in from here for **live** environment or for sandbox environment. The **sandbox** is a testing environment that isolates untested code changes and outright experimentation from the **live** environment. When using this environment. No actual payments will be made. The **live** environment is used to effect actual payments across our different payment providers. {% hint style="success" %} After you are sure that everything is working well in the sandbox, you can consult our support to take your business live. {% endhint %} # API Tokens Each business account can create up-to 2 API Tokens at a given time. The token has two important values; the **api\_key** and the **api\_secret** ### api\_key Uniquely identifies the merchant it is associated with. Every request must include this key ### api\_secret This key is also unique to the merchant account. It is required for every authenticated request. In an authenticated request, the **api\_secret** and **api\_key** are mandatory. ### Creating the keys From the dashboard and from the let navigation of your screen, navigate to the specific business account you want to manage. Once selected, navigate to api tokens page and generate the API tokens. ### Viewing the keys {% hint style="danger" %} **NOTE**\ \ Your **api\_key** and the **api\_secret** are displayed once upon generation. However we store the encrypted version of the **api\_secret**. None of us knows your secret so you have to store and use it in the safest way. {% endhint %} # Step by Step Guide ## 1. Create merchant account A **business account** is a business that is ready to accept payments in multiple ways, typically mobile money, crypto, debit or credit cards. From the left side bar menu, choose business accounts and then tap the `Add business account` button in order to create business accounts. Part of the information included in the merchant account comprise:
#### Name A business name is your business's legal name. It is the official name of the person or entity that owns a company. And, it's the name you use on your government forms and business paperwork #### RR This is the rolling reserve percentage as specified by the acquirer #### RR(Months) The number of months the rolling reserve will take to expire #### Card T+ (Days) The settlement time of the funds ## 2. Create MID/PSP Mids are terminals that are used to route traffic. You will need to set up a mid before you can start transacting
**Mid Business Name** This is the business name as registered at the acquirer. We recommend postfixing the Mid name with the acquirer name for easier management but this is entirely optional. For example a mid name will be like **your-mid-name-acquirer-name** **Service Type** This defines the payment processor who is going to transact eg `vcs - for cybersource`, `mpgs - for mastercard`, etc **Payment Method** This is the means of transacting that is being used eg **CARD** [see](/appendix/payment-methods) **Currency** The currency being used to transact see **Allowed traffic** The kind of traffic that is being used to traffic. This helps to keep afloat with the relevant MCC codes and is route traffic to appropriately. **Merchant Operator** The operator that is being used at the acquirers processor **Merchant Username** The username that is being used at the acquirers processor terminal **Merchant Password** The password to the processor terminal being used **Processing Rank** This determines the priority in which the mid should be selected. The algorithm for selection is based on round robin. 1 for is for highest ranking. **Reject First Time Depositors** This option is one of our fraud detection option in our algorithm. New cards are notorious for fraud. When this option is selected, only cards that have been issued after one year are used for transacting. **Active** Used to make the mid live for processing otherwise the mid wont be selected to be used in the pool as an option for processing ## 3. Generate API Tokens **API Tokens** include a **key** that identifies the merchant responsible for the **API** service request. This **key** is not a **secret**, and must be included in each request. **API Token** includes a confidential **secret key** used for authentication, which is only known to the merchant and to the **API** service.
{% hint style="warning" %} From the left sidebar, navigate to business accounts and create a business account or choose an existing one. After that select the business account you have created then navigate to the Api Keys tab to generate API token. Incase you have lost your secret, you can regenerate a new one {% endhint %} {% hint style="danger" %} Every collection action requires only the **api\_key**. However all disbursements must include the **api\_secret** {% endhint %} Besides the API KEY and API SECRET. The API token includes the following; #### **Notification Email** This is the email that will receive any payment related notifications at the start and then the summaries at the end. #### **Webhook URL** This is used by kitegateway to send real time payment status updates. #### Webhook Hash With just the webhook URL alone, any services on the internet can possibly send request to it so in order to protect against that, the hash comes into play. The hash helps to identify that the request actually came from **Kitegateway** thus providing an extra layer of security. {% hint style="info" %} You have to generate at least 16 character hash {% endhint %} **Email Merchant** Specifies if the merchant should receive payment notifications **Email User** Specifies if the user making the payment request should receive payment notifications ## 4. Make a request Once you have set up the crucial details above, you can now start making transactions to collect and disburse money in the form of mobile money, card and crypto. {% hint style="success" %} Horray! :) {% endhint %} # Test numbers The sandbox environment behaves like the real environment except for the fact that no real transactions are performed. You will need the following parameters for use in sandbox. # Mobile Money Test Numbers | phone | Description | | ------------------------------- | ------------------------------------ | | `256777111786` , `256752000123` | Getting successful requests response | | `256777000456` , `256752000456` | Getting failure requests response | # Card Test Numbers ### Test Card 3D Success > **Card number:** `4024 0071 9269 0864`\ > **cvv:** 334\ > **Expiry:** 02/29\ > **Pin:** 6620\ > **OTP:** 12345 ### Test Card 3D Failure > **Card number:** `4024 0071 4508 7440`\ > **cvv:** 334\ > **Expiry:** 02/29\ > **Pin:** 6620\ > **OTP:** 12345 # Access Token All request must have an **Access token**. Access tokens are used to make API requests on behalf of your merchant account. It is used for **Authorization**. Access tokens must be kept confidential in transit and in storage. The only parties that should ever see the access token are Kitegateway APIs and your servers. Your application should ensure the storage of the access token is not accessible to other applications ## How to get an access token You have to use your merchant [**api\_key**](/dashboard/api-credentials#api_key) and [**api\_secret**](/dashboard/api-credentials#api_secret) in order to get an access token by making a request as below #### Live ```typescript POST https://kitegateway.com/v1/auth/token ``` **Sandbox** ``` POST https://sandbox.kitegateway.com/v1/auth/token ``` {% tabs %} {% tab title="Headers" %} #### Request Headers | Header | Value | Required | | ---------------- | ---------------------- | -------- | | **Content-Type** | **`application/json`** | YES | | **Accept** | **`application/json`** | YES | | **Secret-Key** | **`YOUR_SECRET`** | YES | | {% endtab %} | | | {% tab title="Request" %} #### Request Body | Parameter | Type | Description | Required | | --------------- | ------- | ------------------------------------------------- | ----------------------------- | | **api\_key** | string | Obtained from merchant profile account | YES | | **expires\_in** | integer | The time taken for the token to expire in seconds | Optional. Default 900 seconds | | {% endtab %} | | | | {% tab title="Response" %} #### Response body | Parameters | Type | Description | | ------------ | ------- | ---------------------------------------------------------------------------- | | token | string | The access token that can be used to make a request on any of the end points | | expires | integer | The timestamp of when the token will expire | | {% endtab %} | | | {% tab title="Sample Request" %} ```typescript { "api_key": "2882jj2hh288282jj2", // Obtain from your merchant profile" "expires_in": 300 } ``` {% endtab %} {% tab title="Sample Response" %} ```typescript { "code": 200, "status": "success", "message": "Token generated", "data": { "token": "JWT eyJ0eXAiOiBBV1QzI1NiJ9.eTAW0InJvbGUi2YifQ.f6FPyTxzchGD7ed55Rw7ruqe6P_Go", "expires": 1622197906 } } ``` {% endtab %} {% endtabs %} {% hint style="danger" %} #### Header: Authorization All Requests to whatever Kitegateway end point must contain an authorization header that contains the token generated. This provides another layer of security. To even strengthen the security further, this token should be as short lived as much as possible based on the specified scenario. **`e.g`"Authorization: JWT eyJ0ejjsjjdjjjjsjjs.eTThhhshhshhhs.88asd998sads..."** {% endhint %} # Steps Allows your merchant account to get paid in a way that works for you using the various options we provide. You can receive funds from anyone, anywhere directly into your wallet through our payment methods that support; `mobile` `money`, `card` and `crypto` ### Steps for receiving money 1. Create your request data as a JSON 2. Set the relevant request headers; a) **`Content-Type`: `application/json`**\ b) **`Accept`**: **`application/json`** c) [**`Authorization`**](/authorization/access-token#how-to-get-an-access-token) The access token that was generated on the authorization `API` 3. `POST` the composed data to the collections `API`. 4. Process the response returned by the `API` In-case the response contains a `payment_url` that is required to complete a transaction, we expect your application to redirect the customer to the payment `URL` 5. As the payment is being processed on our side, any change in payment status will be sent to the respective [`webhook URL`](/appendix/webhook) of the merchant account. # Collection Post Request You can make the payment using any of the URLs below #### Live ```typescript POST https://kitegateway.com/v1/collections/request-to-pay ``` **Sandbox** ``` POST https://sandbox.kitegateway.com/v1/collections/request-to-pay ``` {% tabs %} {% tab title="Headers" %} #### Request Headers | Header | Value | Required | | ---------------- | ---------------------- | -------- | | **Content-Type** | **`application/json`** | YES | | Accept | **`application/json`** | YES | | Authorization | **`JWT ***`** | YES | | {% endtab %} | | | {% tab title="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** is`MOBILE_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 | | {% endtab %} | | | | {% tab title="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

| | {% endtab %} | | | {% tab title="Sample Request" %} ```typescript { "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": "ankunda99ruth@gmail.com" } ``` {% endtab %} {% tab title="Sample Response" %} ```javascript { "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": "ankunda99ruth@gmail.com", "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" } ] } } ``` {% endtab %} {% tab title="Sample IPN" %} ```javascript { "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": "ankunda99ruth@gmail.com", "institution_name": "Optional eg: Aritel Money Uganda" } ``` {% endtab %} {% endtabs %} ### # Mobile Money Payment ### Set Payment Method When the payment transaction is to be completed using mobile money, The **`payment_method`** field should be set to **`MOBILE_MONEY`** in the post request collection body. {% tabs %} {% tab title="Sample Request Body" %} ```javascript { ... "method": "MOBILE_MONEY", ... } ``` {% endtab %} {% endtabs %} ### Instructions Directions about how the payment will be completed will be sent in the response body {% tabs %} {% tab title="Sample Response Body" %} ```javascript { ... "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 by entering the PIN" } ] ... } ``` {% endtab %} {% endtabs %} # Card Payment ### Set Payment Method When the payment transaction is to be completed using card, the **`payment_method`** field should be set to **`CARD`** in the post request collection body. For card payments, since we only support 3D. This means that the customer's card must be enabled for 3D authentication for them to complete their card payments. So in the request body, you should provide a **`redirect_url`** where the customer will be navigated to when they complete or cancel the transaction {% hint style="danger" %} #### redirect\_url It must be secured by **SSL.** ie, it must start with **https\://** {% endhint %} {% tabs %} {% tab title="Sample Request Body" %} ```javascript { ... "payment_method": "CARD", "redirect_url": "https://your-redirect_url" ... } ``` {% endtab %} {% endtabs %} ### Redirect customer We expect your application to redirect the customer to that **`payment_url`** to complete the payment # Direct card payment A **direct card payment** is a payment transaction in which your customer has authorized you to take money from their card using their full card details. However, the **`Card`** details are sent as an encrypted string. Posting a direct card request is the same as posting a card payment however the**`encrypted_card`** parameter will have to be specified. By providing this field, kitegateway will know that the transaction is a direct card payment. ## Providing `encrypted_card` ### Encryption #### **1. Create JSON of the Card details** {% tabs %} {% tab title="Data" %} ```javascript { "full_name": "Nakimbugwe Racheal", "card_number": "012345666777888999", "expiry_month": "02", "expiry_year": "24", "cvv": "111", "billing_address": "Some Street", "billing_city": "Some City", "billing_zip": "88653", "billing_state": "JK", "billing_country": "UK" } ``` {% endtab %} {% tab title="Description" %} | Parameter | Type | Description | Required | | ---------------- | ------ | -------------------------------------------------------------------------------------------------------------- | -------- | | full\_name | string | The full name of the card holder as registered by the card issuer | YES | | card\_number | string | The card number. Usually the length of 16 to 19 | YES | | expiry\_month | string | Card expiry month. For single digit months, prefix 0 e.g. `06` | YES | | expiry\_year | string | Card expiry year | YES | | cvv | string | The card CVV, CVC, etc depending on the nature of the card | YES | | billing\_address | string | Billing address as registered by the card issuer. | YES | | billing\_city | string | Billing city name as registered by the issuer. | YES | | billing\_zip | string | The zip/postal code. | YES | | billing\_state | string | State name. | YES | | billing\_country | string | The 2 character ISO country code. The country code list can be obtained using the API description that follows | YES | | {% endtab %} | | | | | {% endtabs %} | | | | #### **2.** Downloading Public Key ```javascript // Live GET https://kitegateway.com/v1/public-key ``` ```javascript // Sandbox GET https://sandbox.kitegateway.com/v1/public-key ``` {% tabs %} {% tab title="Shell" %} ``` // live curl -v -X GET 'https://kitegateway.com/v1/public-key -H 'Authorization: JWT ***' --output kitegateway.public.key.pem ``` {% endtab %} {% endtabs %} #### 3.Encryption Card {% tabs %} {% tab title="NodeJS" %} ```javascript const crypto = require('crypto'); const fs = require('fs'); const card_data = { full_name: "Ankunda Ruth", card_number: "0002221238737737737", expiry_month: "02", expiry_year: "24", cvv: "111", billing_address: "Kensington Street No. 2", billing_city: "London", billing_zip: "12345", billing_state: "London", billing_country: "UK", }; function encrypt(card_data) { // Stringify card data const payload = JSON.stringify(card_data); console.log(`Payload size: ${Buffer.from(payload).length} bytes`); // Load public key const publicKeyFile = "path-to-file/kitegateway.public.key.pem"; const publicKey = fs.readFileSync(publicKeyFile).toString().replace(/\\n/g, '\n'); // Check payload size (max 214 bytes for 2048-bit key with OAEP padding) if (Buffer.from(payload).length > 214) { // Generate AES key and IV const aesKey = crypto.randomBytes(32); // 256-bit AES key const iv = crypto.randomBytes(16); // 128-bit IV // Encrypt payload with AES-256-CBC const cipher = crypto.createCipheriv('aes-256-cbc', aesKey, iv); let encryptedData = cipher.update(payload, 'utf8', 'base64'); encryptedData += cipher.final('base64'); console.log(`AES encrypted data size: ${Buffer.from(encryptedData, 'base64').length} bytes`); // Encrypt AES key with RSA-OAEP const encryptedAesKey = crypto.publicEncrypt( { key: publicKey, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING }, aesKey ); // Combine encrypted data, IV, and encrypted AES key const result = `${encryptedData}::${iv.toString('base64')}::${encryptedAesKey.toString('base64')}`; const base64Result = Buffer.from(result).toString('base64'); // Validate base64 if (!/^[A-Za-z0-9+/=]+$/.test(base64Result)) { console.error('Invalid base64 encoding of hybrid ciphertext.'); return null; } console.log(`Hybrid encrypted data (base64): ${base64Result}`); return base64Result; } // Standard RSA-OAEP encryption const encryptedData = crypto.publicEncrypt( { key: publicKey, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING }, Buffer.from(payload) ); const base64Result = encryptedData.toString('base64'); // Validate base64 if (!/^[A-Za-z0-9+/=]+$/.test(base64Result)) { console.error('Invalid base64 encoding of ciphertext.'); return null; } return base64Result; } ``` {% endtab %} {% tab title="PHP" %} ```php $full_name, 'card_number' => $card_number, 'expiry_month' => $expiry_month, 'expiry_year' => $expiry_year, 'cvv' => $cvv, 'billing_address' => $billing_address, 'billing_city' => $billing_city, 'billing_zip' => $billing_zip, 'billing_state' => $billing_state, 'billing_country' => $billing_country ]); if ($card_data === false) { openssl_free_key($public_key); return $ret; } $data_size = strlen($card_data); // Hybrid encryption for data > 214 bytes if ($data_size > 214) { // Generate AES key and IV $aes_key = openssl_random_pseudo_bytes(32); $iv = openssl_random_pseudo_bytes(16); // Encrypt data with AES-256-CBC $encrypted_data = openssl_encrypt($card_data, 'AES-256-CBC', $aes_key, 0, $iv); if ($encrypted_data === false) { openssl_free_key($public_key); return $ret; } // Encrypt AES key with RSA-OAEP if (!openssl_public_encrypt($aes_key, $encrypted_aes_key, $public_key, OPENSSL_PKCS1_OAEP_PADDING)) { openssl_free_key($public_key); return $ret; } // Combine components $ret = base64_encode($encrypted_data . '::' . base64_encode($iv) . '::' . base64_encode($encrypted_aes_key)); } else { // Standard RSA-OAEP encryption for small data if (!openssl_public_encrypt($card_data, $result, $public_key, OPENSSL_PKCS1_OAEP_PADDING)) { openssl_free_key($public_key); return $ret; } $ret = base64_encode($result); } openssl_free_key($public_key); return $ret; } // Example usage (for testing) /* $public_key_path = 'kitegateway.public.key.pem'; $encrypted = encrypt_card_details( $public_key_path, 'Test User', '4111111111111111', '12', '25', '123', '123 Main St, Apt 4B', 'Springfield', '62701', 'IL', 'US' ); echo $encrypted ? $encrypted : 'Encryption failed'; */ ?> ``` {% endtab %} {% tab title="Python" %} ```python import json import base64 import os from cryptography.hazmat.primitives import serialization, hashes from cryptography.hazmat.primitives.asymmetric import padding, rsa from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes from cryptography.hazmat.backends import default_backend def encrypt_card_details( public_key_path, full_name, card_number, expiry_month, expiry_year, cvv, billing_address, billing_city, billing_zip, billing_state, billing_country ): try: # Load public key if not os.path.exists(public_key_path): return None with open(public_key_path, 'rb') as f: public_key = serialization.load_pem_public_key(f.read(), backend=default_backend()) # Verify key size if not isinstance(public_key, rsa.RSAPublicKey) or public_key.key_size != 2048: return None # Prepare card data as JSON card_data = json.dumps({ 'full_name': full_name, 'card_number': card_number, 'expiry_month': expiry_month, 'expiry_year': expiry_year, 'cvv': cvv, 'billing_address': billing_address, 'billing_city': billing_city, 'billing_zip': billing_zip, 'billing_state': billing_state, 'billing_country': billing_country }).encode('utf-8') data_size = len(card_data) if data_size > 214: # Generate AES key and IV aes_key = os.urandom(32) iv = os.urandom(16) # Encrypt data with AES-256-CBC cipher = Cipher(algorithms.AES(aes_key), modes.CBC(iv), backend=default_backend()) encryptor = cipher.encryptor() padded_data = card_data + b'\0' * (16 - (data_size % 16)) # PKCS7-like padding encrypted_data = encryptor.update(padded_data) + encryptor.finalize() # Encrypt AES key with RSA-OAEP encrypted_aes_key = public_key.encrypt( aes_key, padding.OAEP(mgf=padding.MGF1(algorithm=hashes.SHA1()), algorithm=hashes.SHA1(), label=None) ) # Combine components return base64.b64encode( encrypted_data + b'::' + base64.b64encode(iv) + b'::' + base64.b64encode(encrypted_aes_key) ).decode('utf-8') else: # Standard RSA-OAEP encryption encrypted_data = public_key.encrypt( card_data, padding.OAEP(mgf=padding.MGF1(algorithm=hashes.SHA1()), algorithm=hashes.SHA1(), label=None) ) return base64.b64encode(encrypted_data).decode('utf-8') except Exception: return None # Example usage """ if __name__ == '__main__': result = encrypt_card_details( 'kitegateway.public.key.pem', 'Test User', '4111111111111111', '12', '25', '123', '123 Main St, Apt 4B', 'Springfield', '62701', 'IL', 'US' ) print(result if result else 'Encryption failed') """ ``` {% endtab %} {% tab title="Ruby" %} ```ruby require 'json' require 'base64' require 'openssl' def encrypt_card_details( public_key_path, full_name, card_number, expiry_month, expiry_year, cvv, billing_address, billing_city, billing_zip, billing_state, billing_country ) begin # Load public key return nil unless File.exist?(public_key_path) public_key = OpenSSL::PKey::RSA.new(File.read(public_key_path)) # Verify key size return nil unless public_key.n.num_bytes * 8 == 2048 # Prepare card data as JSON card_data = JSON.dump({ full_name: full_name, card_number: card_number, expiry_month: expiry_month, expiry_year: expiry_year, cvv: cvv, billing_address: billing_address, billing_city: billing_city, billing_zip: billing_zip, billing_state: billing_state, billing_country: billing_country }) data_size = card_data.bytesize if data_size > 214 # Generate AES key and IV aes_key = OpenSSL::Random.random_bytes(32) iv = OpenSSL::Random.random_bytes(16) # Encrypt data with AES-256-CBC cipher = OpenSSL::Cipher.new('AES-256-CBC') cipher.encrypt cipher.key = aes_key cipher.iv = iv encrypted_data = cipher.update(card_data) + cipher.final # Encrypt AES key with RSA-OAEP (simulated via PKCS1_OAEP padding) encrypted_aes_key = public_key.public_encrypt(aes_key, OpenSSL::PKey::RSA::PKCS1_OAEP_PADDING) # Combine components Base64.encode64( encrypted_data + '::' + Base64.encode64(iv) + '::' + Base64.encode64(encrypted_aes_key) ).chomp else # Standard RSA-OAEP encryption encrypted_data = public_key.public_encrypt(card_data, OpenSSL::PKey::RSA::PKCS1_OAEP_PADDING) Base64.encode64(encrypted_data).chomp end rescue nil end end # Example usage =begin result = encrypt_card_details( 'kitegateway.public.key.pem', 'Test User', '4111111111111111', '12', '25', '123', '123 Main St, Apt 4B', 'Springfield', '62701', 'IL', 'US' ) puts result || 'Encryption failed' =end ``` {% endtab %} {% tab title="C#" %} ```csharp using System; using System.IO; using System.Security.Cryptography; using System.Text; using System.Text.Json; public class EncryptCardDetails { public static string Encrypt( string publicKeyPath, string fullName, string cardNumber, string expiryMonth, string expiryYear, string cvv, string billingAddress, string billingCity, string billingZip, string billingState, string billingCountry) { try { // Load public key if (!File.Exists(publicKeyPath)) return null; string keyContent = File.ReadAllText(publicKeyPath); using var rsa = RSA.Create(); rsa.ImportFromPem(keyContent.ToCharArray()); // Verify key size if (rsa.KeySize != 2048) return null; // Prepare card data as JSON var cardData = JsonSerializer.Serialize(new { full_name = fullName, card_number = cardNumber, expiry_month = expiryMonth, expiry_year = expiryYear, cvv, billing_address = billingAddress, billing_city = billingCity, billing_zip = billingZip, billing_state = billingState, billing_country = billingCountry }); byte[] cardDataBytes = Encoding.UTF8.GetBytes(cardData); int dataSize = cardDataBytes.Length; if (dataSize > 214) { // Generate AES key and IV using var aes = Aes.Create(); aes.KeySize = 256; aes.GenerateKey(); aes.GenerateIV(); // Encrypt data with AES-256-CBC using var ms = new MemoryStream(); using (var cs = new CryptoStream(ms, aes.CreateEncryptor(), CryptoStreamMode.Write)) { cs.Write(cardDataBytes, 0, cardDataBytes.Length); cs.FlushFinalBlock(); } byte[] encryptedData = ms.ToArray(); // Encrypt AES key with RSA-OAEP byte[] encryptedAesKey = rsa.Encrypt(aes.Key, RSAEncryptionPadding.OaepSHA1); // Combine components string result = Convert.ToBase64String(encryptedData) + "::" + Convert.ToBase64String(aes.IV) + "::" + Convert.ToBase64String(encryptedAesKey); return Convert.ToBase64String(Encoding.UTF8.GetBytes(result)); } else { // Standard RSA-OAEP encryption byte[] encryptedData = rsa.Encrypt(cardDataBytes, RSAEncryptionPadding.OaepSHA1); return Convert.ToBase64String(encryptedData); } } catch { return null; } } } // Example usage /* class Program { static void Main() { string result = EncryptCardDetails.Encrypt( "kitegateway.public.key.pem", "Test User", "4111111111111111", "12", "25", "123", "123 Main St, Apt 4B", "Springfield", "62701", "IL", "US" ); Console.WriteLine(result ?? "Encryption failed"); } } */ ``` {% endtab %} {% tab title="Java" %} ```java import javax.crypto.Cipher; import javax.crypto.spec.IvParameterSpec; import javax.crypto.spec.SecretKeySpec; import java.io.File; import java.nio.file.Files; import java.security.KeyFactory; import java.security.PublicKey; import java.security.spec.X509EncodedKeySpec; import java.util.Base64; import com.google.gson.Gson; public class EncryptCardDetails { public static String encrypt( String publicKeyPath, String fullName, String cardNumber, String expiryMonth, String expiryYear, String cvv, String billingAddress, String billingCity, String billingZip, String billingState, String billingCountry) { try { // Load public key File keyFile = new File(publicKeyPath); if (!keyFile.exists()) return null; String keyContent = new String(Files.readAllBytes(keyFile.toPath())) .replace("-----BEGIN PUBLIC KEY-----", "") .replace("-----END PUBLIC KEY-----", "") .replaceAll("\\s", ""); byte[] keyBytes = Base64.getDecoder().decode(keyContent); X509EncodedKeySpec spec = new X509EncodedKeySpec(keyBytes); KeyFactory kf = KeyFactory.getInstance("RSA"); PublicKey publicKey = kf.generatePublic(spec); // Verify key size if (publicKey.getAlgorithm().equals("RSA") && ((java.security.interfaces.RSAPublicKey) publicKey).getModulus().bitLength() != 2048) { return null; } // Prepare card data as JSON Gson gson = new Gson(); String cardData = gson.toJson(new CardData( fullName, cardNumber, expiryMonth, expiryYear, cvv, billingAddress, billingCity, billingZip, billingState, billingCountry)); byte[] cardDataBytes = cardData.getBytes("UTF-8"); int dataSize = cardDataBytes.length; if (dataSize > 214) { // Generate AES key and IV byte[] aesKey = new byte[32]; byte[] iv = new byte[16]; new java.security.SecureRandom().nextBytes(aesKey); new java.security.SecureRandom().nextBytes(iv); // Encrypt data with AES-256-CBC Cipher aesCipher = Cipher.getInstance("AES/CBC/PKCS5Padding"); aesCipher.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(aesKey, "AES"), new IvParameterSpec(iv)); byte[] encryptedData = aesCipher.doFinal(cardDataBytes); // Encrypt AES key with RSA-OAEP Cipher rsaCipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding"); rsaCipher.init(Cipher.ENCRYPT_MODE, publicKey); byte[] encryptedAesKey = rsaCipher.doFinal(aesKey); // Combine components String result = Base64.getEncoder().encodeToString(encryptedData) + "::" + Base64.getEncoder().encodeToString(iv) + "::" + Base64.getEncoder().encodeToString(encryptedAesKey); return Base64.getEncoder().encodeToString(result.getBytes("UTF-8")); } else { // Standard RSA-OAEP encryption Cipher rsaCipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding"); rsaCipher.init(Cipher.ENCRYPT_MODE, publicKey); byte[] encryptedData = rsaCipher.doFinal(cardDataBytes); return Base64.getEncoder().encodeToString(encryptedData); } } catch (Exception e) { return null; } } // Helper class for JSON serialization private static class CardData { String full_name, card_number, expiry_month, expiry_year, cvv; String billing_address, billing_city, billing_zip, billing_state, billing_country; CardData(String fullName, String cardNumber, String expiryMonth, String expiryYear, String cvv, String billingAddress, String billingCity, String billingZip, String billingState, String billingCountry) { this.full_name = fullName; this.card_number = cardNumber; this.expiry_month = expiryMonth; this.expiry_year = expiryYear; this.cvv = cvv; this.billing_address = billingAddress; this.billing_city = billingCity; this.billing_zip = billingZip; this.billing_state = billingState; this.billing_country = billingCountry; } } // Example usage /* public static void main(String[] args) { String result = encrypt( "kitegateway.public.key.pem", "Test User", "4111111111111111", "12", "25", "123", "123 Main St, Apt 4B", "Springfield", "62701", "IL", "US" ); System.out.println(result != null ? result : "Encryption failed"); } */ } ``` {% endtab %} {% endtabs %} #### 4. Set card\_cipher parameter From the step above, the resultant string after encryption is what we need to set as the **`encrypted_card`** and include it in the [**`Post Collection Request`**](/receiving-money/make-payment) when making a [**`Card Collection Request`**](/receiving-money/card-payments) {% tabs %} {% tab title="Sample Request Body" %} ```javascript { ... "encrypted_card": "***" ... } ``` {% endtab %} {% endtabs %} {% hint style="info" %} When the **`encrypted_card`** the parameter is specified in the collection request body, Kitegateway will know that you want to make a direct card payment. Since it's 3D processing, the response object will contain the bank authentication URL where you will redirect the customer to complete the payment. {% endhint %} # Crypto Payment ### Set Payment Method When the payment transaction is to be completed using cryptocurrency, The **`payment_method`** field should be set to **`CRYPTO`** in the post request collection body. We expect you to provide a, **`redirect_url`** the customer will be navigated to when they complete or cancel the transaction. {% tabs %} {% tab title="Sample Request Body" %} ```javascript { ... "method": "CRYPTO", "redirect_url": "https://your-redirect_url" ... } ``` {% endtab %} {% endtabs %} {% hint style="danger" %} #### redirect\_url It must be secured by **SSL.** ie, it must start with **https\://** {% endhint %} ### Payment Link in response Once the payment has been initiated, the response body will contain the `payment_url` . {% tabs %} {% tab title="Sample Response Body" %} ```javascript { ... "payment_url": "https://kitegateway.com/v1/collections/payment/387282737839923773737", ... } ``` {% endtab %} {% endtabs %} ### Redirect customer We expect your application to redirect the customer to that **`payment_url`** to complete the payment # Merchant Redirect ### The structure At our end, we append the redirect parameters to the URL that's set in the initial collection request by you. The final redirect URL would look like the following; ```http https://redirect_url?id=&merchant_reference=&kitegateway_reference=&status=&message=&signature= ``` {% hint style="danger" %} #### redirect\_url It must be secured by **SSL.** ie, it must start with **https\://** {% endhint %} Description of the query parameters that we append | Parameter | Type | Description | | ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | id | string | The transaction ID of the transaction | | merchant\_reference | string | Your generated merchant transaction id for the transaction | | kitegateway\_reference | string | The Kitegateway payment reference of the transaction | | status | string |

The transaction status. Values can be one of;

PENDING - When a payment is in the queue for processing, CANCELLED - If a customer cancels a payment,

FAILED - When a payment fails for some reason

COMPLETED - When a payment is successfully completed

| | message | string | Information describing the status of the transaction | | signature | string | The RSA signature generated by **Kitegateway**. This can optionally be verified by the merchant to ensure that the redirect comes from **Kitegateway** before providing service to the customer | {% hint style="warning" %} 1\. We strongly recommend you check for the availability of these parameters in the URL and also confirm that the references correspond to the data available in your application. 2\. Further we assert that you should verify the signature so that you are sure that the request is coming from our servers. This way the legitimacy of the redirect is affirmed. {% endhint %} ### How to verify redirect signature (Optional) This section describes the steps taken to verify the signature using sample query parameters. Assume that the redirect URL is as follows; ```http https://your.redirecturl?id=8828827777762662662662&merchant_reference=merc-19928288-282772&kitegateway_reference=PL4889KJSuSUUSH&status=COMPLETED&message=Transaction%20Completed%20Successfully&signature=c0K46co6bmQkoDW8XjEWQ7nBAteBo5 ``` 1. Form the string payload to be used in the signature verification. This is obtained by concatenating values of the redirect data in the format; `id:merchant_reference:kitegateway_reference:status:redirect_url` where redirect\_url is the value you specified for the **redirect\_url** parameter when making the initial collection request. 2. The string payload in our example would therefore be the following; ```bash 2888377377379926:MERC-6778J-KL8UN:PL377399-KTHHSH-888766:COMPLETED:https://your-redirecturl ``` 3\. Download the public key as described [here](/receiving-money/direct-card-payment#2-downloading-public-key). 4\. Use the public key to verify the signature as described in the sample source code below {% tabs %} {% tab title="JavaScript" %} ```javascript const crypto = require('crypto'); const fs = require('fs'); function isSignatureValid() { const strPayload = "2888377377379926:MERC-6778J-KL8UN:PL377399-KTHHSH-888766:COMPLETED:https://your-redirecturl"; const signature = "signature-from-query-params"; const publicKeyFile = "path-to-file/kitegateway.public.key.pem"; const publicKey = fs.readFileSync(publicKeyFile).toString().replace(/\\n/g, '\n'); const verify = crypto.createVerify("SHA512"); verify.write(strPayload); verify.end(); // true or false return verify.verify(publicKey, signature, 'base64'); } ``` {% endtab %} {% tab title="PHP" %} ```php ``` {% endtab %} {% endtabs %} # Refund post request Collection refunds might not go as planned as such you can request that the funds be returned to the customer. When the refund request is made, we reimburse the customer the exact or a fraction of the amount that was paid in the original transaction request. Each transaction indicates this via **`support_partial_refund`** which is sent when a payment request is made or via the webhook notification. if a fraction of the amount can be sent **`support_partial_refund`** will be **`true`**\ \ During the refund request processing, the funds are debited from your respective currency merchant account wallet.\ \ A notification about the status of the refund will be set to the set [`webhook URL`](/appendix/webhook) set under your merchant account API tokens. {% hint style="danger" %} Based on the provider, partial refunds may not be available in some scenarios {% endhint %} **Live** ```javascript POST https://kitegateway.com/v1/collections/refund ``` **Sandbox** ``` POST https://sandbox.kitegateway.com/v1/collections/refund ``` {% tabs %} {% tab title="Headers" %} #### Request | Header | Value | Required | | ----------------- | ---------------------- | -------- | | **Content-Type** | **`application/json`** | YES | | **Accept** | **`application/json`** | YES | | **Authorization** | **`JWT ***`** | YES | | {% endtab %} | | | {% tab title="Request" %} #### Request | Parameter Name | Type | Description | Required | | ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | -------- | | kitegateway\_reference | string | The Kitegateway reference of the transaction to refund. This is usually included in the API request responses or IPN's | YES | | amount | integer | (Optional) Specify for a partial refund. The amount should be less or equal to the transaction amount in the previous transaction | NO | | {% endtab %} | | | | {% tab title="Response" %}
Parameter NameTypeDescription
Parameter NameTypeDescription
id
kitegateway_referencestringThe Kitegateway reference of the transaction to refund. This is usually included in the API request responses or IPN's
transaction_amountintegerThe amount of money to refund
transaction_currencystringThe currency being refunded
transaction_feeintegerFee charged
total_debitintegerAmount debited from wallet
payment_methodstringThe payment method that was used during collection
merchant_referencestringThe reference provided by the merchant
collection_referencestringThe kitegateway collection reference that was made prior to this refund
transaction_statusstringOne of either PENDING, COMPLETED
{% endtab %} {% endtabs %} # Generate PRN The PRN API allows merchants to create unique payment references for customers. Integrate the API to generate secure, traceable PRNs with a simple request, specifying amount and customer details. The API returns a unique reference, enabling efficient transaction tracking. Streamline payment workflows and enhance user experience with reliable PRN generation for seamless merchant operations. **Live** ```javascript POST https://kitegateway.com/v1/collections/prn ``` **Sandbox** ``` POST https://sandbox.kitegateway.com/v1/collections/prn ``` {% tabs %} {% tab title="Headers" %} #### Request | Header | Value | Required | | ----------------- | ---------------------- | -------- | | **Content-Type** | **`application/json`** | YES | | **Accept** | **`application/json`** | YES | | **Authorization** | **`JWT ***`** | YES | | {% endtab %} | | | {% tab title="Request" %} #### Request | Parameter Name | Type | Description | Required | | ------------------- | ------- | --------------------------------------------------- | -------- | | merchant\_reference | string | The Merchant reference of the transaction to track. | YES | | amount | integer | The amount of money that should be transacted | YES | | currency | string | The currency that should be used to transact | YES | | narration | string | Description of what is being paid for | YES | | {% endtab %} | | | | {% tab title="Response" %}
Parameter NameTypeDescription
Parameter NameTypeDescription
id
kitegateway_referencestringThe Kitegateway reference of the transaction to refund. This is usually included in the API request responses or IPN's
transaction_amountintegerThe amount of money to refund
transaction_currencystringThe currency being refunded
merchant_referencestringThe reference provided by the merchant
transaction_statusstringOne of either PENDING, COMPLETED
transaction_typestringOne of either COLLECTION, DISBURSEMENT
{% endtab %} {% endtabs %} You can also generate the PRN by Navigation to business account and clicking Generate PRN
# Pay PRN Merchants can process payments seamlessly via using either their unique Merchant ID or a generated [Payment Reference Number (PRN)](/prn/generate-prn). This flexible system streamlines transaction management enhances tracking ensures reliability # Wallet Balances ### All wallet Balances Shows the amount of money remaining in the merchant account wallets **Live** ```javascript GET https://kitegateway.com/v1/data/wallets/balances ``` **Sandbox** ``` GET https://sandbox.kitegateway.com/v1/data/wallets/balances ``` {% tabs %} {% tab title="Request Headers" %} #### Request Headers | Header | Value | Required | | ------------- | ---------------------- | -------- | | Content-Type | **`application/json`** | YES | | Accept | **`application/json`** | YES | | Authorization | **`JWT ***`** | YES | | {% endtab %} | | | {% tab title="Response" %} #### Request Body | Parameter Name | Type | Description | | -------------- | ------ | ------------------- | | currency | string | The wallet currency | | balance | double | The wallet balance | | {% endtab %} | | | {% tab title="Sample Response" %} ```javascript { "code": 200, "status": "success", "message": "Request completed successfully.", "data": [ { "currency": "UGX", "balance": 1250000 }, { "currency": "USD", "balance": 7213 } ] } ``` {% endtab %} {% endtabs %} ### Single wallet balance Shows the amount of money remaining in a specific wallet currency **Live** ```javascript GET https://kitegateway.com/v1/data/wallets/:currency/balance ``` **Sandbox** ``` GET https://sandbox.kitegateway.com/v1/data/wallets/:currency/balance ``` {% tabs %} {% tab title="Request Headers" %} #### Request Headers | Header | Value | Required | | ------------- | ---------------------- | -------- | | Content-Type | **`application/json`** | YES | | Accept | **`application/json`** | YES | | Authorization | **`JWT ***`** | YES | | {% endtab %} | | | {% tab title="Response" %} #### Request Body | Parameter Name | Type | Description | | -------------- | ------ | ------------------- | | currency | string | The wallet currency | | balance | double | The wallet balance | | {% endtab %} | | | {% tab title="Sample Response" %} ```javascript { "code": 200, "status": "success", "message": "Request completed successfully.", "data": { "currency": "UGX", "balance": 1250000 } } ``` {% endtab %} {% endtabs %} # Payment Methods Below are supported payment methods on our platform #### MOBILE\_MONEY To collect or disburse funds using mobile money, you need to set the **payment\_method** parameter in the request body as **`MOBILE_MONEY`** {% hint style="info" %} Mobile money payments require the customer's mobile phone number specified in the**`phone_number`**field put in the international format, including its country code e.g **`256777111222`** {% endhint %} {% tabs %} {% tab title="Sample Request Body" %} ```javascript { ... "payment_method": "MOBILE_MONEY" "phone_number": "256777111222", ... } ``` {% endtab %} {% endtabs %} ### CARD Used to collected card payments by specifying the**`CARD`** value in the **payment\_method** field {% hint style="danger" %} The card method supports only collections at the moment {% endhint %} {% tabs %} {% tab title="Sample Request Body" %} ```javascript { ... "payment_method": "CARD" ... } ``` {% endtab %} {% endtabs %} Refunds are supported for cards. Go [here](/refunds/refund-post-request) to learn about them In case you do provide the customer's card details to process the card transactions, we will return a **`payment_url`** where the customer will complete their transaction. When the customer is redirected to the **`payment_url`**, they will securely provide their card details and their transaction will be processed. We do not store the customers' card details but the masked version. The masked version is useful during queries. ### CRYPTO Set the **payment\_method** parameter in the request body as **`CRYPTO`** to collect funds using crypto \ \ Funds collected will be stored in the base currency of the **provider** used to make the payment. e.g setting the **provider=btc\_usd** means we will collect the payment as **BTC** store it as **USD**. Your USD wallet will be credited at the end of the transaction and we will settle you in USD. {% tabs %} {% tab title="Sample Request Body" %} ```javascript { ... "method": "CRYPTO" ... } ``` {% endtab %} {% endtabs %} Completing this transaction redirecting the customer to the **`payment_url`** to complete the payment. # Transaction status codes | Status | Reason | | --------- | ---------------------------------------------------- | | PENDING | A payment that is waiting to be processed | | FAILED | A payment that has failed | | COMPLETED | A payment that was processed successfully | | CANCELLED | A payment that was canceled by the merchant customer | # Webhook 1. All `collection` and `disbursement` transactions notification updates will be sent as **`POST`** to the URL set as the `webhook url` under your merchant account API tokens.
2. Only, `https` URLs can be set or notified.
3. You will need to acknowledge receipt of the notification by responding with the HTTP status code **`200`**. Otherwise, we might keep calling your webhook URL at an interval of 10 minutes for 2 days.
4. To ensure that the notification data sent to your `webhook URL` comes from our servers, set a `webhook hash` under the `Api Tokens`.
5. We will include a header called, `webhook-hash` in the request sent to the `webhook URL`. e.g **webhook-hash: WH-\*\*\*"** {% hint style="info" %} You should verify the `webhook-hash` we sent matches what was set under your merchant account before giving service to your customer {% endhint %} #### **Responding to webhooks** We will stop sending notification to your webhook URL if it responds with the following “HTTP status codes” below; | Code | Description | | ----- | ----------------------- | | `200` | - OK | | `400` | - Bad Request | | `401` | - Unauthorised | | `403` | - Forbidden | | `422` | - Unprocessable entity. | **Rejecting webhook notification** In a scenario where the transaction cannot be processed respond with HTTP codes below; | Code | Description | | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `400` |

- Bad Request.
- e.g when there’s a missing parameter

| | `422` |

- Unprocessable entity.
- e.g when the request is fine but you cannot complete it because the amount does not match what you expected.

| {% hint style="danger" %} **KEYNOTE** Always verify the, **`amount`** to make sure it matches what is meant to be **`paid`** before giving service to the customer. {% endhint %} ```javascript { "id": "383737927636356536773773", "request_amount": 0.4, "request_currency": "USD", "account_amount": 1462.53, "account_currency": "UGX", "transaction_fee": 42.23, "total_credit": 1420.30, "customer_charged": false, "provider": "mtn_ug", "merchant_reference": "88736jh-kkas87-mmn736-9n873ms-6636h", "kitegateway_reference": "PL-KMSSD-30000", "transaction_status": "COMPLETED", "transaction_type": "collection", "message": "Transaction Completed Successfully", "account_number": "Optional - 256777111222", "account_name": "Optional", "institution_name": "Optional - MTN Mobile Money Uganda" } ``` # Webhook Trigger For some reason you might end up not receiving notification from us as such you can trigger the webhook to re-send the latest payment update **Live** ```javascript GET https://kitegateway.com/v1/transactions/send-callback/{kitegateway_reference} ``` **Sandbox** ``` GET https://sandbox.kitegateway.com/v1/transactions/send-callback/{kitegateway_reference} ``` {% hint style="warning" %} This is a secure end point that must be called using the auth token {% endhint %} | Parameter | Type | Description | Required | | ---------------------- | ------ | ----------------------------------------------------------------------------- | -------- | | kitegateway\_reference | string | Unique transaction reference that was sent when the transaction was initiated | YES | # Signature Verification In addition to the header,`Webhook-Hash,`when we are sending notification back to the `webhook URL` we provide`Kitegateway-Signature` so that merchants trust that the callbacks originate from the Kitegateway servers. ### **Signature verification can be done with the following procedure;** 1. Retrieve the value of the `Kitegateway-Signature` header.
2. Form the string payload to be used in signature verification. This is obtained by concatenating values of the notification data in the format that follows\ \ `id:merchant_reference:kitegateway_reference:transaction_status:webhook_url`\ \ where **`webhook_url`** is the full URL as added to your merchant account API token settings. Assume sample notification data below; ```javascript { ... "id": "383737927636356536773773", "merchant_reference": "88736jh-kkas87-mmn736-9n873ms-6636h", "kitegateway_reference": "PL-KMSSD-30000", "transaction_status": "COMPLETED", ... } ``` and that the callback URL is\ `https://some-callback-url`\ \ The string payload would therefore be `383737927636356536773773:88736jh-kkas87-mmn736-9n873ms-6636h:PL-KMSSD-30000:COMPLETED:https://some-callback-url`
1. Obtain the Kitegateway public key as explained [here](/dashboard/api-credentials#aip_key) and store it as a file.
2. Use the Kitegateway public key to verify the signature as described in the example source codes below; #### Signature Verification Code Example {% tabs %} {% tab title="NodeJS" %} ```javascript const crypto = require('crypto'); const fs = require('fs'); function isSignatureValid() { const strPayload = "383737927636356536773773:88736jh-kkas87-mmn736-9n873ms-6636h:PL-KMSSD-30000:COMPLETED:https://some-callback-url"; const signature = "value-of-kitegateway-signature"; const publicKeyFile = "path-to-file/kitegateway.public.key.pem"; const publicKey = fs.readFileSync(publicKeyFile).toString().replace(/\\n/g, '\n'); const verify = crypto.createVerify("SHA512"); verify.write(strPayload); verify.end(); /*true or false*/ return verify.verify(publicKey, signature, 'base64'); } ``` {% endtab %} {% tab title="PHP" %} ```php ``` {% endtab %} {% endtabs %} # Wordpress Woocomerce Plugin This plugin allows business to be able to collect money through woocommerce {% hint style="danger" %} When generating API KEYS to use in this plugin. It is important to set the webook URL to so that when payment status changes at kitegateway servers your application is able to get the updates. {% endhint %} #### Download You can download this plugin from the wordpress store. You can check out the source code here: you can download the woocommerce version here install to your website directly Once you have installed the plugin you should be able to set it in the woocommerce settings
You should fill in appropriate details but the most important are the api tokens
The following page will appear in the checkout