Lipisha REST APIs

Authorize Card

API Description

This API call for authorizes a credit card transaction locking in the specified amount in the card holder's bank account.

The transaction then needs to be completed using the Complete Card Transaction API call to effect settlement of funds into the merchant's account or reversed using the Reverse Card Transaction API call.

This function reserves funds on the cardholder's account and if successful then you must call the complete_card_transaction function with the transaction_index and transaction_reference returned by this function to actually move the money to your account.

Kindly note that in some cases, debit card transactions may be settled before the Complete Card Transaction API call is completed and may NOT be reversible depending on the issuing bank.

API Endpoint

The API service endpoint for making the Authorize Card Transaction API call is:

API Request

The API request is made via HTTP POST and must be url encoded. Some of the parameters are required while others are optional. The parameters are:

Parameter Description Example
api_key Unique string specifying merchant's Lipisha API key.

This should match the api key that you have generated for your Lipisha account
api_signature Unique string specifying merchant's Lipisha API signature.

This should match the api signature that you have generated for your Lipisha account
api_version String specifying the version of the API in use 1.3.0
api_type String specifying the type of handshake or IPN call Callback
account_number The lipisha account number to which the transaction will be charged 00500
card_number The credit card number 4242424242424242
address1 Address line 1 of the Cardholder. 1000
address2 Address line 2 of the Cardholder. 0712345678
expiry Expiry of the card in this format MMYYYY 022012
name Name of the Cardholder. John Doe
email Email of the Cardholder.
mobile_number Mobile Number of the Cardholder. 254700123456
country Country of the Cardholder. KENYA
state The state or province of the Cardholder. NAIROBI
zip Amount to send to the recipient. 1000
security_code The card security code usually on the back of the credit/debit card. 003
amount Amount to be authorized from the cardholder's account 1000
currency Currency for the amount charged KES

API Response

The API reponse will be returned as JSON. Each response will contain a status and content section. The parameters are:

Parameter Description Example
status String specifying whether API Call executed successfully or failed SUCCESS
status_code Integers specifying status code of the API Call result 0000
status_description String containing description of the status Transaction authorized successfully
transaction_reference A transaction reference for the successful authorization 1234
transaction_index A transaction index for the successful authorization {123456789}
reason A reason if available why transaction failed Invalid Card Number

JSON Reponse
  "status": {
    "status_code": "0000",
    "status_description": "Transaction Authorized Successfully",
    "status": "SUCCESS"
  "content": {
    "transaction_index": "{123456789}",
    "transaction_reference": "1234",

Fork me on GitHub