Summary
The SumUp Transactions API returns values for the field verification_method that are not documented and not accepted by the official Python SDK, causing runtime validation errors for otherwise valid transactions.
In particular, the API returns the string value "na", which is not listed in the Cloud API documentation and not included in the SDK’s Pydantic Literal[...] definition.
This breaks transaction fetching and webhook handling, as the SDK raises a ValidationError before the response can be processed.
Documentation vs. Reality
According to the SumUp Cloud API documentation, the field is defined as:
verification_method (string)
Options:
"none""signature""offline pin""online pin""offline pin + signature""confirmation code verified"
Verification method used for the transaction.
However, in real-world POS transactions, the API returns:
"verification_method": "na"
This value is not documented and not accepted by the SDK.
Error Produced by the SDK
pydantic_core._pydantic_core.ValidationError: 1 validation error for TransactionFull
verification_method
Input should be 'confirmation code verified', 'none', 'offline pin',
'offline pin + signature', 'online pin' or 'signature'
[type=literal_error, input_value='na', input_type=str]
Redacted API Response Example
{
"status": "SUCCESSFUL",
"payment_type": "POS",
"simple_payment_type": "EMV",
"verification_method": "na",
"amount": 5.0,
"currency": "EUR",
"entry_mode": "contactless"
}This response represents a successful, completed transaction returned by the SumUp Cloud API.
Impact
- Valid API responses cannot be parsed by the SDK
- Webhook handlers fail before payloads can be inspected
- Production systems crash on real transactions
- Users cannot safely rely on SDK type validation
Expected Behavior
One of the following should be implemented:
- Document
"na" as a valid value for verification_method, and include it in the SDK
- Make
verification_method optional or nullable in the SDK
- Relax the SDK validation to accept unknown string values
Any of these would prevent the SDK from crashing on valid API responses.
Environment
- Python: 3.13.7
- Pydantic: 2.12.5
- sumup-python SDK: current pre-release / main branch
- API: SumUp Cloud Transactions API (POS)
Additional Notes
This issue appears to be a mismatch between documented enum values and actual API behavior. Given that this occurs on real POS transactions, it would be helpful to either align the documentation or make the SDK more tolerant of undocumented but valid values.
I’m happy to submit a PR with a fix and accompanying tests if this approach is acceptable.
Additional undocumented value: entry_mode
In the same transaction payload, the field entry_mode also contains an undocumented value:
"entry_mode": "contactless"
However, the Cloud API documentation lists only:
This suggests either the documentation is outdated or incomplete for POS transactions, or the SDK should not enforce a strict Literal[...] for this field.
I no longer have the original validation stack trace for entry_mode because I patched my fork to accept the value while debugging, but the issue is reproducible by validating the provided payload against the SDK’s current Pydantic models.
Additional variation: case mismatch in verification_method
I also observed the API returning a case-variant value for verification_method:
"verification_method": "offline PIN"
The documentation and SDK expect:
This again causes a pydantic.ValidationError, even though the semantic value is identical.
This suggests that the API does not guarantee:
and further supports relaxing enum validation or normalizing values (e.g. case-insensitive handling) in the SDK.
Summary
The SumUp Transactions API returns values for the field
verification_methodthat are not documented and not accepted by the official Python SDK, causing runtime validation errors for otherwise valid transactions.In particular, the API returns the string value
"na", which is not listed in the Cloud API documentation and not included in the SDK’s PydanticLiteral[...]definition.This breaks transaction fetching and webhook handling, as the SDK raises a
ValidationErrorbefore the response can be processed.Documentation vs. Reality
According to the SumUp Cloud API documentation, the field is defined as:
However, in real-world POS transactions, the API returns:
This value is not documented and not accepted by the SDK.
Error Produced by the SDK
Redacted API Response Example
{ "status": "SUCCESSFUL", "payment_type": "POS", "simple_payment_type": "EMV", "verification_method": "na", "amount": 5.0, "currency": "EUR", "entry_mode": "contactless" }This response represents a successful, completed transaction returned by the SumUp Cloud API.
Impact
Expected Behavior
One of the following should be implemented:
"na"as a valid value forverification_method, and include it in the SDKverification_methodoptional or nullable in the SDKAny of these would prevent the SDK from crashing on valid API responses.
Environment
Additional Notes
This issue appears to be a mismatch between documented enum values and actual API behavior. Given that this occurs on real POS transactions, it would be helpful to either align the documentation or make the SDK more tolerant of undocumented but valid values.
I’m happy to submit a PR with a fix and accompanying tests if this approach is acceptable.
Additional undocumented value:
entry_modeIn the same transaction payload, the field
entry_modealso contains an undocumented value:However, the Cloud API documentation lists only:
CUSTOMER_ENTRYBOLETOThis suggests either the documentation is outdated or incomplete for POS transactions, or the SDK should not enforce a strict
Literal[...]for this field.I no longer have the original validation stack trace for
entry_modebecause I patched my fork to accept the value while debugging, but the issue is reproducible by validating the provided payload against the SDK’s current Pydantic models.Additional variation: case mismatch in
verification_methodI also observed the API returning a case-variant value for
verification_method:The documentation and SDK expect:
This again causes a pydantic.ValidationError, even though the semantic value is identical.
This suggests that the API does not guarantee:
strict casing
or strict enum conformance
and further supports relaxing enum validation or normalizing values (e.g. case-insensitive handling) in the SDK.