Overview Scalapay Orders and Errors

Errors

The Scalapay API uses standard HTTP status codes to indicate the result of requests. In case of an error, a response is returned in JSON format with detailed information.

HTTP Status Codes

Codice	Description
2XX	The request was successful.
4XX	The request is invalid (e.g., missing mandatory parameters or incorrect data).
5XX	Unexpected Scalapay server-side error.

Structure of Error Response

Error responses contain useful information for diagnosing problems. Although the message in readable format may change over time, it is recommended to rely on the error code and HTTP status code for error handling.

Attributo	Tipo	Descrizione
`errorCode`	string	Error identification code (e.g.`order_amount_exceeds_maximum_limit`).
`errorId`	string	Unique identifier of the error.
`message`	string	Readable description of the error. Could be updated, don't use it for application logic.
`httpStatusCode`	integer	HTTP status code associated with the error.

Test Order Flow

How to place a test order with Scalapay

Choose a product with an amount less than the maximum allowed.
Fill out cart information with dummy information.
Select Scalapay as the payment method at checkout.
Log in to Scalapay with a test user (the same one used in the customer portal, or create a new one).
Enter your test card information (see below) to complete your order.
Verify that you have been correctly redirected to your site's confirmation page.

Carte di Test

Cards for Testing with Positive Results

5200 8282 8282 8210
5555 5555 5555 4444
4242 4242 4242 4242

Cards for Test with Negative Results

4000 0000 0000 0341
4000 0000 0000 0002
4000 0000 0000 9995

For all:

CVV: any code (e.g., 123)
Expiration date : any future date
ZIP code: any valid ZIP code

The cards shown are all working, you can try them alternately.

Order Status

Each order has two types of status: Order Status and Capture Status.

Order Status

Status	Description
`pending`	The order has been created but not yet authorized by the customer. It remains in this state for 40 minutes if not completed.
`expired`	The order has expired without authorization from the customer.
`refunded_not_charged`	The order expired but had been authorized. The capture was not made.
`charged`	The order was captured correctly.
`partially_refunded`	The order was partially refunded.
`refunded`	The full amount of the order was refunded.

Capture Status

Status	Description
`pending`	The order has not yet been captured.
`captured`	The order was captured correctly.
`delayed`	Capture was delayed (default: 5 days).
`voided`	The order was cancelled before capture.

You can download a file with the combination of statuses from this link:[Order Status and Capture Status.pdf].

Viewing Orders in the Seller Portal

In the Orders section of the seller portal, orders are displayed with the following statuses:

Paid (charged) - Order successfully finalized
Authorized - Only temporarily visible; if completed it changes to "Paid", otherwise it expires and no longer appears
Refunded / Partially Refunded - Refunded orders, with details of the amount

Please note: Orders in refunded_not_charged and expired status are not shown in the backend.

Expired orders do not indicate technical errors, but simply abandoned or rejected orders from the customer's bank. For privacy reasons, Scalapay cannot provide the reasons for rejection.

Refunded_not_Charged orders, on the other hand, are due to technical problems.

WooCommerce and PrestaShop

On WooCommerce and PrestaShop platforms, the Scalapay plugin creates the order immediately before the customer is redirected to the Scalapay payment page.

This leads to two main consequences:

The order is already visible in the merchant’s backend, even if the payment has not yet been completed.
If the customer does not complete the payment or the session expires, the order still remains in the system.

Magento 2 and Shopify

On Magento 2 and Shopify, the behavior is different. The order is created only after the customer has successfully completed the Scalapay payment and is redirected back to the merchant’s site.

The implications are as follows:

If an error occurs during the redirection (for example, network interruption, browser closed, or session timeout), the order is not created and will therefore not be visible in the merchant’s backend.
In the specific case of Magento 2, an automated process (cron job) is in place to periodically check for transactions where payment capture has failed. In such cases, the system automatically updates the order status to “Cancelled”, helping to keep the order list clean and avoid confusion.

Checks in case of Authorized but not Captured/ Completed Orders (Refunded_not_Charged)

Custom Integration:
- Verifies that the implemented flow is correct.
- See the official documentation at this link: [Documentation link].
- Check that the Order Capture call is present and executed at the right time: when the order is in the authorized state (verifiable with GET ORDER or via Webhook).
- If you use the Delay call , check that the field authorizationExpiryMilliseconds is filled this way

{ "authorizationExpiryMilliseconds": 
432000000 }

Integration via Plugin:
- Check that the plugin version is up to date: [Link Changelog].
- Check that in the plugin the Order Status: Payment Complete field is set correctly as per the documentation. If changed, the flow may not complete.
- Choose your platform at this link: [Documentation] to check the screens and correct values.

Integration via Shopify:
- Check out this documentation link: [Shopify Documentation] to check the settings or configure delayed capture correctly .

Shopify