### Install flittpayments via pip

Source: https://github.com/flittpayments/python/blob/main/README.md

Use this command to install the library in your Python environment.

```bash
pip install flittpayments
```

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

### Initiate PCI-DSS Direct Card Payment (Step 1)

Source: https://context7.com/flittpayments/python/llms.txt

Start a direct card payment for PCI-DSS compliant merchants. Completes payment for non-3DS cards or returns redirect data for 3DS authentication.

```python
from flittpayments import Api, Pcidss

api = Api(merchant_id=1549901, secret_key='test')
pcidss = Pcidss(api=api)

# Direct card payment (requires PCI-DSS compliance)
data = {
    "currency": "GEL",
    "amount": 100,
    "card_number": "4444555511116666",
    "cvv2": "123",
    "expiry_date": "1225",  # Format: MMYY
    "order_desc": "Direct card payment",
    "preauth": "N",         # Set to 'Y' for pre-authorization
    "required_rectoken": "N"  # Set to 'Y' to get recurring token
}
response = pcidss.step_one(data)

if response.get('order_status') == 'approved':
    # Non-3DS card - payment completed
    print(f"Payment approved! Order ID: {pcidss.order_id}")
elif 'acs_url' in response:
    # 3DS card - redirect customer for authentication
    acs_url = response.get('acs_url')
    pareq = response.get('pareq')
    md = response.get('md')
    print(f"Redirect to 3DS: {acs_url}")
    # POST pareq and md to acs_url, then handle callback with step_two
```

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

### Get Transaction History

Source: https://context7.com/flittpayments/python/llms.txt

Fetches all transactions associated with a specific order, including captures and reversals.

```python
from flittpayments import Api, Order

api = Api(merchant_id=1549901, secret_key='test')
order = Order(api=api)

data = {
    "order_id": "order_12345"
}
response = order.transaction_list(data)

for transaction in response:
    print(f"Type: {transaction.get('tran_type')}, Amount: {transaction.get('amount')}")
```

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

### Payment.reports - Get Payment Reports

Source: https://context7.com/flittpayments/python/llms.txt

Retrieves payment transaction reports for a specified date range. Useful for reconciliation and accounting purposes.

```APIDOC
## GET /payment/reports

### Description
Retrieves payment transaction reports for a specified date range. Useful for reconciliation and accounting purposes.

### Method
GET

### Endpoint
/payment/reports

### Parameters
#### Query Parameters
- **date_from** (string) - Required - The start date and time for the report. Format: 'DD.MM.YYYY HH:MM:SS'.
- **date_to** (string) - Required - The end date and time for the report. Format: 'DD.MM.YYYY HH:MM:SS'.

### Request Example
```
GET /payment/reports?date_from=01.01.2023%2000:00:00&date_to=07.01.2023%2023:59:59
```

### Response
#### Success Response (200)
- A list of transaction objects, each containing details like 'order_id', 'amount', 'currency', etc.

#### Response Example
```json
[
  {
    "order_id": "some_uuid_1",
    "amount": 10000,
    "currency": "USD",
    "transaction_date": "02.01.2023 10:30:00"
  },
  {
    "order_id": "some_uuid_2",
    "amount": 5000,
    "currency": "USD",
    "transaction_date": "05.01.2023 15:00:00"
  }
]
```
```

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

### Initialize API and create checkout URL

Source: https://github.com/flittpayments/python/blob/main/README.md

Configure the API client with credentials and generate a checkout URL for a payment request.

```python
from flittpayments import Api, Checkout
api = Api(merchant_id=1549901,
          secret_key='test')
checkout = Checkout(api=api)
data = {
    "currency": "USD",
    "amount": 10000
}
url = checkout.url(data).get('checkout_url')
```

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

### Initialize API Client

Source: https://context7.com/flittpayments/python/llms.txt

The Api class is required for all SDK operations. Credentials can be passed directly or via environment variables.

```python
from flittpayments import Api

# Basic initialization with merchant credentials
api = Api(
    merchant_id=1549901,
    secret_key='your_secret_key'
)

# Advanced initialization with custom settings
api = Api(
    merchant_id=1549901,
    secret_key='your_secret_key',
    request_type='json',       # Options: 'json', 'xml', 'form'
    api_protocol='2.0',        # Options: '1.0', '2.0' (2.0 requires json)
    api_domain='pay.flitt.com' # Custom API domain if needed
)

# Environment variable support (fallback)
# Set CLOUDIPSP_MERCHANT_ID and CLOUDIPSP_SECRETKEY environment variables
import os
os.environ['CLOUDIPSP_MERCHANT_ID'] = '1549901'
os.environ['CLOUDIPSP_SECRETKEY'] = 'your_secret_key'
api = Api()  # Will use environment variables if no args provided
```

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

### Create a Subscription

Source: https://context7.com/flittpayments/python/llms.txt

Initializes a subscription using protocol 2.0. Requires the recurring_data dictionary to define frequency and payment details.

```python
api = Api(merchant_id=1549901, secret_key='test', api_protocol='2.0')
checkout = Checkout(api=api)

data = {
    "currency": "USD",
    "amount": 10000,  # Initial payment amount (100.00 USD)
    "recurring_data": {
        "start_time": "2024-12-01",  # Format: YYYY-MM-DD
        "amount": 10000,              # Recurring payment amount
        "every": 1,                   # Frequency interval
        "period": "month",            # Options: 'day', 'week', 'month'
        "readonly": "y",              # Prevent user modification: 'y' or 'n'
        "state": "y"                  # Default subscription state: 'y' or 'n'
    }
}
response = checkout.subscription(data)
```

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

### Run tests with tox

Source: https://github.com/flittpayments/python/blob/main/README.md

Execute the test suite across all supported Python versions using tox.

```bash
tox
```

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

### Pcidss.step_one - PCI-DSS Direct Card Payment (Step 1)

Source: https://context7.com/flittpayments/python/llms.txt

Initiates a direct card payment for PCI-DSS compliant merchants. For non-3DS cards, this completes the payment. For 3DS cards, it returns redirect data for authentication.

```APIDOC
## POST /pcidss/step_one

### Description
Initiates a direct card payment for PCI-DSS compliant merchants. For non-3DS cards, this completes the payment. For 3DS cards, it returns redirect data for authentication.

### Method
POST

### Endpoint
/pcidss/step_one

### Parameters
#### Request Body
- **currency** (string) - Required - The currency of the transaction (e.g., 'GEL').
- **amount** (integer) - Required - The amount to charge.
- **card_number** (string) - Required - The customer's card number.
- **cvv2** (string) - Required - The CVV2 security code from the card.
- **expiry_date** (string) - Required - The card's expiry date in MMYY format (e.g., '1225').
- **order_desc** (string) - Optional - Description of the order.
- **preauth** (string) - Optional - Set to 'Y' for pre-authorization, 'N' otherwise. Defaults to 'N'.
- **required_rectoken** (string) - Optional - Set to 'Y' to obtain a recurring token, 'N' otherwise. Defaults to 'N'.

### Request Example
```json
{
    "currency": "GEL",
    "amount": 100,
    "card_number": "4444555511116666",
    "cvv2": "123",
    "expiry_date": "1225",
    "order_desc": "Direct card payment",
    "preauth": "N",
    "required_rectoken": "N"
}
```

### Response
#### Success Response (200)
- If non-3DS card: `order_status` will be 'approved'.
- If 3DS card: Returns `acs_url`, `pareq`, and `md` for redirection.

#### Response Example (Non-3DS)
```json
{
  "response_status": "success",
  "order_status": "approved",
  "order_id": "some_uuid"
}
```

#### Response Example (3DS)
```json
{
  "response_status": "success",
  "acs_url": "https://3ds.example.com/auth",
  "pareq": "some_pareq_data",
  "md": "some_md_data"
}
```
```

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

### Complete 3DS Authentication Step Two

Source: https://context7.com/flittpayments/python/llms.txt

Finalize the 3DS authentication process by submitting the PaRes and merchant data received from the callback.

```python
data = {
    "order_id": "order_from_step_one",
    "pares": "eJzVWFmTqkgW...",  # PaRes from 3DS callback
    "md": "merchant_data_from_step_one"
}
response = pcidss.step_two(data)
```

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

### Complete PCI-DSS 3D Secure Payment (Step 2)

Source: https://context7.com/flittpayments/python/llms.txt

Finalize a 3D Secure authenticated payment after the customer returns from the bank's authentication page.

```python
from flittpayments import Api, Pcidss

api = Api(merchant_id=1549901, secret_key='test')
pcidss = Pcidss(api=api)


```

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

### POST /order/reverse

Source: https://context7.com/flittpayments/python/llms.txt

Processes a refund or reversal for an existing order.

```APIDOC
## POST /order/reverse

### Description
Processes a refund or reversal for an existing order, either full or partial.

### Method
POST

### Request Body
- **order_id** (string) - Required - The ID of the order to reverse
- **amount** (integer) - Required - Amount to reverse
- **currency** (string) - Required - Currency code
```

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

### Create Subscription Payment

Source: https://context7.com/flittpayments/python/llms.txt

Generate a checkout URL for creating subscription payments. This method requires API protocol version 2.0 and allows for automatic, scheduled payments.

```APIDOC
## Checkout.subscription - Create Subscription Payment

### Description
The `Checkout.subscription()` method generates a checkout URL that facilitates the creation of subscription payment plans. This feature requires API protocol version 2.0 and enables automatic, scheduled payments based on a defined calendar.

### Method
`checkout.subscription(data)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **currency** (string) - Required - The currency code for the subscription payments (e.g., 'USD', 'GEL').
- **amount** (integer) - Required - The amount for each subscription payment in the smallest currency unit.
- **subscription_data** (object) - Required - Contains details about the subscription schedule.
  - **start_date** (string) - Required - The date when the subscription starts (YYYY-MM-DD).
  - **end_date** (string) - Optional - The date when the subscription ends (YYYY-MM-DD).
  - **interval** (string) - Required - The frequency of payments (e.g., 'day', 'week', 'month', 'year').
  - **period** (integer) - Required - The number of intervals between payments (e.g., '1' for every month, '2' for every two months).
  - **max_amount** (integer) - Optional - The maximum amount that can be charged for a subscription payment.
- **order_id** (string) - Optional - A unique identifier for the initial order.
- **order_desc** (string) - Optional - A description of the order.
- **response_url** (string) - Optional - The URL to redirect the customer to after the initial payment setup.
- **server_callback_url** (string) - Optional - A URL for receiving server-to-server notifications about transaction status.

### Request Example
```python
from flittpayments import Api, Checkout

api = Api(merchant_id=1549901, secret_key='test', api_protocol='2.0') # Requires API protocol 2.0
checkout = Checkout(api=api)

data = {
    "currency": "GEL",
    "amount": 500,
    "order_id": "sub_order_001",
    "order_desc": "Monthly Subscription",
    "response_url": "https://yoursite.com/callback",
    "server_callback_url": "https://yoursite.com/webhook",
    "subscription_data": {
        "start_date": "2024-08-01",
        "end_date": "2025-07-31",
        "interval": "month",
        "period": 1,
        "max_amount": 600
    }
}
response = checkout.subscription(data)
subscription_url = response.get('checkout_url')
# Response: {'response_status': 'success', 'checkout_url': 'https://...'}
```

### Response
#### Success Response (200)
- **response_status** (string) - Indicates the status of the operation ('success' or 'error').
- **checkout_url** (string) - The URL for setting up the subscription.
- **order_id** (string) - The order ID associated with the initial subscription setup.

#### Response Example
```json
{
  "response_status": "success",
  "checkout_url": "https://pay.flitt.com/subscription/setup/def456ghi789jkl"
}
```
```

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

### Pcidss.step_two - PCI-DSS 3D Secure Completion (Step 2)

Source: https://context7.com/flittpayments/python/llms.txt

Completes a 3D Secure authenticated payment after the customer returns from the bank's authentication page.

```APIDOC
## POST /pcidss/step_two

### Description
Completes a 3D Secure authenticated payment after the customer returns from the bank's authentication page. This endpoint is used in conjunction with the redirect data obtained from `Pcidss.step_one` for 3D Secure transactions.

### Method
POST

### Endpoint
/pcidss/step_two

### Parameters
#### Request Body
- **pa_res** (string) - Required - The response from the 3D Secure authentication process (often referred to as PaRes).
- **order_id** (string) - Required - The order ID generated during the `Pcidss.step_one` call.

### Request Example
```json
{
    "pa_res": "some_pares_data_from_bank",
    "order_id": "some_uuid_from_step_one"
}
```

### Response
#### Success Response (200)
- **response_status** (string) - Status of the response (e.g., 'success').
- **order_status** (string) - Status of the order (e.g., 'approved').
- **order_id** (string) - The unique identifier for the order.

#### Response Example
```json
{
  "response_status": "success",
  "order_status": "approved",
  "order_id": "some_uuid_from_step_one"
}
```
```

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

### POST /checkout/subscription

Source: https://context7.com/flittpayments/python/llms.txt

Creates a new recurring subscription. Requires API protocol 2.0.

```APIDOC
## POST /checkout/subscription

### Description
Creates a new recurring subscription for a customer.

### Method
POST

### Request Body
- **currency** (string) - Required - Currency code (e.g., USD)
- **amount** (integer) - Required - Initial payment amount
- **recurring_data** (object) - Required - Subscription details
  - **start_time** (string) - Required - Start date in YYYY-MM-DD format
  - **amount** (integer) - Required - Recurring payment amount
  - **every** (integer) - Required - Frequency interval
  - **period** (string) - Required - Options: 'day', 'week', 'month'
  - **readonly** (string) - Optional - Prevent user modification: 'y' or 'n'
  - **state** (string) - Optional - Default subscription state: 'y' or 'n'
```

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

### Validate Callback Signature with helpers.is_valid

Source: https://context7.com/flittpayments/python/llms.txt

Verify the authenticity of payment callback data using a secret key to prevent tampering.

```python
from flittpayments import helpers

# Callback data received from Flitt webhook/callback
callback_data = {
    "order_id": "order_12345",
    "order_status": "approved",
    "amount": 10000,
    "currency": "USD",
    "signature": "a1b2c3d4e5f6..."  # Signature from callback
}

secret_key = "your_secret_key"
is_valid = helpers.is_valid(
    data=callback_data,
    secret_key=secret_key,
    protocol='1.0'  # Use '2.0' if using protocol 2.0
)

if is_valid:
    print("Callback signature verified - safe to process")
else:
    print("Invalid signature - potential tampering!")
```

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

### POST /order/status

Source: https://context7.com/flittpayments/python/llms.txt

Retrieves the current status and details of an existing order.

```APIDOC
## POST /order/status

### Description
Retrieves the current status and details of an existing order to verify payment completion.

### Method
POST

### Request Body
- **order_id** (string) - Required - The ID of the order to check
```

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

### POST /order/capture

Source: https://context7.com/flittpayments/python/llms.txt

Captures a previously pre-authorized payment.

```APIDOC
## POST /order/capture

### Description
Captures a previously pre-authorized payment.

### Method
POST

### Request Body
- **order_id** (string) - Required - The ID of the pre-authorized order
- **amount** (integer) - Required - Amount to capture
- **currency** (string) - Required - Currency code
```

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

### Perform Card Verification

Source: https://context7.com/flittpayments/python/llms.txt

Creates a checkout URL to verify card validity without processing a charge. Useful for pre-authorizing cards for future recurring payments.

```python
from flittpayments import Api, Checkout

api = Api(merchant_id=1549901, secret_key='test')
checkout = Checkout(api=api)

data = {
    "currency": "GEL",
    "amount": 100,
    "verification_type": "code"  # Options: 'code', 'amount'
}
response = checkout.verification(data)
verification_url = response.get('checkout_url')
# Response: {'response_status': 'success', 'checkout_url': 'https://...'}
```

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

### API Client Initialization

Source: https://context7.com/flittpayments/python/llms.txt

Initialize the Flitt Payments API client with merchant credentials. Supports basic and advanced configurations, including custom API endpoints and protocol versions. Environment variable support is also available.

```APIDOC
## API Client Initialization

### Description
Initialize the `Api` class with your merchant ID and secret key to establish a connection with the Flitt API. This class handles authentication, request signing, and communication.

### Method
`Api(merchant_id, secret_key, request_type='json', api_protocol='1.0', api_domain='pay.flitt.com')`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from flittpayments import Api

# Basic initialization
api = Api(merchant_id=1549901, secret_key='your_secret_key')

# Advanced initialization
api = Api(
    merchant_id=1549901,
    secret_key='your_secret_key',
    request_type='json',       # Options: 'json', 'xml', 'form'
    api_protocol='2.0',        # Options: '1.0', '2.0'
    api_domain='pay.flitt.com'
)

# Using environment variables (CLOUDIPSP_MERCHANT_ID, CLOUDIPSP_SECRETKEY)
import os
os.environ['CLOUDIPSP_MERCHANT_ID'] = '1549901'
os.environ['CLOUDIPSP_SECRETKEY'] = 'your_secret_key'
api = Api()
```

### Response
None (Initialization does not return a response, but prepares the API object for subsequent calls.)
```

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

### Capture Pre-Authorized Payment

Source: https://context7.com/flittpayments/python/llms.txt

Completes a charge for a previously held pre-authorized payment.

```python
from flittpayments import Api, Order

api = Api(merchant_id=1549901, secret_key='test')
order = Order(api=api)

data = {
    "order_id": "preauth_order_12345",
    "amount": 100,      # Amount to capture (can be less than preauth)
    "currency": "GEL"
}
response = order.capture(data)
```

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

### Validate and Check Approval with helpers.is_approved

Source: https://context7.com/flittpayments/python/llms.txt

Perform signature validation and payment status verification in a single operation.

```python
from flittpayments import helpers

callback_data = {
    "order_id": "order_12345",
    "order_status": "approved",
    "amount": 10000,
    "signature": "a1b2c3d4e5f6..."
}

try:
    is_approved = helpers.is_approved(
        data=callback_data,
        secret_key="your_secret_key",
        protocol='1.0'
    )
    if is_approved:
        # Safe to fulfill the order
        print("Payment approved and verified!")
except ValueError as e:
    print(f"Invalid callback data: {e}")
except Exception as e:
    print(f"Payment validation failed: {e}")
```

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

### Generate Checkout URL

Source: https://context7.com/flittpayments/python/llms.txt

Creates a hosted payment page URL for secure customer transactions. This method handles PCI compliance by offloading form rendering to Flitt.

```python
from flittpayments import Api, Checkout

api = Api(merchant_id=1549901, secret_key='test')
checkout = Checkout(api=api)

# Basic checkout URL generation
data = {
    "currency": "USD",
    "amount": 10000  # Amount in cents (100.00 USD)
}
response = checkout.url(data)
checkout_url = response.get('checkout_url')
# Response: {'response_status': 'success', 'checkout_url': 'https://pay.flitt.com/...'}

# Full checkout with all options
data = {
    "order_id": "order_12345",           # Optional: auto-generated if not provided
    "order_desc": "Payment for Order #12345",
    "currency": "GEL",
    "amount": 100,
    "response_url": "https://yoursite.com/callback",
    "server_callback_url": "https://yoursite.com/webhook"
}
response = checkout.url(data)
print(f"Redirect customer to: {response.get('checkout_url')}")
print(f"Order ID: {checkout.order_id}")
```

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

### Perform P2P Card Credit with Payment.p2pcredit

Source: https://context7.com/flittpayments/python/llms.txt

Send funds directly to a card for disbursements, refunds, or P2P transfers. May require special merchant credentials.

```python
from flittpayments import Api, Payment

# P2P credit may require special merchant credentials
api = Api(merchant_id=1000, secret_key='testcredit')
payment = Payment(api=api)

data = {
    "receiver_card_number": "4444555566661111",
    "currency": "GEL",
    "amount": 100,
    "order_desc": "Payout to customer"
}
response = payment.p2pcredit(data)
# Response: {
#   'response_status': 'success',
#   'order_status': 'approved'
# }
```

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

### Generate Checkout URL

Source: https://context7.com/flittpayments/python/llms.txt

Create a URL for a hosted payment page where customers can complete their payments. This method handles form rendering and PCI compliance.

```APIDOC
## Checkout.url - Generate Checkout URL

### Description
The `Checkout.url()` method generates a URL for a hosted payment page. Customers are redirected to this page to complete their payment, simplifying PCI compliance.

### Method
`checkout.url(data)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **currency** (string) - Required - The currency code for the transaction (e.g., 'USD', 'GEL').
- **amount** (integer) - Required - The transaction amount in the smallest currency unit (e.g., cents for USD, tetri for GEL).
- **order_id** (string) - Optional - A unique identifier for the order. If not provided, it will be auto-generated.
- **order_desc** (string) - Optional - A description of the order.
- **response_url** (string) - Optional - The URL to redirect the customer to after a successful or failed payment attempt.
- **server_callback_url** (string) - Optional - A URL for receiving server-to-server notifications about the transaction status.

### Request Example
```python
from flittpayments import Api, Checkout

api = Api(merchant_id=1549901, secret_key='test')
checkout = Checkout(api=api)

# Basic checkout URL generation
data = {
    "currency": "USD",
    "amount": 10000  # Amount in cents (100.00 USD)
}
response = checkout.url(data)
checkout_url = response.get('checkout_url')

# Full checkout with all options
data = {
    "order_id": "order_12345",
    "order_desc": "Payment for Order #12345",
    "currency": "GEL",
    "amount": 100,
    "response_url": "https://yoursite.com/callback",
    "server_callback_url": "https://yoursite.com/webhook"
}
response = checkout.url(data)
print(f"Redirect customer to: {response.get('checkout_url')}")
print(f"Order ID: {checkout.order_id}")
```

### Response
#### Success Response (200)
- **response_status** (string) - Indicates the status of the operation ('success' or 'error').
- **checkout_url** (string) - The URL for the hosted payment page.
- **order_id** (string) - The order ID associated with this transaction.

#### Response Example
```json
{
  "response_status": "success",
  "checkout_url": "https://pay.flitt.com/checkout/abcdef1234567890",
  "order_id": "order_12345"
}
```
```

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

### Create Split Payment with Order Settlement

Source: https://context7.com/flittpayments/python/llms.txt

Use Order.settlement() for marketplace payouts, distributing funds to multiple merchants. Requires API protocol 2.0.

```python
from flittpayments import Api, Order
import json

api = Api(merchant_id=1549901, secret_key='test', api_protocol='2.0')
order = Order(api=api)

data = {
    "operation_id": "original_order_12345",  # The captured order to split
    "order_type": "settlement",
    "receiver": [
        {
            "type": "merchant",
            "requisites": {
                "merchant_id": 600001,
                "amount": 500  # Amount for first merchant
            }
        },
        {
            "type": "merchant",
            "requisites": {
                "merchant_id": 700001,
                "amount": 500  # Amount for second merchant
            }
        }
    ],
    "amount": 1000,
    "currency": "GEL"
}
response = order.settlement(data)
response_data = json.loads(response.get('data'))
# response_data['order']['order_status'] == 'created'
```

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

### Refund or Reverse Order

Source: https://context7.com/flittpayments/python/llms.txt

Processes a full or partial refund for an existing order.

```python
from flittpayments import Api, Order

api = Api(merchant_id=1549901, secret_key='test')
order = Order(api=api)

data = {
    "order_id": "order_12345",
    "amount": 100,      # Amount to reverse
    "currency": "GEL"
}
response = order.reverse(data)
```

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

### Card Verification

Source: https://context7.com/flittpayments/python/llms.txt

Create a checkout URL specifically for card verification without charging the customer, useful for validating cards before future transactions.

```APIDOC
## Checkout.verification - Card Verification

### Description
The `Checkout.verification()` method generates a checkout URL for performing card verification without an actual charge. This is commonly used to validate card details before storing them for recurring payments or other purposes.

### Method
`checkout.verification(data)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **currency** (string) - Required - The currency code for the verification transaction (e.g., 'USD', 'GEL').
- **amount** (integer) - Required - The amount for the verification. This can be a small fixed amount or zero, depending on the `verification_type`.
- **verification_type** (string) - Required - Specifies the type of verification. Options: 'code' (requires a small amount for authorization) or 'amount' (requires a specific amount for authorization).

### Request Example
```python
from flittpayments import Api, Checkout

api = Api(merchant_id=1549901, secret_key='test')
checkout = Checkout(api=api)

data = {
    "currency": "GEL",
    "amount": 100,
    "verification_type": "code"  # Options: 'code', 'amount'
}
response = checkout.verification(data)
verification_url = response.get('checkout_url')
# Response: {'response_status': 'success', 'checkout_url': 'https://...'}
```

### Response
#### Success Response (200)
- **response_status** (string) - Indicates the status of the operation ('success' or 'error').
- **checkout_url** (string) - The URL for the card verification page.

#### Response Example
```json
{
  "response_status": "success",
  "checkout_url": "https://pay.flitt.com/verification/xyz789abc123def"
}
```
```

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

### Process Recurring Payment with Payment.recurring

Source: https://context7.com/flittpayments/python/llms.txt

Charge a customer using a previously obtained recurring token (rectoken) for subscriptions or saved card payments.

```python
from flittpayments import Api, Payment

api = Api(merchant_id=1549901, secret_key='test')
payment = Payment(api=api)

# Use the rectoken obtained from a previous payment with required_rectoken='Y'
data = {
    "rectoken": "eyJhbGciOiJIUzI1NiIs...",  # Recurring token from initial payment
    "currency": "GEL",
    "amount": 100,
    "order_desc": "Monthly subscription"
}
response = payment.recurring(data)
# Response: {
#   'response_status': 'success',
#   'order_status': 'approved',
#   'order_id': 'auto_generated_uuid'
# }
```

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

### Retrieve Payment Reports with Payment.reports

Source: https://context7.com/flittpayments/python/llms.txt

Fetch payment transaction reports for a specified date range, useful for reconciliation. Ensure correct date format (DD.MM.YYYY HH:MM:SS).

```python
from flittpayments import Api, Payment
from datetime import datetime, timedelta

api = Api(merchant_id=1549901, secret_key='test')
payment = Payment(api=api)

# Date format: DD.MM.YYYY HH:MM:SS
data = {
    "date_from": (datetime.now() - timedelta(days=7)).strftime('%d.%m.%Y %H:%M:%S'),
    "date_to": datetime.now().strftime('%d.%m.%Y %H:%M:%S')
}
response = payment.reports(data)
# Response is a list of transactions within the date range
# [{'order_id': '...', 'amount': 10000, 'currency': 'USD', ...}, ...]

for transaction in response:
    print(f"Order: {transaction.get('order_id')}, Amount: {transaction.get('amount')}")
```

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

### Order.settlement - Create Split Payment

Source: https://context7.com/flittpayments/python/llms.txt

Creates a split payment (marketplace payout) distributing funds to multiple merchants. Requires API protocol 2.0.

```APIDOC
## POST /order/settlement

### Description
Creates a split payment (marketplace payout) distributing funds to multiple merchants. Requires API protocol 2.0. This is useful for marketplace scenarios where payment needs to be split among sellers.

### Method
POST

### Endpoint
/order/settlement

### Parameters
#### Request Body
- **operation_id** (string) - Required - The captured order to split
- **order_type** (string) - Required - Must be 'settlement'
- **receiver** (array) - Required - List of receivers for the split payment
  - **type** (string) - Required - Type of receiver, e.g., 'merchant'
  - **requisites** (object) - Required - Receiver specific details
    - **merchant_id** (integer) - Required - The ID of the merchant receiving funds
    - **amount** (integer) - Required - The amount to be paid to the merchant
- **amount** (integer) - Required - The total amount to be split
- **currency** (string) - Required - The currency of the transaction (e.g., 'GEL')

### Request Example
```json
{
    "operation_id": "original_order_12345",
    "order_type": "settlement",
    "receiver": [
        {
            "type": "merchant",
            "requisites": {
                "merchant_id": 600001,
                "amount": 500
            }
        },
        {
            "type": "merchant",
            "requisites": {
                "merchant_id": 700001,
                "amount": 500
            }
        }
    ],
    "amount": 1000,
    "currency": "GEL"
}
```

### Response
#### Success Response (200)
- **data** (string) - JSON string containing order details, including 'order_status'.

#### Response Example
```json
{
  "response_status": "success",
  "data": "{\"order\": {\"order_id\": \"some_uuid\", \"order_status\": \"created\"}}"
}
```
```

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

### POST /order/transaction_list

Source: https://context7.com/flittpayments/python/llms.txt

Retrieves all transactions associated with an order.

```APIDOC
## POST /order/transaction_list

### Description
Retrieves all transactions associated with an order, including original payments, captures, and reversals.

### Method
POST

### Request Body
- **order_id** (string) - Required - The ID of the order
```

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

### Handle API Exceptions

Source: https://context7.com/flittpayments/python/llms.txt

Implement robust error handling for various API failure scenarios including request, response, and service errors.

```python
from flittpayments import Api, Checkout
from flittpayments.exceptions import RequestError, ResponseError, ServiceError

api = Api(merchant_id=1549901, secret_key='test')
checkout = Checkout(api=api)

try:
    data = {
        "currency": "USD",
        "amount": 10000
    }
    response = checkout.url(data)
    print(f"Checkout URL: {response.get('checkout_url')}")

except RequestError as e:
    # Missing required parameter
    print(f"Missing parameter: {e}")
    # Output: "Required parameter 'currency' is missing."

except ResponseError as e:
    # API returned an error response
    print(f"API Error: {e}")
    # Output: "Response status is failure. Error message: Invalid amount. Error code: 1001..."

except ServiceError as e:
    # HTTP error (non-200/201 response)
    print(f"Service Error: {e}")
    # Output: "Response code is: 500"

except ValueError as e:
    # Validation error (invalid amount, date format, etc.)
    print(f"Validation Error: {e}")
```

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

### Generate Checkout Token

Source: https://context7.com/flittpayments/python/llms.txt

Generates a token for embedding the Flitt payment widget directly into a frontend application. This approach provides a seamless user experience while maintaining PCI compliance.

```python
from flittpayments import Api, Checkout

api = Api(merchant_id=1549901, secret_key='test')
checkout = Checkout(api=api)

data = {
    "currency": "GEL",
    "amount": 100,
    "order_desc": "Widget Payment"
}
response = checkout.token(data)
token = response.get('token')
# Response: {'response_status': 'success', 'token': 'eyJhbGciOiJIUzI1NiIs...'}

# Use this token in your frontend JavaScript:
# <script src="https://pay.flitt.com/latest/checkout.js"></script>
# fondy('#checkout-container', { token: 'your_token_here' });
```

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

### Check Order Status

Source: https://context7.com/flittpayments/python/llms.txt

Retrieves the current status of an order to verify payment completion or transaction state.

```python
from flittpayments import Api, Order

api = Api(merchant_id=1549901, secret_key='test')
order = Order(api=api)

data = {
    "order_id": "order_12345"
}
response = order.status(data)

if response.get('order_status') == 'approved':
    print("Payment successful!")
else:
    print(f"Payment status: {response.get('order_status')}")
```

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

### Payment.p2pcredit - P2P Card Credit

Source: https://context7.com/flittpayments/python/llms.txt

Sends funds directly to a card (card credit/payout). This is used for disbursements, refunds to external cards, or P2P transfers.

```APIDOC
## POST /payment/p2pcredit

### Description
Sends funds directly to a card (card credit/payout). This is used for disbursements, refunds to external cards, or P2P transfers. P2P credit may require special merchant credentials.

### Method
POST

### Endpoint
/payment/p2pcredit

### Parameters
#### Request Body
- **receiver_card_number** (string) - Required - The 16-digit card number of the recipient.
- **currency** (string) - Required - The currency of the transaction (e.g., 'GEL').
- **amount** (integer) - Required - The amount to send.
- **order_desc** (string) - Optional - Description of the order.

### Request Example
```json
{
    "receiver_card_number": "4444555566661111",
    "currency": "GEL",
    "amount": 100,
    "order_desc": "Payout to customer"
}
```

### Response
#### Success Response (200)
- **response_status** (string) - Status of the response (e.g., 'success').
- **order_status** (string) - Status of the order (e.g., 'approved').

#### Response Example
```json
{
  "response_status": "success",
  "order_status": "approved"
}
```
```

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

### Generate Checkout Token

Source: https://context7.com/flittpayments/python/llms.txt

Generate a payment token for embedding the Flitt payment widget directly into your web page using JavaScript, offering a seamless checkout experience.

```APIDOC
## Checkout.token - Generate Checkout Token

### Description
The `Checkout.token()` method generates a payment token that can be used with the Flitt JavaScript widget to embed the payment form directly into your website, enhancing user experience while maintaining PCI compliance.

### Method
`checkout.token(data)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **currency** (string) - Required - The currency code for the transaction (e.g., 'USD', 'GEL').
- **amount** (integer) - Required - The transaction amount in the smallest currency unit (e.g., cents for USD, tetri for GEL).
- **order_desc** (string) - Optional - A description of the order.

### Request Example
```python
from flittpayments import Api, Checkout

api = Api(merchant_id=1549901, secret_key='test')
checkout = Checkout(api=api)

data = {
    "currency": "GEL",
    "amount": 100,
    "order_desc": "Widget Payment"
}
response = checkout.token(data)
token = response.get('token')

# Use this token in your frontend JavaScript:
# <script src="https://pay.flitt.com/latest/checkout.js"></script>
# <div id="checkout-container"></div>
# <script>
#   Fondy.checkout('#checkout-container', { token: 'your_token_here' });
# </script>
```

### Response
#### Success Response (200)
- **response_status** (string) - Indicates the status of the operation ('success' or 'error').
- **token** (string) - The generated payment token for the JavaScript widget.

#### Response Example
```json
{
  "response_status": "success",
  "token": "eyJhbGciOiJIUzI1NiIsImtpZCI6IjIwMjQwNzE3MTQ1MzQ1IiwidHlwIjoiSldUIn0.eyJpbnN0YW5jZV9pZCI6IjEyMzQ1Njc4OSIsInRva2VuIjoiYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU2Nzg5IiwibWVyY2hhbnRfaWQiOjE1NDk5MDEsImN1cnJlbmN5IjoiR0VMIiwiYW1vdW50IjoxMDAsIm9yZGVyX2lkIjoiYmFzaWNfdG9rZW4iLCJvcmRlcl9kZXNjIjoiV2lkZ2V0IFBheW1lbnQiLCJleHBpcmVzX2F0IjoxNzIxNzM1MjAwfQ.exampleSignature"
}
```
```

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

### Payment.recurring - Process Recurring Payment

Source: https://context7.com/flittpayments/python/llms.txt

Charges a customer using a previously obtained recurring token (rectoken). Use this for subscription billing or saved card payments.

```APIDOC
## POST /payment/recurring

### Description
Charges a customer using a previously obtained recurring token (rectoken). Use this for subscription billing or saved card payments.

### Method
POST

### Endpoint
/payment/recurring

### Parameters
#### Request Body
- **rectoken** (string) - Required - Recurring token obtained from an initial payment where `required_rectoken` was set to 'Y'.
- **currency** (string) - Required - The currency of the transaction (e.g., 'GEL').
- **amount** (integer) - Required - The amount to charge.
- **order_desc** (string) - Optional - Description of the order.

### Request Example
```json
{
    "rectoken": "eyJhbGciOiJIUzI1NiIs...",
    "currency": "GEL",
    "amount": 100,
    "order_desc": "Monthly subscription"
}
```

### Response
#### Success Response (200)
- **response_status** (string) - Status of the response (e.g., 'success').
- **order_status** (string) - Status of the order (e.g., 'approved').
- **order_id** (string) - The unique identifier for the order.

#### Response Example
```json
{
  "response_status": "success",
  "order_status": "approved",
  "order_id": "auto_generated_uuid"
}
```
```

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

### Stop a Subscription

Source: https://context7.com/flittpayments/python/llms.txt

Terminates an active recurring subscription by its order ID. This method requires API protocol 2.0.

```python
from flittpayments import Api, Checkout

api = Api(merchant_id=1549901, secret_key='test', api_protocol='2.0')
checkout = Checkout(api=api)

# Stop recurring payments for an order
order_id = "subscription_order_12345"
response = checkout.subscription_stop(order_id)
```

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

### POST /checkout/subscription_stop

Source: https://context7.com/flittpayments/python/llms.txt

Stops an active recurring subscription by order ID.

```APIDOC
## POST /checkout/subscription_stop

### Description
Stops an active recurring subscription by order ID. Requires API protocol 2.0.

### Method
POST

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The ID of the subscription order to stop
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.