### Install IntaSend Python SDK

Source: https://github.com/intasend/intasend-python/blob/master/README.md

Use pip to install the IntaSend Python SDK. This is the first step to integrating IntaSend services.

```bash
pip install intasend-python
```

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

### Install and Authenticate IntaSend SDK

Source: https://context7.com/intasend/intasend-python/llms.txt

Install the SDK using pip. Initialize APIService with your API token and publishable key. Use `test=True` for the sandbox environment.

```python
# Install
# pip install intasend-python

import os
from intasend import APIService
from intasend.exceptions import (
    IntaSendBadRequest,
    IntaSendUnauthorized,
    IntaSendNotAllowed,
    IntaSendServerError,
)

API_TOKEN = os.environ["INTASEND_API_TOKEN"]
PUBLISHABLE_KEY = os.environ["INTASEND_PUBLISHABLE_KEY"]

# Sandbox (test) client
service = APIService(
    token=API_TOKEN,
    publishable_key=PUBLISHABLE_KEY,
    test=True,   # Remove or set False for production
)
```

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

### Error Handling Example

Source: https://context7.com/intasend/intasend-python/llms.txt

Demonstrates how to handle API errors using try-except blocks with specific IntaSend exception types.

```APIDOC
## Error Handling

All API methods raise typed exceptions corresponding to HTTP status codes. Wrap calls in try/except blocks to handle failures gracefully.

```python
from intasend import APIService
from intasend.exceptions import (
    IntaSendBadRequest,
    IntaSendUnauthorized,
    IntaSendNotAllowed,
    IntaSendServerError,
)

service = APIService(token="bad-token", publishable_key="bad-key", test=True)

try:
    response = service.collect.mpesa_stk_push(
        phone_number=254712345678,
        email="user@example.com",
        amount=100,
        narrative="Test",
    )
except IntaSendUnauthorized:
    print("Authentication failed — check your API token.")
except IntaSendBadRequest as e:
    print(f"Request validation error: {e}")
except IntaSendNotAllowed as e:
    print(f"Permission denied: {e}")
except IntaSendServerError as e:
    print(f"IntaSend server error, retry later: {e}")
```
```

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

### List and Retrieve Wallets

Source: https://context7.com/intasend/intasend-python/llms.txt

Lists all wallets on the account. Pass a wallet_id to get a single wallet's details.

```python
# List all wallets
all_wallets = service.wallets.retrieve()
print(all_wallets)
# Expected: {'results': [{'wallet_id': 'ZQMMOQO', 'currency': 'KES', 'current_balance': '5000.00', ...}]}

# Fetch a specific wallet
wallet = service.wallets.retrieve(wallet_id="ZQMMOQO")
# or equivalently:
wallet = service.wallets.details("ZQMMOQO")
print(wallet)
```

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

### Get Specific Wallet Details

Source: https://github.com/intasend/intasend-python/blob/master/README.md

Retrieve detailed information about a specific wallet using its unique wallet ID.

```python
response = service.wallets.details(<WALLET-ID>)
print(response)
```

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

### Get Amount Estimate (Quote)

Source: https://context7.com/intasend/intasend-python/llms.txt

Use `service.collect.get_quote()` to retrieve fee breakdowns for a specified amount, method, and tariff before initiating a transaction. This helps in estimating transaction costs.

```python
response = service.collect.get_quote(
    amount=1000,
    method="M-PESA",       # or "CARD-PAYMENT"
    currency="KES",
    tarrif="BUSINESS-PAYS",
)
print(response)
# Expected: {'amount': '1000.00', 'fee': '22.00', 'total': '1000.00', ...}
```

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

### Collect — Get Amount Estimate (Quote)

Source: https://context7.com/intasend/intasend-python/llms.txt

Returns a fee breakdown for a given amount, method, and tariff configuration before initiating a transaction.

```APIDOC
## Collect - Get Amount Estimate (Quote)

### Description
`service.collect.get_quote()` returns the fee breakdown for a given amount, method, and tariff configuration before initiating a transaction.

### Method
`GET` (Implied by the SDK method call)

### Endpoint
`/v1/collect/quote` (Implied by the SDK method call)

### Parameters
#### Query Parameters
- **amount** (number) - Required - The transaction amount.
- **method** (string) - Required - The payment method (e.g., "M-PESA", "CARD-PAYMENT").
- **currency** (string) - Required - The currency code (e.g., KES).
- **tarrif** (string) - Required - The tariff configuration (e.g., "BUSINESS-PAYS").

### Request Example
```python
response = service.collect.get_quote(
    amount=1000,
    method="M-PESA",       # or "CARD-PAYMENT"
    currency="KES",
    tarrif="BUSINESS-PAYS",
)
print(response)
```

### Response
#### Success Response (200)
- **amount** (string) - The base amount.
- **fee** (string) - The calculated transaction fee.
- **total** (string) - The total amount including fees.
- ... (other fee breakdown details)

#### Response Example
```json
{
  "amount": "1000.00",
  "fee": "22.00",
  "total": "1000.00",
  ...
}
```
```

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

### Get Payment Status by Invoice ID

Source: https://github.com/intasend/intasend-python/blob/master/README.md

Retrieve the status of a payment using its unique invoice ID. This is useful for tracking transaction progress.

```python
response = service.collect.status(invoice_id="NR5XKGY")
print(response)
```

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

### Get Transfer Status

Source: https://github.com/intasend/intasend-python/blob/master/README.md

Check the status of a money transfer using its tracking ID. This is crucial for monitoring the progress of outgoing transactions.

```python
status = service.transfer.status(response.get("tracking_id"))
print(f"Status: {status}")
```

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

### Authenticate IntaSend APIService

Source: https://github.com/intasend/intasend-python/blob/master/README.md

Initialize the APIService with your API token and publishable key. Ensure you use your actual credentials.

```python
from intasend import APIService

token = "YOUR-API-TOKEN"
publishable_key = "YOUR-PUBLISHABLE-KEY"
service = APIService(token="token",publishable_key=publishable_key)
```

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

### Create a New Wallet

Source: https://github.com/intasend/intasend-python/blob/master/README.md

Create a new wallet with specified currency, label, and disbursement permissions. Useful for organizing funds or specific payment flows.

```python
response = service.wallets.create(currency="KES", label="API-WALLET", can_disburse=True)
print(response)
```

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

### Create a Wallet

Source: https://context7.com/intasend/intasend-python/llms.txt

Provisions a new working wallet on the account. Set can_disburse=True to allow outgoing transfers from this wallet.

```python
new_wallet = service.wallets.create(
    currency="KES",
    label="Operations-Wallet",
    can_disburse=True,
)
print(new_wallet)
# Expected: {'wallet_id': 'NEWWLT1', 'currency': 'KES', 'label': 'Operations-Wallet', ...}
```

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

### Create and Retrieve Payment Links

Source: https://context7.com/intasend/intasend-python/llms.txt

Generates reusable payment links with `create()` and retrieves them with `retrieve()`. Set `amount=0` for open-amount links. Requires title, currency, and optionally amount and tariff details.

```python
import secrets

# Create a fixed-amount payment link
link = service.payment_links.create(
    title=f"Product Purchase - {secrets.token_hex(4)}",
    currency="KES",
    amount=2500,
    mobile_tarrif="BUSINESS-PAYS",
    card_tarrif="CUSTOMER-PAYS",
    is_active=True,
)
print(link)
# Expected: {'id': 'LNK001', 'url': 'https://payment.intasend.com/pay/LNK001/', ...}
```

```python
# Create an open-amount donation link
donation_link = service.payment_links.create(
    title="Charity Donation",
    currency="KES",
    amount=0,      # Customer enters their own amount
)
print(donation_link["url"])
```

```python
# List all payment links
all_links = service.payment_links.retrieve()
print(all_links)
```

```python
# Fetch a specific link
link_detail = service.payment_links.retrieve(link_id="LNK001")
print(link_detail)
```

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

### Create and Retrieve Chargebacks

Source: https://context7.com/intasend/intasend-python/llms.txt

Opens a dispute for a completed invoice using `create()` or fetches chargebacks using `retrieve()`. `create()` requires invoice ID, amount, and reason. `retrieve()` can fetch all or a specific chargeback by ID.

```python
# Create a chargeback
cb = service.chargebacks.create(
    invoice="NR5XKGY",
    amount=500,
    reason="DISPUTED",
    reason_details="Customer claims item was not delivered.",
)
print(cb)
# Expected: {'id': 'EYVBZR2', 'status': 'PENDING', 'amount': '500.00', ...}
```

```python
# Retrieve all chargebacks
all_cbs = service.chargebacks.retrieve()
print(all_cbs)
```

```python
# Retrieve a specific chargeback
cb_detail = service.chargebacks.retrieve(chargeback_id="EYVBZR2")
print(cb_detail)
```

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

### Wallets — Create a Wallet

Source: https://context7.com/intasend/intasend-python/llms.txt

Provisions a new working wallet on the account. Set `can_disburse=True` to allow outgoing transfers from this wallet.

```APIDOC
## Wallets — Create a Wallet

`service.wallets.create()` provisions a new working wallet on the account. Set `can_disburse=True` to allow outgoing transfers from this wallet.

```python
new_wallet = service.wallets.create(
    currency="KES",
    label="Operations-Wallet",
    can_disburse=True,
)
print(new_wallet)
# Expected: {'wallet_id': 'NEWWLT1', 'currency': 'KES', 'label': 'Operations-Wallet', ...}
```
```

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

### Retrieve All Wallets

Source: https://github.com/intasend/intasend-python/blob/master/README.md

Fetch a list of all wallets associated with your account. This provides an overview of your wallet management.

```python
response = service.wallets.retrieve()
print(response)
```

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

### Fund a Wallet via Checkout URL or STK Push

Source: https://context7.com/intasend/intasend-python/llms.txt

Adds money to a specific wallet. Use 'LINK' mode for a checkout URL or 'MPESA-STK-PUSH' for a direct STK push. Requires wallet ID, phone number, amount, and currency.

```python
# Fund via checkout URL
response = service.wallets.fund(
    wallet_id="ZQMMOQO",
    phone_number=254712345678,
    email="customer@example.com",
    amount=2000,
    narrative="Wallet top-up",
    name="Jane Doe",
    currency="KES",
    mode="LINK",
)
print(response["url"])   # Redirect customer to this URL
```

```python
# Fund via M-Pesa STK Push
response = service.wallets.fund(
    wallet_id="ZQMMOQO",
    phone_number=254712345678,
    email="customer@example.com",
    amount=2000,
    narrative="Wallet top-up",
    mode="MPESA-STK-PUSH",
)
print(response)
```

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

### Initiate M-Pesa STK Push

Source: https://context7.com/intasend/intasend-python/llms.txt

Trigger an M-Pesa STK push using `service.collect.mpesa_stk_push()`. This function returns immediately; poll `collect.status()` to check for completion. Requires phone number, amount, and other transaction details.

```python
try:
    response = service.collect.mpesa_stk_push(
        phone_number=254712345678,
        email="customer@example.com",
        amount=500,
        narrative="School fees payment",
        currency="KES",
        api_ref="txn-9901",
        name="Jane Doe",
    )
    print(response)
    # Expected: {'invoice': {'invoice_id': 'XYZ789', 'state': 'PENDING', ...}}

    # Poll for completion
    import time
    for _ in range(10):
        time.sleep(3)
        status = service.collect.status(invoice_id=response["invoice"]["invoice_id"])
        if status["invoice"]["state"] == "COMPLETE":
            print("Payment received!")
            break
except IntaSendBadRequest as e:
    print(f"STK push failed: {e}")
```

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

### Generate Checkout URL for Payments

Source: https://context7.com/intasend/intasend-python/llms.txt

Use `service.collect.checkout()` to create a hosted payment page URL. Optional `callback_url` and `redirect_url` can be provided for post-payment actions. Handles M-Pesa, card, and other payment methods.

```python
from intasend import APIService
from intasend.exceptions import IntaSendBadRequest

service = APIService(token=API_TOKEN, publishable_key=PUBLISHABLE_KEY, test=True)

try:
    response = service.collect.checkout(
        email="customer@example.com",
        amount=1500,
        currency="KES",
        phone_number=254712345678,
        first_name="Jane",
        last_name="Doe",
        comment="Order #1042 payment",
        api_ref="order-1042",
        callback_url="https://myapp.com/payment/webhook",
        redirect_url="https://myapp.com/payment/success",
        mobile_tarrif="BUSINESS-PAYS",   # or "CUSTOMER-PAYS"
        card_tarrif="BUSINESS-PAYS",
    )
    print(response["url"])
    # Expected: {'id': 'ABCD1234', 'url': 'https://checkout.intasend.com/pay/ABCD1234/', ...}
except IntaSendBadRequest as e:
    print(f"Bad request: {e}")
```

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

### Chargebacks - Create and Retrieve

Source: https://context7.com/intasend/intasend-python/llms.txt

Opens a dispute for a completed invoice or fetches chargebacks by ID or all chargebacks.

```APIDOC
## Chargebacks — Create and Retrieve

`service.chargebacks.create()` opens a dispute for a completed invoice. `service.chargebacks.retrieve()` fetches all chargebacks or a specific one by ID.

```python
# Create a chargeback
cb = service.chargebacks.create(
    invoice="NR5XKGY",
    amount=500,
    reason="DISPUTED",
    reason_details="Customer claims item was not delivered.",
)
print(cb)

# Retrieve all chargebacks
all_cbs = service.chargebacks.retrieve()
print(all_cbs)

# Retrieve a specific chargeback
cb_detail = service.chargebacks.retrieve(chargeback_id="EYVBZR2")
print(cb_detail)
```
```

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

### Buy Airtime via IntaSend

Source: https://github.com/intasend/intasend-python/blob/master/README.md

Purchase airtime for specified phone numbers using the `transfer.airtime` method. Requires a list of transactions with recipient names and accounts.

```python
transactions = [{'name': 'Joe Doe' ,'account': '25472...'}]
response = service.transfer.airtime(currency='KES', transactions=transactions)
print(response)
```

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

### Manage Customer Records

Source: https://context7.com/intasend/intasend-python/llms.txt

Provides CRUD operations for customer profiles. Use `create()` to register, `retrieve()` to list or fetch by ID, and `transactions()` for transaction history. Requires customer ID for retrieval and transaction history.

```python
# Create a customer
customer = service.customers.create(
    email="newcustomer@example.com",
    first_name="Grace",
    last_name="Otieno",
    phone_number="254712345678",
)
print(customer)
# Expected: {'customer_id': 'CUST001', 'email': 'newcustomer@example.com', ...}
```

```python
# Retrieve all customers
all_customers = service.customers.retrieve()
print(all_customers)
```

```python
# Retrieve a single customer
customer = service.customers.retrieve(customer_id="CUST001")
print(customer)
```

```python
# Retrieve a customer's transaction history
txns = service.customers.transactions(customer_id="CUST001")
print(txns)
```

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

### Wallets — List and Retrieve Wallets

Source: https://context7.com/intasend/intasend-python/llms.txt

Lists all wallets on the account. A `wallet_id` can be passed to retrieve details of a specific wallet.

```APIDOC
## Wallets — List and Retrieve Wallets

`service.wallets.retrieve()` lists all wallets on the account. Pass a `wallet_id` to get a single wallet's details.

```python
# List all wallets
all_wallets = service.wallets.retrieve()
print(all_wallets)
# Expected: {'results': [{'wallet_id': 'ZQMMOQO', 'currency': 'KES', 'current_balance': '5000.00', ...}]}

# Fetch a specific wallet
wallet = service.wallets.retrieve(wallet_id="ZQMMOQO")
# or equivalently:
wallet = service.wallets.details("ZQMMOQO")
print(wallet)
```
```

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

### Handle IntaSend API Errors

Source: https://context7.com/intasend/intasend-python/llms.txt

Wraps API calls in try/except blocks to handle specific IntaSend exceptions like `IntaSendUnauthorized`, `IntaSendBadRequest`, `IntaSendNotAllowed`, and `IntaSendServerError`. Requires importing exceptions and initializing `APIService`.

```python
from intasend import APIService
from intasend.exceptions import (
    IntaSendBadRequest,    # 400 — Invalid request payload
    IntaSendUnauthorized,  # 401 — Invalid or missing API token
    IntaSendNotAllowed,    # 403 — Action not permitted for this account
    IntaSendServerError,   # 500 — IntaSend server-side error
)

service = APIService(token="bad-token", publishable_key="bad-key", test=True)

try:
    response = service.collect.mpesa_stk_push(
        phone_number=254712345678,
        email="user@example.com",
        amount=100,
        narrative="Test",
    )
except IntaSendUnauthorized:
    print("Authentication failed — check your API token.")
except IntaSendBadRequest as e:
    print(f"Request validation error: {e}")
except IntaSendNotAllowed as e:
    print(f"Permission denied: {e}")
except IntaSendServerError as e:
    print(f"IntaSend server error, retry later: {e}")
```

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

### Perform Intra-Wallet Transfer

Source: https://context7.com/intasend/intasend-python/llms.txt

Moves funds instantly between two wallets on the same IntaSend account. Requires origin wallet ID, destination wallet ID, and amount.

```python
response = service.wallets.intra_transfer(
    origin_id="ZQMMOQO",
    destination_id="XZY43Q8",
    amount=750,
    narrative="Operations fund allocation",
)
print(response)
# Expected: {'status': 'success', 'origin': 'ZQMMOQO', 'destination': 'XZY43Q8', 'amount': '750.00'}
```

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

### Payment Links - Create and Retrieve

Source: https://context7.com/intasend/intasend-python/llms.txt

Generates reusable payment links and allows retrieval of all links or a specific link by ID.

```APIDOC
## Payment Links — Create and Retrieve

`service.payment_links.create()` generates a reusable, shareable payment link. Set `amount=0` for open-amount links. `retrieve()` lists all links or returns one by ID.

```python
import secrets

# Create a fixed-amount payment link
link = service.payment_links.create(
    title=f"Product Purchase - {secrets.token_hex(4)}",
    currency="KES",
    amount=2500,
    mobile_tarrif="BUSINESS-PAYS",
    card_tarrif="CUSTOMER-PAYS",
    is_active=True,
)
print(link)

# Create an open-amount donation link
donation_link = service.payment_links.create(
    title="Charity Donation",
    currency="KES",
    amount=0,      # Customer enters their own amount
)
print(donation_link["url"])

# List all payment links
all_links = service.payment_links.retrieve()
print(all_links)

# Fetch a specific link
link_detail = service.payment_links.retrieve(link_id="LNK001")
print(link_detail)
```
```

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

### List Wallet Transactions

Source: https://context7.com/intasend/intasend-python/llms.txt

Returns a paginated list of all transactions that have passed through a wallet.

```python
txns = service.wallets.transactions(wallet_id="ZQMMOQO")
print(txns)
# Expected: {'results': [{'id': 1, 'type': 'DEBIT', 'amount': '500.00', 'narrative': '...', ...}]}
```

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

### Send Money via M-Pesa with Approval

Source: https://github.com/intasend/intasend-python/blob/master/README.md

Initiate a money transfer to multiple recipients via M-Pesa. The `requires_approval` flag allows for manual approval before execution. Use `service.transfer.approve` to proceed.

```python
transactions = [{'name': 'Awesome Customer 1', 'account': 25472.., 'amount': 10},
                    {'name': 'Awesome Customer 2', 'account': 25472.., 'amount': 10000}]
                    
requires_approval = 'YES' # Set to 'NO' if you want the transaction to go through without calling the approve method
response = service.transfer.mpesa(currency='KES', transactions=transactions, requires_approval=requires_approval)
print(response)

if requires_approval == 'YES':
    response = service.transfer.approve(response)
    print(f"Approve response: {response}")
```

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

### Buy Airtime

Source: https://context7.com/intasend/intasend-python/llms.txt

Tops up airtime for one or more phone numbers in a single call. Set requires_approval to 'NO' for automatic processing.

```python
transactions = [
    {"account": "254712345678", "amount": 50,  "name": "Alice"},
    {"account": "254798765432", "amount": 100, "name": "Bob"},
]

response = service.transfer.airtime(
    currency="KES",
    transactions=transactions,
    requires_approval="NO",
)
print(response)
# Expected: {'tracking_id': 'TRK789', 'status': 'Processing', ...}
```

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

### Retrieve Chargeback Details

Source: https://github.com/intasend/intasend-python/blob/master/README.md

Fetch details of a specific chargeback using its ID. This is essential for managing disputes and understanding transaction reversals.

```python
response = service.chargebacks.retrieve(<CHARGEBACK-ID>)
print(response)
```

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

### Generate Checkout URL for Payment Collection

Source: https://github.com/intasend/intasend-python/blob/master/README.md

Use the `collect.checkout` method to generate a payment URL. Remember to set `test=True` for sandbox testing and `False` or remove it for live transactions.

```python
service = APIService(token="token",publishable_key=publishable_key, test=True)

response = service.collect.checkout(phone_number=2547...,
                                    email="felix@intasend.com", amount=10, currency="KES", comment="Fees")
print(response)
```

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

### Wallets - Intra-Wallet Transfer

Source: https://context7.com/intasend/intasend-python/llms.txt

Moves funds between two wallets on the same IntaSend account instantly.

```APIDOC
## Wallets — Intra-Wallet Transfer

`service.wallets.intra_transfer()` moves funds between two wallets on the same IntaSend account instantly.

```python
response = service.wallets.intra_transfer(
    origin_id="ZQMMOQO",
    destination_id="XZY43Q8",
    amount=750,
    narrative="Operations fund allocation",
)
print(response)
```
```

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

### Send Money via Bank Transfer (PesaLink)

Source: https://context7.com/intasend/intasend-python/llms.txt

Disburses funds to Kenyan bank accounts via PesaLink. Use get_bank_codes() to retrieve valid bank codes beforehand. Requires explicit approval if requires_approval is 'YES'.

```python
# Fetch supported bank codes first
bank_codes = service.transfer.get_bank_codes()
print(bank_codes)
# Expected: [{'name': 'KCB', 'code': '01'}, {'name': 'Equity', 'code': '68'}, ...]

transactions = [
    {
        "account": "1234567890",   # Bank account number
        "amount": 10000,
        "name": "John Mwangi",
        "bank_code": "01",         # KCB
        "narrative": "Supplier payment",
    },
]

response = service.transfer.bank(
    currency="KES",
    transactions=transactions,
    requires_approval="YES",
)
approval = service.transfer.approve(response)
print(approval)
```

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

### Perform Intra-Wallet Transfer

Source: https://github.com/intasend/intasend-python/blob/master/README.md

Transfer funds between two wallets. Requires the IDs of the source and destination wallets, amount, and a description.

```python
response = service.wallets.intra_transfer(<WALLET-ID-1>, <WALLET-ID-2>, 1, "Charge capture")
print(response)
```

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

### Fund a Specific Wallet

Source: https://github.com/intasend/intasend-python/blob/master/README.md

Add funds to a specific wallet using a customer's phone number and email. This is useful for topping up balances or processing incoming payments.

```python
response = service.wallets.fund(
         wallet_id=<WALLET-ID>, phone_number=25472.., email="customer@example.com", amount=10, narrative="Fees", name="Awesome Customer")
print(response)
```

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

### List Wallet Transactions

Source: https://github.com/intasend/intasend-python/blob/master/README.md

View all transactions associated with a particular wallet by providing its wallet ID.

```python
response = service.wallets.transactions(<WALLET-ID>)
print(response)
```

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

### Wallets — List Wallet Transactions

Source: https://context7.com/intasend/intasend-python/llms.txt

Returns a paginated list of all transactions that have passed through a wallet.

```APIDOC
## Wallets — List Wallet Transactions

`service.wallets.transactions()` returns a paginated list of all transactions that have passed through a wallet.

```python
txns = service.wallets.transactions(wallet_id="ZQMMOQO")
print(txns)
# Expected: {'results': [{'id': 1, 'type': 'DEBIT', 'amount': '500.00', 'narrative': '...', ...}]}
```
```

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

### Collect — Generate Checkout URL

Source: https://context7.com/intasend/intasend-python/llms.txt

Creates a hosted payment page and returns a URL for customer redirection. Supports various payment methods and allows customization of callback and redirect URLs.

```APIDOC
## Collect - Generate Checkout URL

### Description
`service.collect.checkout()` creates a hosted payment page and returns a URL to which the customer is redirected. Supports M-Pesa, card (Visa/Mastercard), and other methods. Optional `callback_url` and `redirect_url` control post-payment webhooks and redirects.

### Method
`POST` (Implied by the SDK method call)

### Endpoint
`/v1/collect/checkout` (Implied by the SDK method call)

### Parameters
#### Request Body
- **email** (string) - Required - Customer's email address.
- **amount** (number) - Required - The payment amount.
- **currency** (string) - Required - The currency code (e.g., KES).
- **phone_number** (number) - Optional - Customer's phone number.
- **first_name** (string) - Optional - Customer's first name.
- **last_name** (string) - Optional - Customer's last name.
- **comment** (string) - Optional - A comment or description for the payment.
- **api_ref** (string) - Optional - An API reference ID for the transaction.
- **callback_url** (string) - Optional - URL for post-payment webhooks.
- **redirect_url** (string) - Optional - URL to redirect the customer after payment.
- **mobile_tarrif** (string) - Optional - Tariff for mobile payments (e.g., "BUSINESS-PAYS").
- **card_tarrif** (string) - Optional - Tariff for card payments (e.g., "BUSINESS-PAYS").

### Request Example
```python
response = service.collect.checkout(
    email="customer@example.com",
    amount=1500,
    currency="KES",
    phone_number=254712345678,
    first_name="Jane",
    last_name="Doe",
    comment="Order #1042 payment",
    api_ref="order-1042",
    callback_url="https://myapp.com/payment/webhook",
    redirect_url="https://myapp.com/payment/success",
    mobile_tarrif="BUSINESS-PAYS",   # or "CUSTOMER-PAYS"
    card_tarrif="BUSINESS-PAYS",
)
print(response["url"])
```

### Response
#### Success Response (200)
- **id** (string) - The unique ID of the checkout session.
- **url** (string) - The URL to redirect the customer to for payment.

#### Response Example
```json
{
  "id": "ABCD1234",
  "url": "https://checkout.intasend.com/pay/ABCD1234/",
  ...
}
```

### Error Handling
- **IntaSendBadRequest**: Raised for invalid requests.
```

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

### Wallets - Fund a Wallet

Source: https://context7.com/intasend/intasend-python/llms.txt

Adds money to a specific wallet. Supports both checkout URL and direct M-Pesa STK push.

```APIDOC
## Wallets — Fund a Wallet

`service.wallets.fund()` adds money to a specific wallet. By default uses `mode="LINK"` (checkout URL); set `mode="MPESA-STK-PUSH"` for a direct STK push.

```python
# Fund via checkout URL
response = service.wallets.fund(
    wallet_id="ZQMMOQO",
    phone_number=254712345678,
    email="customer@example.com",
    amount=2000,
    narrative="Wallet top-up",
    name="Jane Doe",
    currency="KES",
    mode="LINK",
)
print(response["url"])

# Fund via M-Pesa STK Push
response = service.wallets.fund(
    wallet_id="ZQMMOQO",
    phone_number=254712345678,
    email="customer@example.com",
    amount=2000,
    narrative="Wallet top-up",
    mode="MPESA-STK-PUSH",
)
print(response)
```
```

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

### Send Money via M-Pesa (B2C)

Source: https://context7.com/intasend/intasend-python/llms.txt

Disburses funds to one or more M-Pesa numbers. When requires_approval is 'YES' (default), the batch must be explicitly approved before funds move. Use the callback_url to receive webhook notifications.

```python
transactions = [
    {"account": "254712345678", "amount": 500,   "name": "Alice Wanjiku",  "narrative": "July salary"},
    {"account": "254798765432", "amount": 1200,  "name": "Bob Kamau",      "narrative": "July salary"},
]

try:
    response = service.transfer.mpesa(
        currency="KES",
        transactions=transactions,
        requires_approval="YES",   # Set "NO" to auto-approve
        callback_url="https://myapp.com/transfers/webhook",
    )
    print(response)
    # Expected: {'tracking_id': 'TRK123', 'status': 'Preview', ...}

    # Approve the batch
    approval = service.transfer.approve(response)
    print(f"Approval: {approval}")

    # Check final status
    status = service.transfer.status(response["tracking_id"])
    print(f"Status: {status}")
except IntaSendBadRequest as e:
    print(f"Transfer failed: {e}")
```

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

### Trigger M-Pesa STK Push

Source: https://github.com/intasend/intasend-python/blob/master/README.md

Initiate an M-Pesa STK push to a customer's phone number for payment collection. Provide necessary details like phone number, amount, and narrative.

```python
response = service.collect.mpesa_stk_push(phone_number=2547...,
                                      email="customer@example.com", amount=10, narrative="Fees")
print(response)
```

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

### Transfer — Buy Airtime

Source: https://context7.com/intasend/intasend-python/llms.txt

Tops up airtime for one or more phone numbers in a single call.

```APIDOC
## Transfer — Buy Airtime

`service.transfer.airtime()` tops up airtime for one or more phone numbers in a single call.

```python
transactions = [
    {"account": "254712345678", "amount": 50,  "name": "Alice"},
    {"account": "254798765432", "amount": 100, "name": "Bob"},
]

response = service.transfer.airtime(
    currency="KES",
    transactions=transactions,
    requires_approval="NO",
)
print(response)
# Expected: {'tracking_id': 'TRK789', 'status': 'Processing', ...}
```
```

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

### Collect — M-Pesa STK Push

Source: https://context7.com/intasend/intasend-python/llms.txt

Triggers a real-time M-Pesa payment prompt (STK push) directly on the customer's phone. The function returns immediately, and the payment status should be polled using `collect.status()`.

```APIDOC
## Collect - M-Pesa STK Push

### Description
`service.collect.mpesa_stk_push()` triggers a real-time M-Pesa payment prompt (STK push) directly on the customer's phone. Returns immediately; poll `collect.status()` for final state.

### Method
`POST` (Implied by the SDK method call)

### Endpoint
`/v1/collect/mpesa-stk-push` (Implied by the SDK method call)

### Parameters
#### Request Body
- **phone_number** (number) - Required - The customer's M-Pesa phone number.
- **email** (string) - Required - Customer's email address.
- **amount** (number) - Required - The payment amount.
- **narrative** (string) - Required - A description for the transaction.
- **currency** (string) - Required - The currency code (e.g., KES).
- **api_ref** (string) - Optional - An API reference ID for the transaction.
- **name** (string) - Optional - The customer's name.

### Request Example
```python
response = service.collect.mpesa_stk_push(
    phone_number=254712345678,
    email="customer@example.com",
    amount=500,
    narrative="School fees payment",
    currency="KES",
    api_ref="txn-9901",
    name="Jane Doe",
)
print(response)

# Poll for completion
import time
for _ in range(10):
    time.sleep(3)
    status = service.collect.status(invoice_id=response["invoice"]["invoice_id"])
    if status["invoice"]["state"] == "COMPLETE":
        print("Payment received!")
        break
```

### Response
#### Success Response (200)
- **invoice** (object) - An object containing invoice details.
  - **invoice_id** (string) - The ID of the initiated invoice.
  - **state** (string) - The initial state of the invoice (e.g., "PENDING").
  - ... (other invoice details)

#### Response Example
```json
{
  "invoice": {
    "invoice_id": "XYZ789",
    "state": "PENDING",
    ...
  }
}
```

### Error Handling
- **IntaSendBadRequest**: Raised if the STK push fails.
```

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

### Send Money via M-Pesa (B2B)

Source: https://context7.com/intasend/intasend-python/llms.txt

Sends funds from a business account to another business M-Pesa paybill or till number. Set requires_approval to 'NO' for automatic processing.

```python
transactions = [
    {"account": "174379", "amount": 5000, "name": "Supplier Ltd", "narrative": "Invoice #88"},
]

response = service.transfer.mpesa_b2b(
    currency="KES",
    transactions=transactions,
    requires_approval="NO",
)
print(response)
# Expected: {'tracking_id': 'TRK456', 'status': 'Processing', ...}
```

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

### Customers - Manage Customer Records

Source: https://context7.com/intasend/intasend-python/llms.txt

Provides CRUD operations for customer profiles, including creating, retrieving, and fetching transaction history.

```APIDOC
## Customers — Manage Customer Records

`service.customers` provides CRUD operations for customer profiles. `create()` registers a customer; `retrieve()` lists all or fetches one by ID; `transactions()` returns a customer's transaction history.

```python
# Create a customer
customer = service.customers.create(
    email="newcustomer@example.com",
    first_name="Grace",
    last_name="Otieno",
    phone_number="254712345678",
)
print(customer)

# Retrieve all customers
all_customers = service.customers.retrieve()
print(all_customers)

# Retrieve a single customer
customer = service.customers.retrieve(customer_id="CUST001")
print(customer)

# Retrieve a customer's transaction history
txns = service.customers.transactions(customer_id="CUST001")
print(txns)
```
```

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

### Transfer — Bank Transfer (PesaLink)

Source: https://context7.com/intasend/intasend-python/llms.txt

Disburses funds to Kenyan bank accounts via PesaLink. Requires bank codes obtained via `get_bank_codes()`.

```APIDOC
## Transfer — Bank Transfer (PesaLink)

`service.transfer.bank()` disburses to Kenyan bank accounts via PesaLink. Use `get_bank_codes()` to retrieve valid bank codes before initiating.

```python
# Fetch supported bank codes first
bank_codes = service.transfer.get_bank_codes()
print(bank_codes)
# Expected: [{'name': 'KCB', 'code': '01'}, {'name': 'Equity', 'code': '68'}, ...]

transactions = [
    {
        "account": "1234567890",   # Bank account number
        "amount": 10000,
        "name": "John Mwangi",
        "bank_code": "01",         # KCB
        "narrative": "Supplier payment",
    },
]

response = service.transfer.bank(
    currency="KES",
    transactions=transactions,
    requires_approval="YES",
)
approval = service.transfer.approve(response)
print(approval)
```
```

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

### Send Money via IntaSend Internal Transfer

Source: https://context7.com/intasend/intasend-python/llms.txt

Moves funds directly to other IntaSend account holders on the IntaSend network. Set requires_approval to 'NO' for automatic processing.

```python
transactions = [
    {"account": "user@example.com", "amount": 300, "name": "Peer User", "narrative": "Refund"},
]

response = service.transfer.intasend(
    currency="KES",
    transactions=transactions,
    requires_approval="NO",
)
print(response)
```

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

### Check Payment Status

Source: https://context7.com/intasend/intasend-python/llms.txt

Query the status of an invoice using `service.collect.status()` with the `invoice_id`. For checkout-flow verification, include `checkout_id` and `signature`.

```python
try:
    response = service.collect.status(invoice_id="NR5XKGY")
    print(response)
    # Expected: {'invoice': {'invoice_id': 'NR5XKGY', 'state': 'COMPLETE', 'value': '1500.00', ...}}

    # For checkout-flow verification (with JWT signature):
    response = service.collect.status(
        invoice_id="NR5XKGY",
        checkout_id="CHECKOUT-ABC",
        signature="eyJ...",
    )
    print(response)
except IntaSendBadRequest as e:
    print(f"Error: {e}")
```

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

### Transfer — Send Money via M-Pesa (B2C)

Source: https://context7.com/intasend/intasend-python/llms.txt

Disburses funds to one or more M-Pesa numbers in a single batch. Batches require explicit approval by default.

```APIDOC
## Transfer — Send Money via M-Pesa (B2C)

`service.transfer.mpesa()` disburses funds to one or more M-Pesa numbers in a single batch. When `requires_approval='YES'` (default), the batch must be explicitly approved before funds move.

```python
transactions = [
    {"account": "254712345678", "amount": 500,   "name": "Alice Wanjiku",  "narrative": "July salary"},
    {"account": "254798765432", "amount": 1200,  "name": "Bob Kamau",      "narrative": "July salary"},
]

try:
    response = service.transfer.mpesa(
        currency="KES",
        transactions=transactions,
        requires_approval="YES",   # Set "NO" to auto-approve
        callback_url="https://myapp.com/transfers/webhook",
    )
    print(response)
    # Expected: {'tracking_id': 'TRK123', 'status': 'Preview', ...}

    # Approve the batch
    approval = service.transfer.approve(response)
    print(f"Approval: {approval}")

    # Check final status
    status = service.transfer.status(response["tracking_id"])
    print(f"Status: {status}")
except IntaSendBadRequest as e:
    print(f"Transfer failed: {e}")
```
```

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

### Transfer — Send Money via IntaSend Internal Transfer

Source: https://context7.com/intasend/intasend-python/llms.txt

Moves funds directly to other IntaSend account holders within the IntaSend network.

```APIDOC
## Transfer — Send Money via IntaSend Internal Transfer

`service.transfer.intasend()` moves funds to other IntaSend account holders directly on the IntaSend network.

```python
transactions = [
    {"account": "user@example.com", "amount": 300, "name": "Peer User", "narrative": "Refund"},
]

response = service.transfer.intasend(
    currency="KES",
    transactions=transactions,
    requires_approval="NO",
)
print(response)
```
```

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

### Check Transfer Status

Source: https://context7.com/intasend/intasend-python/llms.txt

Retrieves the current processing state of any batch transfer using its tracking_id.

```python
status = service.transfer.status(tracking_id="TRK123")
print(status)
# Expected: {'tracking_id': 'TRK123', 'status': 'Sent', 'transactions': [...]}
```

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

### Transfer — Check Transfer Status

Source: https://context7.com/intasend/intasend-python/llms.txt

Retrieves the current processing state of any batch transfer using its `tracking_id`.

```APIDOC
## Transfer — Check Transfer Status

`service.transfer.status()` retrieves the current processing state of any batch transfer using its `tracking_id`.

```python
status = service.transfer.status(tracking_id="TRK123")
print(status)
# Expected: {'tracking_id': 'TRK123', 'status': 'Sent', 'transactions': [...]} 
```
```

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

### Transfer — Send Money via M-Pesa (B2B)

Source: https://context7.com/intasend/intasend-python/llms.txt

Sends funds from a business account to another business M-Pesa paybill or till number.

```APIDOC
## Transfer — Send Money via M-Pesa (B2B)

`service.transfer.mpesa_b2b()` sends funds from a business account to another business M-Pesa paybill or till number.

```python
transactions = [
    {"account": "174379", "amount": 5000, "name": "Supplier Ltd", "narrative": "Invoice #88"},
]

response = service.transfer.mpesa_b2b(
    currency="KES",
    transactions=transactions,
    requires_approval="NO",
)
print(response)
# Expected: {'tracking_id': 'TRK456', 'status': 'Processing', ...}
```
```

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

### Collect — Check Payment Status

Source: https://context7.com/intasend/intasend-python/llms.txt

Queries the current state of an invoice using its tracking ID. Can also verify checkout-API payments with an optional `checkout_id` and `signature`.

```APIDOC
## Collect - Check Payment Status

### Description
`service.collect.status()` queries the current state of an invoice using its tracking ID. Can also verify checkout-API payments by supplying an optional `checkout_id` and `signature`.

### Method
`GET` (Implied by the SDK method call)

### Endpoint
`/v1/collect/status` (Implied by the SDK method call)

### Parameters
#### Query Parameters
- **invoice_id** (string) - Required - The ID of the invoice to check.
- **checkout_id** (string) - Optional - The checkout session ID for verification.
- **signature** (string) - Optional - The JWT signature for checkout verification.

### Request Example
```python
# Check status by invoice ID
response = service.collect.status(invoice_id="NR5XKGY")
print(response)

# Verify checkout-flow payment
response = service.collect.status(
    invoice_id="NR5XKGY",
    checkout_id="CHECKOUT-ABC",
    signature="eyJ...",
)
print(response)
```

### Response
#### Success Response (200)
- **invoice** (object) - An object containing invoice details.
  - **invoice_id** (string) - The ID of the invoice.
  - **state** (string) - The current state of the invoice (e.g., "COMPLETE", "PENDING").
  - **value** (string) - The amount of the invoice.
  - ... (other invoice details)

#### Response Example
```json
{
  "invoice": {
    "invoice_id": "NR5XKGY",
    "state": "COMPLETE",
    "value": "1500.00",
    ...
  }
}
```

### Error Handling
- **IntaSendBadRequest**: Raised for invalid requests.
```

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