# Transactions

## Create Transaction

<mark style="color:green;">`POST`</mark> `https://api.lahza.io/transaction/initialize`

Initialize a transaction from your backend

#### Headers

| Name                                            | Type   | Description                     |
| ----------------------------------------------- | ------ | ------------------------------- |
| authorization<mark style="color:red;">\*</mark> | String | Set value to Bearer SECRET\_KEY |
| content-type<mark style="color:red;">\*</mark>  | String | Set value to application/json   |

#### Request Body

| Name                                       | Type    | Description                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| amount<mark style="color:red;">\*</mark>   | String  | Amount should be in aghora if currency is ILS, qirsh, if currency is JOD, and cents, if currency is USD                                                                                                                                                                                                        |
| email<mark style="color:red;">\*</mark>    | String  | Customer's email address                                                                                                                                                                                                                                                                                       |
| currency<mark style="color:red;">\*</mark> | 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 ](https://docs.lahza.io/payments/metadata)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                                                                                                                                                                                                                                                                                      |

{% tabs %}
{% tab title="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)." %}

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

{% endtab %}
{% endtabs %}

## Verify Transaction

<mark style="color:blue;">`GET`</mark> `https://api.lahza.io/transaction/verify/:reference`

Confirm the status of a transaction<br>

#### Path Parameters

| Name                                        | Type   | Description                                               |
| ------------------------------------------- | ------ | --------------------------------------------------------- |
| reference<mark style="color:red;">\*</mark> | String | The transaction reference used to intiate the transaction |

#### Headers

| Name                                            | Type   | Description                     |
| ----------------------------------------------- | ------ | ------------------------------- |
| authorization<mark style="color:red;">\*</mark> | String | Set value to Bearer SECRET\_KEY |

{% tabs %}
{% tab title="200: OK " %}

```
  "status": true,
  "message": "Verification successful",
  "data": {
    "amount": 27000,
    "currency": "ILS",
    "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": "bojack@horseman.com"
    },
    "plan": "PLN_0as2m9n02cl0kp6",
    "requested_amount": 1500000
  }
}
```

{% endtab %}
{% endtabs %}

## List Transactions

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | String | Set value to Bearer SECRET\_KEY |

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "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": "ahmed.khalil@example.com",
        "phone": "+970592345678",
        "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": "+970598765432"
          }
        ]
      },
      "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": "jameela.ahmed@example.com",
        "phone": "+970592345679",
        "customer_code": "CUS_1djk392ndsjn1",
        "metadata": null,
        "risk_action": "default"
      },
      "requested_amount": 5000
    }
  ],
  "meta": {
    "total": 1,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}
```

{% endtab %}
{% endtabs %}

## Fetch Transaction

<mark style="color:blue;">`GET`</mark> `https://api.lahza.io/transaction/:id`

Get details of a transaction carried out on your integration.

#### Path Parameters

| Name                                 | Type | Description                        |
| ------------------------------------ | ---- | ---------------------------------- |
| id<mark style="color:red;">\*</mark> |      | An ID for the transaction to fetch |

#### Headers

| Name                                            | Type   | Description                      |
| ----------------------------------------------- | ------ | -------------------------------- |
| authorization<mark style="color:red;">\*</mark> | String | Set value to `Bearer SECRET_KEY` |

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "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": "+97000000000"
        }
      ],
      "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": "customer@example.com",
      "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
  }
}
```

{% endtab %}
{% endtabs %}

## Charge Authorization

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | String | Set value to Bearer SECRET\_KEY |
| content-type<mark style="color:red;">\*</mark>  | String | Set value to `application/json` |

#### Request Body

| Name                                                  | Type    | Description                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| amount<mark style="color:red;">\*</mark>              | string  | Amount should be in aghora if currency is ILS, qirsh, if currency is JOD, and cents, if currency is USD                                                                                                                                                                                                                             |
| email<mark style="color:red;">\*</mark>               | string  | Customer's email address                                                                                                                                                                                                                                                                                                            |
| authorization\_code<mark style="color:red;">\*</mark> | 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<mark style="color:red;">\*</mark>            | 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. |

{% tabs %}
{% tab title="200: OK " %}

```json
  "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": "mail@mail.com",
      "customer_code": "CUS_jdjw92ni2",
      "phone": null,
      "metadata": null,
      "risk_action": "default"
    },
    "plan": null,
    "id": 696105928
  }
}
```

{% endtab %}
{% endtabs %}

## Capture Transaction

<mark style="color:green;">`POST`</mark> `https://api.lahza.io/transaction/capture/:reference`

Capture a transaction (For manual capture mode only)

#### Path Parameters

| Name                                        | Type   | Description                      |
| ------------------------------------------- | ------ | -------------------------------- |
| reference<mark style="color:red;">\*</mark> | String | The reference of the transaction |

#### Headers

| Name                                            | Type   | Description                     |
| ----------------------------------------------- | ------ | ------------------------------- |
| authorization<mark style="color:red;">\*</mark> | String | Set value to Bearer SECRET\_KEY |

{% tabs %}
{% tab title="200: OK " %}

```json
  "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": "mail@mail.com",
      "customer_code": "CUS_jdjw92ni2",
      "phone": null,
      "metadata": null,
      "risk_action": "default"
    },
    "plan": null,
    "id": 696105928
  }
}
```

{% endtab %}
{% endtabs %}

## View Transaction Timeline

<mark style="color:blue;">`GET`</mark> `https://api.lahza.io/transaction/timeline/:id_or_reference`

View the timeline of a transaction

#### Path Parameters

| Name                                                | Type   | Description                                |
| --------------------------------------------------- | ------ | ------------------------------------------ |
| id\_or\_reference<mark style="color:red;">\*</mark> | String | The ID or the reference of the transaction |

#### Headers

| Name                                            | Type   | Description                     |
| ----------------------------------------------- | ------ | ------------------------------- |
| authorization<mark style="color:red;">\*</mark> | String | Set value to Bearer SECRET\_KEY |

{% tabs %}
{% tab title="200: OK " %}

```json
  "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
      }
    ]
  }
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-docs.lahza.io/api-endpoints/transactions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.