API - create a order

This API allows you to create an order on our platform.

Request

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

Endpoint

				
					Sandbox: https://api.sandbox.soisy.it/api/shops/{shopId}/orders
Produzione: https://api.soisy.it/api/shops/{shopId}/orders
				
			

Accepted methods

				
					POST

				
			

Authentication

This API requires authentication viashopId and headerX-Auth-Token .

Parameters

ParameterRequiredGuyFormatDescription
e-mailNoStringA valid email address
firstnameNoStringName of the user
lastnameNoStringUser’s surname
amountNoEntireTotal order, in € cents
instalmentsNoEntireThe number of installments, between 3 and 60. If the parameter is omitted, the applicant will be able to choose the number of installments once landed on our webapp. If the parameter is entered, however, the number of installments will be fixed and cannot be changed by the applicant.
vatIdNoString11 charactersVAT number, Example: 12345678912
vatCountryNoString2 charactersVAT number country, Example: IT
fiscal CodeNoString16 charactersTax ID code
mobilePhoneNoStringMobile number, without country code
cityNoStringCity (Municipality of residence or domicile)
provincesNoString2 uppercase charactersProvince. Example: MI
addressNoStringStreet. ExampleVia Roma , without commas or house numbers
civicNumberNoStringHouse number
postalCodeNoString5 digitsPOSTAL CODE. Example: 20100
zeroInterestRateNoBooleanEnable zero rate. (*) If omitted, your store’s default setting will be used.
successUrlNoStringURLURL on your site, to which the user can be redirected in case of successful payment
errorUrlNoStringURLURL on your site, to which to redirect the user in case of error, refusal of payment or abandonment of the user
callbackUrlNoStringURLURL of your server for automated callback calls.
orderReferenceNoStringReference code of the ecommerce order or other reference
(*) The zero rate is an option that allows you to not charge interest to your customers. Find more information on our FAQs . For more info on this feature, contact our dedicated partner support at partner@soisy.it .

Answer

The API returns a JSON object.

CodeDescription
200Request completed successfully
403Failed to authenticate the request
404Resource not found
500System error

The JSON object returned in case of success 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>
}
				
			

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

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

				
					 {
     "errors": {
         {parametro}: [
             {messaggio}
         ]
      }
 }
				
			

Here are some possible errors:

Messageparameter
emailThis value is not a valid email address.
amountThis value should be between 5000 and 1500000
fiscalCodeInvalid tax code
addressThe combination of address, city, province, civicNumber and postalCode for ‘{address} ‘ it is not valid. Valid example: via Dei Plauti 2, 10100 Milan (MI)

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

				
					 {
     "errors": "Authentication Failed"
 }
				
			

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

				
					{
    "errors": {errorMessage}
}
				
			

At this stage you can decide whether to continue the integration or redirect the user to our webapp. Redirect the requester to Soisy using the field redirectUrl, which you find in the response payload.

Ciao!

Siamo on line dal lunedì al venerdì dalle 9.30 alle 12.30 e dalle 14.30 alle 17.30

Scrivici in questi orari, grazie!