Skip to content

PTHMINT-118: POS receipt and order cancel features#57

Open
zulquer wants to merge 2 commits intomasterfrom
PTHMINT-118
Open

PTHMINT-118: POS receipt and order cancel features#57
zulquer wants to merge 2 commits intomasterfrom
PTHMINT-118

Conversation

@zulquer
Copy link
Copy Markdown
Collaborator

@zulquer zulquer commented Apr 23, 2026

This pull request introduces support for cancelling Cloud POS orders and improves the example scripts and internal API structure for order cancellation and receipt fetching. The main changes include the addition of a new cancel_transaction method to the OrderManager, new request and response models for order cancellation, and several new and updated example scripts demonstrating Cloud POS order creation, cancellation, and receipt retrieval.

New Cloud POS order cancellation support:

  • OrderManager.cancel_transaction method: Adds a new method to cancel POS transactions by order ID, supporting both direct order ID strings and request objects, with optional terminal group scoping.
  • New request/response models and API structure for cancellation:
    • Adds CancelTransactionRequest and CancelTransaction models for request and response handling. [1] [2]
    • Adds corresponding __init__.py files to expose these models and document their purpose. [1] [2] F37e056cR1)
    • Integrates these models into the OrderManager and its response handling. [1] [2]

Example scripts for Cloud POS flows:

  • Adds examples/order_manager/cancel.py to demonstrate Cloud POS order creation, waiting, and cancellation.
  • Adds examples/order_manager/cloud_pos_order.py to demonstrate Cloud POS order creation with terminal-group scoped authentication.
  • Updates and expands examples/pos_manager/get_receipt.py to show both receipt fetching for an existing order and a complete flow including order creation, event monitoring, and receipt retrieval.

Improvements to authentication and scoping:

  • Updates example scripts and internal APIs to consistently support and document terminal group scoping and environment variable configuration for credentials. [1] [2] [3] [4] [5] [6]

These changes collectively provide a full workflow for Cloud POS order management, including creation, cancellation, and receipt retrieval, with improved code organization and documentation.

Base automatically changed from PTHMINT-116 to master April 27, 2026 09:18
Introduce POS and order cancellation functionality: add PosManager with get_receipt and add cancel_transaction to OrderManager. Support terminal-group scoped authentication for order create and cancel (AuthScope / ScopedCredentialResolver) and ensure order_id path segments are encoded. Add request/response models for cancel transaction and rich receipt models with component types (merchant, order, items, tips, payment, related transactions). Wire PosManager into Sdk. Include examples for Cloud POS create, cancel, and fetching receipts. Add unit and integration tests covering create with terminal-group scope, cancel_transaction behavior, PosManager.get_receipt, and existing order operations.
@codecov
Copy link
Copy Markdown

codecov Bot commented Apr 30, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.83%. Comparing base (ab879cf) to head (3cbb437).

Additional details and impacted files
@@            Coverage Diff             @@
##           master      #57      +/-   ##
==========================================
+ Coverage   91.82%   92.83%   +1.00%     
==========================================
  Files         148      164      +16     
  Lines        2655     2889     +234     
==========================================
+ Hits         2438     2682     +244     
+ Misses        217      207      -10     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copy link
Copy Markdown
Member

@danielcivit danielcivit left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • I reported a few inline bugs in the code (typos and non existing arguments within a API response).
  • Also a comment - question about code consistency and conventions previously adopted related to the custom_api_response, custom_cancel_transaction_response, within OrderManager class.

created (Optional[str]): Creation timestamp.
modified (Optional[str]): Last modification timestamp.
custom_info (Optional[CustomInfo]): Additional custom info.
customer (Optional[Customer]): The customer data.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is no "customer" in this response.
https://docs.multisafepay.com/reference/cancelpostransaction#response-schemas
For your reference: the following is a raw response returned by the cancel endpoint:

{'success': True, 'data': {'costs': [], 'created': '2026-05-05T14:17:08', 'custom_info': {'custom_1': None, 'custom_2': None, 'custom_3': None}, 'fastcheckout': 'NO', 'financial_status': None, 'modified': '2026-05-05T14:17:13', 'order_id': 'cloud-pos-cancel-1777983428', 'payment_details': {}, 'payment_methods': None, 'status': 'cancelled'}}

customer (Optional[Customer]): The customer data.
fastcheckout (Optional[str]): Fastcheckout flag/status.
financial_status (Optional[str]): Financial status.
items (Optional[str]): Rendered items payload.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is no "items" in this response.
https://docs.multisafepay.com/reference/cancelpostransaction#response-schemas

For your reference: the following is a raw response returned by the cancel endpoint:

{'success': True, 'data': {'costs': [], 'created': '2026-05-05T14:17:08', 'custom_info': {'custom_1': None, 'custom_2': None, 'custom_3': None}, 'fastcheckout': 'NO', 'financial_status': None, 'modified': '2026-05-05T14:17:13', 'order_id': 'cloud-pos-cancel-1777983428', 'payment_details': {}, 'payment_methods': None, 'status': 'cancelled'}}

"""Order information included in receipt data."""

amount: Optional[int]
amount_refunded: Optional[int]
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be "amountrefunded" following API docs. Or is docs wrong.

The following is an example of this API response:

{'data': {'merchant': {'address': 'Vijzelstraat Amsterdam', 'name': 'MultiSafepay B.V.'}, 'order': {'amount': 100, 'amountrefunded': 0, 'completed': '2026-05-05T12:18:27', 'currency': 'EUR', 'items': None, 'tip': None, 'transaction_id': '1777976306101201'}, 'payment': {'application_id': 'a0000000041010', 'authorization_code': '006459', 'card_acceptor_location': 'Amsterdam', 'card_entry_mode': 'ICC_CONTACTLESS', 'card_expiry_date': '3303', 'cardholder_verification_method': 'NO_CVM_REQUIRED', 'issuer_bin': '548913', 'issuer_country_code': None, 'last4': '6907', 'payment_method': 'MASTERCARD', 'response_code': '00', 'terminal_id': '000013Z1'}, 'printed_on': '2026-05-05T14:36:54', 'related_transactions': None}, 'success': True}


return CustomApiResponse(**args)

@staticmethod
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The location of this method impress me like something strange and breaking the convention and paterns created under this SDK.

  • The "__custom_cancel_transaction_response" static method, is only being consumed under one single method, the "cancel_transaction()".
  • Why this logic is extracted into a static method, and is not being implemented directly in the "cancel_transaction()" method?

Something similar and unclear is happening with the "__custom_api_response"? Why it's there is not clear to me in a first look?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants