v0.3.5

khipu-python-sdk 0.3.5

This release fixes HTTP error handling and response preservation in the Python SDK for Khipu Instant Payments v3 and Automatic Payments v1.

Fixed

• Preserve HTTP status codes and bounded response bodies when generated response parsing fails.
• Correctly classify malformed or incomplete PAC HTTP 422 responses as KhipuApiError.
• Preserve diagnostic information for ambiguous payment creation outcomes, supporting safer reconciliation.
• Report locally unserialisable request payloads as KhipuValidationError.

Maintenance

• Modernize GitHub Actions and improve CI reproducibility.
• Add Dependabot monitoring for GitHub Actions.
• Simplify release documentation and strengthen version consistency tests.

Installation

pip install khipu-python-sdk==0.3.5

For details, see the CHANGELOG.

This is an independently maintained, unofficial SDK and is not affiliated with or endorsed by Khipu.

v0.3.4

khipu-python-sdk v0.3.4

Documentation and package-metadata maintenance release for the community-maintained Python SDK for Khipu Instant Payments (v3) and Automatic Payments / PAC (v1).

This release improves the package documentation displayed on PyPI. There are no changes to SDK runtime behavior, public APIs, or dependencies.

What's changed

Improved PyPI documentation

• Fixed broken links to LICENSE, CHANGELOG.md, SECURITY.md, and CONTRIBUTING.md in the PyPI project description.
• Updated installation instructions and examples to reference version 0.3.4.
• Updated the changelog to reflect the completed 0.3.3 release and the changes included in 0.3.4.
• Added automated validation to prevent repository-relative links from appearing in future PyPI package descriptions.

Currency precision documentation

Clarified the currency minor-unit validation rules:

• CLP: Requires whole-peso amounts. Trailing decimal zeros are permitted because they do not change the monetary value.
• CLF: Supports up to four decimal places.
• Amounts exceeding the permitted precision are rejected with KhipuValidationError; the SDK never silently rounds amounts.

These are documentation clarifications only. The underlying validation behavior is unchanged.

Installation

pip install khipu-python-sdk==0.3.4

The Python import package remains khipu_sdk.

Compatibility

Version 0.3.4 preserves the runtime behavior and public API of 0.3.3, including Instant Payments, PAC operations, retry and idempotency behavior, generated clients, and compatibility overlays.

Project independence

This is a community-maintained SDK. It is not affiliated with, endorsed by, or maintained by Khipu.

Source code: https://github.com/yaselc/khipu-python-sdk

Full changelog: v0.3.3...v0.3.4

v0.3.3

khipu-python-sdk v0.3.3

First public PyPI release of the community-maintained Python SDK for Khipu Instant Payments (v3) and Automatic Payments / PAC (v1).

Version 0.3.3 introduces PyPI distribution, adopts Khipu's updated Instant Payments OpenAPI specification, and establishes a secure, maintainer-controlled release process.

Highlights

PyPI distribution

Install the SDK with:

pip install khipu-python-sdk==0.3.3

The Python import package remains khipu_sdk.

This release includes updated package metadata, MIT licensing, support declarations for Python 3.10–3.12, and security and contribution documentation.

Updated Instant Payments specification

Adopts Khipu's Instant Payments OpenAPI document published as of October 11, 2026.

• Adds generated-client support for GET /v3/predict/all.
• Updates prediction result enum values to Khipu's uppercase wire format.
• Preserves the existing direct_debit compatibility overlay.

Compatibility note: The prediction enum change is breaking for applications using the generated client directly. The supported KhipuClient facade, payment operations, PAC operations, retry behavior, and error-handling contracts are unchanged from 0.3.2.

Secure package publishing

• Introduces explicit TestPyPI and PyPI publication workflows.
• Uses GitHub Actions Trusted Publishing with OIDC, without stored PyPI API tokens.
• Validates source distributions and wheels, package metadata, version consistency, and clean installations.
• Restricts release builds to approved commits on master.
• Includes additional GitHub Actions security hardening validated with CodeQL.
• Successfully completed the 0.3.3 TestPyPI publication and installed-package smoke test.

Project independence

This is a community-maintained SDK. It is not affiliated with, endorsed by, or maintained by Khipu.

Source code: https://github.com/yaselc/khipu-python-sdk

Full changelog: v0.3.2...v0.3.3

v0.3.2

[0.3.2] - 2026-09-23

Added

• create_charge accepts an explicit, optional notify_api_version (#14).
  It selects the contract Khipu uses for the charge's notify_url callback.
  A supplied value is sent unchanged as "notify_api_version"; omitting it, or
  passing None, leaves the key out of the request entirely. The SDK does
  not default it to "3.0" or to anything else, and does not restrict the
  value beyond Khipu's own free-string schema. Applications that rely on signed
  JSON notifications should request "3.0" explicitly.

Fixed

• notify_api_version=None passed through **extra_fields used to be sent as
  "notify_api_version": null. As a named parameter, None now means
  omission, like the other optional charge fields.

Notes

• Callers already passing notify_api_version="3.0" through **extra_fields
  keep the same call shape and the same request body. **extra_fields is
  unchanged.
• Retry behaviour (none), success-status handling (201, plus 200 for
  compatibility) and charge correlation fields are unchanged. No generated code
  or OpenAPI document changed.

v0.3.1

[0.3.1] - 2026-09-23

Fixed

• A PAC payment could not be retrieved with get_instant_payment (#15).
  Observed against the live developer-mode API in parle-cl/telemaco#377:
  GET /v3/payments/{id} for an Automatic Payments charge returned
  payment_method: "direct_debit", which Khipu's published Instant Payments
  document does not declare (it still lists only regular_transfer,
  simplified_transfer and not_available). The generated parser raised
  ValueError, so the call failed with KhipuResponseError and none of the
  verification fields could be read.

  direct_debit is now accepted for that field on that endpoint only, as a
  typed PaymentGetPaymentPaymentMethod.DIRECT_DEBIT member reachable through
  raw. InstantPaymentStatus is unchanged. Any other undeclared
  payment_method, and any undeclared status, status_detail or
  funds_source, is still reported as KhipuResponseError.

Added

• tools/spec_compat.py, a generation-time compatibility overlay.
  make generate-instant now generates from a derived copy of the Instant
  Payments spec under build/openapi/; the committed spec is still Khipu's
  document byte for byte and its sha256 lock is unchanged. The overlay's single
  entry is strict: generation fails if Khipu publishes direct_debit itself
  (the entry is then obsolete and must be deleted) or changes the enum in any
  other way. make check-spec-compat runs the same check without writing
  anything.
• CI fails when committed generated/ differs from a fresh
  make generate-all, and the spec-drift watch checks the overlay against
  the freshly published spec.

Notes

• This is a deliberate, temporary divergence from Khipu's published schema,
  kept only until Khipu documents direct_debit. No retry behaviour changed and
  nothing new is logged.

v0.3.0

[0.3.0] - 2026-09-22

Adopts the Automatic Payments OpenAPI document Khipu republished after the
2026-08-28 revision this SDK had pinned. One upstream document carries the
fixes for both #10 (subscription status contract) and #9
(max_amount_per_charge), so they land together.

Also re-syncs the Instant Payments document (#12), so both committed specs
match what Khipu publishes and the spec-drift watch is green for both.

Contains breaking changes to the Automatic Payments facade.

Fixed

• PAC subscription retrieval raised on valid provider responses (#10).
  Observed against the live developer-mode API in parle-cl/telemaco#377:

  • a pre-signing subscription with status: "PENDING" raised
    ValueError: 'PENDING' is not a valid SubscriptionStatusStatus;
  • a post-signing subscription that omitted customer_bank_code raised
    KhipuResponseError (KeyError: 'customer_bank_code').

  Khipu's current document resolves both: PENDING is a declared status, and
  customer_bank_code has been removed from the schema entirely. It also adds
  DISCARDED, which would have caused the identical enum failure on an
  unsubscribed mandate.

• create_charge could not read a successful charge. Khipu now documents
  POST /v1/automatic-payment/charge-intent as 201 Created; the generated
  client parsed only 200, so a successful charge surfaced as
  KhipuResponseError: "success status with no usable body". This had not been
  hit in practice because no PAC charge had been attempted yet.

Added

• max_amount_per_charge (#9) is now a required, typed parameter of
  create_subscription, matching Khipu's required field. It is validated
  against the currency's minor-unit scale like max_amount.
• AutomaticSubscriptionStatus now carries developer and
  service_reference. Khipu returns service_reference as an empty string
  until the customer signs; "" is passed through unchanged and never rewritten
  to None.
• Charge rejections (422) are raised as KhipuApiError with Khipu's
  error_message as the message and error_code reachable through payload.
• The generated client now covers DELETE /v1/automatic-payment/subscription/{id}
  (unsubscribe). It is deliberately not exposed on KhipuClient: the
  operation is irreversible and exposing it is a separate API-design decision.
• A release-metadata regression (tests/unit/test_release_metadata.py) ties
  project.version to a dated CHANGELOG section and to the README's pinned
  install examples. Merging to master tags whatever version pyproject.toml
  declares, and silently does nothing when that tag already exists, so an
  un-bumped version is a defect this now catches before merge.

Changed

• create_subscription requires max_amount_per_charge. Breaking for
  callers of 0.2.0.
• create_charge makes body, custom and transaction_id optional,
  matching Khipu's revised ChargeRequest, which no longer requires them. An
  omitted field is left out of the request entirely -- never sent as null,
  never given a fabricated value. Callers that pass them are unaffected. They
  remain the only merchant-side correlation fields Khipu echoes back, so an
  application reconciling charges against its own records should keep requiring
  them in its own service layer; that is application policy, not a constraint
  the SDK imposes on every consumer.
• AutomaticSubscriptionStatus gained developer and service_reference
  before raw. Keyword construction and attribute reads are unaffected;
  positional construction of this result type would be.
• create_charge accepts Khipu's documented 201 and, for compatibility with
  the contract Khipu published until 2026-09, a 200 carrying a usable
  ChargeResult. That allowance is a closed set of exactly those two statuses:
  any other 2xx -- 202 Accepted most importantly -- is reported as
  KhipuResponseError rather than being given the meaning of a created charge.

Instant Payments spec sync (#12)

Khipu's Instant Payments revision is additive only. No endpoint, response
status, required field, enum or security scheme changed; the status
(pending / verifying / done) and status_detail vocabularies are
identical to the previous document. Most of the diff is Spanish terminology
(reversa -> devolución) and added response examples.

• payment-get-payment gains three optional fields: refunds,
  total_refunded and void_payout_date. They refine when money actually
  moved, which status_detail alone cannot express: a refund with
  status: expired never pays out, and total_refunded excludes those.
• These are not promoted onto InstantPaymentStatus in this release.
  Promoting them is an API-design decision (refunds is a list of objects and
  would need a stable result type of its own), not a spec-sync one. They are
  reachable through raw, and are covered by regressions so promoting them
  later is a small step.
• No facade change was required, and none was made. Every Instant Payments
  invariant is unchanged: no idempotency primitive exists in the document (the
  word does not appear in it at all), transaction_id remains correlation
  only, there is still no automatic retry, get_instant_payment remains the
  authoritative retrieval primitive, incomplete success bodies remain
  KhipuResponseError, payer PII stays unpromoted and out of repr, and money
  stays exact Decimal.
• Instant Payments declares exactly 200 for both payment endpoints, and a
  regression now pins that the Automatic Payments charge compatibility
  allowance (201 plus 200) did not leak into them: 201, 202 and 204 are
  rejected there.

Notes

• Khipu's ChargeError vocabulary mentions IDEMPOTENCY_KEY_REUSED, but the
  published ChargeRequest defines no idempotency field or header. The SDK
  therefore sends none and treats no field as one -- transaction_id included.
  Retry guidance is unchanged: the SDK still performs no retries. Tracked for
  investigation in parle-cl/telemaco#377.

v0.2.0

[0.2.0] - 2026-08-28

Production-hardening release. Contains breaking changes to the exception
taxonomy and to the result dataclasses.

Fixed

• Packaging (blocking). generated/ was excluded from the built
  distribution, so a wheel or Git install produced an SDK where every method
  raised "generated client is not available". pyproject.toml now includes
  generated*, and generated/__init__.py makes it a real package.
• Missing runtime dependencies (blocking). attrs and python-dateutil
  are required by the shipped generated code but were undeclared.
• Khipu error bodies were discarded. Non-success responses raised
  "Empty response" even when Khipu returned useful JSON. KhipuApiError now
  carries payload (parsed JSON), body (bounded raw text) and a message
  derived from Khipu's own diagnostics.
• Exceptions could not be pickled, breaking Celery result backends. The
  dataclass-based KhipuApiError was replaced with explicit Exception
  subclasses.
• create_charge signature defect. error_response_url, custom and
  notify_url are required by Khipu's ChargeRequest schema but were absent
  from the public signature, so calling the method as documented failed. They
  are now required parameters.
• KhipuConfig no longer exposes the API key through repr().

Added

• Decimal money support. amount / max_amount accept Decimal, int,
  str or float. Decimal is canonical; conversion to float/int happens
  only at the generated-model boundary (khipu_sdk.money.amount_to_wire).
• Currency minor-unit validation. Amounts are checked against the currency's
  ISO-4217 scale before serialisation and are never silently rounded. Fractional
  CLP (e.g. Decimal("9700.5")) now raises KhipuValidationError with no HTTP
  request made. New module khipu_sdk.money.
• Exception taxonomy under KhipuError: KhipuConfigurationError,
  KhipuValidationError, KhipuTransportError (with KhipuTimeoutError and
  KhipuConnectionError), KhipuApiError and KhipuResponseError. Transport
  errors expose request_may_have_been_delivered, derived from httpx's own
  taxonomy, so an ambiguous create-payment outcome is explicit.
• Correlation and verification fields promoted onto InstantPaymentStatus:
  transaction_id, custom, status_detail, receiver_id,
  notification_token, expires_date, conciliation_date and
  out_of_date_conciliation. Callers no longer need .raw.
• All create-response URLs promoted onto InstantPaymentCreateResult:
  simplified_transfer_url, transfer_url, app_url, ready_for_terminal.
• py.typed marker so downstream type checkers see the package as typed.
• Public exports from khipu_sdk: the client, config, every exception, every
  result dataclass, and CURRENCY_MINOR_UNITS / SUPPORTED_CURRENCIES.
• httpx.Timeout is accepted by KhipuConfig.timeout for per-phase control.
• CI packaging regression guard: a package job builds the wheel, asserts it
  contains the generated clients and py.typed, installs it into a clean
  virtualenv and creates/retrieves a payment against a mock server
  (make build, make smoke-dist, tools/smoke_installed.py).
• Real HTTP-boundary tests using pytest-httpx, replacing SimpleNamespace
  stubs of sync_detailed. Coverage added for the x-api-key header, 400/401/
  403/500/429 responses, timeouts, connection failures, malformed JSON, missing
  required fields, Decimal serialization, fractional-CLP rejection, the real
  pending/verifying/done status values, status_detail == "reversed",
  correlation round-trip, exception pickling and credential-repr safety.
• .env / .env.* added to .gitignore.

Changed

• Breaking: a missing generated client now raises KhipuConfigurationError
  instead of KhipuApiError(500).
• Breaking: timeouts, connection failures, local validation errors and
  malformed responses no longer surface as KhipuApiError(status_code=500).
  Catch KhipuError for a blanket handler.
• Breaking: InstantPaymentCreateResult.status was removed. It was always
  None — Khipu's create response carries no status.
• Breaking: InstantPaymentStatus.amount is now Optional[Decimal] instead
  of Optional[float], and status is a plain str rather than a generated
  enum leaking through an Optional[str] annotation.
• raw is excluded from repr() on all result types; the underlying Khipu
  payment model carries payer PII.
• Removed the vestigial types-requests dev dependency (requests is unused);
  added build.

Upstream API

• Adopted the Khipu OpenAPI specifications as published on 2026-08-28, replacing
  the 2025-12-26 snapshot, and refreshed OPENAPI_SPECS.lock.json and the
  generated clients accordingly.
• Instant Payments. payment-get-payment.amount and .discount changed from
  number to string upstream; the facade continues to expose
  InstantPaymentStatus.amount as Optional[Decimal] and accepts either
  representation. status_detail gained partially-refunded and
  fully-refunded, surfaced verbatim as plain strings. New optional fields
  authorizer_operation_code (response) and psp_client_merchant_logo_url
  (request). POST /v3/payments/{id}/refunds is now marked obsolete, takes no
  body and refunds the full amount only; POST /v3/payments/{id}/void,
  POST /v3/refunds, GET /v3/refund-wallet/balance and
  GET /v3/receivers/children are new. The receiver creation response now also
  returns an api_key.
• Automatic Payments. Documentation-URL change only; no schema change and no
  effect on create_charge.
• The new refund, void and receiver operations are generated but deliberately
  not exposed on KhipuClient. The facade stays small; promoting an
  operation is a separate decision.
• Pinned openapi-python-client==0.28.0 exactly. The generator produces the
  committed contents of generated/, so a floating version could change that
  code with no change in this repository. Regeneration from the committed specs
  is byte-identical.

Notes

Unchanged by design, because Khipu does not provide them:

• create_instant_payment is not idempotent, and transaction_id is not
  documented by Khipu as a deduplication key.
• There is no lookup-by-transaction_id endpoint.
• There is no pre-payment merchant-fee quotation in either vendored spec.
• There is no settlement/report API, and the SDK contains no webhook
  handling.
• The SDK still performs no retries, including on create-payment.

v0.1.2

[0.1.2] - 2026-01-01

Fixed

• Corrected SDK imports to match generated client module paths.

Added

• Mocked integration tests covering instant payments and automatic payment flows.
• Unit regression ensuring missing generated clients raise actionable errors.

v0.1.1

[0.1.1] - 2025-12-30

Added

• Include generated code for Khipu clients.

v0.1.0

[0.1.0] - 2025-12-26

Added

• Initial repository structure.
• KhipuClient high-level wrapper for Khipu Instant Payments (v3) and Automatic Payments / PAC (v1).
• OpenAPI download and client generation tasks.
• Unit/integration test scaffolding.