Add pre-authorization (confirmation_mode) support to Merchant resources

[paulosouza-stark]

Description and impact

The feat/pre-approve branch of api-v2-ms-card-merchant introduced manual confirmation mode (pre-authorization) for merchant purchases: a new confirmationMode field (automatic / manual, default automatic) on MerchantSession and MerchantPurchase. In manual mode the purchase is approved but only captured after an explicit confirmation (PATCH /merchant-purchase/{id} with status=confirmed), and a new DELETE /merchant-purchase/{id} endpoint cancels (approved) or fully reverses (confirmed) a purchase.

The Python SDK did not expose confirmationMode nor the delete endpoint, so integrators could not use pre-authorization through the SDK. This PR adds that support.

Planning card: ACQ-413.

Change

• Added the confirmation_mode attribute to the MerchantSession, MerchantPurchase and MerchantSession.Purchase resources. It is serialized as confirmationMode and omitted when None (so the server default automatic applies). starkcore.from_api_json silently drops unknown fields, so the attribute must exist in the resource for the value to be exposed on responses.
• Added merchantpurchase.delete(id) → DELETE /merchant-purchase/{id} (cancels an approved purchase or fully reverses a confirmed one; the operation is inferred server-side from the current status).
• Confirming a pre-authorized purchase uses the existing merchantpurchase.update(id, status="confirmed", amount=...).
• Updated README.md (field in the session/purchase examples + new Confirm/Cancel a MerchantPurchase sections), CHANGELOG.md ([Unreleased]), and the builders/tests under tests/.
• The POST /merchant-purchase/{id} route listed in the service permissions.yaml was intentionally not implemented (it has no handler). The manual + debit restriction is enforced server-side; the SDK just forwards the value.

SDK usage examples

1. Create a pre-authorization session (confirmation_mode="manual")

import starkbank

session = starkbank.merchantsession.create(
    starkbank.MerchantSession(
        allowed_funding_types=["credit"],
        allowed_installments=[
            starkbank.merchantsession.AllowedInstallment(total_amount=0, count=1),
        ],
        expiration=3600,
        challenge_mode="disabled",
        confirmation_mode="manual",
        tags=["pre-auth"],
    )
)

# session.id                -> "5950134772826112"
# session.uuid              -> "0bb894a2697d41d99fe02cad2c00c9bc"
# session.confirmation_mode -> "manual"
# session.status            -> "created"

2. Create a purchase directly in manual mode (optional — credit only)

purchase = starkbank.merchantpurchase.create(
    starkbank.MerchantPurchase(
        amount=10000,
        installment_count=1,
        card_id="6295415968235520",
        funding_type="credit",
        confirmation_mode="manual",
    )
)

# purchase.status            -> "approved"   (approved, not yet captured)
# purchase.confirmation_mode -> "manual"

3. Confirm (capture) the pre-authorized purchase

purchase = starkbank.merchantpurchase.update(
    id="5189831499972623",
    status="confirmed",
    amount=10000,
)

# purchase.status            -> "confirmed"
# purchase.amount            -> 10000
# purchase.confirmation_mode -> "manual"

4. Cancel an approved purchase / fully reverse a confirmed one

purchase = starkbank.merchantpurchase.delete("5189831499972623")

# purchase.status -> "canceling"   (approved -> canceling)
#                 -> "reversing"   (confirmed -> reversing)

print(...) on these objects renders as MerchantSession[<id>] / MerchantPurchase[<id>]; the values shown above are the attributes populated on the returned object.

Rollback Plan

• Additive, backwards-compatible change to a client SDK (new optional attribute + new method); no API/database impact.
• If needed, revert commit e82170e (Added pre-authorization) and/or pin the dependency to the previously released SDK version.

Acceptance Criteria

• merchantsession.create(...) with confirmation_mode="manual" returns a session and confirmation_mode round-trips on the response.
• A purchase created in a manual session is approved (not captured) until confirmed.
• merchantpurchase.update(id, status="confirmed", amount=...) confirms (captures) a manual purchase.
• merchantpurchase.delete(id) cancels an approved purchase and fully reverses a confirmed one.
• Existing MerchantSession/MerchantPurchase tests keep passing.