Error reference

Errors can occur at different stages of the payment process.

Some errors prevent your application from communicating with ICEPAY, while others occur later during the customer payment flow or when ICEPAY sends an update back to your integration.

The first step is to determine what type of issue you are dealing with.

Error types at a glance

Payment

The API request succeeded, but the customer payment did not complete as expected.

Check the payment status and the payment details in the ICEPAY Portal.

API

Your application sent a request to the Checkout API and ICEPAY returned an HTTP error response.

Developers should inspect the HTTP status and response body.

Webhook

ICEPAY attempted to send a payment update to your webhookUrl, but the update could not be delivered or be processed successfully.

Configuration

The merchant, payment method, credentials, environment, or integration configuration is preventing the expected payment flow.

Using a ready-made integration?

Most API and webhook communication is handled by the integration automatically.

If you use WooCommerce, Magento, PrestaShop, or another ready-made integration, start by checking the payment and order in your store and the ICEPAY Portal.

You generally do not need to troubleshoot raw API requests unless you are developing or maintaining the integration yourself.

API Errors

When the Checkout API cannot process a request successfully, it returns an HTTP error response.

The HTTP status indicates the general type of problem, while the response body can contain additional information about what went wrong.

Use the status code to determine how your integration should handle the error, then inspect the response body for more specific details.

API errors are different from payment failures

An API error means there was a problem with the request itself or while ICEPAY was processing it.

A payment that was created successfully can still later be cancelled, expire, remain pending, or fail during the customer payment flow. These situations are represented by the payment lifecycle rather than by an API error.

API response codes

The Checkout API uses standard HTTP response codes to indicate whether a request succeeded.

HTTP status	Meaning
200–299	The request was successful.
400	The request is invalid.
401	Authentication failed.
404	The requested resource could not be found.
422	The request was understood but could not be processed.
500	An unexpected server-side error occurred.

HTTP success does not mean payment success

A successful API response means ICEPAY successfully handled the API request.

It does not necessarily mean that the customer has completed the payment.

Use the payment’s status to determine where the payment is in its lifecycle.

400 — Invalid request

A 400 Bad Request means that ICEPAY cannot accept the request as submitted.

Common things to check include:

• the request body is valid JSON;
• all required fields are present;
• field names are spelled correctly;
• values use the expected data type;
• amounts are provided in minor currency units;
• URLs meet the documented requirements;
• values such as currency and payment method are supported.

For example, payment amounts must be integers in minor currency units:

{
  "amount": {
    "value": 299,
    "currency": "eur"
  }
}

This represents €2.99.

Do not send:

{
  "amount": {
    "value": 2.99,
    "currency": "eur"
  }
}

Check URLs

When supplied, redirectUrl and webhookUrl must use HTTPS.

For example:

https://merchant.example.com/payment-complete

rather than:

http://merchant.example.com/payment-complete

Check the API request structure

If you are unsure about a request field, start with the Checkout API overview and open the guide for the operation you are using. Compare your request with its schema and available fields.

401 — Authentication failed

A 401 Unauthorized response means ICEPAY could not authenticate the API request.

The Checkout API uses HTTP Basic Authentication:

username: Merchant ID
password: Merchant Secret

Check that:

• you are using the correct Merchant ID;
• you are using the Merchant Secret belonging to that merchant;
• the Authorization header is being sent;
• your HTTP client is using Basic Authentication;
• the credentials do not contain accidental whitespace or formatting changes.

Never expose your Merchant Secret

Keep the Merchant Secret on your server.

Do not include it in browser JavaScript, frontend source code, mobile applications, logs, screenshots, or public repositories.

If you regenerate or change credentials, make sure your integration uses the current values.

404 — Resource not found

A 404 Not Found response means the requested resource could not be found.

For payment operations, first check the ICEPAY payment key.

For example:

pi-01j1ps8zf4jgnk0c3dnd477sp1

Make sure:

• the key was copied correctly;
• you are using the correct endpoint;
• the payment belongs to the merchant whose credentials you are using;
• you are not accidentally using your own order reference where an ICEPAY payment key is required.

For example:

GET /api/payments/{key}

expects the ICEPAY payment key:

GET /api/payments/pi-01j1ps8zf4jgnk0c3dnd477sp1

not:

GET /api/payments/ORD-16307

422 — Request cannot be processed

A 422 Unprocessable Entity response means ICEPAY understood the request, but the requested operation cannot be completed with the supplied data or in the current situation.

Review:

• the values in the request;
• the state of the payment;
• restrictions of the operation;
• the amount being requested;
• whether the required feature is available for the account.

For example, some operations have additional requirements.

Payment forwarding requires the original payment to have:

financialStatus: cleared

A refund also needs to be valid for the original payment and available refundable amount.

Read the response body

When ICEPAY returns an error response, inspect the response body as well as the HTTP status.

It may contain additional information about why the request could not be processed.

500 — Server error

A 500 Internal Server Error indicates an unexpected problem while ICEPAY was processing the request.

First confirm that your request follows the documented API structure.

If the request is valid and the error continues, contact the ICEPAY team.

Include information that helps identify the request, such as:

• your Merchant ID;
• your order or payment reference;
• the ICEPAY payment key, when available;
• the endpoint you called;
• the HTTP status;
• the approximate date and time of the request;
• the error response, if one was returned.

Do not include your Merchant Secret or Authorization header.

Error response bodies

API error responses can contain additional information about the problem.

For example:

{
  "message": "Invalid request.",
  "errors": {}
}

The exact contents can differ depending on the endpoint and error.

Your integration should primarily use the HTTP response status to determine the error category and use the response body to provide additional diagnostic information.

Log identifiers, not secrets

When logging API failures, useful values include the ICEPAY payment key, your own order reference, the HTTP status, endpoint, and safe parts of the response.

Never log the Merchant Secret or complete Authorization header.

Payment errors

An unsuccessful customer payment is different from an API error.

For example, your application may successfully create a payment:

POST /api/payments → 201 Created

but the customer can later:

• cancel checkout;
• leave checkout without paying;
• have their payment declined;
• remain in a pending payment flow;
• allow the payment to expire.

These situations are represented through the payment lifecycle rather than through the original API response.

started

Checkout can still continue.

pending

The final payment result is not yet known.

completed

The payment completed successfully.

expired

The payment expired before completing.

cancelled

The payment was cancelled.

For more information about these states, see the Payment lifecycle page.

Payment-method errors

Some payment failures originate from the payment method rather than from the ICEPAY Checkout API.

For example, a card payment can be rejected by the card issuer.

For card payments, common payment errors can be viewed in the ICEPAY Portal.

If the available information does not explain why the card payment failed, contact the ICEPAY team for more detailed information.

Do not treat every failed payment as a technical error

A technically correct integration can still have unsuccessful payments.

The customer, bank, issuer, or payment provider can reject or interrupt the payment after the payment was successfully created in ICEPAY.

Webhook errors

ICEPAY sends payment updates to the webhookUrl configured when the payment is created.

Webhook delivery is server-to-server and does not depend on the customer’s browser.

If ICEPAY cannot reach your webhook endpoint or the webhook cannot be delivered successfully, payment updates may not reach your application.

“Error detected during postback”

ICEPAY may send you an email with the subject:

Error detected during postback

In this email, postback means a webhook. The message indicates that ICEPAY attempted to send a payment status update to your server but was unable to reach it successfully.

Your developer should investigate the webhook endpoint and server configuration.

Check your webhook endpoint

Confirm that:

• the URL is publicly reachable;
• the URL uses HTTPS;
• the endpoint accepts POST requests;
• your firewall or security rules do not block the request;
• the server does not require browser authentication;
• the endpoint returns a successful HTTP response after processing the update.

For example:

https://merchant.example.com/payment-webhook

Check webhook signature validation

Checkout API webhooks contain the:

ICEPAY-Signature

header.

The signature is generated using the raw JSON request body and your Merchant Secret.

If your application verifies the signature after your framework has modified or re-encoded the JSON body, signature validation can fail.

Verify the raw request body

Keep access to the original request body and verify the signature before processing the webhook payload.

Do not recreate or re-serialise the JSON before calculating the expected signature.

Firewall and allow-listing

Security rules can prevent ICEPAY from reaching your webhook endpoint.

If your infrastructure restricts incoming requests, confirm that it allows ICEPAY webhook traffic.

If your organisation requires IP-based allow-listing, contact the ICEPAY team for the current server information.

Avoid permanently depending on an old IP list because infrastructure can change.

Webhook received more than once

Your webhook implementation should be safe when the same payment state is received more than once.

This is known as idempotent webhook processing.

For example:

1. Find the payment

   Locate the payment using its ICEPAY payment key.

2. Check your stored state

   Compare the incoming payment state with the state already stored.

3. Update when necessary

   Store the latest status and financial status.

4. Trigger business actions only once

   Do not ship the same order, send the same confirmation, or perform another irreversible operation twice.

Receiving a duplicate update should not cause duplicate business actions.

Customer returned, but the order was not updated

The customer redirect and the webhook are separate mechanisms.

The customer can return to your website before the webhook has been processed.

The opposite can also happen: ICEPAY can successfully update your backend even if the customer closes their browser and never returns.

The redirect is not your source of truth

Use webhooks for backend payment updates.

Use the customer return primarily to continue the customer experience and display the latest known payment result.

If you need a fresh payment state when the customer returns, retrieve the payment once using:

GET /api/payments/{key}

Do not repeatedly poll this endpoint for ongoing payment monitoring.

Use webhooks for ongoing updates.

Test mode and Live mode

Every merchant has a processing mode.

Test

Used to test your integration without processing real payments.

New merchants start in Test mode.

Live

Used to process real customer payments after the merchant has been approved and switched to Live mode.

If your integration behaves differently than expected, confirm which merchant and processing mode you are using.

Test payments are shown separately from live payments in the ICEPAY Portal.

Test availability does not guarantee live availability

Payment methods can be available while testing but may still require activation or configuration before they can be used for live payments.

Ready-made integration errors

If you use an ICEPAY plugin or ready-made integration, first determine whether the problem is:

• creating the payment;
• redirecting the customer;
• updating the order after payment;
• a particular payment method;
• configuration of the ICEPAY merchant.

Check:

• that the correct merchant is configured;
• whether the merchant is in Test mode or Live mode as expected;
• whether the required payment method is enabled;
• whether the related payment exists in the ICEPAY Portal;
• whether the order has the ICEPAY payment key and your own reference stored with it.

Technical details are usually handled by the integration

You normally do not need to manually implement authentication, API requests, or webhook signature validation when using a ready-made integration.

If the integration reports a technical error, collect the order and payment details before contacting the ICEPAY team or the integration maintainer.

Troubleshooting

The customer payment failed but the API returned success

The API response confirms that the payment was created successfully. It does not guarantee that the customer later completed it.

Open the payment in the ICEPAY Portal and review its payment status.

For card payments, the Portal can also show common card-payment errors.

I received an “Error detected during postback” email

ICEPAY attempted to send a payment update to your configured webhook endpoint but could not reach it successfully.

Ask your developer to check:

• whether the webhook URL is publicly reachable;
• whether it accepts HTTPS POST requests;
• firewall and security rules;
• the HTTP response returned by the endpoint;
• webhook signature validation.

My webhook is not being delivered

Confirm that the configured webhookUrl is correct and publicly accessible.

Check whether your server, firewall, reverse proxy, CDN, or other security layer is blocking the incoming request.

If your infrastructure requires IP allow-listing, contact the ICEPAY team for current server information.

The webhook signature does not validate

Calculate the expected signature using the raw JSON body exactly as it was received.

Some frameworks parse or modify the JSON before your application code runs. Make sure you still have access to the original request body.

Also confirm that you are using the Merchant Secret belonging to the correct merchant.

The customer returned but my order is still unpaid

Do not use the customer’s browser redirect as the only way to update an order.

Check whether the webhook was received and processed.

If you need the latest state while handling the customer return, retrieve the payment once using the payment retrieval endpoint.

A payment method works in Test mode but not in Live mode

Payment methods available during testing may still require activation or configuration for live payments.

Check the merchant’s payment-method configuration in the ICEPAY Portal.

Contact the ICEPAY team if the payment method should be available but cannot be enabled.

I cannot determine why a payment failed

Open the payment in the ICEPAY Portal and review the available payment information.

If the reason is still unclear, contact the ICEPAY team and include the Merchant ID, payment identifier, order reference, payment method, and approximate payment time.

What to include when contacting the ICEPAY team

Providing enough context makes an error easier to investigate.

Include:

• your Merchant ID;
• your order or payment reference;
• the ICEPAY payment key when available;
• the payment method;
• whether the merchant is in Test or Live Mode;
• the HTTP status, when relevant;
• the endpoint or operation that failed;
• the approximate date and time of the issue;
• the error response or message;
• relevant server or integration logs with secrets removed.

Do not include:

• your Merchant Secret;
• the full Authorization header;
• passwords or other credentials;
• unnecessary sensitive customer information.

Continue reading

Payment lifecycle

Understand payment statuses and distinguish payment outcomes from API errors.

Contact the ICEPAY team

Find out what information to provide when you need help from the ICEPAY team.