Bill Payments — Python

import os
from chipi_sdk import ChipiSDK, ChipiSDKConfig

sdk = ChipiSDK(
    config=ChipiSDKConfig(
        api_public_key=os.environ["CHIPI_PUBLIC_KEY"],
        api_secret_key=os.environ["CHIPI_SECRET_KEY"],
    )
)

# however you obtain a signed session token for the requesting user —
# e.g. from Clerk's Python SDK, your custom JWT service, or an exchange
# flow against your auth provider.
bearer_token: str = get_current_user_jwt()

from chipi_sdk import GetSkuListQuery

result = sdk.get_sku_list(
    params=GetSkuListQuery(
        chipi_category="RECARGAS",
        carrier_name="Telcel",
        limit=20,
    ),
    bearer_token=bearer_token,
)

print(f"{result.total} matching SKUs")
print(result.data[0].name, result.data[0].fixed_amount, result.data[0].currency)

import os
import uuid
import httpx

def buy_sku(
    chosen_sku,
    user_phone: str,
    bearer_token: str,
    *,
    org_markup: float = 0,
) -> dict:
    """Debit org credits + queue carrier fulfillment. Returns the
    freshly-created Transaction row (status="PENDING" initially)."""
    body = {
        # transactionHash is used purely as an idempotency key — any
        # unique string works (UUID, your internal order id, etc.).
        # Re-sending the same value within today returns the existing
        # Transaction row instead of double-charging.
        "transactionHash": f"order-{uuid.uuid4()}",
        "skuId": chosen_sku.id,
        "skuReference": user_phone,
        "currencyAmount": chosen_sku.fixed_amount,
        "chain": "STARKNET",
        "token": "USDC",
        "walletAddress": "0x0",   # required by the DTO but unused for credits flow
        "orgMarkup": org_markup,  # optional analytics field
    }
    response = httpx.post(
        "https://api.chipipay.com/v1/sku-purchases",
        headers={
            "Content-Type": "application/json",
            "x-api-key": os.environ["CHIPI_PUBLIC_KEY"],
            "Authorization": f"Bearer {bearer_token}",
        },
        json=body,
        timeout=15.0,
    )
    response.raise_for_status()
    return response.json()

transaction = buy_sku(chosen_sku, "5512345678", bearer_token)
purchase_id = transaction["id"]
print(f"Purchase created: {purchase_id} (status={transaction['status']})")

import time

def wait_for_settlement(sdk, purchase_id: str, bearer_token: str):
    for _ in range(12):
        purchase = sdk.get_sku_purchase(
            purchase_id,
            bearer_token=bearer_token,
        )
        if purchase.status in ("SUCCESS", "FAILED"):
            return purchase
        time.sleep(2.5)
    raise TimeoutError("Settlement timeout — set up a webhook for production")

final = wait_for_settlement(sdk, purchase_id, bearer_token)
print(final.status, "file:", final.sku_file_number)

# DEV response shape (key fields)
{
    "id": "tx-...",
    "status": "SUCCESS",                  # always SUCCESS in DEV
    "ledgerEntryId": "le-dev-<uuid>",     # synthetic, not a real DB row
    "skuFileNumber": "dev-sandbox-<ts>",  # not a real carrier receipt
}

import os, time, uuid
import httpx
from chipi_sdk import ChipiSDK, ChipiSDKConfig, GetSkuListQuery


def pay_telcel_recharge(sdk: ChipiSDK, user_phone: str, bearer_token: str):
    # 1. Find the right SKU — say, Telcel $200 prepaid
    listing = sdk.get_sku_list(
        params=GetSkuListQuery(
            chipi_category="RECARGAS",
            carrier_name="Telcel",
            limit=50,
        ),
        bearer_token=bearer_token,
    )
    sku = next((s for s in listing.data if s.fixed_amount == 200), None)
    if sku is None:
        raise ValueError("SKU not found")

    # 2. Debit credits + queue fulfillment
    response = httpx.post(
        "https://api.chipipay.com/v1/sku-purchases",
        headers={
            "Content-Type": "application/json",
            "x-api-key": os.environ["CHIPI_PUBLIC_KEY"],
            "Authorization": f"Bearer {bearer_token}",
        },
        json={
            "transactionHash": f"order-{uuid.uuid4()}",
            "skuId": sku.id,
            "skuReference": user_phone,
            "currencyAmount": 200,
            "chain": "STARKNET",
            "token": "USDC",
            "walletAddress": "0x0",
        },
        timeout=15.0,
    )
    response.raise_for_status()
    purchase_id = response.json()["id"]

    # 3. Wait for settlement
    for _ in range(12):
        p = sdk.get_sku_purchase(purchase_id, bearer_token=bearer_token)
        if p.status == "SUCCESS":
            return p
        if p.status == "FAILED":
            raise RuntimeError("Purchase failed")
        time.sleep(2.5)

    raise TimeoutError("Settlement timeout — set up a webhook for production")