### Example GET Request for Products with Pagination

Source: https://dev-docs.streampay.sa/docs/guides/pagination-and-filtering

This example demonstrates how to construct a GET request to the products endpoint, specifying pagination parameters like page number, limit, sort field, and sort direction. It shows the default values for sort_field and sort_direction.

```http
GET api/v2/products?page=1&limit=20&sort_field=created_at&sort_direction=desc
```

--------------------------------

### Example GET Request for Payments with Pagination and Filtering

Source: https://dev-docs.streampay.sa/docs/guides/pagination-and-filtering

This example illustrates a GET request to the payments endpoint, incorporating both pagination and filtering. It shows how to specify a page, limit, filter by invoice ID, and filter by multiple statuses using repeating keys.

```http
GET api/v2/payments?page=1&limit=20&invoice_id=73b89d47-1bb1-443c-9a4c-f0ee23e22191&statuses=PENDING&statuses=PROCESSING
```

--------------------------------

### Python Example: Basic Pagination

Source: https://dev-docs.streampay.sa/docs/guides/pagination-and-filtering

A Python example demonstrating how to fetch the first page of results for products with a custom limit using the `requests` library.

```APIDOC
## Example: Basic Pagination (Python)

Fetching the first page of results with a custom limit.

### Request Example
```python
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://stream-app-service.streampay.sa/api/v2/products"

response = requests.get(
    BASE_URL,
    headers={"x-api-key": API_KEY},
    params={
        "page": 1, 
        "limit": 20
    }
)

data = response.json()
print(f"Showing page {data['pagination']['current_page']} of {data['pagination']['max_page']}")
```
```

--------------------------------

### Create Payment Link for a New Recurring Subscription (cURL)

Source: https://dev-docs.streampay.sa/docs/guides/getting-started

This cURL example demonstrates creating a payment link to initiate a recurring subscription. The product must be pre-configured as recurring. Upon successful payment, StreamPay automatically creates a subscription and an initial invoice. The `organization_consumer_id` can be included to target a specific customer or omitted to allow new customer creation.

```bash
curl -X POST https://stream-app-service.streampay.sa/api/v2/payment_links \
  -H "x-api-key: <your-base64-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Plan Subscription",
    "description": "Monthly recurring plan",
    "items": [
      { "product_id": "recurring-product-uuid-here", "quantity": 1 }
    ],
    "contact_information_type": "EMAIL",
    "currency": "SAR",
    "max_number_of_payments": 1,
    "organization_consumer_id": "your-customer-uuid-here",
    "success_redirect_url": "https://example.com/success",
    "failure_redirect_url": "https://example.com/failure"
  }'
```

--------------------------------

### Create a Customer (Consumer) using Stream API

Source: https://dev-docs.streampay.sa/docs/guides/getting-started

This cURL example demonstrates how to create a new customer record in Stream. It sends a POST request to the consumers endpoint with customer details like name, email, and phone number in JSON format.

```bash
curl -X POST https://stream-app-service.streampay.sa/api/v2/consumers \
  -H "x-api-key: <your-base64-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ahmad Ali",
    "email": "ahmad@example.com",
    "phone": "+966501234567"
  }'
```

--------------------------------

### Python: Basic Pagination with Requests Library

Source: https://dev-docs.streampay.sa/docs/guides/pagination-and-filtering

This Python code example uses the 'requests' library to fetch the first page of products with a custom limit. It demonstrates setting the API key in headers and passing pagination parameters in the request. The response JSON is then parsed to display pagination details.

```python
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://stream-app-service.streampay.sa/api/v2/products"

response = requests.get(
    BASE_URL,
    headers={"x-api-key": API_KEY},
    params={
        "page": 1, 
        "limit": 20
    }
)

data = response.json()
print(f"Showing page {data['pagination']['current_page']} of {data['pagination']['max_page']}")
```

--------------------------------

### POST /api/v2/consumers

Source: https://dev-docs.streampay.sa/docs/guides/getting-started

Create a customer record (consumer) for use with payment links. This allows you to associate payments with specific individuals.

```APIDOC
## POST /api/v2/consumers

### Description
Create a customer record (consumer) for use with payment links. This allows you to associate payments with specific individuals.

### Method
POST

### Endpoint
`/api/v2/consumers`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name of the customer.
- **email** (string) - Required - The email address of the customer.
- **phone** (string) - Optional - The phone number of the customer.

### Request Example
```json
{
  "name": "Ahmad Ali",
  "email": "ahmad@example.com",
  "phone": "+966501234567"
}
```

### Response
#### Success Response (200 or 201)
- **id** (string) - The unique identifier for the created consumer.
- **name** (string) - The name of the customer.
- **email** (string) - The email address of the customer.
- **phone** (string) - The phone number of the customer.

#### Response Example
```json
{
  "id": "cus_abc123xyz",
  "name": "Ahmad Ali",
  "email": "ahmad@example.com",
  "phone": "+966501234567"
}
```
```

--------------------------------

### Retrieve Payment or Subscription Status

Source: https://dev-docs.streampay.sa/docs/guides/getting-started

Use the Get Payment and Get Subscription endpoints to fetch the latest status programmatically using your API key.

```APIDOC
## Retrieve Payment or Subscription Status

### Description
Use the **Get Payment** and **Get Subscription** endpoints to fetch the latest status programmatically.

### Method
GET

### Endpoints
- **Payment status:** `/api/v2/payments/{payment_id}` → [Payments API](/api/v2-payments-get)
- **Subscription status:** `/api/v2/subscriptions/{subscription_id}` → [Subscriptions API](/api/v2-subscriptions-get)

### Authentication
Use the same `x-api-key` header described in [Authorization](#authorization):

```
x-api-key: <base64(api-key:api-secret)>
```

### Request Example: Fetch Payment Status (cURL)

```bash
curl -X GET https://stream-app-service.streampay.sa/api/v2/payments/your-payment-id \
  -H "x-api-key: <your-base64-token>"
```

### Response
#### Success Response (200)
(Details depend on whether fetching payment or subscription status, refer to respective API documentation)

#### Response Example
(Example not provided in the input text, refer to respective API documentation)
```

--------------------------------

### Create Payment Link for Multiple Customers (cURL)

Source: https://dev-docs.streampay.sa/docs/guides/getting-started

This cURL command demonstrates how to create a payment link that can be used by multiple customers. Each customer will enter their information upon checkout. The `organization_consumer_id` is omitted to allow for multiple payers.

```bash
curl -X POST https://stream-app-service.streampay.sa/api/v2/payment_links \
  -H "x-api-key: <your-base64-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Event Registration",
    "description": "Annual conference registration",
    "items": [
      { "product_id": "your-product-uuid-here", "quantity": 1 }
    ],
    "contact_information_type": "PHONE",
    "currency": "SAR",
    "max_number_of_payments": 100,
    "success_redirect_url": "https://example.com/success",
    "failure_redirect_url": "https://example.com/failure"
  }'
```

--------------------------------

### Installment Settings

Source: https://dev-docs.streampay.sa/docs/api/logo-upload-api-v-2-organization-logo-upload-put

Configure general installment payment options.

```APIDOC
## PUT /api/payment/settings/installment

### Description
Configures general installment payment settings, including the minimum installment amount, whether to exclude coupons, and the available split options.

### Method
PUT

### Endpoint
/api/payment/settings/installment

### Parameters
#### Request Body
- **min_installment_amount** (number) - Optional - The minimum amount for an installment payment.
- **exclude_coupons** (boolean) - Optional - Whether to exclude coupons from installment calculations.
- **split_options** (array of objects) - Optional - Defines the available installment split options. Each object should contain:
  - **num_of_installments** (integer) - Required - The number of installments.
  - **split_period** (string, enum: ["MONTHLY", "TWO_MONTHS", "QUARTERLY", "FOUR_MONTHS", "FIVE_MONTHS", "TWO_QUARTERS", "SEVEN_MONTHS", "EIGHT_MONTHS", "THREE_QUARTERS", "TEN_MONTHS", "ELEVEN_MONTHS", "YEARLY"]) - Required - The period for each installment.

### Request Example
```json
{
  "min_installment_amount": 100,
  "exclude_coupons": false,
  "split_options": [
    {
      "num_of_installments": 2,
      "split_period": "MONTHLY"
    },
    {
      "num_of_installments": 3,
      "split_period": "MONTHLY"
    }
  ]
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the update.

#### Response Example
```json
{
  "message": "Installment settings updated successfully."
}
```
```

--------------------------------

### Configure Installment Settings

Source: https://dev-docs.streampay.sa/docs/api/get-subscription-details-api-v-2-consumer-portal-profile-subscription-subscription-id-details-get

Defines the parameters for installment payments. This includes setting a minimum installment amount, an option to exclude coupons, and defining available split options (e.g., number of installments and period). The default configuration sets a minimum of 100 and offers monthly splits.

```json
{
  "installment": {
    "min_installment_amount": 100,
    "exclude_coupons": false,
    "split_options": [
      {
        "num_of_installments": 2,
        "split_period": "MONTHLY"
      },
      {
        "num_of_installments": 3,
        "split_period": "MONTHLY"
      },
      {
        "num_of_installments": 4,
        "split_period": "MONTHLY"
      }
    ]
  }
}
```

--------------------------------

### POST /api/v2/products

Source: https://dev-docs.streampay.sa/docs/api/v2-products-create

Create a new product with pricing and description. Supports multiple currencies and recurring billing options.

```APIDOC
## POST /api/v2/products

### Description
Create a new product with pricing and description. Supports multiple currencies and recurring billing options.

### Method
POST

### Endpoint
/api/v2/products

### Parameters
#### Request Body
- **name** (string) - Required - Name of the product. Max length 160, min length 1.
- **description** (string) - Optional - Description of the product. Max length 500.
- **price** (number | string | null) - Optional - [DEPRECATED] Price of the product. Use 'prices' array for multi-currency support.
- **prices** (array) - Optional - Prices for the product in different currencies. At least one price is required.
  - **currency** (string) - Required - ISO 4217 currency codes supported by Moyasar.
  - **amount** (number | string) - Required - Price amount (must be >= 1).
  - **is_price_inclusive_of_vat** (boolean) - Optional - If True, amount includes VAT. Defaults to true.
  - **is_price_exempt_from_vat** (boolean) - Optional - If True, no VAT applies to this price. Defaults to false.
- **is_one_time** (boolean) - Optional - Will this product be used only one time in one invoice? Defaults to false.
- **type** (string) - Required - The type of product: one off or recurring. Enum: ["RECURRING", "ONE_OFF", "METERED"].
- **recurring_interval** (string) - Optional - Represents the billing cycle interval if product is recurring. Required for cyclic products. Enum: ["WEEK", "MONTH", "SEMESTER", "YEAR"].
- **recurring_interval_count** (integer) - Optional - The billing cycle multiple if the product is recurring. Defaults to 1.
- **is_price_exempt_from_vat** (boolean) - Optional - [DEPRECATED] Is the price exempt from VAT? Use VAT settings in prices[] instead.
- **is_price_inclusive_of_vat** (boolean) - Optional - [DEPRECATED] Is the price inclusive of VAT? Use VAT settings in prices[] instead.

### Request Example
```json
{
  "name": "Premium Subscription",
  "description": "Monthly access to premium features.",
  "prices": [
    {
      "currency": "SAR",
      "amount": 100,
      "is_price_inclusive_of_vat": true
    },
    {
      "currency": "USD",
      "amount": 30,
      "is_price_exempt_from_vat": false
    }
  ],
  "type": "RECURRING",
  "recurring_interval": "MONTH",
  "recurring_interval_count": 1
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the created product.
- **name** (string) - Name of the product.
- **description** (string) - Description of the product.
- **prices** (array) - Prices for the product in different currencies.
- **type** (string) - Type of the product.
- **recurring_interval** (string) - Billing cycle interval if recurring.
- **recurring_interval_count** (integer) - Billing cycle multiple if recurring.

#### Response Example
```json
{
  "id": "prod_12345abcde",
  "name": "Premium Subscription",
  "description": "Monthly access to premium features.",
  "prices": [
    {
      "currency": "SAR",
      "amount": 100,
      "is_price_inclusive_of_vat": true,
      "is_price_exempt_from_vat": false
    },
    {
      "currency": "USD",
      "amount": 30,
      "is_price_inclusive_of_vat": false,
      "is_price_exempt_from_vat": false
    }
  ],
  "type": "RECURRING",
  "recurring_interval": "MONTH",
  "recurring_interval_count": 1,
  "is_one_time": false,
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Retrieve Payment Status (cURL)

Source: https://dev-docs.streampay.sa/docs/guides/getting-started

This example demonstrates how to programmatically retrieve the status of a payment using the StreamPay API. It utilizes a GET request to the payments endpoint with the payment ID and an authentication header.

```bash
curl -X GET https://stream-app-service.streampay.sa/api/v2/payments/your-payment-id \
  -H "x-api-key: <your-base64-token>"
```

--------------------------------

### Handling Payment Redirects (URL Examples)

Source: https://dev-docs.streampay.sa/docs/guides/getting-started

After a customer completes or fails a payment, Stream redirects them to a specified URL with query parameters indicating the outcome. These examples show the structure of success and failure redirect URLs.

```url
https://example.com/success?id=...&invoice_id=...&status=paid&message=APPROVED
```

```url
https://example.com/failure?payment_link_id=...&id=...&status=failed&message=...
```

--------------------------------

### Create a Simple Payment Link with TypeScript SDK

Source: https://dev-docs.streampay.sa/sdks/typescript

Demonstrates how to initialize the Stream SDK with an API key and create a simple payment link. This includes defining subscription details, consumer information, product details, and redirect URLs for success and failure scenarios.

```typescript
const client = StreamSDK.init(process.env.STREAM_API_KEY!);

const result = await client.createSimplePaymentLink({
  name: "Monthly Subscription",
  amount: 99.99,
  consumer: {
    email: "customer@example.com",
    name: "Ahmad Ali",
    phone: "+966501234567",
  },
  product: {
    name: "Premium Plan",
    price: 99.99,
  },
  successRedirectUrl: "https://yourapp.com/success",
  failureRedirectUrl: "https://yourapp.com/failure",
});

console.log("Payment URL:", result.paymentUrl);
```

--------------------------------

### Install Stream TypeScript SDK

Source: https://dev-docs.streampay.sa/sdks/typescript

Installs the Stream TypeScript SDK using npm. This is the first step to integrate Stream's payment functionalities into your Node.js or TypeScript project.

```bash
npm install @streamsdk/typescript
```

--------------------------------

### Fetch Payment Status

Source: https://dev-docs.streampay.sa/docs/guides/getting-started

Retrieves the status of a specific payment using its ID. Requires an API key for authentication.

```APIDOC
## GET /api/v2/payments/{paymentId}

### Description
Fetches the status of a given payment.

### Method
GET

### Endpoint
`/api/v2/payments/{paymentId}`

### Parameters
#### Path Parameters
- **paymentId** (string) - Required - The unique identifier for the payment.

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const API_BASE = "https://stream-app-service.streampay.sa/api/v2";
const API_KEY = process.env.STREAM_API_KEY_BASE64; // base64(api-key:api-secret)

async function getPaymentStatus(paymentId) {
  const res = await fetch(`${API_BASE}/payments/${paymentId}`, {
    headers: { "x-api-key": API_KEY }
  });
  if (!res.ok) throw new Error(`Payment fetch failed: ${res.status}`);
  const payment = await res.json();
  return payment.status;
}
```

### Response
#### Success Response (200)
- **status** (string) - The current status of the payment.

#### Response Example
```json
{
  "status": "completed"
}
```
```

--------------------------------

### GET /products/top-used

Source: https://dev-docs.streampay.sa/docs/api/get-top-used-products-api-v-2-products-top-used-get

Retrieves a list of the top used products. This endpoint provides product details including pricing information, VAT applicability, and active status. It supports backward compatibility by including legacy price fields alongside a new multi-currency `prices` array.

```APIDOC
## GET /products/top-used

### Description
Retrieves a list of the top used products. This endpoint provides product details including pricing information, VAT applicability, and active status. It supports backward compatibility by including legacy price fields alongside a new multi-currency `prices` array.

### Method
GET

### Endpoint
/products/top-used

### Parameters
#### Query Parameters
* **limit** (integer) - Optional - The maximum number of top used products to return.
* **offset** (integer) - Optional - The number of top used products to skip before starting to collect the result set.

### Request Example
```json
{
  "limit": 10,
  "offset": 0
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the product.
- **name** (string) - The name of the product.
- **description** (string) - A detailed description of the product.
- **price** (string) - The default price of the product (legacy field).
- **currency** (string) - The currency code for the default price (legacy field).
- **is_price_inclusive_of_vat** (boolean) - Indicates if the default price includes VAT (legacy field).
- **price_excluding_vat** (string) - The default price excluding VAT (legacy field).
- **vat_amount** (string) - The VAT amount for the default price (legacy field).
- **prices** (array) - An array of product prices across different currencies.
  - **id** (string) - Unique identifier for the price.
  - **currency** (string) - ISO 4217 currency code.
  - **amount** (string) - The price amount.
  - **is_active** (boolean) - Indicates if the price is active.
  - **is_price_inclusive_of_vat** (boolean) - Indicates if the price includes VAT.
  - **is_price_exempt_from_vat** (boolean) - Indicates if the price is exempt from VAT.
  - **price_excluding_vat** (string) - The price excluding VAT.
  - **vat_amount** (string) - The VAT amount for the price.
- **is_active** (boolean) - Indicates if the product is active and can be used in invoices or subscriptions.
- **is_one_time** (boolean) - Indicates if the product is intended for a single use.
- **is_used_in_finalized_invoice** (boolean) - Indicates if the product has been used in a finalized invoice.

#### Response Example
```json
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Example Product",
  "description": "This is an example product description.",
  "price": "100.00",
  "currency": "SAR",
  "is_price_inclusive_of_vat": true,
  "price_excluding_vat": "86.96",
  "vat_amount": "13.04",
  "prices": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "currency": "SAR",
      "amount": "100.00",
      "is_active": true,
      "is_price_inclusive_of_vat": true,
      "is_price_exempt_from_vat": false,
      "price_excluding_vat": "86.96",
      "vat_amount": "13.04"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-2345-67890abcdef1",
      "currency": "USD",
      "amount": "25.00",
      "is_active": true,
      "is_price_inclusive_of_vat": false,
      "is_price_exempt_from_vat": false,
      "price_excluding_vat": "25.00",
      "vat_amount": "0.00"
    }
  ],
  "is_active": true,
  "is_one_time": false,
  "is_used_in_finalized_invoice": false
}
```

#### Error Response (422)
- **detail** (array) - A list of validation errors.
  - **loc** (array) - The location of the error in the request.
  - **msg** (string) - The error message.
  - **type** (string) - The type of error.
  - **input** (any) - The input that caused the error.
  - **ctx** (object) - Additional context for the error.

#### Response Example
```json
{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "ensure this value is a valid integer",
      "type": "type_error.integer",
      "input": "abc"
    }
  ]
}
```
```

--------------------------------

### Fetch Subscription Status

Source: https://dev-docs.streampay.sa/docs/guides/getting-started

Retrieves the status of a specific subscription using its ID. Requires an API key for authentication.

```APIDOC
## GET /api/v2/subscriptions/{subscriptionId}

### Description
Fetches the status of a given subscription.

### Method
GET

### Endpoint
`/api/v2/subscriptions/{subscriptionId}`

### Parameters
#### Path Parameters
- **subscriptionId** (string) - Required - The unique identifier for the subscription.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET https://stream-app-service.streampay.sa/api/v2/subscriptions/your-subscription-id \
  -H "x-api-key: <your-base64-token>"
```

### Response
#### Success Response (200)
- **status** (string) - The current status of the subscription.

#### Response Example
```json
{
  "status": "active"
}
```
```

--------------------------------

### List Products

Source: https://context7_llms

Lists all available products with support for pagination, filtering, and sorting.

```APIDOC
## GET /v2/products/list

### Description
List all products with pagination, filtering, and sorting options.

### Method
GET

### Endpoint
/v2/products/list

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of products to return per page.
- **offset** (integer) - Optional - Number of products to skip.
- **sort_by** (string) - Optional - Field to sort by (e.g., 'name', 'price').
- **order** (string) - Optional - Sort order ('asc' or 'desc').
- **category** (string) - Optional - Filter by product category.

### Response
#### Success Response (200)
- **products** (array) - A list of product objects.
  - **id** (string) - Product ID.
  - **name** (string) - Product name.
  - **description** (string) - Product description.
  - **price** (number) - Product price.
- **total_count** (integer) - Total number of products available.

#### Response Example
```json
{
  "products": [
    {
      "id": "prod_123",
      "name": "Standard Widget",
      "description": "A reliable standard widget.",
      "price": 25.00
    }
  ],
  "total_count": 100
}
```
```

--------------------------------

### General Settings

Source: https://dev-docs.streampay.sa/docs/api/update-contact-settings-api-v-2-organization-settings-contact-put

Configure general API settings such as version and time zone.

```APIDOC
## GET /api/settings/general

### Description
Retrieves the current general settings for the organization.

### Method
GET

### Endpoint
/api/settings/general

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **version** (string) - The API version.
- **time_zone** (string) - The time zone for the organization.

#### Response Example
```json
{
  "version": "v2",
  "time_zone": "Asia/Riyadh"
}
```
```

```APIDOC
## PUT /api/settings/general

### Description
Updates the general settings for the organization.

### Method
PUT

### Endpoint
/api/settings/general

### Parameters
#### Request Body
- **version** (string) - Optional. The API version. Allowed values: v1, v2.
- **time_zone** (string) - Optional. The time zone for the organization (e.g., 'Asia/Riyadh').

### Request Example
```json
{
  "version": "v1",
  "time_zone": "UTC"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "General settings updated successfully."
}
```
```

--------------------------------

### POST /api/v2/payment_links

Source: https://dev-docs.streampay.sa/docs/guides/getting-started

Creates a payment link. This endpoint can be used to generate links for one-time payments, multiple payers, or to initiate recurring subscriptions.

```APIDOC
## POST /api/v2/payment_links

### Description
Creates a payment link that can be used for various payment scenarios. The behavior (e.g., collecting customer details, recurring payments) is determined by the request body parameters and the product configuration.

### Method
POST

### Endpoint
`https://stream-app-service.streampay.sa/api/v2/payment_links`

### Parameters
#### Headers
- **x-api-key** (string) - Required - Your base64 encoded API key and secret (`<your-base64-token>`)
- **Content-Type** (string) - Required - `application/json`

#### Request Body
- **name** (string) - Required - The name of the payment link.
- **description** (string) - Optional - A description for the payment link.
- **items** (array) - Required - An array of items to be paid for.
  - **product_id** (string) - Required - The UUID of the product.
  - **quantity** (integer) - Required - The quantity of the product.
- **contact_information_type** (string) - Required - The type of contact information to collect (e.g., `PHONE`, `EMAIL`).
- **currency** (string) - Required - The currency code for the payment (e.g., `SAR`).
- **max_number_of_payments** (integer) - Required - The maximum number of payments allowed for this link. Set to `1` for single payments or subscriptions.
- **organization_consumer_id** (string) - Optional - The UUID of a specific customer. If provided, customer details are not collected at checkout.
- **success_redirect_url** (string) - Required - The URL to redirect to upon successful payment.
- **failure_redirect_url** (string) - Required - The URL to redirect to upon failed payment.
- **custom_metadata** (object) - Optional - A key-value object for custom metadata.

### Request Example (Multiple Customers)
```json
{
  "name": "Event Registration",
  "description": "Annual conference registration",
  "items": [
    {
      "product_id": "your-product-uuid-here",
      "quantity": 1
    }
  ],
  "contact_information_type": "PHONE",
  "currency": "SAR",
  "max_number_of_payments": 100,
  "success_redirect_url": "https://example.com/success",
  "failure_redirect_url": "https://example.com/failure",
  "custom_metadata": {
    "event_id": "conf_2025",
    "campaign_source": "email_marketing"
  }
}
```

### Request Example (Specific Customer - Subscription)
```json
{
  "name": "Premium Plan Subscription",
  "description": "Monthly recurring plan",
  "items": [
    {
      "product_id": "recurring-product-uuid-here",
      "quantity": 1
    }
  ],
  "contact_information_type": "EMAIL",
  "currency": "SAR",
  "max_number_of_payments": 1,
  "organization_consumer_id": "your-customer-uuid-here",
  "success_redirect_url": "https://example.com/success",
  "failure_redirect_url": "https://example.com/failure",
  "custom_metadata": {
    "plan": "premium_monthly",
    "source": "pricing_page"
  }
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the created payment link.
- **url** (string) - The URL of the payment link.
- **created_at** (string) - The timestamp when the payment link was created.

#### Response Example
```json
{
  "id": "plink_xxxxxxxxxxxxxxxxx",
  "url": "https://checkout.streampay.sa/pay/xxxxxxxxxxxxxxxxx",
  "created_at": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### POST /api/v2/payment_links

Source: https://dev-docs.streampay.sa/docs/guides/getting-started

Create a payment link that redirects customers to Stream's secure checkout page. This can be for general use or tied to a specific customer.

```APIDOC
## POST /api/v2/payment_links

### Description
Create a payment link that redirects customers to Stream's secure checkout page. This can be for general use or tied to a specific customer. Payment links can contain either one-time or recurring products, but not a mix of both.

### Method
POST

### Endpoint
`/api/v2/payment_links`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **products** (array) - Required - An array of product objects to include in the payment link. Each object should have at least a `product_id` and `quantity`.
  - **product_id** (string) - Required - The ID of the product.
  - **quantity** (integer) - Required - The quantity of the product.
- **organization_consumer_id** (string) - Optional - The ID of the customer to associate this payment link with. If omitted, the link is for general use.
- **metadata** (object) - Optional - Key-value pairs for additional information.

### Request Example
```json
{
  "products": [
    {
      "product_id": "prod_123",
      "quantity": 1
    }
  ],
  "organization_consumer_id": "cus_abc123xyz"
}
```

### Response
#### Success Response (200 or 201)
- **id** (string) - The unique identifier for the created payment link.
- **url** (string) - The URL for the payment link.
- **status** (string) - The status of the payment link (e.g., 'pending', 'paid').

#### Response Example
```json
{
  "id": "pl_def456uvw",
  "url": "https://checkout.streampay.sa/pay/pl_def456uvw",
  "status": "pending"
}
```
```

--------------------------------

### Product Pricing Information

Source: https://dev-docs.streampay.sa/docs/api/v2-invoices-update

This section details the structure of product pricing, including default currency, VAT applicability, and a list of prices across various currencies.

```APIDOC
## Product Pricing Details

### Description
Provides information about a product's pricing, including default currency, VAT settings, and a comprehensive list of prices in different currencies.

### Method
GET

### Endpoint
`/products/{productId}/pricing`

### Parameters
#### Path Parameters
- **productId** (string) - Required - The unique identifier of the product.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **currency** (string) - The default currency code for the product (e.g., SAR).
- **is_price_exempt_from_vat** (boolean) - Indicates if the default price is exempt from VAT.
- **is_price_inclusive_of_vat** (boolean) - Indicates if the default price includes VAT.
- **price_excluding_vat** (string) - The default price excluding VAT.
- **vat_amount** (string) - The VAT amount for the default price.
- **prices** (array) - A list of available prices for the product in different currencies.
  - **id** (string) - Unique identifier for the price entry.
  - **currency** (string) - ISO 4217 currency code (e.g., SAR, USD).
  - **amount** (string) - The price amount in the specified currency.
  - **is_active** (boolean) - Whether this price is currently active.
  - **is_price_inclusive_of_vat** (boolean) - Whether this price includes VAT.
  - **is_price_exempt_from_vat** (boolean) - Whether this price is exempt from VAT.
  - **price_excluding_vat** (string) - The price excluding VAT in the specified currency.
  - **vat_amount** (string) - The VAT amount for the specified currency price.
- **is_active** (boolean) - Indicates if the product is active and can be used.
- **is_one_time** (boolean) - Indicates if the product is intended for a single use.
- **is_used_in_finalized_invoice** (boolean) - Indicates if the product has been used in a finalized invoice.

#### Response Example
```json
{
  "currency": "SAR",
  "is_price_exempt_from_vat": false,
  "is_price_inclusive_of_vat": true,
  "price_excluding_vat": "91.30",
  "vat_amount": "8.70",
  "prices": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "currency": "SAR",
      "amount": "100.00",
      "is_active": true,
      "is_price_inclusive_of_vat": true,
      "is_price_exempt_from_vat": false,
      "price_excluding_vat": "91.30",
      "vat_amount": "8.70"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-2345-67890abcdef1",
      "currency": "USD",
      "amount": "25.00",
      "is_active": true,
      "is_price_inclusive_of_vat": false,
      "is_price_exempt_from_vat": false,
      "price_excluding_vat": "25.00",
      "vat_amount": "0.00"
    }
  ],
  "is_active": true,
  "is_one_time": false,
  "is_used_in_finalized_invoice": false
}
```
```

--------------------------------

### Installment Settings

Source: https://dev-docs.streampay.sa/docs/api/update-contact-settings-api-v-2-organization-settings-contact-put

Configure installment payment options, including minimum amounts and split options.

```APIDOC
## GET /api/settings/installments

### Description
Retrieves the current installment settings for the organization.

### Method
GET

### Endpoint
/api/settings/installments

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **installment** (object) - General installment settings.
- **payment_link_installment_settings** (object) - Installment settings specific to payment links.

#### Response Example
```json
{
  "installment": {
    "min_installment_amount": 100,
    "exclude_coupons": false,
    "split_options": [
      {"num_of_installments": 2, "split_period": "MONTHLY"},
      {"num_of_installments": 3, "split_period": "MONTHLY"},
      {"num_of_installments": 4, "split_period": "MONTHLY"}
    ]
  },
  "payment_link_installment_settings": {
    "min_installment_amount": 100,
    "exclude_coupons": false,
    "split_options": [
      {"num_of_installments": 2, "split_period": "MONTHLY"},
      {"num_of_installments": 3, "split_period": "MONTHLY"},
      {"num_of_installments": 4, "split_period": "MONTHLY"}
    ]
  }
}
```
```

```APIDOC
## PUT /api/settings/installments

### Description
Updates the installment settings for the organization.

### Method
PUT

### Endpoint
/api/settings/installments

### Parameters
#### Request Body
- **installment** (object) - Optional. General installment settings.
  - **min_installment_amount** (number) - Optional. Minimum amount for an installment plan.
  - **exclude_coupons** (boolean) - Optional. Whether to exclude coupons from installment calculations.
  - **split_options** (array[object]) - Optional. List of available installment split options.
    - **num_of_installments** (integer) - Required. Number of installments.
    - **split_period** (string) - Optional. The period for each installment (e.g., MONTHLY, QUARTERLY).
- **payment_link_installment_settings** (object) - Optional. Installment settings specific to payment links.
  - **min_installment_amount** (number) - Optional. Minimum amount for an installment plan.
  - **exclude_coupons** (boolean) - Optional. Whether to exclude coupons from installment calculations.
  - **split_options** (array[object]) - Optional. List of available installment split options.
    - **num_of_installments** (integer) - Required. Number of installments.
    - **split_period** (string) - Optional. The period for each installment (e.g., MONTHLY, QUARTERLY).

### Request Example
```json
{
  "installment": {
    "min_installment_amount": 150,
    "split_options": [
      {"num_of_installments": 6, "split_period": "MONTHLY"}
    ]
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Installment settings updated successfully."
}
```
```

--------------------------------

### Handling Payment Redirects

Source: https://dev-docs.streampay.sa/docs/guides/getting-started

Stream redirects customers to your specified success or failure URLs with payment information as query parameters. Your server should parse these parameters to update your system.

```APIDOC
## Handling Payment Redirects

### Description
After checkout, Stream redirects the customer to your `success_redirect_url` or `failure_redirect_url` with payment information as query parameters. Your server can read these parameters to update your system accordingly.

### Redirect URL Examples

**Success redirect:**
```
https://example.com/success?id=...&invoice_id=...&status=paid&message=APPROVED
```

**Failure redirect:**
```
https://example.com/failure?payment_link_id=...&id=...&status=failed&message=...
```

### Query Parameters

All redirects include these parameters:

| Parameter         | Description                                                                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`              | Payment gateway payment ID - for internal use only. Useful for debugging when contacting support, but cannot be used in Stream APIs. Use `payment_id` or `invoice_id` instead. |
| `payment_link_id` | UUID of the payment link that was used                                                                                                                                         |
| `status`          | Payment status: `paid`, `failed`, or `pending`                                                                                                                                 |
| `message`         | Status message from the gateway (e.g., `APPROVED`, `DECLINED`, `The customer’s bank has declined.`)                                                                            |
| `login_method`    | Consumer's preferred login method: `PHONE` or `EMAIL`                                                                                                                          |

**Additional parameters on success only:**

| Parameter                  | Description                                                                                            |
| -------------------------- | ------------------------------------------------------------------------------------------------------ |
| `invoice_id`               | UUID of the invoice created from the payment link                                                      |
| `consent_id`               | UUID of the payment consent/authorization                                                              |
| `payment_id`               | UUID of the payment record in Stream's system                                                          |
| `organization_consumer_id` | UUID of the customer who made the payment (newly created if not set when the payment link was created) |

> **Note**: On failure, the additional parameters above are not included since the payment did not complete successfully.

### Processing the Redirect

Parse the query parameters from the redirect URL on your server. **Important:** Always validate the payment server-side before accepting the order or completing any business action. Fetch the invoice using the `invoice_id` from the redirect with the [Invoice API](/api/v2-invoices-get), and verify its status, amount, and currency match your expectations. This server-side verification ensures the payment is legitimate before updating your system state. Never trust redirect parameters alone, always verify through our API.
```

--------------------------------

### Payment Link Creation Response

Source: https://dev-docs.streampay.sa/docs/guides/getting-started

The API returns a payment link object upon successful creation. The 'url' field is crucial for redirecting customers to complete the payment.

```APIDOC
## POST /api/v2/payment-links

### Description
Creates a new payment link for a customer.

### Method
POST

### Endpoint
/api/v2/payment-links

### Request Body
(Details not provided in the input text, refer to API Reference)

### Response
#### Success Response (200 or 201)
- **url** (string) - The URL to redirect the customer to for payment.
- **id** (string) - The unique identifier for the payment link.
- **status** (string) - The current status of the payment link (e.g., "ACTIVE").
- **amount** (string) - The payment amount.
- **currency** (string) - The currency of the payment.

#### Response Example
```json
{
  "url": "https://checkout.streampay.sa/pay/...",
  "id": "payment-link-uuid",
  "status": "ACTIVE",
  "amount": "2500.00",
  "currency": "SAR"
}
```

> **Note**: The full response includes additional fields like `items`, `custom_metadata`, `success_redirect_url`, and more. See the [API Reference](/api/v2-payment-links-create) for the complete response schema.
```