Checkout flow — orders and payments

Sequence

sequenceDiagram
    participant App
    participant SDK as VillaClient
    participant Cognito
    participant Villa as shop.villamarket.com

    App->>SDK: login(user, password)
    SDK->>Cognito: USER_PASSWORD_AUTH
    Cognito-->>SDK: IdToken
    SDK->>Villa: Bearer IdToken on all calls

    App->>SDK: OrderBuilder.build()
    App->>SDK: pre_payment.validate(order, expected_grand_total)
    SDK->>Villa: schema + pricing APIs
    Villa-->>SDK: valid / errors

    App->>SDK: orders.create(order)
    SDK->>Villa: POST order

    App->>SDK: payments.card_token(...)
    App->>SDK: payments.card_payment(...)
    SDK->>Villa: payment3(dev) endpoints

Typical Python flow

from villa_backend_sdk import VillaClient, OrderBuilder

client = VillaClient.from_env()
client.login("user@example.com", "password")
order_id = client.orders.generate_order_id("1000").order_id

order = (
    client.order_builder(order_id=order_id)
    .with_branch("1000")
    .add_product(cprcode=25281, quantity=1, price=20, row_total=20)
    .as_test_order()
    .build()
)

# ownerId is Cognito token sub — set automatically by order_builder()
assert order.owner_id == client.owner_id

result = client.pre_payment.validate(order, expected_grand_total=174.0)
assert result.valid

client.create_order(order)
# ... card token + card payment via client.payments

Modules

Module	Role
`villa_backend_sdk.orders`	`OrderBuilder`, create/get/list
`villa_backend_sdk.validation`	Schema + remote pre-payment validation
`villa_backend_sdk.payments`	Card token, card payment, verify

Payment paths switch by VILLA_ENV: dev uses /api/payment3devapi/*, prod uses /api/payment3/*.

Full API reference: MANUAL (docs/MANUAL.md).

Order API endpoints (Postman)

Step	Method	Path
Generate ID	POST	`/api/order2/gentele`
Create	POST	`/api/order/create`
Get	POST	`/api/order/get`
Update	POST	`/api/order/update`

ownerId rule

ownerId **must** equal the logged-in user's Cognito ID token **sub**. Use client.owner_id after login() — never a random UUID.