API - create a order
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
| Parameter | Required | Guy | Format | Description |
|---|---|---|---|---|
| No | String | A valid email address | ||
| firstname | No | String | Name of the user | |
| lastname | No | String | User’s surname | |
| amount | No | Entire | Total order, in € cents | |
| instalments | No | Entire | The 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. | |
| vatId | No | String | 11 characters | VAT number, Example: 12345678912 |
| vatCountry | No | String | 2 characters | VAT number country, Example: IT |
| fiscal Code | No | String | 16 characters | Tax ID code |
| mobilePhone | No | String | Mobile number, without country code | |
| city | No | String | City (Municipality of residence or domicile) | |
| provinces | No | String | 2 uppercase characters | Province. Example: MI |
| address | No | String | Street. ExampleVia Roma , without commas or house numbers | |
| civicNumber | No | String | House 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 the user can be redirected 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 abandonment of the user |
| callbackUrl | No | String | URL | URL of your server for automated callback calls. |
| orderReference | No | String | Reference code of the ecommerce order or other reference |
Answer
The API returns a JSON object.
HTTP response codes
| Code | Description |
|---|---|
| 200 | Request completed successfully |
| 403 | Failed to authenticate the request |
| 404 | Resource not found |
| 500 | System error |
Valid answer
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>
}
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 submitted request contained a formally incorrect parameter.
{
"errors": {
{parametro}: [
{messaggio}
]
}
}
Here are some possible errors:
| Message | parameter |
|---|---|
| This value is not a valid email address. | |
| amount | This value should be between 5000 and 1500000 |
| fiscalCode | Invalid tax code |
| address | The combination of address, city, province, civicNumber and postalCode for ‘{address} ‘ it is not valid. Valid example: via Dei Plauti 2, 10100 Milan (MI) |
Error 403
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"
}
Error 500
Responses with this HTTP code indicate that a system error has occurred.
{
"errors": {errorMessage}
}
Ability to redirect
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.
