Transactions

The Transactions API allows you create and manage payments on your integration.

Create Transaction

POST https://api.lahza.io/transaction/initialize

Initialize a transaction from your backend

Headers

Name	Type	Description
authorization*	String	Set value to Bearer SECRET_KEY
content-type*	String	Set value to application/json

Request Body

Name	Type	Description
amount*	String	Amount should be in aghora if currency is ILS, qirsh, if currency is JOD, and cents, if currency is USD
email*	String	Customer's email address
currency*	String	The transaction currency (ILS, JOD or USD). Defaults to your dashboard currency.
reference	String	Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
callback_url	String	Fully qualified url, e.g. https://example.com/ . Use this to override the callback url provided on the dashboard for this transaction
metadata	String	Stringified JSON object of custom data. Kindly check the Metadata page for more information.
mobile	String	Customer's mobile
plan	String	If transaction is to create a subscription to a predefined plan, provide plan code here. This would invalidate the value provided in amount
invoice_limit	integer	Number of times to charge customer during subscription to plan
channels	array	An array of payment channels to control what channels you want to make available to the user to make a payment with. Available channels include:
split_code	String	he split code of the transaction split. e.g. SPL_98WF13Eb3w
subaccount	String	The code for the subaccount that owns the payment. e.g. ACCT_8f4s1eq7ml6rlzj
transaction_charge	integer	A flat fee to charge the subaccount for this transaction (). This overrides the split percentage set when the subaccount was created. Ideally, you will need to use this if you are splitting in flat rates (since subaccount creation only allows for percentage split). e.g. 7000 for a 70 naira flat fee.
bearer	String	Who bears Lahza charges? account or subaccount (defaults to account).
first_name	String	First name of the customer
last_name	String	Last name of the customer

200: OK 200-201 Request was successful and intended action was carried out. Note that we will always send a 200 if a charge or verify request was made. Do check the data object to know how the charge went (i.e. successful or failed).

{
  "status": true,
  "message": "Authorization URL created",
  "data": {
    "authorization_url": "https://checkout.lahza.io/aksadasdadd",
    "access_code": "cwkmdksduwo2",
    "reference": "TKSksdmsdk2sss323"
  }
}

Verify Transaction

GET https://api.lahza.io/transaction/verify/:reference

Confirm the status of a transaction

Path Parameters

Name	Type	Description
reference*	String	The transaction reference used to intiate the transaction

Headers

Name	Type	Description
authorization*	String	Set value to Bearer SECRET_KEY

200: OK

  "status": true,
  "message": "Verification successful",
  "data": {
    "amount": 27000,
    "currency": "NGN",
    "transaction_date": "2016-10-01T11:03:09.000Z",
    "status": "success",
    "reference": "DG4uishudoq90LD",
    "domain": "test",
    "metadata": 0,
    "gateway_response": "Successful",
    "message": null,
    "channel": "card",
    "ip_address": "41.1.25.1",
    "log": {
      "time_spent": 9,
      "attempts": 1,
      "authentication": null,
      "errors": 0,
      "success": true,
      "mobile": false,
      "input": [],
      "channel": null,
      "history": [{
        "type": "input",
        "message": "Filled these fields: card number, card expiry, card cvv",
        "time": 7
        },
        {
          "type": "action",
          "message": "Attempted to pay",
          "time": 7
        },
        {
          "type": "success",
          "message": "Successfully paid",
          "time": 8
        },
        {
          "type": "close",
          "message": "Page closed",
          "time": 9
        }
      ]
    }
    "fees": null,
    "authorization": {
      "authorization_code": "AUTH_8dfhjjdt",
      "card_type": "visa",
      "last4": "1381",
      "exp_month": "08",
      "exp_year": "2018",
      "bin": "412345",
      "bank": "TEST BANK",
      "channel": "card",
      "signature": "SIG_idyuhgd87dUYSHO92D",
      "reusable": true,
      "country_code": "NG",
      "account_name": "BoJack Horseman"
    },
    "customer": {
      "id": 84312,
      "customer_code": "CUS_hdhye17yj8qd2tx",
      "first_name": "BoJack",
      "last_name": "Horseman",
      "email": "[e-mail]"
    },
    "plan": "PLN_0as2m9n02cl0kp6",
    "requested_amount": 1500000
  }
}

List Transactions

GET https://api.lahza.io/transaction

List transactions carried out on your integration.

Query Parameters

Name	Type	Description
perPage	integer	Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page	integer	Specify exactly what page you want to retrieve. If not specify we use a default value of 1.
amount	intger	Filter transactions by amount. Specify the amount (in agora if currency is ILS, qirsh, if currency is JOD, and cents, if currency is USD)
to	datetime	A timestamp at which to stop listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
from	datetime	A timestamp from which to start listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
status	String	Filter transactions by status
customer	integer	Specify an ID for the customer whose transactions you want to retrieve

Headers

Name	Type	Description
authorization*	String	Set value to Bearer SECRET_KEY

200: OK

{
  "status": true,
  "message": "Transactions retrieved",
  "data": [
    {
      "id": 5833,
      "domain": "test",
      "status": "failed",
      "reference": "dh4i7lj1ck",
      "amount": 250,
      "message": null,
      "gateway_response": "Declined",
      "paid_at": null,
      "created_at": "2023-07-15T14:30:52.000Z",
      "channel": "card",
      "currency": "ILS",
      "ip_address": null,
      "metadata": null,
      "timeline": null,
      "customer": {
        "first_name": "أحمد",
        "last_name": "خليل",
        "email": "[e-mail]",
        "phone": "[phone]",
        "metadata": null,
        "customer_code": "CUS_1djk392ndsjn1"
      },
      "authorization": {},
      "requested_amount": 250
    },
    {
      "id": 298126,
      "domain": "live",
      "status": "failed",
      "reference": "r1o9gz3isv4",
      "amount": 5000,
      "message": null,
      "gateway_response": "Declined",
      "paid_at": null,
      "created_at": "2023-11-18T09:15:07.000Z",
      "channel": "card",
      "currency": "ILS",
      "ip_address": null,
      "metadata": {
        "custom_fields": [
          {
            "display_name": "Mobile Number",
            "variable_name": "mobile_number",
            "value": "[phone]"
          }
        ]
      },
      "log": null,
      "fees": null,
      "paidAt": "2023-11-18T09:15:12.000Z",
      "createdAt": "2023-11-18T09:15:07.000Z",
      "authorization": {
        "authorization_code": "AUTH_3o8d4fn3",
        "bin": "456789",
        "last4": "4321",
        "exp_month": "03",
        "exp_year": "2025",
        "card_type": "visa DEBIT",
        "bank": "Bank of  Palestine",
        "country_code": "PS",
        "brand": "visa",
        "account_name": "جميلة أحمد"
      },
      "customer": {
        "id": 8279,
        "first_name": "جميلة",
        "last_name": "أحمد",
        "email": "[e-mail]",
        "phone": "[phone]",
        "customer_code": "CUS_1djk392ndsjn1",
        "metadata": null,
        "risk_action": "default"
      },
      "requested_amount": 5000
    }
  ],
  "meta": {
    "total": 1,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}

Fetch Transaction

GET https://api.lahza.io/transaction/:id

Get details of a transaction carried out on your integration.

Path Parameters

Name	Type	Description
id*		An ID for the transaction to fetch

Headers

Name	Type	Description
authorization*	String	Set value to Bearer SECRET_KEY

200: OK

{
  "status": true,
  "message": "Transaction retrieved",
  "data": {
    "id": 932932930,
    "domain": "test",
    "status": "success",
    "reference": "92399230",
    "amount": 10000,
    "message": null,
    "gateway_response": "Successful",
    "paid_at": "2023-10-09T13:03:28.000Z",
    "created_at": "2023-10-09T13:00:16.000Z",
    "channel": "card",
    "currency": "ILS",
    "ip_address": "10.10.01.10",
    "metadata": {
      "custom_fields": [
        {
          "display_name": "Mobile Number",
          "variable_name": "mobile_number",
          "value": "[phone]"
        }
      ],
      "referrer": "http://example.com/pay.html?"
    },
    "log": {
      "start_time": 1570626018,
      "time_spent": 192,
      "attempts": 1,
      "errors": 0,
      "success": true,
      "mobile": false,
      "input": [],
      "history": [
        {
          "type": "action",
          "message": "Attempted to pay with card",
          "time": 191
        },
        {
          "type": "success",
          "message": "Successfully paid with card",
          "time": 192
        }
      ]
    },
    "fees": 150,
    "fees_split": null,
    "authorization": {
      "authorization_code": "AUTH_k2k3429sj52",
      "bin": "408228",
      "last4": "3011",
      "exp_month": "12",
      "exp_year": "2030",
      "channel": "card",
      "card_type": "visa DEBIT",
      "bank": "Test Bank",
      "country_code": "PS",
      "brand": "visa",
      "reusable": true,
      "signature": "SIG_mskJH82jUjsj32Ko",
    },
    "customer": {
      "id": 999329234,
      "first_name": null,
      "last_name": null,
      "email": "[e-mail]",
      "customer_code": "CUS_ssd22323LOSNSK",
      "phone": null,
      "metadata": null,
      "risk_action": "deny"
    },
    "order_id": null,
    "paidAt": "2023-10-09T13:03:28.000Z",
    "createdAt": "2023-10-09T13:00:16.000Z",
    "requested_amount": 1500000
  }
}

Charge Authorization

POST https://api.lahza.io/transaction/charge_authorization

All authorizations marked as reusable can be charged with this endpoint whenever you need to receive payments.

Headers

Name	Type	Description
authorization*	String	Set value to Bearer SECRET_KEY
content-type*	String	Set value to application/json

Request Body

Name	Type	Description
amount*	string	Amount should be in aghora if currency is ILS, qirsh, if currency is JOD, and cents, if currency is USD
email*	string	Customer's email address
authorization_code*	String	Valid authorization code to charge
metadata	String	To add custom fields to your transaction when it is displayed on the dashboard, include a custom_fields attribute in your JSON object. This attribute should be a stringified JSON array containing objects representing each custom field.
currency*	String	The transaction currency (ILS, JOD or USD). Defaults to your dashboard currency.
reference	String	Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
queue	boolean	When making a scheduled charge call, it is advisable to queue the requests to prevent overloading the processing system, which could result in transaction processing errors. By including the parameter "queue:true" in your request, you can leverage our queued charging feature and ensure smoother processing of transactions.

200: OK

  "status": true,
  "message": "Charge attempted",
  "data": {
    "amount": 10000,
    "currency": "ILS",
    "transaction_date": "2024-04-23T10:42:05.000Z",
    "status": "success",
    "reference": "jciewopcmvbeu2",
    "domain": "test",
    "metadata": "",
    "gateway_response": "Approved",
    "message": null,
    "channel": "card",
    "ip_address": null,
    "log": null,
    "fees": 14500,
    "authorization": {
      "authorization_code": "AUTH_ksie923sxc",
      "bin": "408300",
      "last4": "2011",
      "exp_month": "12",
      "exp_year": "2028",
      "channel": "card",
      "card_type": "visa DEBIT",
      "bank": "Test Bank",
      "country_code": "PS",
      "brand": "visa",
      "reusable": true,
      "signature": "SIG_kskd82jhcncwo38f4",
      "account_name": null
    },
    "customer": {
      "id": 23215815,
      "first_name": null,
      "last_name": null,
      "email": "[e-mail]",
      "customer_code": "CUS_jdjw92ni2",
      "phone": null,
      "metadata": null,
      "risk_action": "default"
    },
    "plan": null,
    "id": 696105928
  }
}

Capture Transaction

POST https://api.lahza.io/transaction/capture/:reference

Capture a transaction (For manual capture mode only)

Path Parameters

Name	Type	Description
reference*	String	The reference of the transaction

Headers

Name	Type	Description
authorization*	String	Set value to Bearer SECRET_KEY

200: OK

  "status": true,
  "message": "Transaction Captured successfully",
  "data": {
    "amount": 10000,
    "currency": "ILS",
    "transaction_date": "2024-04-23T10:42:05.000Z",
    "status": "success",
    "reference": "jciewopcmvbeu2",
    "domain": "test",
    "metadata": "",
    "gateway_response": "Approved",
    "message": null,
    "channel": "card",
    "ip_address": null,
    "log": null,
    "fees": 14500,
    "authorization": {
      "authorization_code": "AUTH_ksie923sxc",
      "bin": "408300",
      "last4": "2011",
      "exp_month": "12",
      "exp_year": "2028",
      "channel": "card",
      "card_type": "visa DEBIT",
      "bank": "Test Bank",
      "country_code": "PS",
      "brand": "visa",
      "reusable": true,
      "signature": "SIG_kskd82jhcncwo38f4",
      "account_name": null
    },
    "customer": {
      "id": 23215815,
      "first_name": null,
      "last_name": null,
      "email": "[e-mail]",
      "customer_code": "CUS_jdjw92ni2",
      "phone": null,
      "metadata": null,
      "risk_action": "default"
    },
    "plan": null,
    "id": 696105928
  }
}

View Transaction Timeline

GET https://api.lahza.io/transaction/timeline/:id_or_reference

View the timeline of a transaction

Path Parameters

Name	Type	Description
id_or_reference*	String	The ID or the reference of the transaction

Headers

Name	Type	Description
authorization*	String	Set value to Bearer SECRET_KEY

200: OK

  "status": true,
  "message": "Timeline retrieved",
  "data": {
    "time_spent": 9061,
    "attempts": 1,
    "authentication": null,
    "errors": 1,
    "success": false,
    "mobile": false,
    "input": [],
    "channel": "card",
    "history": [
      {
        "type": "open",
        "message": "Opened payment page",
        "time": 1
      },
      {
        "type": "input",
        "message": "Filled these fields: card number, card expiry, card cvc",
        "time": 39
      },
      {
        "type": "action",
        "message": "Attempted to pay",
        "time": 39
      },
      {
        "type": "error",
        "message": "Error: Declined",
        "time": 48
      },
      {
        "type": "input",
        "message": "Filled these fields: card expiry, card cvc",
        "time": 9061
      },
      {
        "type": "close",
        "message": "Page closed",
        "time": 9061
      }
    ]
  }
}