Get request approval

With this API, you can request approval of the request created with the previous call.

Request

Endpoint

Sandbox: https://api.sandbox.soisy.it/api/shops/{shopId}/requests/{fiscalCode}
Production: https://api.soisy.it/api/shops/{shopId}/requests/{fiscalCode}

Accepted methods

POST

Authentication

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

Prerequisites

To access this endpoint, you must have successfully completed creating a request.

Parameters

Parameter Mandatory Type Format Description
amount Yes Total Total to be requested, in € cents
installments Yes Total Number of installments, from 3 to 60
loanFinality Yes String Purpose. Set to ecommerce_shop
email Yes String Valid Email Address
lastname Yes String
firstname Yes String
iban No String
mobilePhone Yes String Mobile number, without international prefix
countryCallingCode No String International prefix, example +39. Default value: + 39
city Yes String City
province Yes String 2 uppercase characters Province. Example: MI
address Yes String Street For example via roma, without commas or street number
streetNumber Yes String Street number
postalCode Yes String 5 digits Postal Code Example: 20100
citizenship Yes String Values allowed: Italian for Italian citizenship, eu for any non-Italian European citizenship, outside_eu for non-EU citizenship.
zeroInterestRate No Boolean Enable the zero rate. If omitted, the Sales Channel setting will be used.
orderToken Yes String Single-item order identification token
residence No* String Type of residence. Values allowed: rent, home_ownership, home_ownership_mortgage, home_business, with_relatives. Required if additionalDataNeeded is true.
residenceStartDate No* String MM/YYYY Date of change of residence. Example 01/2001. Required if additionalDataNeeded is true.
educationalQualification No* String Level of education. Values allowed: middle_school, diploma, graduation, master, doctorate. Required if additionalDataNeeded is true.
children No* String Number of children. Number of children. Example values: 1, 2, ..., 5+. Required if additionalDataNeeded is true.
salaryType No* String Salary type. Values allowed: net-monthly, gross-yearly. Required if additionalDataNeeded is true.
salary No* Total Salary, expressed in €. Required if additionalDataNeeded is true.

(*) This parameter may be mandatory in certain situations. See the description column next to the item.

Response

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
422 User's approval request has been refused
500 System error

Valid response

{
     "approved": true,
     "redirectUrl": "http:\/\/shops.soisy.it\/SCOREP85R02C521Z\/randomstring",
     "approvalMessageApiFull": "Congratulations, your monthly payment has been approved.",
     "approvalMessageApiSemiFull": "Congratulations, your monthly payment has been approved. We've sent you an email with the instructions to complete your payment.",
     "email": "name@example.com",
     "lastname": "Rossi",
     "firstname": "Carlo",
     "fiscalCode": "SCOREP85R02C521Z",
     "mobilePhone": "3491234567",
     "city": "Milano",
     "address": "Via Sassetti",
     "province": "MI",
     "postalCode": "00200",
     "streetNumber": "32",
     "citizenship": "Italian",
     "iban": "IT40S0542811101000000123456",
     "amount": 100000,
     "netAmount": 95000,
     "instalments": 12,
     "zeroInterestRate": true,
     "orderToken": "aafku7asdufjahg3",
     "paymentDayOfMonth": 15,
}

Where:

Parameter Type Description
approved Boolean Indicates if the request has been approved, and then you can proceed with the next steps
redirectUrl String URL to redirect the applicant in case of continuation on the Soisy funnel
approvalMessageApiFull String Deprecated: Do not use. Text message related to approval
approvalMessageApiSemiFull String Deprecated: Do not use. Text message related to approval.
email String
lastname String
firstname String
fiscalCode String
mobilePhone String
city String
address String
province String
postalCode String
streetNumber String
citizenship String
iban String
amount Total Total requested, in € cents
netAmount Total Amount that you will see credited to your account for this order, in case of successful payment. In € cents
installments Total
zeroInterestRate Boolean Indicates whether the zero rate option is enabled
orderToken String Single-item order identification token
paymentDayOfMonth Total Day of the month on which the installment payment will be made

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}: [
             {message}
         ]
      }
 }

Possible errors are listed below:

Parameter Message
actualJobEndingDate Invalid date format
address This value should not be blank.
amount This value should be between 25000 and 1500000
citizenship This value should be one of the available options.
streetNumber This value should not be blank.
email This value should not be blank.
firstname This value should not be blank.
fiscalCode Invalid fiscal code
iban This value is not a valid IBAN (International Bank Account Number).
installments The number of installments must be between 3 and 36
lastname This value should not be blank.
mobilePhone This value should not be blank.
postalCode This value should not be blank.
privacy This value should be equal to "true".

Domain specific errors:

  • User not found: if the fiscal code was incorrect or omitted.

    {
    "errors": {
        "domain": [
            "User not found" 
        ]
    }
}

  • User already evaluated

    {
    "errors": {
        "domain": [
            "User already evaluated for approval" 
        ]
    }
}

  • Sales point not authorized to request a loan

    {
    "errors": {
        "domain": [
            "This sales point cannot apply for a loan" 
        ]
    }
}

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.

 {
     "error": "Access denied"
 }

Error 409

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

 {
     "errors": "message"
 }

Errore 422

When a user is refused by our systems, we notify it by sending a 422 HTTP error code.
You'll be seeing the same response payload of a valid response but with the approved parameter with value false. The request for approval cannot be repeated.

Error 500

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

{
    "errors": {
        "system": [
            "System error"
        ]
    }
}

Redirect chance

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.