Order Callbacks

Order callbacks are automatically triggered by SpectroCoin whenever there is a change in the order status . When this occurs, SpectroCoin initiates a POST request to the specified callbackUrl, which provides updated information about the order state. Callbacks are sent for the following status changes:

• PAID – The order was successfully paid.
• EXPIRED – The payment window has expired without a successful transaction.
• FAILED – The payment(s) was rejected by transaction monitoring.

How callbacks work

When SpectroCoin sends a callback to the specified callbackUrl, it expects a response from the client’s server. If the callback is processed successfully, the client should return a 200 OK status code to acknowledge receipt. If the client’s server encounters an issue (such as invalid data, missing parameters, or server-side errors), it should return an appropriate HTTP error status code (e.g., 400 Bad Request, 500 Internal Server Error). Read more about Status Codes .

How to test order callbacks?

1. Go to your project settings in SpectroCoin and toggle the Test mode.
2. In Test mode, choose either the Paid or Expired status to simulate the payment flow.

When Test mode is active, the payment flow window will not prompt for an actual payment. Instead, it will simulate the selected status and automatically send the corresponding callback to the specified callbackUrl. This is especially useful for testing whether the callback successfully reaches your custom API integration or one of the CMS plugins .

Callback failures

A callback may fail to reach the specified URL for several reasons:

• A callback may fail if the target URL is on a local or private network, making it inaccessible, leading to a 404 (Not Found) or 503 (Service Unavailable) status.
• A 400 (Bad Request) may occur if the callbackUrl fails validation due to improper formatting based on URL standards.
• If the target server encounters an issue processing the callback, such as malformed data or internal errors, a 500 (Internal Server Error) or 422 (Unprocessable Entity) status may be returned.
• A response code of 0 typically indicates that no response was received from the target server.

How to debug and retry order callbacks

1. In the project window, scroll down to the Order History and click on one of the orders, which you want debug..

2. Scroll down to the bottom of the page until the list of callbacks becomes visible, as shown here:

   

3. Click on the ID of the callback to see more details about the order callback. The Response field will contain the data received from the callbackUrl.

If further debugging is required, you can retrieve callback information using two endpoints:

• GET /public/merchants/orders/{id}/callbacks to fetch all callback attempts for a specific order.
• GET /public/merchants/orders/callbacks/{callbackId} to inspect detailed information about a particular callback.

Retrying a callback

If a callback fails to reach your server or encounters an error during processing, you can retry it through two methods: