Developer Portal

 

Getting Started

We will be explaining here how to get started in building your first Etvas integration. 

  • 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)

    • These are the most advanced type of integrations available to Etvas users

    • The applications are built as Single Page Applications using the Etvas developer toolchain and the Etvas styles components

    • The applications are hosted in the Etvas cloud environment

    • When presented to the user the Etvas Apps are displayed as embedded/native apps and offer the highest level of customer experience 

  • Legacy Applications​

    • These applications are hosted by our service partners themselves​

    • The integration is limited to registration, login and payment

    • When end customers experience them it is always in a new browser tab

Example applications:

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"
    }
  }
}

User Deleted