> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paytring.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Development

> Preview changes locally to update your docs

## Payment Popup

If you wish to integrate Paytring's JS / iframe checkout into your platform, follow the steps outlined below.

### 1. Include Paytring Iframe JavaScript Library

Include the Paytring Iframe JavaScript library by adding the following CDN link to your HTML file:

```html theme={null}
<script src="https://cdn.paytring.com/js/checkout/iframe.v1.2.0.js"></script> 
```

### 2. Creating an Order

After including the Paytring Iframe library, you can create an order and initiate the iframe checkout. Use the following JavaScript code:

```javascript theme={null}
// Define a function to be executed if the transaction fails
async function fail_handle(order_id) {
    // This function executes if the transaction fails
    // You will receive the order id as an argument
    // You can use the Fetch API to check order details
}

// Define a function to be executed if the transaction is successful
async function success_handle(order_id) {
    // This function executes if the transaction is successful
    // You will receive the order id as an argument
    // You can use the Fetch API to check order details
}

// Define a function to log events
async function event_happen(resp) {
    console.log("Event Name: " + resp.event_name);
    console.log("Event Value: " + resp.event_value);
}

// Define a function to handle popup closure
async function on_close(order_id) {
    // This function executes if the popup is closed
    // You will receive the order id as an argument
    // You can use the Fetch API to check order details
}

// Define options for the Paytring Iframe
var options = {
    "order_id": response.order_id, // Replace with the order id you received when creating the order
    "success": success_handle,
    "failed": fail_handle,
    "events": event_happen, // Executes on various events, such as payment option selection or proceeding with payment
    "onClose": on_close
    // optional parameters
    "zIndex": 99999 // optional parameter to set z-index of the iframe
};

// Create an instance of the Paytring class with the specified options
const paytring = new Paytring(options);

// Open the Paytring Iframe
paytring.open();
```

#### Explanation

1. **fail\_handle Function**:
   * This function is a callback that will be executed if the transaction fails.
   * It receives the `order_id` as an argument, allowing you to handle and log information about failed transactions.
   * You can use the Fetch API or other methods to check and retrieve details about the failed order.

2. **success\_handle Function**:
   * This function is a callback that will be executed if the transaction is successful.
   * Similar to `fail_handle`, it receives the `order_id` as an argument.
   * You can use the Fetch API or other methods to check and retrieve details about the successful order.

3. **event\_happen Function**:
   * This function is a callback that logs events related to the Paytring Iframe.
   * It logs the event name and event value to the console.
   * The function is intended to be used for debugging and monitoring purposes.

4. **on\_close Function**:
   * This function is a callback that will be executed if the popup is closed for any reason.
   * Similar to other callback functions, it receives the `order_id` as an argument.
   * You can use the Fetch API or other methods to check and retrieve details about the order.

5. **options Object**:
   * An object that holds various options for configuring the Paytring Iframe.
   * It includes the `order_id` received when creating the order, success and failed callback functions, and an events callback for logging events.
   * The `order_id` is mandatory, while the other parameters (`success`, `failed`, and `events`) are optional.

6. **Paytring Instance**:
   * Creates an instance of the Paytring class with the specified options.

7. **Open Iframe**:
   * The `open()` method is called on the Paytring instance, which opens the Paytring Iframe for the user to complete the payment.
   * Ensure that you replace `response.order_id` with the actual order id obtained from your order creation process. The provided callbacks (`fail_handle`, `success_handle`, and `event_happen`) allow you to customize how your application handles different aspects of the payment process.

### 3. Handling Events

If you prefer not to pass callback functions directly in the options, you can alternatively use event handling to capture specific events during the iframe checkout process. This approach allows you to receive notifications for various actions, such as successful payments (`payment.success`), failed transactions (`payment.failed`), and the user closing the iframe before completing the transaction (`payment.close`).

#### Event Handling Example

To capture events, you can utilize the following code:

* **Failed Event**

  ```javascript theme={null}
  document.addEventListener("payment.failed", (e) => {
      // This code block executes when the payment transaction fails
      console.log("Payment Failed order id:", e.detail.order_id);
  });
  ```

* **Success Event**

  ```javascript theme={null}
  document.addEventListener("payment.success", (e) => {
      // This code block executes when the payment transaction is successful
      // You can add your custom logic here
      console.log("Payment Successful order id:", e.detail.order_id);
  });
  ```

* **Close Event**

  ```javascript theme={null}
  document.addEventListener("payment.close", (e) => {
      // This event is triggered when the user closes the iframe before completing the transaction
      console.log("Iframe closed for order id:", e.detail.order_id);
  });
  ```

If you prefer using these events, you don't need to pass functions in the options. Simply use the following code:

```javascript theme={null}
var options = {
    "order_id": response.order_id, // Replace with the order id you received when creating the order
};

const paytring = new Paytring(options);
// Open Iframe
paytring.open();
```

## Payment Callback Request

| Param       | Datatype | Sample Value                                                                                                                     |
| :---------- | :------- | :------------------------------------------------------------------------------------------------------------------------------- |
| order\_id   | string   | 488659548274428965                                                                                                               |
| receipt\_id | string   | TXN01071200893                                                                                                                   |
| hash        | string   | ceb38f5bfba8ba190754d6cadd7af58b845406010b01aa297e10b145ca45da8f9eb1632d814158d0e88c15cc78ccc8e0a8661ae93c8a7f2356432e2b25fada65 |

Above is a sample of a request in Form Data Format. We strongly suggest you perform a lookup of the transaction in your database with the given details and fetch the order using the "**Fetch by Order ID**" API endpoint before updating your database.

## Payment Webhook Request

```json theme={null}
{
    "key": "test_123",
    "receipt_id": "HYD2245637",
    "hash": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

Above is a sample of a request in JSON format. We strongly suggest you verify the hash, fetch the transaction, and perform a lookup of the transaction in your database with the given details before updating your database.