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