Waffo Python SDK

English | 中文

Official Python SDK for Waffo Payment Platform, providing typed access to payments, refunds, subscriptions, subscription changes, merchant configuration, payment method configuration, and webhook signature verification.

Latest Release Highlights

• Subscription update API: Added subscription.update() with amount, trialPeriodAmount, and scheduledAmounts support.
• Scheduled amount models: Added generated scheduled amount fields across subscription create, change, update, and inquiry models.
• Contract hardening: Added order capture timestamp auto-injection and expanded schema field coverage.

Introduction

Core Features

• Global Payments: Create, query, cancel, and refund payment orders.
• Subscription Management: Create, query, cancel, manage, and change subscriptions.
• Webhook Handling: Verify Waffo signatures and route notification callbacks.
• Typed Models: Pydantic v2 request/response models generated from openapi.json.
• Secure Defaults: RSA request signing, response signature verification, explicit environment selection, and configurable timeouts.

Table of Contents

• Latest Release Highlights
• Requirements
• Installation
• Quick Start
• Configuration
• API Usage
• Webhook Handling
• Payment Method Types
• Advanced Configuration
• Handling New API Fields (ExtraParams)
• Error Handling
• Development
• Support
• License

Requirements

• Python 3.9+
• pip

Version Compatibility

Installation

python -m pip install "waffo==0.1.0b0"
# or install the latest beta/pre-release
python -m pip install --pre waffo

Quick Start

1. Initialize the SDK

from waffo import Environment, Waffo, WaffoConfig

config = WaffoConfig(
    api_key="your-api-key",
    private_key="your-base64-encoded-private-key",
    waffo_public_key="waffo-public-key",
    merchant_id="your-merchant-id",
    environment=Environment.SANDBOX,
)

waffo = Waffo(config)

2. Create a Payment Order

from uuid import uuid4

payment_request_id = uuid4().hex

response = waffo.order().create(
    {
        "paymentRequestId": payment_request_id,
        "merchantOrderId": f"ORDER_{payment_request_id}",
        "orderCurrency": "HKD",
        "orderAmount": "100.00",
        "orderDescription": "Test Product",
        "notifyUrl": "https://your-site.com/webhook",
        "userInfo": {
            "userId": "user_123",
            "userEmail": "user@example.com",
            "userTerminal": "WEB",
        },
        "paymentInfo": {
            "productName": "ONE_TIME_PAYMENT",
        },
        "goodsInfo": {
            "goodsUrl": "https://your-site.com/product/001",
            "goodsName": "Test Product",
        },
    }
)

if response.is_success():
    data = response.get_data()
    print("Redirect action:", data.order_action if data else None)
    print("Acquiring Order ID:", data.acquiring_order_id if data else None)
else:
    print("Error:", response.get_message())

3. Query Order Status

response = waffo.order().inquiry({"paymentRequestId": payment_request_id})

if response.is_success():
    data = response.get_data()
    print("Order Status:", data.order_status if data else None)
    print("Order Amount:", data.order_amount if data else None)

Configuration

Full Configuration Options

from waffo import Environment, Waffo, WaffoConfig

waffo = Waffo(
    WaffoConfig(
        api_key="your-api-key",
        private_key="your-base64-private-key",
        waffo_public_key="waffo-public-key",
        environment=Environment.SANDBOX,
        merchant_id="your-merchant-id",
        connect_timeout=10000,
        read_timeout=30000,
    )
)

Environment Variables

export WAFFO_API_KEY=your-api-key
export WAFFO_PRIVATE_KEY=your-private-key
export WAFFO_PUBLIC_KEY=waffo-public-key
export WAFFO_ENVIRONMENT=SANDBOX
export WAFFO_MERCHANT_ID=your-merchant-id

from waffo import Waffo

waffo = Waffo.from_env()

Environment URLs

Important: Environment must be explicitly specified. SDKs do not default to any environment to prevent accidental requests to wrong environments.

Request-Level Configuration

from waffo import RequestOptions

response = waffo.order().create(
    params,
    RequestOptions(connect_timeout=10000, read_timeout=30000),
)

API Usage

Order Management

Subscription Management

Subscription Change (Upgrade/Downgrade)

Change an existing subscription to a new plan (upgrade or downgrade).

Change Subscription

from uuid import uuid4

from waffo import WaffoUnknownStatusError

subscription_request = uuid4().hex
origin_subscription_request = "original-subscription-request-id"

try:
    response = waffo.subscription().change(
        {
            "subscriptionRequest": subscription_request,
            "originSubscriptionRequest": origin_subscription_request,
            "remainingAmount": "50.00",
            "currency": "HKD",
            "notifyUrl": "https://your-site.com/webhook/subscription",
            "productInfoList": [
                {
                    "description": "Annual Premium Subscription (12 months)",
                    "periodType": "MONTHLY",
                    "periodInterval": "12",
                    "amount": "999.00",
                }
            ],
            "userInfo": {
                "userId": "user_123",
                "userEmail": "user@example.com",
            },
            "goodsInfo": {
                "goodsId": "GOODS_PREMIUM",
                "goodsName": "Premium Plan",
            },
            "paymentInfo": {
                "productName": "SUBSCRIPTION",
            },
        }
    )

    if response.is_success():
        data = response.get_data()
        print("Change Status:", data.subscription_change_status if data else None)
        print("New Subscription ID:", data.subscription_id if data else None)
except WaffoUnknownStatusError as exc:
    print("Unknown status, query later or wait for webhook:", exc)

Subscription Change Status Values

Query Subscription Change Status

response = waffo.subscription().change_inquiry(
    {
        "subscriptionRequest": "new-subscription-request-id",
        "originSubscriptionRequest": "original-subscription-request-id",
    }
)

if response.is_success():
    data = response.get_data()
    print("Change Status:", data.subscription_change_status if data else None)
    print("New Subscription ID:", data.subscription_id if data else None)
    print("Remaining Amount:", data.remaining_amount if data else None)
    print("Currency:", data.currency if data else None)

Refund Query

response = waffo.refund().inquiry({"refundRequestId": "refund_request_id"})

Merchant Configuration

response = waffo.merchant_config().inquiry({})

Query Available Payment Methods

The payMethodDetails response includes the payment method category, supported currency, order amount limits, and refund policy. currentStatus can be absent when real-time availability is temporarily unavailable.

# merchant_id is auto-injected from config if not provided
response = waffo.pay_method_config().inquiry()

if response.is_success():
    data = response.get_data()
    for detail in data.pay_method_details if data and data.pay_method_details else []:
        print(
            {
                "name": detail.pay_method_name,
                "type": detail.pay_method_type,
                "country": detail.country,
                "currency": detail.currency,
                "amount_range": [detail.order_amount_min, detail.order_amount_max],
                "refund_allowed": detail.refund_allowed,
                "current_status": detail.current_status,
            }
        )
else:
    print("Pay method config inquiry failed:", response.get_code(), response.get_message())

Wallet Address Inquiry (x402)

Inquire the on-chain stablecoin receiving address for an x402 payment. The response returns the target network, the on-chain token contract, and the Waffo platform wallet address to send funds to. Phase 1 supports USDC.

# paymentRequestId: unique idempotency key; orderCurrency: Phase 1 supports USDC
# merchantInfo is auto-injected from config if not provided
response = waffo.wallet().inquiry(
    {
        "paymentRequestId": "unique-request-id",
        "orderCurrency": "USDC",
    }
)

if response.is_success():
    data = response.get_data()
    print("Network:", data.network if data else None)  # e.g. eip155:8453 (Base mainnet)
    print("Asset:", data.asset if data else None)       # on-chain token contract address
    print("Pay to:", data.pay_to if data else None)     # Waffo platform receiving wallet address
else:
    print("Wallet inquiry failed:", response.get_code(), response.get_message())

Wallet Inquiry Response Fields

Webhook Handling

from fastapi import FastAPI, Header, Request, Response
from waffo import Waffo

app = FastAPI()
waffo = Waffo.from_env()

waffo.webhook().on_payment(
    lambda notification: print(notification.get("result", {}).get("acquiringOrderId"))
)

@app.post("/webhook")
async def webhook(request: Request, x_signature: str | None = Header(default=None)) -> Response:
    body = (await request.body()).decode("utf-8")
    result = waffo.webhook().handle_webhook(body, x_signature)
    return Response(
        content=result.response_body,
        media_type="application/json",
        headers={"X-SIGNATURE": result.response_signature},
        status_code=200 if result.success else 400,
    )

Webhook Notification Types

Subscription Notification Types Explained

Selection Guide:

• If you only care about subscription activation/cancellation, use SUBSCRIPTION_STATUS_NOTIFICATION
• If you only care about final renewal result of each period, use SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION
• If you only care about subscription change (upgrade/downgrade) final result, use SUBSCRIPTION_CHANGE_NOTIFICATION
• If you need to track every payment attempt (including retries), use PAYMENT_NOTIFICATION

Subscription Payment Note: Each period's payment (including first payment and renewals) triggers PAYMENT_NOTIFICATION events. You can get subscription-related info (subscriptionId, period, etc.) from subscriptionInfo.

Subscription Change (Upgrade/Downgrade) Webhook Note: When a subscription change is processed, the following notifications are triggered:

• SUBSCRIPTION_CHANGE_NOTIFICATION: When subscription change completes (SUCCESS or CLOSED)
• SUBSCRIPTION_STATUS_NOTIFICATION: When original subscription status changes to MERCHANT_CANCELLED
• SUBSCRIPTION_STATUS_NOTIFICATION: When new subscription status changes to ACTIVE
• PAYMENT_NOTIFICATION: If upgrade requires additional payment (price difference)

Webhook Notification Payload Examples

The following examples show the actual payload structure for each notification type.

PAYMENT_NOTIFICATION

{
  "eventType": "PAYMENT_NOTIFICATION",
  "result": {
    "acquiringOrderId": "A2026xxxxxxxxxxxxxxxxxxxx",
    "orderStatus": "PAY_SUCCESS",
    "orderAmount": "109.00",
    "orderCurrency": "USD",
    "finalDealAmount": "109.00",
    "userCurrency": "USD",
    "orderDescription": "Sample Product",
    "orderRequestedAt": "2026-02-28T10:05:58.000Z",
    "orderCompletedAt": "2026-02-28T10:06:10.000Z",
    "orderUpdatedAt": "2026-02-28T10:06:10.000Z",
    "refundExpiryAt": "2026-08-26T23:59:59.999Z",
    "userInfo": {
      "userId": "user@example.com",
      "userEmail": "user@example.com"
    },
    "merchantInfo": {
      "merchantId": "YOUR_MERCHANT_ID"
    },
    "goodsInfo": {
      "goodsId": "goods_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "goodsName": "Sample Product"
    },
    "addressInfo": {},
    "paymentInfo": {
      "productName": "SUBSCRIPTION",
      "payMethodType": "CREDITCARD",
      "payMethodName": "CC_VISA",
      "payMethodProperties": "{\"cardToken\":\"CARD_TOKEN_XXXXXXXXXXXXXXXXXXXX\",\"cardTransactionType\":\"CIT\"}",
      "payMethodResponse": "{\"maskCardData\":\"XXXX42****XX4242\"}"
    },
    "subscriptionInfo": {
      "subscriptionId": "SC2026xxxxxxxxxxxxxxxxxxxxxxxxxx",
      "subscriptionRequest": "sub_req_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "merchantRequest": "sub_req_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "period": "1"
    },
    "cancelRedirectUrl": "https://YOUR_DOMAIN/checkout/YOUR_CHECKOUT_ID"
  }
}

For x402 stablecoin payments, PAYMENT_NOTIFICATION.result also includes x402Info with x402Request, paymentSignatureHeader, and x402Response.

SUBSCRIPTION_STATUS_NOTIFICATION / SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION

These two notification types share the same payload structure:

{
  "eventType": "SUBSCRIPTION_STATUS_NOTIFICATION",
  "result": {
    "subscriptionId": "SC2026xxxxxxxxxxxxxxxxxxxxxxxxxx",
    "subscriptionRequest": "sub_req_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "merchantSubscriptionId": "sub_req_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "subscriptionStatus": "ACTIVE",
    "currency": "USD",
    "userCurrency": "USD",
    "amount": "109.00",
    "requestedAt": "2026-02-28T10:05:58.000Z",
    "updatedAt": "2026-02-28T10:06:10.000Z",
    "userInfo": {
      "userId": "user@example.com",
      "userEmail": "user@example.com"
    },
    "merchantInfo": {
      "merchantId": "YOUR_MERCHANT_ID"
    },
    "goodsInfo": {
      "goodsId": "goods_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "goodsName": "Sample Product"
    },
    "productInfo": {
      "periodType": "MONTHLY",
      "periodInterval": "1",
      "currentPeriod": "1",
      "startDateTime": "2026-02-28T10:06:10.000Z",
      "nextPaymentDateTime": "2026-03-28T10:06:10.000Z",
      "description": "Sample Product"
    },
    "paymentInfo": {
      "productName": "SUBSCRIPTION",
      "payMethodType": "CREDITCARD",
      "payMethodName": "CC_VISA",
      "payMethodProperties": "{}"
    },
    "paymentDetails": [
      {
        "period": "1",
        "acquiringOrderId": "A2026xxxxxxxxxxxxxxxxxxxx",
        "orderAmount": "109.00",
        "orderCurrency": "USD",
        "orderStatus": "PAY_SUCCESS",
        "orderUpdatedAt": "2026-02-28T10:06:10.000Z"
      }
    ]
  }
}

Payment Method Types

payMethodType Reference

Usage Examples

// Specify type only, let user choose on checkout page
paymentInfo: {
  payMethodType: 'CREDITCARD',
}

// Specify exact payment method
paymentInfo: {
  payMethodType: 'CREDITCARD',
  payMethodName: 'CC_VISA',
}

// Combine multiple types
paymentInfo: {
  payMethodType: 'CREDITCARD,DEBITCARD',
}

// E-wallet with specific channel
paymentInfo: {
  payMethodType: 'EWALLET',
  payMethodName: 'GCASH',
}

Note: For available ProductName, PayMethodType, PayMethodName values, merchants can log in to Waffo Portal to view contracted payment methods (Home → Service → Pay-in).

Advanced Configuration

Timeout Configuration Recommendations

Connection Pool Recommendations

Instance Reuse

Create one Waffo instance during application startup and reuse it across requests.

Handling New API Fields (ExtraParams)

When Waffo API adds new fields that are not yet defined in the SDK, you can use the ExtraParams feature to access these fields without waiting for an SDK update.

Reading Unknown Fields from Responses

Sending Extra Fields in Requests

Important Notes

Upgrade SDK Promptly

ExtraParams is designed as a temporary solution for accessing new API fields before SDK updates.

Best Practices:

1. Check SDK release notes regularly for new field support
2. Once SDK officially supports the field, migrate from getExtraParam("field") to the official getter (e.g., getField())
3. The SDK logs a warning when you use getExtraParam() on officially supported fields

Why migrate?

• Official getters provide type safety
• Better IDE auto-completion and documentation
• Reduced risk of typos in field names

Error Handling

Error Code Classification

Error codes are classified by first letter:

Complete Error Code Table

SDK Internal Errors (Sxxxx)

Important: S0001 and E0001 (returned by server) indicate unknown status. Do not close order directly! Should call query API or wait for webhook to confirm actual status.

Merchant Related Errors (Axxxxx)

User Related Errors (Bxxxxx)

System Related Errors (Cxxxxx)

Risk Related Errors (Dxxxxx)

Unknown Status Errors (Exxxxx)

Note: When receiving E0001 error code, it indicates transaction status is unknown. Do not close order directly, should call query API to confirm actual status, or wait for webhook callback notification.

Development

python -m pip install -e ".[dev]"
ruff check src tests examples
mypy src/waffo
pytest tests/unit -q

Support

• GitHub Issues: https://github.com/waffo-com/waffo-sdk/issues
• PyPI: https://pypi.org/project/waffo/

License

MIT