REFUND PROTECT INTEGRATION GUIDE

protectgroup.co/api-guide/refundprotect

Introduction

Welcome to the brief Refund Protect integration guide, designed to help you set up the
offering on your booking platform.

Our team will provide you with a VendorId and API Key for your new platform account.

Our integrations team are at hand to support you along the way, contact them at
integrations@protectgroup.com.

About the API

We use a REST SERVICE with UTF-8 encoding.

We have produced a Postman collection to allow you to view examples of the requests and to
act as a template, you can view the collections in the sections below.

Suggested Development Process

1. Receive your UAT VendorID and API Key from Protect Group Manager
(integrations@protectgroup.co)
2. Using the Sales Request Header and Data Structure as found in this guide, write your
code and test using the UAT Endpoint (found below). Here are a couple of hints:
1. You can use the json data from this guide as a content starting point and send
transactions from within Postman.
2. Using Postman you can input your data to create content and validate
3. Each API call requires a unique vendor reference ID
3. Once the integration work is tested and approved, you will need to swap the UAT
Endpoint and UAT VendorID / API Key with the Live Production Platform Endpoint
and VendorID / API Key. Please Note: UAT and production credentials are NOT the
same and production credentials are provided by the Protect Group team once tests
have been validated.
4. Remember that transactions sent through UAT will be not be officially protected and
are not billed for, therefore you can send through as many as are needed for testing. We
recommend a minimum of 10 test transactions before proceeding to the Live
Production Platform and this includes both sold:true and sold:false transactions.

1/11
 Request Header
There are 2 parts to the request header.

X-RefundProtect-VendorId

This is your unique VendorID (UAT VendorID will be replaced with a production VendorID
once testing has been verified)


X-RefundProtect-AuthToken
This is your unique API Key (UAT API Key will be replaced with a production Key once
testing has been verified)

Request Header

Content-Type: application/json

X-RefundProtect-VendorId: Your unique VendorID

X-RefundProtect-AuthToken: Your unique API Key

Post

What does this do?

We need to receive all of the transactions in the format as provided below. We also need to
know when the customer chooses not to select a Refundable Booking as this helps us improve
your customer conversion and prevent fraud.

Method Required: PUT/POST http method (other methods will return an error message).

Request URL
UAT Request URL - https://test.api.protectgroup.co/api/v1/refundprotect/salesoffering

IMPORTANT INFORMATION

Please note: Any transactions submitted to the UAT Request URL are tests only and will
not be billed for. No test transactions should be sent to the Live Production Protect
Platform as these will be charged for.

2/11
 Sales Request Data Structure
Each sales request must have a predefined set of content and must conform exactly to the
specified rules as found below:

Data format: JSON

Request In case no response is returned from the API, a request timeout should be
timeout: set to 10 seconds.

The data structure is separated into 2 entities:

Transaction related data

Sales related data

{

"vendorCode": "DemoVendorId ",
"vendorSalesReferenceId": "UniqueID-9166-9877-1234-3211",
"VendorSalesDate":"2020-03-02T07:42:36.73+11:00",
"customerFirstName": "John",

"customerLastName": "Doe",

"products": [
{

"productCode": "HTL",

"currencyCode": "USD",

"productPrice": 100,

"premiumRate": 8.0,

"offeringMethod": "OPT-OUT",

"sold": true,

"insuranceEndDate": "2018-06-15T23:59:59.999"
}
]
}

Transaction Related Data Explanation:

Data Field Mandatory? Data Description

Type

vendorCode YES Character Your VendorID as found in the

Account Management section of the
UAT or Live Production Protect
Platform

3/11
 vendorSalesReferenceID YES Character The customer’s booking
confirmation reference/number

vendorSalesDate YES Character Date of when booking was made

customerFirstName YES Character First name of customer

customerLastName YES Character Last name of customer

Sales Related Data Explanation:

SELECT - The service is not pre-selected but mandatory to choose either options.

Data Field Mandatory? Data Description

Type

productCode YES Character The type of main product sold in booking.

Can either be:
TKT: This is any type of individual ticket or
booking for an event, transportation, tour,
activity, or any other non-refundable ticket
for admission.
PKG: This is a package that includes a
combination of ticket/tour/transportation
AND accommodation, travel etc.
HTL: This is any type of accommodation
booking which is non-refundable or non-
cancellable.

currencyCode YES Character Code of currency that the booking was

bought in (ISO 4217 code, reference:
https://en.wikipedia.org/wiki/ISO_4217)

productPrice YES Numeric End value of the transaction (includes

product cost, booking fees, payment fees,
Refund Protect fee etc). This numeric
value must have decimal point set to “.”

sold YES Boolean This tells the Protect Platform if the

customer has selected Refund Protect on
their booking. If sold the content should be
“true”. If the customer has not selected to
protect their booking the content should be
“false”.

premiumRate YES Numeric This is the percentage the customer is

charged for the service (e.g 8).

4/11
 offeringMethod NO Character The method that you are offering Refund
Protect and must use the following values:

OPT-IN – The customer is required to opt-
in to the protection. 

OPT-OUT – The service is either pre-
selected for the customer or automatically
build into the transaction

insuranceEndDate YES Character The start date and time of the booking.
This needs to be in ISO8601 UTC format
(YYYY-MM-DDTHH:mm:ss.ssss)
E.g. 2021-08-01T00:00:00+00:00

Response Signals:

200 OK Signal

202 OK Signal, delay more than 3 seconds occurred

400 Bad Request, Request Call not implemented

401 Not-authorised; you are missing authorisation

405 Current method not allowed; needs to be PUT/POST method

408 Request timeout response taking too much time to complete

413 Request entity too large or submitted entry too large

422 Entity unable to be processed as it is missing data (e.g. missing productPrice value)

500 Internal server error, no data stored

507 Insufficient storage, no data stored

IMPORTANT INFORMATION

We require all transactions. Both sold:true and sold:false to enable ongoing commercial
management.

Cancellation API
This API is used to cancel a previously submitted transaction. This API uses a slightly
different Request URL, requiring the transaction booking reference number at the end of the
URL however everything else is exactly the same.

5/11
UAT Request URL -
https://test.api.protectgroup.co/api/v1/refundprotect/{transactionID}

Method Required: DELETE http method

Once the tests have been validated by the Protect Group team, you will be provided with a
Request URL for the Live Production Environment.

Request Header

Content-Type: application/json

X-RefundProtect-VendorId: Your unique VendorID

X-RefundProtect-AuthToken: Your unique API Key

Commercial Succes
Our service must be offered to your customers using the following template information.

It is important that you decide on the best front-end sales process of Refund Protect to
incorporate within your booking flow. You MUST consider the local consumer sales
regulations of your country as this sales process is your responsibility as the Member of
Refund Protect.

You must present Refund Protect in the following way to ensure that your option of a
refundable booking is in no way considered insurance and is not connected to our Refund
Protect brand.

Option A INFORMED CHOICE

Option B CUSTOMER OPTING IN

Option C APPLY TO ALL

6/11
OPTION A: INFORMED CHOICE
The service is offered in a single page checkout and/or booking
flow.

The section is highlighted and recommended.

The customer is presented with a yes and no option and must

positively select either one to proceed.

**IMPORTANT: Please ensure that INFORMED CHOICE is

compliant with consumer sales regulations within your country
if you wish to adopt this sales process.

WORDING

O Refundable booking (Recommended) £X.XX

- Covid-19 infection, see details

- Sickness, Accident, Injury

- Public transport failure
- Private vehicle failure
- Emergency services recall
- Home emergency
- Immediate relative sickness
- Pre-existing medical conditions
And many more…

Upgrade your booking and receive a 100% refund if you

cannot attend and can evidence one of the many reasons in
our Terms and Conditions, which you accept when you select a
Refundable Booking.

O Non-refundable booking

Terms and Conditions URL

You must link the Terms and Conditions in the placement wording
above to our most up-to-date terms using the URL:
https://www.refundable.me/

For a personalised Refundable URL with your brand included,

please contact your Protect Group Manager.

7/11
OPTION B: NEXT STEP
NEXT STEP is designed for multi-step checkouts whereby the
Refundable option is offered to the customer on a separate page
before payment. The customer is encouraged to opt-in through the
“Refundable booking” button in Green.

This process is only suitable for booking flows that are multi-stage
and would not be fit for implementation into a single page checkout.
We’d therefore recommend the INFORMED CHOICE sales process
for these types of checkouts.

**IMPORTANT: Please ensure that NEXT STEP is compliant with

consumer sales regulations within your country if you wish to
adopt this sales process.

WORDING

Upgrade to a Refundable booking (Recommended)

- Sickness, Accident, Injury

- Public transport failure
- Private vehicle failure
- Emergency services recall
- Home emergency
- Immediate relative sickness
- Pre-existing medical conditions
And many more…

Upgrade your booking and receive a 100% refund if you cannot

attend and can evidence one of the many reasons in our Terms
and Conditions, which you accept when you select a Refundable
Booking.

Keep my booking Non-refundable

Terms and Conditions URL

You must link the Terms and Conditions in the placement wording
above to our most up-to-date terms using the URL:
https://www.refundable.me/

For a personalised Refundable URL with your brand included,

please contact your Protect Group Manager.

8/11
 OPTION C: APPLY TO ALL
APPLY TO ALL is designed for members who wish to build the enhanced Refundable
terms into every transaction they process. This option does not require a front-end
selection box.

Terms of Sale
To add the latest version of the Refundable Terms into your existing terms of sale, you can
either insert a section of text which directs customers to the external Refundable Terms URL
(https://refundable.me).

Both of these methods are inserted within your Terms of Sale to customers to always provide
customers with access to the Refundable Terms and Conditions and all wording is provided
below:

Option A: External Link Wording

Please insert the following wording into your existing Terms of Sale alongside your standard
refund terms. Please note, if you choose the “Apply to All” sales implementation method
above, please insert the Apply To All wording as below.

INFORMED CHOICE / NEXT STEP sales methods wording:

If you have selected Refundable Terms on your booking and are unable to attend your
booking due to unforeseen circumstances outside of your control you may be entitled to a
refund - please see our full set of Refundable Terms and Conditions here. To apply for a
refund, please find the instructions on how to apply in the booking confirmation email you
received after payment.

For any other refund enquiries, including where your is cancelled or changed by the , please
contact our customer service team at .

APPLY TO ALL sales method wording:

We provide all our customers with Refundable Terms so if you are unable to attend your
booking due to unforeseen circumstances outside of your control you may be entitled to a
refund - please see our full set of Refundable Terms and Conditions here. To apply for a
refund, please find the instructions on how to apply in the booking confirmation email you
received after payment.

For any other refund enquiries, including where your is cancelled or changed by the , please
contact our customer service team at .

9/11
 Booking Confirmation Email
It’s very important that you place the wording in your Booking Confirmation
email which you normally send to customers after their payment to confirm
their booking. This must be the only email referencing Refundable Terms to
position the service correctly in a legal and compliant manner.

The following additional wording in your booking confirmation email

provides information on their Refundable Terms which are applied to their
booking, how to apply for a refund should they be prevented from attending
due to a circumstance within the Refundable Terms and the reference (your
own booking referenceb posted through API) they should use for the
Refund Application Form:

INFORMED CHOICE / NEXT STEP sales methods wording:

You selected refundable terms with your booking, so if you are unable to
attend your booking due to unforeseen circumstances and can provide
evidence as listed in the Terms and Conditions here, you may be entitled
to a full refund.

You will need your reference number

<Insert VendorSalesReferenceID> to apply for your refund using the
form here.

For any other refund enquiries, including where your <Insert booking
type> is cancelled or changed by the <Insert supplier type>, please contact
our customer service team at <Insert your standard customer service point
of contact>.

APPLY TO ALL sales methods wording:

This is a Refundable booking, so if you are unable to attend your booking
due to unforeseen circumstances and can provide evidence as listed in the
Terms and Conditions here, you may be entitled to a full refund.

You will need your reference number

<Insert VendorSalesReferenceID> to apply for your refund using the
form here.

For any other refund enquiries, including where your <Insert booking
type> is cancelled or changed by the <Insert supplier type>, please contact
our customer service team at <Insert your standard customer service point
of contact>.

CONTACT OUR TEAM

If you have any questions or require further clarification on the Refund Protect API
Integration, please get in touch with our technical support team using at
integration@protectgroup.com

10/11
11/11