New Request Handling
Process flow
This diagram illustrates the process of receiving a new client request (account/policy opening) from a tenant via Zinsli. It shows the interactions between Zinsli and the Product Provider during the tenant onboarding process.
Implementation
Follow this step-by-step guide to implement the product opening process.
TIP: See API Specification below for Swagger docu.
Auth Setup
-
OAuth authorization
Obtain authorization using the Client Credentials Grant flow of OAuth 2.0.
Follow the instructions under Setup OAuth App to create an OAuth App and getclient_id
andclient_secret
.warningThe following scopes must be set for the OAuth App.
rental_collateral:read
rental_collateral:update
- post:
/v1/user/auth/token
infoFor all subsequent API calls, include the following header:
Authorization: Bearer <access_token>
. - post:
Get new requests
-
Retrieve Product Opening Information
Obtain details about tenants who have completed the Zinsli onboarding process and wish to open one of your products. You can choose between two methods to retrieve this information: Webhooks and Polling.Webhooks:
Follow the instructions under Setup Webhooks to activate them. After that you can receive events which have the following schema:
{
collateralId: string
state: 'tenant-onboarded'
}Polling:
Another variant is to poll the following endpoint:
- GET:
/v1/{organizationSlug}/product-provider/rental-collateral
infostate must have the value
tenant-onboarded
(this means the tenant has onboarded themselves to the collateral and sent their request for a specific product).
collateralId contains the ID needed to get collateral data
- GET:
-
Get Tenant Onboarding Data
Find all information about the rental deposit to be opened, including information about the landlord, tenant and property. You will find the relevant information in the following places:- Primary tenant email and locale:
state.tenant.email
andstate.tenant.locale
- All other Primary tenant information:
state.product.primaryTenant
- All secondary tenant information:
state.product.secondaryTenants
- All rental deposit information (ex. required amount):
deposit
- All rental property information (ex. address):
property
- Property owner:
property.owner
- Property manager:
property.management
(In case you need information about your own product that the tenant chose, please check under
state.product.product
, for example the fees understate.product.product.fees
).warningOnly objects with the state
tenant-onboarded
should be processed by the product provider. You need to track which objects with this state you are already processing. (For more information on the different states, please refer to the explanations).- get:
/v1/product-provider/rental-collateral/{id}
- Primary tenant email and locale:
Confirm tenant onboarding & activation status
- Get your config
- A: Personal + waiting
- B: Collective + waiting
- C: External direct
Determine your product configuration
Check your product settings.
billing.kind
for the configured payment optionshouldLockAfterAccountCreation
for the guarantee confirmation
For more information about the different configurations, please see here.
Continue in the appropriate tab:
-
Patch Billing information (optional)
In case you processes require you to do so (ex. to get filled in template contract), you mayPATCH
the collateral with billing information BEFORE updating the state of the collateral (step 5). Please note that the information at this point does NOT trigger a state change (and the associated notifications and process updates).Even if you use this
PATCH
you MUST complete the next step in order for the process to be complete!
-
Inform Zinsli about the Outcome of Your Product Onboarding
After completing your internal onboarding process, there are two possible outcomes: onboarding has either succeeded (you accept the tenant as a client) or failed (you do not want to open an account/policy for this tenant).
You need to inform Zinsli about the outcome as soon as possible, which you can do with one of the following POST requests.
-
Accept Client
Thecreation-succeeded
should contain all the billing information required for the tenant. Based on this information, Zinsli will create a QR bill and send it to the tenant. Pay special attention to the IBAN & Reference fields: only send a Reference if your IBAN type requires it!FYI: If you used the
PATCH
method in step 1, thePOST
in this step will overwrite your previous information!- post:
/v1/product-provider/rental-collateral/{id}/creation-succeeded
This POST will change the state of a collateral to
ready-for-payment
.For a bank account, POST will look like this
{
"paymentInfo": {
"iban": "CH3908704016075473007",
"message":"some optional message",
"reference":"only include if your IBAN needs it",
"recipient": {
"street": "Main Street",
"streetNumber": "15",
"zip": "8000",
"city": "Zürich",
"country": "CH",
"name": "Hans Muster"
}
},
"additionalInfos": {
}
}tip- Only include a reference if your IBAN type requires a reference
- If you include a reference, make sure it follows the required standard!
- For the recipient address, check the
property.correspondenceAddress
field: IfTRUE
, then use the property address here, as this is the tenant's new address. IfFALSE
, then use the address under primaryTenant. - If you do not use the 'reference' or 'message' field, omit them from your POST. Do not include them with empty strings!
- post:
-
Reject Client Request
- post:
/v1/product-provider/rental-collateral/{id}/creation-rejected
This POST will change the state of a collateral to
partner-account-creation-rejected
and you will lose access to the request on Zinsli!warningThe text that you send with the
creation-rejected
call is shown to the tenant and the landlord. Make sure it does not contain any sensitive information! - post:
-
-
Upload a Confirmation or Contract files (optional)
It is possible to provide the certificate or contract documents to the landlord and tenant. You can set the visibility of the document to be either the landlord, the tenant or both (
permissionReadTenant
andpermissionReadLandlord
).The documents are available to the parties as long as the product is active. This is the preferred way of transmitting the payment confirmation to the tenant and landlord.
- post:
/v1/product-provider/rental-collateral/{id}/documents/upload
- post:
/v1/product-provider/rental-collateral/{id}/documents
- post:
-
Inform Zinsli when payment is received
As soon as the payment has been received, update the state! This means that the rental security is now in force.
The confirmation should only be made when the final amount in the account is at least the requested collateral amount. All applicable fees should be subtracted and ensured that the remaining amount is still sufficient. Do NOT confirm if you have not received sufficient funds. (Zinsli will send out automated reminders to the tenant if confirmation of payment is not received).
With this POST, the state of a collateral changes to
locked
, and the collateral cannot be modified anymore.Make sure to post any required documents (confirmation statements etc) BEFORE you make this confirmation post.
- post:
/v1/product-provider/rental-collateral/{id}/confirm-payment
- post:
-
Get Collateral Summary as PDF (optional)
Optionally, you can fetch a summary of the whole collateral which contains all the information in a PDF.(Tenant, landlord and rental object owner information, rental object address, deposit amount, as well as terms agreement dates).
- get:
/v1/product-provider/rental-collateral/{id}/pdf
- get:
-
Inform Zinsli about the Outcome of Your Product Onboarding
After completing your internal onboarding process, there are two possible outcomes: onboarding has either succeeded (you accept the tenant as a client) or failed (you do not want to open an account/policy for this tenant).
You need to inform Zinsli about the outcome as soon as possible, which you can do with one of the following POST requests.
-
Accept Client
Thecreation-succeeded
should contain all the billing information required for the tenant. Based on this information, Zinsli will create a QR bill and send it to the tenant. Pay special attention to the IBAN & Reference fields: only send a Reference if your IBAN type requires it!- post:
/v1/product-provider/rental-collateral/{id}/creation-succeeded
This POST will change the state of a collateral to
ready-for-payment
.A POST will look like this
{
"paymentInfo": {
"message": "some additional infos",
"reference":"only include if your IBAN needs it"
},
"additionalInfos": {
}
}tip- To check the configured collective account information for your product, check
billing.recipient
configuration of your product - Only include a reference if your IBAN type requires a reference
- If you include a reference, make sure it follows the required standard!
- If you do not use the 'reference' field, omit it from your POST. Do not include it with an empty string!
- post:
-
Reject Client Request
- post:
/v1/product-provider/rental-collateral/{id}/creation-rejected
This POST will change the state of a collateral to
partner-account-creation-rejected
and you will lose access to the request on Zinsli!warningThe text that you send with the
creation-rejected
call is shown to the tenant and the landlord. Make sure it does not contain any sensitive information! - post:
-
-
Upload a Confirmation or Contract files (optional)
It is possible to provide the certificate or contract documents to the landlord and tenant. You can set the visibility of the document to be either the landlord, the tenant or both (
permissionReadTenant
andpermissionReadLandlord
).The documents are available to the parties as long as the product is active. This is the preferred way of transmitting the payment confirmation to the tenant and landlord.
- post:
/v1/product-provider/rental-collateral/{id}/documents/upload
- post:
/v1/product-provider/rental-collateral/{id}/documents
TIP: If you used the
PATCH
method in step 4, thePOST
in step 5 will overwrite your previous information!
- post:
-
Inform Zinsli when the payment is made
As soon as the payment has been received, update the state! This means that the rental security is now in force.
The confirmation should only be made when the final amount in the account is at least the requested collateral amount. All applicable fees should be subtracted and ensured that the remaining amount is still sufficient. Do NOT confirm if you have not received sufficient funds. (Zinsli will send out automated reminders to the tenant if confirmation of payment is not received).
With this POST, the state of a collateral changes to
locked
, and the collateral cannot be modified anymore.Make sure to post any required documents (confirmation statements etc) BEFORE you make this confirmation post.
- post:
/v1/product-provider/rental-collateral/{id}/confirm-payment
- post:
-
Get Collateral Summary as PDF (optional)
Optionally, you can fetch a summary of the whole collateral which contains all the information in a PDF.(Tenant, landlord and rental object owner information, rental object address, deposit amount, as well as terms agreement dates).
- get:
/v1/product-provider/rental-collateral/{id}/pdf
- get:
-
Upload a Confirmation or Contract files
While this is an optional step, it is highly recommended!
It is possible to provide the certificate or contract documents to the landlord and tenant. You can set the visibility of the document to be either the landlord, the tenant or both (
permissionReadTenant
andpermissionReadLandlord
).The documents are available to the parties as long as the product is active. This is the preferred way of transmitting the payment confirmation to the tenant and landlord.
- post:
/v1/product-provider/rental-collateral/{id}/documents/upload
- post:
/v1/product-provider/rental-collateral/{id}/documents
tip- Only upload documents when you have decided to accept the client request.
- Upload the documents BEFORE you make the 'creation-succeeded' call, as the 'succeeded' call will lock the collateral and will block any modifications, including uploads of documents!
- post:
-
Inform Zinsli about the Outcome of Your Product Onboarding
After completing your internal onboarding process, there are two possible outcomes: onboarding has either succeeded (you accept the tenant as a client) or failed (you do not want to open an account/policy for this tenant).
You need to inform Zinsli about the outcome as soon as possible, which you can do with one of the following POST requests.
-
Accept Client
Thecreation-succeeded
should the account or policy ID for the tenant. Use theadditionalInfos > policyNumber
field for this.- post:
/v1/product-provider/rental-collateral/{id}/creation-succeeded
This POST will change the state of a collateral to
active
. No changes are allowed afterwards, make sure to upload any documents before this call!For an insurance policy, the POST will look like this
{
"additionalInfos": {
"policyNumber": "AB_12345567"
}
} - post:
-
Reject Client Request
- post:
/v1/product-provider/rental-collateral/{id}/creation-rejected
This POST will change the state of a collateral to
partner-account-creation-rejected
and you will lose access to the request on Zinsli!warningThe text that you send with the
creation-rejected
call is shown to the tenant and the landlord. Make sure it does not contain any sensitive information! - post:
-
-
Inform Zinsli when the payment is made
As soon as the payment has been received, update the state! This means that the rental security is now in force.
The confirmation should only be made when the final amount in the account is at least the requested collateral amount. All applicable fees should be subtracted and ensured that the remaining amount is still sufficient. Do NOT confirm if you have not received sufficient funds. (Zinsli will send out automated reminders to the tenant if confirmation of payment is not received).
With this POST, the state of a collateral changes to
locked
, and the collateral cannot be modified anymore.Make sure to post any required documents (confirmation statements etc) BEFORE you make this confirmation post.
- post:
/v1/product-provider/rental-collateral/{id}/confirm-payment
- post:
-
Get Collateral Summary as PDF (optional)
Optionally, you can fetch a summary of the whole collateral which contains all the information in a PDF.(Tenant, landlord and rental object owner information, rental object address, deposit amount, as well as terms agreement dates).
- get:
/v1/product-provider/rental-collateral/{id}/pdf
- get: