Create a request

Create a payment request on the Soisy platform.




Accepted methods



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


To access this endpoint you must have successfully completed creating an order.


Parameter Required Type Format Description
amount Yes Total Total to be requested, in € cents
installments Yes Total Number of installments, from 3 to 60
privacy Yes Boolean Approval of the privacy information by the user
marketing No Boolean Approval of the marketing policy by the user
fiscalCode Yes String 16 characters Codice fiscale [fiscal code]
jobDescription Yes String Employment type. Values allowed: student, retired, unemployed, inheritance, entrepreneur, self_employed, seasonal_worker, freelance_professional, employee_open_ended_contract, employee_fixed_term_contract.
actualJobEndingDate No* String MM/YYYY Employment end date. Required if jobDescription is employee_fixed_term_contract
vatId No* String 11 characters VAT number. Required if jobDescription is entrepreneur
vatCountry No* String 2 uppercase characters Country VAT number. Required if jobDescription is entrepreneur
zeroInterestRate No Boolean Enable the zero rate. (#) If omitted, the Sales Channel setting will be used.

(*) This parameter may be mandatory in certain situations. See the description column next to the item. (#) The zero rate is an option that allows you not to charge your customers interest. You can find more information on our FAQ. To activate this feature, contact our partner support team at


The API returns a JSON object.

HTTP Error codes

Code Description
201 Resource created
400 Syntax or domain error
403 The request could not be authenticated
404 Resource not found
500 System error

Valid response

The API returns a JSON object containing the data of the newly created request. The parameters returned are:

     "apr": <float>,
     "fiscalCode": <stringa>,
     "totalRepayment": <intero>,
     "instalmentAmount": <intero>,
     "zeroInterestRate": <booleano>
     "additionalDataNeeded": <booleano>


Parameter Type Description
apr Total APR, in € cents
fiscalCode String Codice fiscale [fiscal code]
totalRepayment Total Total to repay, in € cents
instalmentAmount Total Installment to be paid, in € cents
zeroInterestRate Boolean Indicates if the zero rate is active
** additionalDataNeeded ** Boolean Indicates if additional information is required in the Approval request and Send documents calls

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}: [

Possible errors are listed below:

Parameter Message
amount This value should be between 25000 and 1500000
privacy This value should be equal to "true".
jobDescription This value should not be blank
** actualJobEndingDate ** Invalid date format. The correct format is the following: MM/YYYY
vatId VAT number must be a string
The VAT number country code must be a string
The VAT number country code is not valid
The VAT number is not valid for the country
fiscalCode Invalid fiscal code
installments The number of installments must be between 3 and 36

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 409

The request sent can't be completed. More informations are contained in the error message.

     "errors": "message"

Error 500

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

    "errors": "System error"