Pulling Checkout Response violates security

[ChrisCoder123]

Hi,

I am doing successful an checkout over the API and the Solo device displays successful the amount given in the check-out.
Afterwards i am polling the status, but than i am getting a security violation, polling the status.
which is weird, because i have done successful the check-out.
Why should i not be able to poll the status of my check-out.
Code used for calling and polling.

checkout = await client.readers.create_checkout(
            merchant_code,
            solo.id,
            CreateReaderCheckoutBody(
                total_amount=CreateReaderCheckoutBodyTotalAmount(currency="EUR", value=100, minor_unit=2),
            ),
        )
        logging.info(f"DEBUG: Empfangenes Checkout-Objekt: {checkout}")

        client_tx_id = checkout.data.client_transaction_id
        logging.info(f"Checkout gestartet. Client Transaction ID: {client_tx_id}")

        # 2. Status der Zahlung abfragen (Polling)
        logging.info("Warte auf Zahlungsstatus (Polling)...")
        for _ in range(30):  # Maximal 60 Sekunden warten
            await asyncio.sleep(2)  # 2 Sekunden warten zwischen den Abfragen
            transaction = await client.transactions.get(client_tx_id)
            logging.info(f"Polling-Status für Transaktion {client_tx_id}: {transaction.status}")
            if transaction.status == "SUCCESSFUL":
                logging.info(f"✅ Zahlung {client_tx_id} erfolgreich!")
                return
            if transaction.status in ["FAILED", "CANCELLED"]:
                logging.warning(f"❌ Zahlung {client_tx_id} fehlgeschlagen oder wurde abgebrochen.")
                return

        # Wenn die Schleife ohne Ergebnis endet
        logging.warning(f"⌛ Timeout bei der Abfrage des Zahlungsstatus für {client_tx_id}.")
    except APIError as e:
        logging.error(f"Fehler bei der Kommunikation mit der SumUp API: {e.message}")
        logging.error(f"   HTTP Status Code: {e.status}")
        logging.error(f"   Antwort vom Server (Body): {e.body}")
    except Exception as e:
        logging.error(f"Ein unerwarteter Fehler ist aufgetreten: {e}")
:

Doing this results in an error.

2025-12-18 10:10:40,642 [INFO] - Warte auf Zahlungsstatus (Polling)...
2025-12-18 10:10:42,713 [INFO] - HTTP Request: GET https://api.sumup.com/v2.1/merchants/1297a595-a703-446f-84f1-002d43543f34/transactions "HTTP/1.1 403 Forbidden"
2025-12-18 10:10:42,715 [ERROR] - Fehler bei der Kommunikation mit der SumUp API: Unexpected response
2025-12-18 10:10:42,715 [ERROR] -    HTTP Status Code: 403
2025-12-18 10:10:42,715 [ERROR] -    Antwort vom Server (Body): {"type":"https://developer.sumup.com/problem/forbidden","detail":"Not allowed, subject \"user:b026ff1e...........\" doesn't have permission \"merchant_read\" for object \"merchant:1297a595-a........\".","instance":"3b890...........","status":403,"title":"Forbidden"}

By the way, would be easier, if you extend your python examples a little bit in Github.
Sumup Version used 0.0.15

[matoous]

Heya, upon a quick glance 1297a595-a703-446f-84f1-002d43543f34 is not a valid merchant code (in the call to /transactions). Merchant codes are usually ~8 characters long alphanumeric strings with uppercase letters and starting with M. I think you might need to update your code to:

    transaction = await client.transactions.get(merchant_code, GetTransactionV21Params(
                                client_transaction_id=client_tx_id,
                            ))

[ChrisCoder123]

Hi
i tried your code but no i got

2025-12-18 12:03:56,653 [INFO] - HTTP Request: GET https://api.sumup.com/v2.1/merchants/M0FV97S8/transactions?client_transaction_id=42e916a3-c83f-4764-9969-523d16077bf0 "HTTP/1.1 200 OK"
2025-12-18 12:03:56,660 [ERROR] - Ein unerwarteter Fehler ist aufgetreten: 1 validation error for TransactionFull
entry_mode
  Input should be 'BOLETO' or 'CUSTOMER_ENTRY' [type=literal_error, input_value='none', input_type=str]
    For further information visit https://errors.pydantic.dev/2.11/v/literal_error

Maybe this is correct because as i said i did a check-out on the Solo reader, and just polling the status, until it is conformed.
As i still do not have a transaction, i probably run in a pydantic error.
Thus I tried the following

checkout = await client.readers.create_checkout(
            merchant_code,
            solo.id,
            CreateReaderCheckoutBody(
                total_amount=CreateReaderCheckoutBodyTotalAmount(currency="EUR", value=100, minor_unit=2),
            ),
        )
        logging.info(f"DEBUG: Empfangenes Checkout-Objekt: {checkout}")      
       client_tx_id = checkout.data.client_transaction_id
        logging.info(f"Checkout gestartet. Client Transaction ID: {client_tx_id}")

        # 2. Status der Zahlung abfragen (Polling)
        logging.info("Warte auf Zahlungsstatus (Polling)...")
        for _ in range(30):  # Maximal 60 Sekunden warten
            await asyncio.sleep(2)  # 2 Sekunden warten zwischen den Abfragen
            status = await client.checkouts.get(client_tx_id)
            logging.info(f"Polling-Status für Checkout {client_tx_id}: {status.status}")

which results in

2025-12-18 12:15:56,528 [INFO] - Checkout gestartet. Client Transaction ID: 43d1f9fe-d9d8-4573-ae71-537c062a69bc
2025-12-18 12:15:56,528 [INFO] - Warte auf Zahlungsstatus (Polling)...
2025-12-18 12:15:58,593 [INFO] - HTTP Request: GET https://api.sumup.com/v0.1/checkouts/43d1f9fe-d9d8-4573-ae71-537c062a69bc "HTTP/1.1 404 Not Found"
2025-12-18 12:15:58,595 [ERROR] - Fehler bei der Kommunikation mit der SumUp API: Not Found
2025-12-18 12:15:58,596 [ERROR] -    HTTP Status Code: 404
2025-12-18 12:15:58,597 [ERROR] -    Antwort vom Server (Body): {"error_code":"NOT_FOUND","message":"checkout not found"}

With this approach it cannot find a checkout, however i am seeing it on the solo device?

[matoous]

We have just released v0.0.16 which fixes the payment_type enum: https://github.com/sumup/sumup-py/releases/tag/v0.0.16, could you please try again with this version? It should resolve this error:

2025-12-18 12:03:56,653 [INFO] - HTTP Request: GET https://api.sumup.com/v2.1/merchants/M0FV97S8/transactions?client_transaction_id=42e916a3-c83f-4764-9969-523d16077bf0 "HTTP/1.1 200 OK"
2025-12-18 12:03:56,660 [ERROR] - Ein unerwarteter Fehler ist aufgetreten: 1 validation error for TransactionFull
entry_mode
  Input should be 'BOLETO' or 'CUSTOMER_ENTRY' [type=literal_error, input_value='none', input_type=str]
    For further information visit https://errors.pydantic.dev/2.11/v/literal_error

[ChrisCoder123]

Hi ,
Still not working.

2025-12-19 09:02:19,557 [INFO] - Checkout gestartet. Client Transaction ID: 9c4379e4-bcfb-4cb4-8a1f-960336052cbd
2025-12-19 09:02:19,557 [INFO] - Warte auf Zahlungsstatus (Polling)...
2025-12-19 09:02:21,651 [INFO] - HTTP Request: GET https://api.sumup.com/v2.1/merchants/M0FV97S8/transactions?client_transaction_id=9c4379e4-bcfb-4cb4-8a1f-960336052cbd "HTTP/1.1 200 OK"
2025-12-19 09:02:21,654 [ERROR] - Ein unerwarteter Fehler ist aufgetreten: 1 validation error for TransactionFull
entry_mode
  Input should be 'BOLETO' or 'CUSTOMER_ENTRY' [type=literal_error, input_value='none', input_type=str]
    For further information visit https://errors.pydantic.dev/2.11/v/literal_error

I see 1 euro on me solo, and i can log a transaction_id Client Transaction ID: 9c4379e4-bcfb-4cb4-8a1f-960336052cbd.
However polling the status with

            transaction = await client.transactions.get(merchant_code, GetTransactionV21Params(
                                client_transaction_id=client_tx_id,
                            ))

Results in the above error.
Using sumup 0.0.16

[ChrisCoder123]

Hi,

i think i am narrowing your problem down.
I want to do 3 steps.

1. Doing a Chekcout on a solo (this works so far)
2. Pooling the status of the reader, to find out if the customer is doing anything (could be the case checkout was done, but no card was displayed)
3. Checking the status of the Checkout.

My guts feeling is with transaction you are refering to my step 3. As there is no transaction (i am still looking at the solo device seeing my 1.00 euro check-out, there is this error (which should be also not the case))

Thus i checked your source code a little bit and found show_reader_status. and i have implemented it

status = await client.readers.show_reader_status(merchant_code,solo.id)
to fullfill my step 2.

i gave a print of the return object into my logging.
Polling-Status für Checkout bb8ec247-d281-4d66-a77e-1b2b336f0374: data={'battery_level': 1.35, 'battery_temperature': 22, 'connection_type': None, 'firmware_version': '3.3.38.0', 'last_activity': '2025-12-19T08:47:55.304193', 'state': None, 'status': 'ONLINE'}
I am wondering why State =None, but at least i get a return object. However my intention is to monitor the device, until the card is placed in front of it.
According to your documentation, i should get
Supported States
* IDLE – Reader ready for next transaction
* SELECTING_TIP – Waiting for tip input
* WAITING_FOR_CARD – Awaiting card insert/tap
* WAITING_FOR_PIN – Waiting for PIN entry
* WAITING_FOR_SIGNATURE – Waiting for customer signature
* UPDATING_FIRMWARE – Firmware update in progress

    Device Status

    * `ONLINE` – Device connected and operational
    * `OFFLINE` – Device disconnected (last state persisted)

[ChrisCoder123]

And here another remark.
Now I tried,

1. Doing a Checkout on a solo (this works so far)
2. skipping polling, and I directly presented my card to the reader.
   Reader says "Zahlung erfolgreich"
3. Your code

            transaction = await client.transactions.get(merchant_code, GetTransactionV21Params(
                                client_transaction_id=client_tx_id,
                            ))

Now i would have expected i have a transaction, as the solo device says "Zahlung erfolgreich"
However also in this case error is.

2025-12-19 09:34:47,609 [INFO] - Warte auf Zahlungsstatus (Polling)...
2025-12-19 09:34:57,797 [INFO] - HTTP Request: GET https://api.sumup.com/v2.1/merchants/M0FV97S8/transactions?client_transaction_id=b852e2e4-c121-4325-b5ca-ede627848e87 "HTTP/1.1 200 OK"
2025-12-19 09:34:57,802 [ERROR] - Ein unerwarteter Fehler ist aufgetreten: 1 validation error for TransactionFull
entry_mode
  Input should be 'BOLETO' or 'CUSTOMER_ENTRY' [type=literal_error, input_value='contactless', input_type=str]
    For further information visit https://errors.pydantic.dev/2.11/v/literal_error

And now the final funny thing.
I logged in on the sumup merchant test portal. And here i see the transaction from 1,00 euro.

[matoous]

Sorry, I think my initial changes didn't address your issue, I think the latest version should have that fixed. I should have some time this week to test this on my side so either you can test again, or I will try to replicate and get back to you by the end of the week.

[ChrisCoder123]

No worries,
And do not forget we have X-mas this week, thus happy X-mas to the whole Sumup Team and my best wishes to everybody.

[ChrisCoder123]

Hi happy new year to everybody.
I just tried it today again, now wit sumup 0.0.20 but I have still the same behavior.
Any news?

[matoous]

I was able to replicate locally and it worked of me with the changes released in v0.0.21. The enums for the list transactions unfortunately had some discrepancies between the enums used in filtering (query params) and in the response schema(s).

[ChrisCoder123]

Hi
o.k. I changed back to the original approach, and using now 0.0.21.

1. I do a Reader Check-out. (Works fine, and I see 1 Euro on my device)
2. Now i Do a pulling and checking against the Transaction Status

            transaction = await client.transactions.get(merchant_code, GetTransactionV21Params(
                                  client_transaction_id=client_tx_id,
            ))
            if transaction.status == "SUCCESSFUL":
:

Now I see the Transaction Status in Pending, as long as the customer is not presenting his card. If card is presented Status is successful, if card is not presented, solo device breaks after a while and status is "Failed".

Thus this works fine for me. Issue can be closed.

However I have sometimes the problem that i receive a 404 error retrieving the transaction, i put this in a try, catch thus this works also for me. But maybe somebody else might have the problem.

Second i am wondering what happens if card needs to be inserted, because I have not found any status in the transaction about inserting cards.

[VitorVRS]

However I have sometimes the problem that i receive a 404 error retrieving the transaction, i put this in a try, catch thus this works also for me. But maybe somebody else might have the problem.

This is a known problem that is going to be fixed this year. We highly recommend the usage of webhooks, because you will get the accurate status of the transaction even if Transaction API returns 404.

Second i am wondering what happens if card needs to be inserted, because I have not found any status in the transaction about inserting cards.

Can you elaborate more? When card is inserted, state will be WAITING_FOR_PIN

[ChrisCoder123]

However I have sometimes the problem that i receive a 404 error retrieving the transaction, i put this in a try, catch thus this works also for me. But maybe somebody else might have the problem.

This is a known problem that is going to be fixed this year. We highly recommend the usage of webhooks, because you will get the accurate status of the transaction even if Transaction API returns 404.

Webhook might be a little complicated on my side due to local network restrictions, That´s why I am doing polling every 2 seconds. However I might be able to move this into the cloud, than Webhook should be possible.
But i checked the documentation from your side and i only found https://developer.sumup.com/online-payments/webhooks#_top about this topic. According to this I would have to give you my Webhook URL during readers checkout but there is no security token registered. Which, besides my network issues, concerns me a little bit.
Any plans to exchange security tokens in the future, or was this a misunderstanding from my side, and i did not find the security token?

Can you elaborate more? When card is inserted, state will be WAITING_FOR_PIN

I see the following scenarios.

1. Scenario:

• Check-out created, Card is presented (with a tap) and transaction is done "Successfull" or "Failed" or "Canceled".

2. Scenario:

• Check-out Created, Card is presented (with a tap) and Pin is from Sumup requested. Transaction has status "WAITING_FOR_PIN". Customer can enter pin on device.

3. Scenario (which I am refering to)

• Check-out Created, Card is presented and Sumup requests to insert card into the slot. (i have seen this once in a shop). If transaction has status "WAITING_FOR_PIN" there would be no difference to Scenario 2.

As i am steering a couple of Solo devices remotly, I would not recognize the difference, between customer is not entering the Pin (scenario 2) or customer is not entering the card into the slot.

And finally I have seen a software update request yesterday on my solo device (I switched the device on again).
Do you push the update automatically to the devices or does the device pull always for new versions when it is swiched on, or can i somehow prevent these update requests on the solo device.
Would be a little bit odd, if the customer would see an update request on the solo device remotely.

[VitorVRS]

The webhook URL is informed in the return_url on the Reader Checkout endpoint.

But i checked the documentation from your side and i only found https://developer.sumup.com/online-payments/webhooks#_top about this topic

This section is going to be revamped. As of now documentation is not really complete, sorry about that.

Any plans to exchange security tokens in the future, or was this a misunderstanding from my side, and i did not find the security token?

The security token is already mapped on our backlog, but I can't give you an estimation on when would be ready.

Well, looks like webhooks is not really suitable for you, given all the issues you mentioned. I would stick with the polling, even though 404s might happen.

---

As i am steering a couple of Solo devices remotly, I would not recognize the difference, between customer is not entering the Pin (scenario 2) or customer is not entering the card into the slot.

We don't have a specific state for "INSERT_CARD", if device is waiting for a card the state will be "WAITING_FOR_CARD", regardless if consumer already tapped. This feature is really new and you are one of the first users of it. We are still monitoring the usage, gathering feedback in order to improve it.

---

And finally I have seen a software update request yesterday on my solo device (I switched the device on again).
Do you push the update automatically to the devices or does the device pull always for new versions when it is swiched on, or can i somehow prevent these update requests on the solo device.
Would be a little bit odd, if the customer would see an update request on the solo device remotely.

Regarding the update, it happens in 2 steps:

• Whenever there is a new update, device will download it in background
• When device detects inactivity (e.g 5 minutes), it will install the update and reboot itself.

As of now, it is not possible to disable this behavior

[ChrisCoder123]

Thanks so far.