Entwickler
Loslegen
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 :-)
- Making your first API request
- Example
- API Reference
Typically every Etvas integration will need to deal with the following topics:
- Authenticating API requests
- Handling Registration of users coming in through the Etvas Customer Portal
- Authenticating users that have purchased the product in the Etvas Customer Portal
- Payment
- Receiving event updates from Etvas
Examples
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:
- Etvas Applications (Coming in summer 2020)
undefinedundefinedundefinedundefined - Legacy Applications
undefinedundefinedundefined
Example applications:
- Example 1 - ...
Authenticating your API requests
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.
User registration & login with OAuth
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.
Payment collection
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:
- The business partner (insurance, bank, etc) will collect the payment for the added value service offered and accessed by its customers - the most convenient and user friendly option since customers don't need to add yet another payment method, or
- Etvas will collect the payment
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.
Events
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:
- User Created - when a new user is created
- Product Purchased - when the customer will purchase your product
- Product Canceled - when the customer has canceled their subscription/purchase of your product
- Payment Failed - when Etvas failed to collect the payment from the user
- Payment Resumed - when Etvas was able to (re)collect the payment from the user
- User Profile Changed - when the user updates any personal details in their user profile (eg. name, address, etc)
User Created
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.
Product Purchased
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"
}
}
}
Product Canceled
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"
}
}
}
Payment Failed
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"
}
}
}
Payment Resumed
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"
}
}
}
User Profile Updated
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"
}
}
}