PhonePOS API Error Codes

This page is the canonical reference for shared status codes and terminal error codes used across the low-level and high-level PhonePOS APIs.

Primary Status Codes

These are the top-level status code returns by our APIs.

Code	Name	Description
`0`	`STATUS_TERMINAL_OPERATIONAL`	The terminal is operational and ready for payments.
`1`	`STATUS_PERSONALIZATION_NOT_DONE_YET`	The terminal has not been personalised yet.
`2`	`STATUS_TERMINAL_NOT_OPERATIONAL`	The personalisation generally finished, but there are still issues that prevent full operation.
`3`	`STATUS_PERSONALIZATION_IN_PROGRESS`	The personalisation is currently in progress.
`100`	`STATUS_PERSONALIZATION_FAILED`	The personalisation failed.
`102`	`STATUS_APP_IS_OUTDATED`	PhonePOS must be updated first.

Terminal Error Codes

Depending on the API response, you may also receive one of the following terminal error codes. Error codes are classified as either General (🌎) or Personalisation (▶️). During Personalisation you need to handle both scopes. During startup and regular operation you only need to handle the General error codes.

Filter: All (🌎 + ▶️) Only General (🌎)

Code	Name	Description	Recommended Action	Scope
`0100`	`INVALID_JSON`	The received provided JSON does not meet the required format specifications or is missing parts.	Please check the format of the data you provided to PhonePOS.	Personalisation ▶️
`0117`	`INVALID_CREDENTIAL_FORMAT`	The received personalisation data does not meet the required format specifications or is missing parts.	Please check the format of the data you provided to PhonePOS.	Personalisation ▶️
`0120`	`OTP_TYPE_NOT_AVAILABLE`	The requested personalisation type is not available for the supplied credentials.	Please re-onboard the terminal with your required personalisation type or switch to a supported personalisation type.	Personalisation ▶️
`0121`	`RESEND_LIMIT_EXCEEDED`	The quota for sending the confirmation challenge has been reached.	Please advise your client to wait.	Personalisation ▶️
`0222`	`NETWORK_UNSTABLE`	The device connection is unstable.	Instruct the user to establish a stable connection first.	General 🌎
`0300`	`NETWORK_UNAVAILABLE`	An internet connection could not be established.	Instruct the user to establish a stable connection first.	General 🌎
`0504`	`SMS_SENDING_FAILED`	Errors occurred while sending the confirmation challenge via SMS.	It is likely that the configured phone number for the terminal is incorrect. Please contact our support.	Personalisation ▶️
`0511`	`EMAIL_SENDING_FAILED`	Errors occurred while sending the confirmation challenge via mail.	It is likely that the configured mail address for the terminal is incorrect. Please contact our support.	Personalisation ▶️
`0512`	`EMAIL_VERIFICATION_TIMEOUT_SERVER`	The user did not react to the confirmation challenge in time.	Please restart the personalisation and advise the user to complete the challenge as soon as possible.	Personalisation ▶️
`0614`	`INVALID_CREDENTIALS`	The provided authentication credentials are invalid.	Advise the user to check the credentials and try the personalisation again.	Personalisation ▶️
`2310`	`BATTERY_TOO_LOW`	The battery level is too low for personalisation (<=15%) or transaction (<=10%).	Instruct the user to charge the device first.	General 🌎
`2311`	`INTERNAL_TERMINAL_CONNECTION_TIMEOUT`	The connection to the terminal could not be established.	Please contact support for further instructions.	General 🌎
`2314`	`CANCELLED_BY_USER`	The user canceled the personalisation process by performing a manual reset.	Advise the user to start the personalisation again.	Personalisation ▶️
`2316`	`PHONEPOS_ALREADY_PERSONALISED`	The terminal is already personalised.	Perform a reset first if you want to start a new personalisation.	Personalisation ▶️
`2317`	`PERSONALISATION_NOT_ALLOWED`	The request for personalisation was rejected.	Please contact support for further instructions.	Personalisation ▶️
`2318`	`EMV_UPLOAD_DENIED_FOR_SECURITY_REASONS`	The OPI init with EMV upload was blocked for security reasons.	The device is not compliant. Please contact our support.	General 🌎
`2319`	`EMV_UPLOAD_FAILED`	The OPI init with EMV upload was not successful.	Ensure that the merchant's firewall does not block PhonePOS traffic. If the error persists, please contact our support.	General 🌎
`2321`	`INVALID_OTP_TYPE`	The requested OTP confirmation service type is unknown to the terminal.	Please check the values you submitted for the personalisation.	Personalisation ▶️
`2322`	`INVALID_ATTESTATION_PROVIDER_REQUEST`	The requested attestation provider is unknown to the terminal.	Please check the values you submitted for the personalisation.	Personalisation ▶️
`2323`	`CANCELED_BY_TERMINAL_HELPER`	The personalisation was canceled through a call from the terminal helper service.	Instruct the user to retry the personalisation. If the error persists, please contact our support.	Personalisation ▶️
`2324`	`CANCELED_BY_ATTESTATION`	The personalisation was canceled through a reset action which was transmitted by the attestation service.	Instruct the user to retry the personalisation. If the error persists, please contact our support.	Personalisation ▶️
`2325`	`INSECURE_KEYSTORE`	The device keystore is insecure. The device is incompatible with PhonePOS.	Inform the user that the device cannot be used for PhonePOS.	General 🌎
`2527`	`CERTIFICATE_ERROR`	An error occurred during the mTLS handshake process. This is often caused by an inaccurate device clock or deep package inspection in the network.	Instruct the user to adjust the time of the device. If the error persists, please contact our support.	General 🌎
`2602`	`BAD_HTTP_CODE`	The server responded with an unexpected HTTP code.	Please contact our support.	General 🌎
`2604`	`INVALID_CRYPTO_STATUS`	Payload decryption failed on the server side or on the client side.	Please contact our support.	General 🌎
`2605`	`INVALID_API_STATUS`	The backend service could not process the request and returned a non-OK API response.	Please contact our support.	General 🌎
`2610`	`SERVER_TOO_BUSY`	The backend servers are currently under high load.	Please contact our support.	General 🌎

Java Enum

When you use the Low-Level API this ENUM will help you to process the error codes correctly.
When you use the High-Level PhonePOS API, this ENUM is already included in the library.

public enum TerminalErrorCode {
    INVALID_JSON("0100"),
    INVALID_CREDENTIAL_FORMAT("0117"),
    OTP_TYPE_NOT_AVAILABLE("0120"),
    RESEND_LIMIT_EXCEEDED("0121"),
    NETWORK_UNSTABLE("0222"),
    NETWORK_UNAVAILABLE("0300"),
    SMS_SENDING_FAILED("0504"),
    EMAIL_SENDING_FAILED("0511"),
    EMAIL_VERIFICATION_TIMEOUT_SERVER("0512"),
    INVALID_CREDENTIALS("0614"),
    BATTERY_TOO_LOW("2310"),
    INTERNAL_TERMINAL_CONNECTION_TIMEOUT("2311"),
    CANCELLED_BY_USER("2314"),
    PHONEPOS_ALREADY_PERSONALISED("2316"),
    PERSONALISATION_NOT_ALLOWED("2317"),
    EMV_UPLOAD_DENIED_FOR_SECURITY_REASONS("2318"),
    EMV_UPLOAD_FAILED("2319"),
    INVALID_OTP_TYPE("2321"),
    INVALID_ATTESTATION_PROVIDER_REQUEST("2322"),
    CANCELED_BY_TERMINAL_HELPER("2323"),
    CANCELED_BY_ATTESTATION("2324"),
    INSECURE_KEYSTORE("2325"),
    CERTIFICATE_ERROR("2527"),
    BAD_HTTP_CODE("2602"),
    INVALID_CRYPTO_STATUS("2604"),
    INVALID_API_STATUS("2605"),
    SERVER_TOO_BUSY("2610");

    private final String code;

    TerminalErrorCode(String code) {
        this.code = code;
    }

    public String getCode() {
        return code;
    }

    public static TerminalErrorCode fromCode(String code) {
        for (TerminalErrorCode value : values()) {
            if (value.code.equals(code)) {
                return value;
            }
        }

        return null;
    }

    public static TerminalErrorCode fromCode(int code) {
        return fromCode(String.format(java.util.Locale.ROOT, "%04d", code));
    }
}

Primary Status Codes

Terminal Error Codes

Java Enum​

Java Enum