Insurance

Authorization

To use the Insurance API you will need an API Token, which can be requested from support@paycertify.com

With that token, you’ll be able to access our API. You should send the token in every request to our API, in order to authenticate and identify yourself. For every request, you should pass the Authorization HTTP Header containing your token, prefixed by “Bearer “ string. Example below:

curl -H 'Authorization: Bearer YOUR_API_TOKEN' https://insurance-api.paycertify.com/api/products

An authentication error message would return a message like the following:

{
    "error": {
        "status": 401,
        "message": {
            "base": [
                "Not authenticated"
            ]
        }
    }
}

Please note that the error messages use the same structure of an error node, with then a message node, and subsequently either base being a general error, unrelated to any field submitted, fatal being a system error, or a field name, for example, amount when the request message contains any errors under that field. All messages also contain an HTTP status following W3C recommendations, e.g. an unauthenticated request will return HTTP status 401.

We include the HTTP status on the JSON message, as well as on the headers of all JSON error responses.

Quotes

In order to select among the possible insurance options and prices available, you need to request a quote. When requesting a quote you need to provide details about the trip and also for each person that will be covered by the policy.

The results will depend on which products are configured and available for your merchant account.

Requesting quotes is an asynchronous process. The first request (see Requesting quotes) will start the quoting process, but it may not be able to deliver the full response with all options in time. For this reason, we provide another endpoint (see Receiving Quote Responses) where you can make another request and fetch the full response when status is finished.

Requesting quotes

To request a quote you must provide the coverage time period, trip details and personal information about each beneficiary of the policy. Keep in mind that you can include more than one beneficiary per request. Check the example in the box below for details.

POST https://insurance-api.paycertify.com/api/quotes

Parameter Type Presence Description Example
start_date timestamp required The start date of the coverage ISO 8601. It needs to be greater than the current date/time. 2018-05-12T21:07:59.508Z
end_date timestamp required The end date of the coverage. It needs to be greater than the start_date. 2018-06-12T21:07:59.508Z
dest_countries.* array required An array with destination countries, as 3-letter strings (see ISO 3166-1 alpha-3) USA
initial_trip_deposit_date timestamp optional Initial trip deposit date. This must be lower than the current date. 2018-04-12T21:07:59.508Z
people array required Description of each person  
people.*.first_name string required Person’s name Jim
people.*.last_name string required Person’s last name Carter
people.*.middle_name string optional Person’s middle name F
people.*.passport_issuer string optional Passport issuer (see ISO 3166-1 alpha-3) USA
people.*.passport_number string optional Passport number 598854699
people.*.gender string required Gender “M” or “F” M
people.*.birth_date string required Birth date (ISO 8601) 1980-04-12T00:00:00.000Z
people.*.email string required Email address user@domain.com
people.*.phone string required Telephone number +1-202-555-0178
people.*.relationship string required Options are “Primary” (default), “Spouse”, “Child” and “Other” Primary
people.*.address string optional Street info 2378 W 12th St
people.*.city string optional City Los Angeles
people.*.state string optional 2-digit state name CA
people.*.postal_code string optional Postal code 90006
people.*.country string optional Country code (see ISO 3166-1 alpha-3) USA
people.*.trip_cost float required Trip cost 2034.00
Field Type Description Example
id uuid The quote ID .
status string The quote status processing
session_id string Session ID 80ca5b7a-a1eb-4692-ba75-72ae6e3cc79b
purchase_id string Purchase ID a74bc912-7ac3-9237-0cbe-7c1ade3cc02a
quote_options array An object with the possible options. It will be empty while status is processing. As the quoting process is asynchronous, the expected result for the first call is an empty array. You can see the complete description of the quote option’s fields in the Response Fields for the section Receiving Quote Responses  
curl --request POST \
  --url 'https://insurance-api.paycertify.com/api/quotes' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'content-type: multipart/form-data;' \
  --form 'start_date=2018-05-12T21:07:59.508Z' \
  --form 'end_date=2018-06-12T21:07:59.508Z' \
  --form 'dest_countries[]=USA' \
  --form 'initial_trip_deposit_date=2018-04-12T16:51:04.265Z' \
  --form 'people[][first_name]=Jim' \
  --form 'people[][last_name]=Carter' \
  --form 'people[][middle_name]=M' \
  --form 'people[][passport_issuer]=USA' \
  --form 'people[][passport_number]=34567' \
  --form 'people[][gender]=M' \
  --form 'people[][birth_date]=1980-04-12T00:00:00.000Z' \
  --form 'people[][email]=username@domain.com' \
  --form 'people[][phone]=+1-202-555-0178' \
  --form 'people[][relationship]=Primary' \
  --form 'people[][address]=2378 W 12th St' \
  --form 'people[][city]=Los Angeles' \
  --form 'people[][state]=CA' \
  --form 'people[][postal_code]=90006' \
  --form 'people[][country]=USA' \
  --form 'people[][trip_cost]=2034.00'

Responds with:

{
  "quote": {
    "id": "20f1864d-f4d3-4b9c-990a-ffb5e53a1c34",
    "status": "processing",
    "session_id": "ea2468a4-ce45-4078-87c3-d37945e7c2f1",
    "purchase_id": null,
    "quote_options": [

    ]
  }
}

Receiving quote responses

Use this URL to fetch the quote response by passing the quote_id provided by the previous response. Once the quote process is finished, you will receive a set of Quote Options. Each option is a package of benefits with a price related to it.

After this process you shall choose between the options available and pass its related quote_option_id in the next call (see Purchasing insurance)

GET https://insurance-api.paycertify.com/api/quotes/{quote_id}

Field Type Description Example
quote_id uuid Session ID, to be set in the URL ac35fbb1-5fcc-4927-89cd-4b5c96d31c16
Field Type Description Example
id uuid Quote ID ac35fbb1-5fcc-4927-89cd-4b5c96d31c16
status string Quote status processing, finished
session_id uuid Session ID ac35fbb1-5fcc-4927-89cd-4b5c96d31c16
purchase_id uuid Purchase ID (for records in which a purchase was consolidaded) ac35fbb1-5fcc-4927-89cd-4b5c96d31c16
quote_options object An object representing an option that can be purchased by the user
quote_options.*.id uuid Quote option’s ID
quote_options.*.amount float The quote option’s price
quote_options.*.created_at timestamp Created at 2018-04-12T21:07:59.353Z
quote_options.*.updated_at timestamp Updated at 2018-04-12T21:07:59.353Z
quote_options.*.status string Quote option state: processing, quoted, invalid, error quoted
quote_options.*.product object An object representing the product that is associated to the quote option  
quote_options.*.product.id uuid Product ID ac35fbb1-5fcc-4927-89cd-4b5c96d31c16
quote_options.*.product.name string Product name Plan 6
quote_options.*.product.active boolean true if product is active, false otherwise true
quote_options.*.coverages.*.id string Coverage element ID 4533171c-db5e-45ec-b88e-1e20a46e5c98
quote_options.*.coverages.*.description string The coverage description Cancel for any reason
quote_options.*.coverages.*.value string A description of the value associated to the coverage (per person limit) 75% of non-refundable trip cost
curl --request GET \
  --url https://insurance-api.paycertify.com/api/quotes/20f1864d-f4d3-4b9c-990a-ffb5e53a1c34 \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \

Responds with:

{
  "quote": {
    "id": "12e3e0d0-0447-40c2-9d3b-953cc5f94202",
    "created_at": "2018-05-04T21:06:26.849Z",
    "updated_at": "2018-05-04T21:06:29.453Z",
    "status": "finished",
    "session_id": "49b46755-6c7e-4b0a-ba3f-73326f8e2643",
    "purchase_id": null,
    "quote_options": [
      {
          "id": "fd6d933a-3e58-4c12-802c-10d8e4d1a906",
          "created_at": "2018-05-04T21:06:29.433Z",
          "updated_at": "2018-05-04T21:06:29.433Z",
          "amount": "36.0",
          "status": "quoted",
          "coverages": [
              {
                  "id": "4533171c-db5e-45ec-b88e-1e20a46e5c98",
                  "description": "Cancel for any reason",
                  "value": "75% of non-refundable trip cost "
              },
              {
                  "id": "a86b6309-70fa-414b-aacd-b7b544a71c08",
                  "description": "Rental Car Damage Coverage",
                  "value": "$30.000"
              }
          ],
          "product": {
              "id": "eaa59318-9359-4c60-891c-5a96480be14e",
              "created_at": "2018-04-19T16:26:06.495Z",
              "updated_at": "2018-05-04T20:44:04.342Z",
              "name": "RoundTrip Economy",
              "active": true
          }
        }
      ]
    }
  }

Purchase

Since you’ve performed a new Quote and have chosen a Quote Option, you can request a purchase through the URL below, informing the selected quote_option_id received in the previous calls (see Receiving quote responses above). This is also an asynchronous process, so

Purchasing insurance

To perform a purchase you must inform mainly the selected quote_option_id and finally the purchasing info like credit card number and cardholder details. The coverage letter URL in the response will be null until the process is completely terminated with status finished. It will be available for querying in the next call. (See Showing purchases)

POST https://insurance-api.paycertify.com/api/purchases/

Parameter Type Presence Description Example
quote_option_id string required One of the quote options retured when a quote is created (see above) 2b0e8eb8-be4e-4c8e-a3d2-b2c6e95be608
name string required Cardholder name Jim Carter
address string required Street address 2378 W 12th St
city string required City name Los Angeles
country string required Country code (see ISO 3166-1 alpha-3) USA
state string required 2-digit state name CA
phone_number string required Phone number +1-202-555-0178
postal_code string required Postal code 90006
email string required Email address user@domain.com
card_number string required Card Number 370000000000002
card_cvv string required Card CVV Number 9000
card_expiry_month string required Card expiration month (2-digit) 10
card_expiry_year string required Card expiration year (2-digit) 20
agreement_disclaimer boolean required The consumer’s agreement with the disclaimer for this purchase. This field must be filled with true to result in a successful response. true
Field Type Description Example
id uuid Purchase ID bd8f819e-4951-441f-83bb-56f9a88648e0
created_at timestamp Created at 2018-04-12T21:07:59.508Z
updated_at timestamp Updated at 2018-04-12T21:07:59.508Z
status string The purchase status (waiting, processing, purchased, invalid, error). This process is asynchronous, which means that immediately after this request the status returned will be ‘processing’. You can fetch the purchase details further by using the endpoint above. When the process finishes, this status shall be changed to ‘purchased’ if all data is correct. processing
quote_option_id uuid The quote options selected whento create the purchase. 2b0e8eb8-be4e-4c8e-a3d2-b2c6e95be608
coverage_letter_url string The coverage letter URL. This will be null unless the status is ‘purchased’. null
curl --request POST \
  --url https://insurance-api.paycertify.com/api/purchases \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'content-type: multipart/form-data;' \
  --form 'name=Jim Carter' \
  --form 'address=2378 W 12th St' \
  --form 'city=Los Gatos' \
  --form 'country=USA' \
  --form 'state=CA' \
  --form 'phone_number=+1-202-555-0178' \
  --form 'postal_code=90006' \
  --form 'email=gramofone@gmail.com' \
  --form 'card_number=370000000000002' \
  --form 'card_cvv=9000' \
  --form 'card_expiry_month=10' \
  --form 'card_expiry_year=20' \
  --form 'quote_option_id=ece2ff5d-3c2a-4429-a1fb-571cb946a8d1'


Responds with:

{
  "purchase": {
    "id": "bd8f819e-4951-441f-83bb-56f9a88648e0",
    "created_at": "2018-04-12T21:07:59.508Z",
    "updated_at": "2018-04-12T21:07:59.508Z",
    "status": "processing",
    "quote_option_id": "ece2ff5d-3c2a-4429-a1fb-571cb946a8d1",
    "coverage_letter_url": null
  }
}

Showing purchases

In this URL you are able to check for purchasing status and collect the Coverage Letter link for download as soon as the status is set to finished. You must pass in the URL the Purchase ID informed in the previous call (see Purchasing insurance)

GET https://insurance-api.paycertify.com/api/purchases/{id}

Parameter Type Presence Description Example
id uuid required The purchase ID bd8f819e-4951-441f-83bb-56f9a28648e0
Field Type Description Example
id uuid Purchase ID bd8f819e-4951-441f-83bb-56f9a28648e0
created_at timestamp Created at 2018-04-12T21:07:59.508Z
updated_at timestamp Updated at 2018-04-12T21:07:59.508Z
status string The purchase status (waiting, processing, purchased, invalid, error) processing
quote_option_id uuid The quote options selected whento create the purchase. 2b0e8eb8-be4e-4c8e-a3d2-b2c6e95be608
coverage_letter_url string The coverage letter URL. This will be null unless the status is ‘purchased’. https://insurance-api.paycertify.com/api/purchases/2c4de833/coverage_letter
curl --request GET \
  --url https://insurance-api.paycertify.com/api/purchases/bd8f819e-4951-441f-83bb-56f9a28648e0 \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \

Responds with:

{
  "purchase": {
    "id": "bd8f819e-4951-441f-83bb-56f9a28648e0",
    "created_at": "2018-04-12T21:07:59.508Z",
    "updated_at": "2018-04-12T21:07:59.508Z",
    "status": "purchased",
    "quote_option_id": "2b0e8eb8-be4e-4c8e-a3d2-b2c6e95be608",
    "coverage_letter_url": "https://insurance-api.paycertify.com/api/purchases/2c4de833/coverage_letter"
  }
}