Create an order

This API allows you to create and order on Soisy.


This allows us to communicate to our platform the data relating to the order made by the customer on your e-commerce with a simple POST call, for example the order total, the customer's first and last name, plus other advanced options. This call will return a token identifying the payment and a redirect link.



Accepted methods



This API requires authentication via shopId and headerX-Auth-Token.


Parameter Request Type Format Description
email No String A valid email address
firstname No String Username
lastname No String User surname
amount No Total Order total, in € cents
installments No Total The number of installments, between 3 and 60. If the parameter is omitted, the applicant can choose the number of installments once landed on our webapp. If the parameter is valued, instead, the number of installments will be fixed and cannot be modified by the applicant.
vatId No String 11 characters VAT number, Example: 12345678912
vatCountry No String 2 characters Country VAT ID, Example: IT
fiscalCode No String 16 characters Codice fiscale [fiscal code]
mobilePhone No String Mobile number, without international prefix
city No String City (Municipality of residence or domicile)
province No String 2 uppercase characters Province. Example: MI
address No String Street Example Via Roma, without commas or street number
streetNumber No String Street number
postalCode No String 5 digits Postal Code Example: 20100
zeroInterestRate No Boolean Enable zero rate.(*) If omitted, your store's default setting will be used.
successUrl No String URL URL on your site, to which to redirect the user in case of successful payment
errorUrl No String URL URL on your site, to which to redirect the user in case of error, refusal of payment, or user abandonment
callbackUrl No String URL URL of your server for automated callback calls.
orderReference No String Reference code of the e-commerce order or other reference

(#) The zero rate is an option that allows you not to charge your customers interest. You can find more information on our FAQ. For more info on this feature, contact our dedicated partner support at


The API returns a JSON object.

HTTP Error codes

Code Description
200 Request completed successfully
403 The request could not be authenticated
404 Resource not found
500 System error

Valid response

The JSON object successfully returned contains the token associated with the order and a link that can be used to redirect the user to our webapp.

     "token": <stringa>
     "redirectUrl": <stringa>

Error response

The JSON object returned in the event of an error varies depending on the HTTP response code.

Error 400

Responses with this HTTP code indicate a client-side error. The request sent contained a formally incorrect parameter.

     "errors": {
         {parameter}: [

Here are some possible errors:

Parameter Message
email This value is not a valid email address.
amount This value should be between 5000 and 1500000
fiscalCode Invalid fiscal code
address The combination of address, city, province, street number, and postal code for '{address}' is not valid. Valid example: via Dei Plauti 2, 10100 Milano (MI)

Error 403

The request sent contains invalid credentials. Check the shopId and the X-Auth-Token header. Find more info on credentials in the paragraph about authentication.

     "errors": "Authentication Failed"

Error 500

Replies with this HTTP code indicate that a system error has occurred.

    "errors": {errorMessage}

Optional Redirect

In this phase you can decide whether to continue integration or redirect the user to our webapp. Redirect the requestor to Soisy using the redirectUrl field, which you will find in the response payload.