# Introduction

### API Basics <a href="#introduction-api-basics" id="introduction-api-basics"></a>

The Lahza API provides comprehensive access to the various features available on our dashboard, allowing you to leverage and expand their functionality within your own application. Our API follows RESTful principles and is structured around the primary resources that you'll interact with, with a few exceptions worth mentioning.

{% hint style="info" %}
[Sign up](https://dashboard.lahza.io/register) for a free Lahza account to access and test the API. Test keys will be provided for making API calls.\
Requests and Response
{% endhint %}

### Requests and Response <a href="#introduction-requests-response" id="introduction-requests-response"></a>

```json
{
  "status": [boolean],  // Only true if the details provided could be processed and no error occured while processing
  "message": [string], // Explains why status is false... Entirely informational. Please only log this but do not use for your checks
  "data": [object]    // contains actionable result of processing if present
}
```

We recommend using HTTP status codes to determine the outcome of an API call. However, we also provide additional keys to give you more information about the response.

The "status" key indicates whether the request was successful or not. If it is set to true, the request was successful. If it is set to false, there was an error.

The "message" key provides a summary of the response and its status. For example, when retrieving a list of customers, the message might say "Customers retrieved". In case of an error, the message will contain a description of the error, such as the authorization header situation mentioned earlier. This key is consistent across all requests.

The "data" key contains the actual result of the request. It can be an object or an array, depending on the type of request made. For example, retrieving a single customer will return a customer object in the data key, while retrieving a list of customers will return an array of customer objects.

The "meta" key is used to provide additional contextual information about the contents of the data key. For instance, when retrieving a list of transactions for a customer, pagination parameters can be included in the meta key to limit the result set. The meta key will contain an object with relevant attributes to provide this context.

```json
"meta": {
  "total": 2,
  "skipped": 0,
  "perPage": 50,
  "page": 1,
  "pageCount": 1
}
```

### Keys

| <p>Total<br>Number</p>     | This is the total number of transactions that were performed by the customer.                                                                                                                                                    |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p>Skipped<br>Number</p>   | This is the number of records skipped before the first record in the array returned.                                                                                                                                             |
| <p>PerPage<br>Number</p>   | This is the maximum number of records that will be returned per request. This can be modified by passing a new value as a `perPage` query parameter. **Default: 50**                                                             |
| <p>Page<br>Number</p>      | This is the current `page` being returned. This is dependent on what page was requested using the `page` query parameter. **Default: 1**                                                                                         |
| <p>PageCount<br>Number</p> | This is how many pages in total are available for retrieval considering the maximum records per page specified. For context, if there are 51 records and perPage is left at its default value, pageCount will have a value of 2. |


# Authentication

To ensure proper authentication of your API calls, make sure to include your secret key in the Authorization header of each request you send. You can manage your API keys directly from the [dashboard](https://dashboard.lahza.io).

In our integration, we provide both public and secret keys. Public keys are intended for use on the front-end when integrating with Lahza Inline and in our Mobile SDKs exclusively. Public keys have limitations and cannot modify any aspect of your account, except for initiating transactions towards your account. On the other hand, secret keys are intended to be kept confidential. If you suspect that your secret key has been compromised or if you wish to reset it for any reason, you can easily do so from the dashboard.<br>

{% hint style="danger" %}
**Secure your secret key**

Do not commit your secret keys to git, or use them in client-side code.
{% endhint %}

Authorization headers should be in the following format:

&#x20;`Authorization: Bearer SECRET_KEY`

{% hint style="info" %}
**Sample Authorization Header**\
Authorization: Bearer sk\_test\_UkqerSTELjYhf6GNe6lB
{% endhint %}

API requests made without authentication will fail with the status code&#x20;

`401: Unauthorized`. All API requests must be made over HTTPS.<br>

{% hint style="danger" %}
**Secure your requests**\
Do not set `VERIFY_PEER` to `FALSE`. Ensure your server verifies the SSL connection to Lahza.
{% endhint %}

<br>


# Errors

Lahza's API follows a RESTful architecture and utilizes conventional HTTP response codes to communicate the outcome of requests, indicating success or failure.

\
Outlined below are some frequently encountered errors along with their possible causes:

#### The authorization code provided either does not exist or has been deactivated.

1. All authorizations remain inactive until a transaction successfully occurs on the card. If you attempt to charge an inactive authorization, you will receive this message.
2. It is important to note that you can only charge an authorization for the customer who originally saved it. If an authorization is paired with the incorrect email, you may encounter this error message.

#### This authorization is not reusable

To utilize our charge authorization endpoint, only authorizations marked as reusable can be used. Prior to attempting a charge, please ensure that the authorization object has confirmed reusability. This step will help you avoid encountering this message.

#### &#x20;Duplicate Transaction Reference

Each transaction within your integration on a specific domain must possess a unique reference. If you try to initiate a new transaction using a reference that has already been utilized, you will receive this message.

#### HTTP Codes

| 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). |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400                     | A validation or client side error occurred and the request was not fulfilled.                                                                                                                                             |
| 401                     | The request was not authorized. This can be triggered by passing an invalid secret key in the authorization header or the lack of one                                                                                     |
| 404                     | Request could not be fulfilled as the request resource does not exist.                                                                                                                                                    |
| 500, 501, 502, 503, 504 | Request could not be fulfilled due to an error on Lahza's end. This shouldn't happen so please report as soon as you encounter any instance of this.                                                                      |

<br>


# Transactions

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

## 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 %}


# Payment Pages

## Create Page

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

Create a payment page on your integration

#### Headers

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

#### Request Body

| Name                                   | Type   | Description                                                                                                          |
| -------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
| name<mark style="color:red;">\*</mark> | String | <p>Name of page<br></p>                                                                                              |
| redirect\_url                          | String | If you would like Lahza to redirect someplace upon successful payment, specify the URL here.                         |
| metadata                               | object | Extra data to configure the payment page including, logo image                                                       |
| slug                                   | String | URL slug you would like to be associated with this page. Page will be accessible at <https://pay.lahza.iom/\\[slug>] |
| amount                                 | String | Amount should be in agora if currency is ILS, qirsh, if currency is JOD, and cents, if currency is USD               |
| description                            | String | A description for this page                                                                                          |
| custom\_fields                         | array  | If you would like to accept custom fields, specify them here.                                                        |

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

```json
{
  "status": true,
  "message": "Page created",
  "data": {
    "name": "Testing page",
    "description": "This is the description",
    "domain": "live",
    "slug": "jwirRT64W",
    "currency": "ILS",
    "active": true,
    "id": 18,
    "createdAt": "2023-02-30T01:49:57.514Z",
    "updatedAt": "2023-02-30T01:49:57.514Z"
  }
}
```

{% endtab %}
{% endtabs %}

## List Pages

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

List payment pages available on your integration.

#### Query Parameters

| Name    | Type     | Description                                                                                                     |
| ------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| perPage | integer  | <p>Specify how many records you want to retrieve per page. If not specify we use a default value of 50.<br></p> |
| page    | integer  | <p><br>Specify exactly what page you want to retrieve. If not specify we use a default value of 1.</p>          |
| to      | datetime | A timestamp at which to stop listing page e.g. 2023-09-24T00:00:05.000Z, 2023-09-21                             |
| from    | datetime | A timestamp from which to start listing page e.g. 2023-09-24T00:00:05.000Z, 2023-09-21                          |

#### 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": "Pages retrieved",
  "data": [
    {
      "domain": "test",
      "name": "Donation Page",
      "description": null,
      "amount": null,
      "currency": "NGN",
      "slug": "kdjrWH46J",
      "custom_fields": null,
      "redirect_url": null,
      "active": true,
      "id": 2223,
      "createdAt": "2016-10-01T10:59:11.000Z",
      "updatedAt": "2016-10-01T10:59:11.000Z"
    },
    {
      "domain": "test",
      "name": "Name of the page",
      "description": "description",
      "amount": 10000,
      "currency": "ILS",
      "slug": "special-slug",
      "custom_fields": [
        {
          "display_name": "Speciality",
          "variable_name": "speciality"
        },
        {
          "display_name": "Age",
          "variable_name": "age"
        }
      ],
      "redirect_url": "http://example.com",
      "active": true,
      "id": 1807,
      "createdAt": "2023-11-09T19:18:37.000Z",
      "updatedAt": "2023-11-14T17:51:49.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "skipped": 0,
    "perPage": "3",
    "page": 1,
    "pageCount": 1
  }
}
```

{% endtab %}
{% endtabs %}

## Fetch Page

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

Get details of a payment page on your integration.

#### Path Parameters

| Name                                           | Type   | Description                                      |
| ---------------------------------------------- | ------ | ------------------------------------------------ |
| id\_or\_slug<mark style="color:red;">\*</mark> | String | <p>The page ID or slug you want to fetch<br></p> |

#### 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": "Page retrieved",
  "data": {
    "domain": "test",
    "name": "Test page",
    "description": "description of the page.",
    "amount": 10000,
    "currency": "ILS",
    "slug": "ji84Ju234J",
    "active": true,
    "id": 112,
    "createdAt": "2023-10-30T00:49:57.000Z",
    "updatedAt": "2023-10-30T00:49:57.000Z"
  }
}
```

{% endtab %}
{% endtabs %}

## Update Page

<mark style="color:orange;">`PUT`</mark> `https://api.lahza.io/page/:id_or_slug`

Update a payment page details on your integration

#### Headers

| Name                                            | Type   | Description                                |
| ----------------------------------------------- | ------ | ------------------------------------------ |
| authorization<mark style="color:red;">\*</mark> | String | <p>Set value to Bearer SECRET\_KEY<br></p> |
| id\_or\_slug                                    | String | Page ID or slug                            |
| content-type<mark style="color:red;">\*</mark>  | String | Set value to application/json              |

#### Request Body

| Name                                   | Type    | Description                                                                                             |
| -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| name<mark style="color:red;">\*</mark> | String  | Name of page                                                                                            |
| amount                                 | integer | Amount should be in aghora if currency is ILS, qirsh, if currency is JOD, and cents, if currency is USD |
| description                            | String  | A description for this page                                                                             |
| active                                 | boolean | Set to false to deactivate page url                                                                     |

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

```json
{
  "status": true,
  "message": "Page updated",
  "data": {
    "domain": "test",
    "name": "Buttercup Brunch",
    "description": "Gather your friends for the ritual that is brunch",
    "amount": null,
    "currency": "NGN",
    "slug": "5nApBwZkvY",
    "active": true,
    "id": 18,
    "integration": 100032,
    "createdAt": "2016-03-30T00:49:57.000Z",
    "updatedAt": "2016-03-30T04:44:35.000Z"
  }
}
```

{% endtab %}
{% endtabs %}

## Check Slug Availability

<mark style="color:blue;">`GET`</mark> `https://api.lahza.io/page/check_slug_availability/:slug`

Check the availability of a slug for a payment page.

#### Path Parameters

| Name | Type   | Description              |
| ---- | ------ | ------------------------ |
| slug | String | URL slug to be confirmed |

#### 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": "Page retrieved",
  "data": {
    "integration": 100032,
    "domain": "test",
    "name": "Offering collections",
    "description": "Give unto the Lord, and it shall be multiplied ten-fold to you.",
    "amount": null,
    "currency": "NGN",
    "slug": "5nApBwZkvY",
    "active": true,
    "id": 18,
    "createdAt": "2016-03-30T00:49:57.000Z",
    "updatedAt": "2016-03-30T00:49:57.000Z",
    "products": [
      {
        "product_id": 523,
        "name": "Product Four",
        "description": "Product Four Description",
        "product_code": "PROD_l9p81u9pkjqjunb",
        "page": 18,
        "price": 500000,
        "currency": "NGN",
        "quantity": 0,
        "type": "good",
        "features": null,
        "is_shippable": 0,
        "domain": "test",
        "integration": 343288,
        "active": 1,
        "in_stock": 1
      },
      {
        "product_id": 522,
        "name": "Product Five",
        "description": "Product Five Description",
        "product_code": "PROD_8ne9cxutagmtsyz",
        "page": 18,
        "price": 500000,
        "currency": "NGN",
        "quantity": 0,
        "type": "good",
        "features": null,
        "is_shippable": 0,
        "domain": "test",
        "integration": 343288,
        "active": 1,
        "in_stock": 0
      }
    ]
  }
}
```

{% endtab %}
{% endtabs %}


# Refunds

The Refunds API allows you create and manage transaction refunds.

## Create Refund

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

Initiate a refund on your integration

#### 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                                                                                                                                                                                                                                           |
| --------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| transaction<mark style="color:red;">\*</mark> | String | Transaction reference or id                                                                                                                                                                                                                           |
| amount                                        | String | Amount ( in agora if currency is ILS, qirsh, if currency is JOD, and cents, if currency is USD ) to be refunded to the customer. Amount is optional(defaults to original transaction amount) and cannot be more than the original transaction amount. |
| currency                                      | String | Three-letter ISO currency. Allowed values are: ILS, JOD or USD                                                                                                                                                                                        |
| customer\_note                                | String | Customer reason                                                                                                                                                                                                                                       |
| merchant\_note                                | String | Merchant reason                                                                                                                                                                                                                                       |

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

```json
{
  "status": true,
  "message": "Refund has been queued for processing",
  "data": {
    "transaction": {
      "id": 1004723697,
      "domain": "live",
      "reference": "T685312322670591",
      "amount": 10000,
      "paid_at": "2021-08-20T18:34:11.000Z",
      "channel": "card",
      "currency": "ILS",
      "authorization": {
        "exp_month": null,
        "exp_year": null,
        "account_name": null
      },
      "customer": {
        "international_format_phone": null
      },
      "plan": {},
      "subaccount": {
        "currency": null
      },
      "split": {},
      "order_id": null,
      "paidAt": "2021-08-20T18:34:11.000Z",
      "pos_transaction_data": null,
      "source": null,
      "fees_breakdown": null
    },
    "integration": 412829,
    "deducted_amount": 0,
    "channel": null,
    "merchant_note": "Refund for transaction T685312322670591 by test@example.com",
    "customer_note": "Refund for transaction T685312322670591",
    "status": "pending",
    "refunded_by": "test@example.com",
    "expected_at": "2021-12-16T09:21:17.016Z",
    "currency": "ILS",
    "domain": "live",
    "amount": 10000,
    "fully_deducted": false,
    "id": 3018284,
    "createdAt": "2021-12-07T09:21:17.122Z",
    "updatedAt": "2021-12-07T09:21:17.122Z"
  }
}
```

{% endtab %}
{% endtabs %}

## Fetch Refund

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

Get details of a refund on your integration<br>

#### Path Parameters

| Name                                        | Type   | Description                               |
| ------------------------------------------- | ------ | ----------------------------------------- |
| reference<mark style="color:red;">\*</mark> | String | Identifier for transaction to be refunded |

#### 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": "Refund retrieved",
  "data": {
    "transaction": 1641,
    "domain": "live",
    "amount": 500000,
    "deducted_amount": 500000,
    "fully_deducted": true,
    "currency": "ILS",
    "channel": "card",
    "status": "processed",
    "refunded_by": "test@example.com",
    "refunded_at": "2023-11-18T10:54:47.000Z",
    "expected_at": "2023-11-22T21:10:59.000Z",
    "customer_note": "xxx",
    "merchant_note": "xxx",
    "id": 1,
    "createdAt": "2023-09-24T21:10:59.000Z",
    "updatedAt": "2023-11-18T11:59:56.000Z"
  }

```

{% endtab %}
{% endtabs %}

## List Refunds

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

List refunds available on your integration.

#### Query Parameters

| Name      | Type    | Description                                                                                          |
| --------- | ------- | ---------------------------------------------------------------------------------------------------- |
| reference | String  | Identifier for transaction to be refunded                                                            |
| currency  | String  | Three-letter ISO currency. Allowed values are: ILS, JOD or USD                                       |
| page      | integer | Specify exactly what refund you want to page. If not specify we use a default value of 1.            |
| perPage   | integer | Specify how many records you want to retrieve per page. If not specify we use a default value of 50. |
| to        | date    | A timestamp at which to stop listing refund e.g. 2016-09-21                                          |
| from      | date    | A timestamp from which to start listing refund e.g. 2016-09-21                                       |

#### 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": "Refunds retrieved",
  "data": [
    {
      "id": 1,
      "domain": "live",
      "transaction": 1641,
      "dispute": 20,
      "amount": 500000,
      "deducted_amount": 500000,
      "currency": "ILS",
      "channel": "card",
      "fully_deducted": 1,
      "refunded_by": "customer@gmail.com",
      "refunded_at": "2023-06-15T16:32:19.000Z",
      "expected_at": "2023-03-28T10:49:57.000Z",
      "customer_note": "xxx",
      "merchant_note": "xxx",
      "created_at": "2023-03-21T10:49:57.000Z",
      "updated_at": "2023-06-21T08:41:37.000Z",
      "status": "processed"
    },
    {
      "id": 2,
      "domain": "test",
      "transaction": 323896,
      "amount": 500000,
      "deducted_amount": null,
      "currency": "ILS",
      "channel": "card",
      "fully_deducted": null,
      "refunded_by": "customer@gmail.com",
      "refunded_at": "2023-03-21T10:50:40.000Z",
      "expected_at": "2023-06-10T14:22:03.000Z",
      "customer_note": "xxx",
      "merchant_note": "xxx",
      "created_at": "2023-03-21T10:50:40.000Z",
      "updated_at": "2023-03-21T10:50:40.000Z",
      "status": "pending"
    }
  ]
}
```

{% endtab %}
{% endtabs %}


# Payment Session Timeout

The API allows you manage the session timeout of the transaction

## Fetch Timeout

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

Fetch the payment session timeout

#### 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": "Payment session timeout retrieved",
  "data": {
    "payment_session_timeout": 30
  }
}
```

{% endtab %}
{% endtabs %}

## Update Timeout

<mark style="color:orange;">`PUT`</mark> `https://api.lahza.io/payment_session_timeout`

Update the payment session timeout

#### 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                                                                    |
| ----------------------------------------- | ------- | ------------------------------------------------------------------------------ |
| timeout<mark style="color:red;">\*</mark> | Integer | Time before stopping session (in seconds). Set to 0 to cancel session timeouts |

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

```json
{
  "status": true,
  "message": "Payment session timeout updated",
  "data": {
    "payment_session_timeout": 30
  }
}
```

{% endtab %}
{% endtabs %}