Troubleshooting

A payment or refund shows Result unknown

1. Open History, filter by Needs attention and open the original payment or refund.
2. Tap Check result again. For a terminal, the app asks it for that transaction's outcome.
3. If the result is still unknown, find the payment in Customer Area › Payments › Payment list by reference, time and amount. Decide what to do only after checking.

A crash or restart leaves the interrupted operation in History as unknown. Do not clear the app's data to remove it.

With Tap to Pay, Check result again first uses a received late answer, then asks the selected Payments app for the original result. Status checks require version 1.8.0 or later; confirm beta access with Adyen. A missing callback or NotFound leaves the result unknown. Check Customer Area › Payments › Payment list before charging again.

Back to contents

A payment is declined or not processed

The result screen shows the status, Adyen's reason and advice. Follow the advice:

“Do not retry with this card. Ask the shopper for a different card or payment method.”

FixAsk for another card or payment method. The customer's bank can explain the refusal; the Adyen refusal reasons explain the reason shown.

Cause

The card issuer refused this card for a reason that will not change, such as a blocked or restricted card or suspected fraud, or the card is not allowed for this payment.

“You can try again.”

FixTap Try again, or ask for another card.

Cause

The payment was canceled, the PIN was wrong, or the card was refused for a reason that may not repeat, such as insufficient funds.

“The terminal is busy with another transaction or its admin menu.”

FixFinish the other payment or leave the menu, then try again. If the screen offers Cancel the terminal’s current transaction, use it only to stop that transaction, and check its result before retrying.

Cause

The terminal is handling another payment or showing its admin menu.

“The terminal is not available right now.”

FixWait a moment, check that the terminal is on and connected, then try again. See network dropouts.

Cause

The terminal or its card reader is temporarily unavailable.

“The terminal did not accept the request. Check the Terminal settings before trying again.”

FixRun the tests in Settings › Terminal; see pairing and setup. If they pass, ask Adyen to check the terminal's configuration.

Cause

The terminal rejected the request as sent, usually because of a setup problem.

“The terminal or your Adyen account doesn’t support this request. Ask Adyen Support to check it’s enabled, then try again.”

FixAsk Adyen Support to check that it is enabled for the merchant account. For Tap to Pay, check that Tap to Pay on Android is enabled, not only the Adyen Payments App role. Then try again.

Cause

The terminal or Adyen does not offer what the payment asked for, often because it is not enabled for the account.

“Do not charge again: this payment went through.”

FixDo not charge again. Refund it if the customer should not pay.

Cause

The payment was approved even though the terminal reported a cancellation.

Back to contents

An optional terminal feature is missing or totals differ

A terminal feature is missing or rejected

Check the selected destination and Adyen capabilities, refresh its settings, and confirm the API roles and Adyen account configuration. Local checkout switches alone do not enable a service at Adyen. Tap to Pay does not offer the physical-terminal workflows. For tips, compare terminal tipping with receipt tipping.

Only part of the amount was approved

Follow the partial-payment workflow from the result screen. Do not charge the full original total again. If a later attempt's result is unknown, resolve it before collecting more.

Terminal totals do not match Mini mPOS

Review the terminal period, other devices using that terminal, retained local history and unresolved transactions in terminal reconciliation. Closing the period does not fix differences or confirm settlement.

An offline sale has no PSP reference or unconfirmed batches remain

Follow offline-payment checks. Restore the terminal's connection to Adyen and verify its uploaded payments in the Customer Area. Do not collect an approved payment again just because its PSP reference is missing.

Back to contents

Scan wallet is missing or scanning fails

No Scan wallet button

Open Settings › Terminal and tap Refresh scanned wallets. A successful check with no eligible POS wallets leaves the button hidden. Check the assigned store, current currency and API key roles. Tap to Pay and pre-authorizations do not offer this action.

Wallet discovery reports an error

The error appears only in Settings and does not block card payments. Fix the credential, environment or read access there, then refresh. A temporary failure keeps the last verified wallets.

The code is invalid or no code arrives

Use the shopper’s payment code, not a profile, transfer or receipt QR, and choose the correct wallet. A terminal scan ends after 30 seconds: tap Scan again or Use camera.

Saving is rejected or no token is created

An approved payment stays approved without a saved token. After a rejection, turn off Save card and scan again if appropriate. For Result unknown, check the original transaction instead.

See the wallet payment procedure.

Back to contents

Pairing or setup fails

Start with the message on Home, then open Settings › Terminal and complete the final Test connection step. This verifies API access and the connection checks supported by your integration. Network and cloud setup use Find terminal to set up to test API access and list terminals; Test API is offered for on-device terminals and Tap to Pay. For the full steps, see Connect to Adyen.

For any integration, open Settings › Help and troubleshooting › Troubleshooting details. Results include setup gaps, API access, supported connection checks, timestamps and device details; unsupported checks are identified. These checks do not prove that payments, refunds or printing will succeed and do not take payments, register phones or change keys. Use Share redacted report to share the displayed details: merchant, terminal, installation and credential IDs remain; secrets, unstructured messages and shopper data are excluded.

Home says “Payments aren’t set up yet”

FixTap Finish setting up payments. In Settings › Terminal, enter what is missing, or enter the key again, then tap Test connection.

Cause

A required field is empty, a saved key could not be read on this device, or no connection test has passed since the setup changed. Until then, payments, refunds, printing and other Adyen actions explain this instead of running.

The API test fails or setup reports an access problem

FixCheck the credential's roles and access against the credential requirements. For LIVE, check the Live URL prefix.

Cause

The API key, merchant account or live URL prefix is wrong, a role is missing, or the credential is from another company account or environment.

“The merchant account does not match this terminal’s current assignment.”

FixEnter the merchant account that the terminal is assigned to, or reassign the terminal in the Customer Area.

Cause

The terminal is assigned to a different merchant account at Adyen.

The connection test fails on an Adyen terminal or network terminal

FixCompare the shared key's identifier, passphrase and version with the Customer Area. For a network terminal, check the IP address and POIID on the terminal's Device info screen.

Cause

The shared key does not match, or the IP address or Terminal ID (POIID) is out of date.

The connection is rejected because of the environment

FixFor a network/cloud terminal or Tap to Pay, check Environment in Settings › Terminal. On an Adyen terminal, use a device from the right environment.

Cause

TEST and LIVE are mixed: the terminal, account and API key must all be from one environment.

A cloud terminal cannot be reached

FixCheck that the terminal is on and online, then check the POIID and the credential's roles.

Cause

The terminal is offline, the POIID is wrong, or the API key lacks the Cloud Device API role.

The selected Payments app is missing

FixCheck Settings › Terminal › Environment and install the matching app from Google Play. Both apps can stay installed. Finish registration and enter the matching shared key; confirm with a TEST payment.

Cause

The Payments app for the selected TEST or LIVE environment is not installed.

Tap to Pay returns UnavailableService before card presentation

The Payments app could not complete the request. This generic error does not prove an Adyen outage or a missing client key.

Run Test connection in Settings › Terminal. For a compact table of checks and a redacted report, expand Settings › Help and troubleshooting › Troubleshooting details.

Set up Tap to Pay automatically provisions the registration credential and client key using your primary API key. Check its required roles if provisioning is denied. Allow a few minutes for new keys to propagate, then run Test connection again. If recovery still fails, retry later or ask Adyen Support to inspect the matching TEST Customer Area or LIVE Customer Area. See the Adyen Payments app requirements.

The client key must belong to the same credential used for boarding. When asking for help, use Share redacted report.

“The new key is saved. Update this terminal’s config”

FixOn the terminal, open Admin menu › Config › Update, then return to Mini mPOS and tap Check again. If creation was interrupted, tap Resume key setup; it does not create a second key. See key creation and the Adyen configuration update guide.

Cause

The encryption key was created at Adyen, but the terminal has not loaded it yet.

Actions on an older payment are blocked

FixRestore the setup that took the payment, or handle it in the Customer Area. Do not process it under another account.

Cause

The merchant account, environment or terminal changed after that payment.

Back to contents

The connection drops or the terminal does not answer

“The terminal did not answer”, or a network terminal works only sometimes

Fix

1. Check the terminal's IP address on its Device info screen and update it in Settings › Terminal.
2. Connect the device and terminal to the same network. Avoid guest Wi-Fi, which often isolates devices.
3. Ask the network administrator to allow TCP 8443 between them and to reserve the terminal's IP address; see network requirements.

Cause

The terminal's IP address changed, the device moved to another network, or the network blocks the connection.

Payments or API tests fail on every setup

FixCheck the internet connection, then make sure HTTPS on TCP 443 to Adyen's domains is allowed.

Cause

The device or terminal has no internet access, or a firewall blocks Adyen.

Cloud payments time out

FixCheck the terminal's Wi-Fi, Ethernet or mobile data, then run Test connection.

Cause

The terminal lost its internet connection.

Back to contents

A capture or adjustment failed or is unknown

Open the original entry in History and read its reason. If Checkout API setup is missing, complete it; if the account or environment changed, restore the original one.

Capture failed or Capture result unknown

FixTap Retry capture. It resends the same capture safely; do not create a new payment.

An amount adjustment is unresolved

FixRetry with the same amount. A different amount is a separate request and may be blocked until the first is resolved.

A tip was not saved

FixEnter a smaller tip, or tap No tip.

Cause

The card issuer refused to increase the hold for a tip over 20%.

Capture requested or Refund requested does not change

FixCheck the final outcome in the Customer Area.

Cause

These mean Adyen accepted the request. Mini mPOS has no server, so it never receives the final confirmation.

Holds expire, so resolve these promptly. For the normal steps, see deposits and tips on the receipt.

Back to contents

Payment links are missing or not updating

Checkout has no Create payment link

FixComplete Checkout API setup in Settings › Terminal. Links are offered for sales only. The simulator offers demo links without setup.

Cause

Checkout API setup is incomplete, or the checkout is for a pre-authorization or a tip on the receipt.

A paid link still shows Awaiting payment

FixOpen the entry in History and tap Check payment.

Cause

The app checks only while the link screen is open.

Creating a link was interrupted

FixOpen the original entry and tap Check payment. It retries with the original request; do not create another sale just to get a link.

Refund paid links in Customer Area › Payments › Payment list.

Back to contents

The printer or email receipts do not work

Nothing prints, or Print receipt is missing

Fix

1. In Settings › About, check that Printer shows Available. If not, run Test connection in Settings › Terminal.
2. In Settings › Receipts, set Printer to Detect automatically and check Print automatically.
3. Tap Print test receipt. If nothing prints, check the terminal's paper roll.

Cause

The terminal has no printer, the printer was not detected, or the connection is down. AMS1 terminals and Tap to Pay phones have no printer.

The layout is cut off or wraps badly

FixChange Characters per line in Settings › Receipts and print a test receipt.

The test email fails

FixIn Settings › Email receipts, check the server, port, STARTTLS or SSL/TLS, username and password. Your provider may require SMTP access to be turned on or an app password; see email setup.

Cause

Wrong server, port, security or password, or the provider blocks SMTP or password login.

Test emails work, but customers get no receipt

FixIn Settings › Email receipts, check when the email is asked for and whether receipts are sent automatically.

Logo did not print

Check the preview in Settings › Receipts and print a test receipt. If the terminal refuses the logo, Mini mPOS can still print the receipt text and shows a notice on the first refusal. Paper problems, a missing printer or an unanswered print request stop printing. See receipt logo settings to try a simpler image or remove the logo.

Back to contents

PIN and setup transfer problems

Staff forgot the Manager PIN

FixAn administrator can replace or remove it in Settings › Security. The admin PIN and Manager PIN protect different actions; one does not unlock the other.

The admin PIN is forgotten

CauseThere is no PIN recovery.

To start again without the admin PIN, follow storage recovery. Read the data-loss warning before resetting.

The transfer code is rejected, or keys are missing after import

FixUse the code shown with these QR codes, not a newly generated one. Every transfer needs its code. A wrong or blank code imports nothing. After copying, check the destination and credentials on the new device; see more devices.

Cause

The code does not belong to these QR codes, or it was left blank.

To review which actions each PIN protects, see staff PINs.

Back to contents

Saved settings or credentials cannot be read or written

Mini mPOS stops rather than replacing unreadable settings or credentials. This preserves the files, including any unfinished setup or payment recovery records.

1. Restart the device and open Mini mPOS again. If device storage is full, free space outside Mini mPOS first. Clearing only the app's cache does not reset its saved settings.
2. Before resetting, keep the records you need and resolve unfinished payments, refunds, captures and adjustments. If the app cannot open, check their outcomes in the Customer Area; see unknown results. If an outcome is still uncertain, keep the app's data and reconcile it with Adyen first. Do not send the operation again just because the app cannot open.
3. If the error persists and you accept losing all local data, reset Mini mPOS. On a phone or tablet, open Android Settings › Apps › Mini mPOS › Storage & cache › Clear storage (labels vary by device), or uninstall Mini mPOS and reinstall it from the latest release. On an Adyen terminal, have the person managing your terminal apps arrange the reset or removal and reinstallation; see the Adyen app deployment guide .
4. Set up Mini mPOS again, or import a trusted setup transfer, then complete Test connection before taking real payments. See Connect to Adyen.

Installing an update over the existing app does not reset its storage. If the error returns, report an app problem on GitHub; do not attach saved configuration files or credentials.

Back to contents

The app does not install on a terminal

INSTALL_PARSE_FAILED_NO_CERTIFICATES

FixUpload the signed minimpos-<version>.apk from the latest release.

Cause

The APK is unsigned.

INVALID_SIGNING_CERTIFICATE_MISMATCH

FixKeep the original signing source. If you need to change it, ask Adyen Support about removing earlier versions.

Cause

The APK is signed with a different key from earlier uploads.

The Android version is not supported

FixUse a supported terminal; see installation.

Cause

Mini mPOS needs Android 9 or later; the older S1E runs Android 7.1.

Back to contents

An error message names a problem

Each message names the problem and what to check. Details in brackets, such as an IP address, an HTTP status or Adyen’s own words, help Adyen support: include them when you ask for help. If a payment was in progress, check its result before you fix anything else.

Back to contents

Still need help?

For Adyen accounts, terminal deployment, payment methods or final payment outcomes, contact Adyen. For an app problem, open a GitHub issue with the app version, device model, setup, TEST or LIVE environment and the steps to reproduce.

Back to contents