Wir werden hier erläutern, wie Sie mit dem Aufbau Ihrer ersten Etvas-Integration beginnen können. Sorry, wir arbeiten noch an der Übersetzung ins Deutsche :-)
Typically every Etvas integration will need to deal with the following topics:
A good way to get started with your first Etvas integration is to head over to Github and have a look at our at two at our example integrations.
Etvas supports two types of integrations:
Example applications:
API requests to the Etvas platform are authenticated using API keys.
You can retrieve your API from the Etvas Service Partner Portal in the Integrations section or you can contact your designated partner success manager.
One of the key value propositions for end users of Etvas is that they only need to create one account, login only once, add they credit card only once, and then have access to all the value added services that their insurance/bank/etc is providing them with.
So, integrated Single Sign On, is the corner stone of your integration into Etvas.
Single Sign On in Etvas is implemented by using the OAuth standard. You can find detailed information about OAuth at https://www.oauth.com/
Please contact your designated partner success manager on implementation details.
After registration and login with multiple service partners, payment is another benefit of the Etvas end customers enjoy.
Payments in Etvas works in one of two way:
In the case when Etvas collects the payment then end customers of Etvas need to only add their payment method once and then access any value added service.
In your integration this means that for customers which are registered via Etvas (see the reference to the "Product Purchased" event below) all payment related functionalities (including but not limited to credit card collection, invoices, etc) must be disabled and hidden.
Payments will be settled weekly/monthly between Etvas and you based on our billing reports.
Please contact your designated partner success manager on implementation details.
When creating your product in the Etvas Service Partner Portal - https://service.etvas.com - you will be required to provide an web callback URL.
Etvas will send relevant, real time, events and updates such as user profile changes, payment status, product status, etc.
By default Etvas will assume this web callback URL is available at the /etvas-events path relative to the URL at which your product is available.
Etvas will send real time updates to your web callback URL when the following events occur:
The User Created event is most likely the first event you will receive after your integration with Etvas. It is sent sent by Etvas when a user purchases your product in order to register a user on your platform.
Request
{
"event": {
"id": "5fa30c48-7c7f-4440-bbc6-fdd927e7dc48",
"type": "user.create",
"timestamp": 19786584376
},
"user": {
"id": "52f3d719-a192-4153-a05c-2b6bcc26c839",
"partnerId": null,
"auth": {
"token": "378aee42-49a8-41ef-acdb-52d1259814de",
"expires": 2086584376
}
},
"data": {
"user": {
"salutation":"Mr.",
"firstName": "john",
"lastName": "Doe",
"email": "john@doe.com",
"phone": "+1303500600",
"dateOfBirth": "1990-12-21",
"address1":"2698 Sundown Lane",
"address2":"Ap. 255",
"city":"Berlin",
"region/state":"Brandenburg",
"country":"Germany",
"postalCode": "10101"
},
"webIdentity": {
"status": "verified",
"verificationId": "450a936a-aa4a-4d3d-a3dd-333d73c8ba99"
}
}
}
Response
{
"status": 200,
"event": {
"id": "5fa30c48-7c7f-4440-bbc6-fdd927e7dc48"
},
"data": {
"user": {
"id": "52f3d719-a192-4153-a05c-2b6bcc26c839",
"partnerId": "u-111111"
}
}
}
We will include any key-value pairs that are transmitted in the Data section of the Response to the User Created event in every subsequent request that we will make to your API. You should include here any data such as user id, authorisation token or any other key-value pair that you need to match the Etvas user id to the data in your own database.
The Product Purchased event is sent by Etvas after we receive the response to the User Created event when a user purchases your product. The information provided in this event should be sufficient to create a user profile in your app and start the delivery process of the product.
Request
{
"event": {
"id": "5fa30c48-7c7f-4440-bbc6-fdd927e7dc48",
"type": "product.purchase",
"timestamp": 19786584376
},
"user": {
"id": "52f3d719-a192-4153-a05c-2b6bcc26c839",
"partnerId": "u-12345",
"auth": {
"token": "378aee42-49a8-41ef-acdb-52d1259814de",
"expires": 2086584376
}
},
"data": {
"product": {
"id": "ecc8f6f0-aef2-444d-9a6d-f49f6678c9c6",
"name": "SicurNET",
"price": 123.45,
"priceType": "SUBSCRIPTION",
"priceInterval": "MONTHLY"
}
}
}
Response
{
"status": 200,
"event": {
"id": "5fa30c48-7c7f-4440-bbc6-fdd927e7dc48"
},
"user": {
"id": "4a759a3a-9f3b-48a3-b570-95426285f7c2",
"partnerId": "u-111111"
},
"data": {
"product": {
"id": "ecc8f6f0-aef2-444d-9a6d-f49f6678c9c6",
"partnerId": "p-222222"
}
}
}
The Product Canceled event is sent by Etvas when a user cancels their subscription of purchase your product.
Request
{
"event": {
"id": "bd6016af-ffe8-422d-9419-7a71d890e002",
"type": "product.cancel",
"timestamp": 19786584376
},
"user": {
"id": "4a759a3a-9f3b-48a3-b570-95426285f7c2",
"partnerId": "u-111111",
"auth": {
"token": "378aee42-49a8-41ef-acdb-52d1259814de",
"expires": 2086584376
}
},
"data": {
"product": {
"id": "ecc8f6f0-aef2-444d-9a6d-f49f6678c9c6",
"partnerId": "p-222222",
"name": "SicurNET",
"price": 123.45,
"priceType": "SUBSCRIPTION",
"priceInterval": "MONTHLY"
}
}
}
Response
{
"status": 200,
"event": {
"id": "bd6016af-ffe8-422d-9419-7a71d890e002"
},
"user": {
"id": "4a759a3a-9f3b-48a3-b570-95426285f7c2",
"partnerId": "u-111111"
},
"data": {
"product": {
"id": "ecc8f6f0-aef2-444d-9a6d-f49f6678c9c6",
"partnerId": "p-222222"
}
}
}
The Payment Failed event is sent by Etvas when we are not able to collect the payment from the user for your product. This can happen for a variety of reasons such as insufficient funds, credit card expired, technical issues with the payment gateway, etc.
This event is to inform you that the payment has not been collected in order for you to take appropriate action (eg. suspend access to product 7 days after receiving this event).
Request
{
"event": {
"id": "6fc09149-3102-4f8a-9cc0-77cddfb5d700",
"type": "product.suspend",
"timestamp": 19786584376
},
"user": {
"id": "4a759a3a-9f3b-48a3-b570-95426285f7c2",
"partnerId": "u-111111",
"auth": {
"token": "378aee42-49a8-41ef-acdb-52d1259814de",
"expires": 2086584376
}
},
"data": {
"product": {
"id": "ecc8f6f0-aef2-444d-9a6d-f49f6678c9c6",
"partnerId": "p-222222",
"name": "SicurNET",
"price": 123.45,
"priceType": "SUBSCRIPTION",
"priceInterval": "MONTHLY"
}
}
}
Response
{
"status": 200,
"event": {
"id": "6fc09149-3102-4f8a-9cc0-77cddfb5d700"
},
"user": {
"id": "52f3d719-a192-4153-a05c-2b6bcc26c839",
"partnerId": "u-111111"
},
"data": {
"product": {
"id": "ecc8f6f0-aef2-444d-9a6d-f49f6678c9c6",
"partnerId": "p-222222"
}
}
}
The Payment Resumed event is sent by Etvas when we are able, as the result of a retry, to collect the payment for your service.
As a result of receiving this event you should immediately resume delivery of the service to the user.
Request
{
"event": {
"id": "10276225-6741-4abc-9b06-fdcedace8005",
"type": "product.resume",
"timestamp": 19786584376
},
"user": {
"id": "4a759a3a-9f3b-48a3-b570-95426285f7c2",
"partnerId": "u-111111",
"auth": {
"token": "378aee42-49a8-41ef-acdb-52d1259814de",
"expires": 2086584376
}
},
"data": {
"product": {
"id": "ecc8f6f0-aef2-444d-9a6d-f49f6678c9c6",
"partnerId": "p-222222",
"name": "SicurNET",
"price": 123.45,
"priceType": "SUBSCRIPTION",
"priceInterval": "MONTHLY"
}
}
}
Response
{
"status": 200,
"event": {
"id": "10276225-6741-4abc-9b06-fdcedace8005"
},
"user": {
"id": "52f3d719-a192-4153-a05c-2b6bcc26c839",
"partnerId": "u-111111"
},
"data": {
"product": {
"id": "ecc8f6f0-aef2-444d-9a6d-f49f6678c9c6",
"partnerId": "p-222222"
}
}
}
The User Profile Updated event is sent by Etvas when the user updates his profile information (eg. name, address, email address, etc).
Request
{
"event": {
"id": "2a689b77-c2d5-4152-a417-650f717711b9",
"type": "user.update",
"timestamp": 19786584376
},
"user": {
"id": "52f3d719-a192-4153-a05c-2b6bcc26c839",
"partnerId": "u-111111",
"auth": {
"token": "378aee42-49a8-41ef-acdb-52d1259814de",
"expires": 2086584376
}
},
"data": {
"user": {
"salutation":"Mr.",
"firstName": "john",
"lastName": "Doe",
"email": "john@doe.com",
"phone": "+1303500600",
"dateOfBirth": "1990-12-21",
"address1":"2698 Sundown Lane",
"address2":"Ap. 255",
"city":"Berlin",
"region/state":"Brandenburg",
"country":"Germany",
"postalCode": "10101"
},
"webIdentity": {
"status": "verified",
"verificationId": "450a936a-aa4a-4d3d-a3dd-333d73c8ba99"
}
}
}
Response
{
"status": 200,
"event": {
"id": "2a689b77-c2d5-4152-a417-650f717711b9"
},
"data": {
"user": {
"id": "52f3d719-a192-4153-a05c-2b6bcc26c839",
"partnerId": "u-111111"
}
}
}