## Payment API Documentation

This API provides endpoints to create payment requests, verify payments, retrieve payment statuses, list all payments,
and get detailed information on specific payments. All endpoints required authentication.

### List of Contents

- [Create Payment](#1-create-payment)
- [Verify Payment](#2-verify-payment)
- [Payment Status](#3-payment-status)
- [List Payments](#4-list-payments)
- [Payment Info](#5-payments-gateway-link)

### Authentication

- Authentication is handled using [Sanctum](https://laravel.com/docs/sanctum) tokens. Ensure that you include a valid
  token in the `Authorization` header of your requests to access protected endpoints.

### Content Type

- All API endpoints operate with `application/json` for both requests and responses.

---

### 1. Create Payment

- **Endpoint**: `POST /api/v1/payment/create`
- **Description**: Initiates a payment for a specific advertisement using a selected method (e.g., package,
  subscription, or gateway).
- **Authentication**: Yes
- **Permissions**: User

#### Request Parameters:

| Parameter     | Required/Optional         | Type    | Description                                             |
|---------------|---------------------------|---------|---------------------------------------------------------|
| `order_id`    | Required without amount   | Integer | ID of the order if you want to create an order payment. |
| `amount`      | Required without order_id | Decimal | Amount to be paid.                                      |
| `gateway`     | Required                  | String  | Name of the payment gateway (e.g "BitPay").             |
| `description` | Optional                  | String  | The description of your payment.                        |

#### Request Example:

```json
{
    "order_id": 1,
    "description": "It's a payment for an order",
    "amount": 50.00,
    "gateway": "BitPay"
}
```

#### Response Example:

```json
{
    "status": true,
    "message": "success!",
    "data": {
        "id": 1,
        "payment_link": "http://127.0.0.1:8000/payment/473b2dd6-19cc-4192-8d36-d4be20c927a5/pay",
        "uuid": "473b2dd6-19cc-4192-8d36-d4be20c927a5"
    }
}
```

---

### 2. Verify Payment

- **Endpoint**: `POST /api/v1/payment/{gateway}/verify`
- **Description**: Verifies the status of a payment after processing through a gateway.
- **Authentication**: No
- **Permissions**: User

#### Request Parameters:

| Parameter | Required/Optional | Type   | Description                           |
|-----------|-------------------|--------|---------------------------------------|
| `gateway` | Required          | String | Name of the payment gateway (In url). |

#### Request Example:

`https://127.0.0.1:8000/api/v1/payment/BitPay/verify`

#### Response Example:

Response structure based on the gateway's service (e.g "BitPay" or...) structure (It's dynamic).

---

### 3. Payment Status

- **Endpoint**: `POST /api/v1/payment/info`
- **Description**: Retrieves the status of a payment (Based on payment's ID or UUID).
- **Authentication**: Yes
- **Permissions**: User

#### Request Parameters:

| Parameter      | Required/Optional             | Type    | Description                             |
|----------------|-------------------------------|---------|-----------------------------------------|
| `payment_id`   | Required without payment_uuid | Integer | ID of the payment to retrieve status.   |
| `payment_uuid` | Required without payment_id   | Integer | UUID of the payment to retrieve status. |

#### Request Example:

```json
{
    "payment_id": 1
}
```

#### Response Example:

```json
{
    "status": true,
    "message": "success!",
    "data": {
        "id": 1,
        "payer": {
            "id": 1,
            "type": "User",
            "name": "John",
            "email": "john@emaple.com"
        },
        "payment_for": {
            "id": 1,
            "type": "Order"
        },
        "gateway": "BitPayService",
        "transaction_details": {
            "transaction_id": "31430",
            "transaction_number_1": "37330",
            "transaction_number_2": null
        },
        "amount": "50000",
        "uuid": "a42e84aa-90c3-4829-be16-0a5debf8c58c",
        "tracking_code": "2024091082151",
        "status": "successful",
        "data": null,
        "created_at": "2024-09-10T19:15:25.000000Z"
    }
}
```

---

### 4. List Payments

- **Endpoint**: `POST /api/v1/payment/list`
- **Description**: Retrieves a list of all payments made by the authenticated user.
- **Authentication**: Yes
- **Permissions**: User

#### Request Example:

No parameters required.

#### Response Example:

```json
{
    "status": true,
    "message": "success!",
    "data": [
        {
            "id": 1,
            "payment_for": {
                "id": 1,
                "type": "Wallet"
            },
            "gateway": "BitPayService",
            "transaction_details": {
                "transaction_id": null,
                "transaction_number_1": "37329",
                "transaction_number_2": null
            },
            "amount": "5000",
            "uuid": "96ac83cb-1456-4bcb-9518-b209ab6f8628",
            "tracking_code": "2024091033593",
            "status": "awaiting",
            "data": null,
            "created_at": "2024-09-10T19:15:15.000000Z"
        },
        {
            "id": 2,
            "payment_for": {
                "id": 1,
                "type": "Order"
            },
            "gateway": "BitPayService",
            "transaction_details": {
                "transaction_id": "31430",
                "transaction_number_1": "37330",
                "transaction_number_2": null
            },
            "amount": "50000",
            "uuid": "a42e84aa-90c3-4829-be16-0a5debf8c58c",
            "tracking_code": "2024091082151",
            "status": "successful",
            "data": null,
            "created_at": "2024-09-10T19:15:25.000000Z"
        }
    ]
}
```

---

### 5. Payment's Gateway Link

- **Endpoint**: `POST /api/v1/payment/redirectLink`
- **Description**: Retrieves link generated for the payment for using in redirection process.
- **Authentication**: Yes
- **Permissions**: User

#### Request Parameters:

| Parameter    | Required/Optional              | Type    | Description                                                                                           |
|--------------|--------------------------------|---------|-------------------------------------------------------------------------------------------------------|
| `payment_id` | Required                       | Integer | ID of the payment to retrieve details.                                                                |
| `get_link`   | Optional (Recommended for API) | Boolean | Pass 1 to get the link as string and 2 to get the link in a array instance of RedirectResponse class. |

#### Request Example:

```json
{
    "payment_id": 45,
    "get_link": 1
}
```

#### Response Example (From BitPay Service):

```json
{
    "status": true,
    "message": "success!",
    "data": {
        "redirect_link": "https://bitpay.ir/payment-test/gateway-37330-get"
    }
}
```

---