Introduction
Welcome to the Refund Protect Integration Guide, which is designed to help you set up the Refund Protect offering on your booking platform.
For the first step of the Refund Protect
integration, a member of the Protect
Group team will provide you with a new
Protect Platform account with your
VendorID and API Key.
If you have registered for a Protect
Platform account you will receive an
email from our Protect Platform with
access credentials.
Please get in touch with our integrations team ([email protected]) should you require your VendorID, API Key and/or Protect Platform details
About the API
This simple Refund Protect API is a REST service with UTF-8 encoding.
This Integration Guide is split into 2 parts:
- REST API Documentation
- Checkout Placement Setup
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
- Receive your UAT VendorID and API Key from Protect Group Manager ([email protected])
- 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:
- You can use the json data from this guide as a content starting point and send transactions from within Postman.
- Using Postman you can input your data to create content and validate
- Each API call requires a unique vendor reference ID
- 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.
- 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.
![]() |
Postman Collections You can access our Postman Collection which contains examples of the headers, requests and allows you to directly test your data structure. |
![]() |
Request Header
There are 2 parts to the request header found in every method call which you will be provided when you sign up to the UAT Protect Platform:
X-RefundProtect-VendorId
This is your unique VendorID as provided to you by the Protect Group team when you create a new UAT Protect Platform account. This UAT VendorID will be replaced with a production VendorID once testing has been verified.
X-RefundProtect-AuthToken
This is your unique API Key as provided to you by the Protect Group team when you create a new UAT Protect Platform account. This 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 |
![]() |
Postman Collections Please find examples of the Request Header structure in our Postman Collections here. |
![]() |
Sales Request
What does this do?
This tells us that a customer has or has not selected Refund Protect to protect their non-refundable transaction. You will send us the request in the same format as the data structure as shown below when a customer completes their booking and makes their payment.
We also need to know when the customer chooses not to select Refund Protect on their booking as this helps us to analyse your customer conversion rate and help optimise your sales process of Refund Protect. Please note: this is a mandatory requirement however can receive “false” information in the data structure to comply with data regulations.
Method Required: | PUT/POST http method (other methods will return an error message). |
Request URL
The following URL is to be used in order to send test transactions to the UAT Endpoint. Once tests have been validated by the Refund Protect Technical team, you will be provided with a Live Production URL which you will simply swap.
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. |
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 timeout: | In case no response is returned from the API, a request timeout should be 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"
}
]
}
![]() |
Postman Collections Test your data structure using our Postman Collections here! |
![]() |
Transaction Related Data Explanation:
Data Field | Mandatory? | Data Type | Description |
vendorCode | YES | Character | Your VendorID as found in the Account Management section of the UAT or Live Production Protect Platform |
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:
Data Field | Mandatory? | Data Type | Description |
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 by you for Refund Protect e.g. 8.0 (this is not the basic flat-fee cost that we charge to the Member). The decimal point must be set to “.” |
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 – Refund Protect is either pre-selected for the customer or automatically built 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. 2019-08-01T00:00:00.0000 |
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
It is mandatory as per your agreement to send Protect Group sales requests for all transactions including where Refund Protect has not been sold and therefore the sold data field is “false”. This is to enable the Protect Group team to measure your conversion and help you optimise the performance of this offering.
During the testing process, you must also send tests of sold = false transactions in order for you to receive your LIVE Platform credentials. If you have any questions please discuss with your dedicated Protect Group Manager. |
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.
UAT Request URL - https://test.api.protectgroup.co/api/v1/refundprotect/{transactionID}{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 |
Checkout Placement Setup
The following section provides the wording and visuals for the front-end placement of Refund Protect in your online checkout and booking confirmation emails.
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 |
NEXT STEP |
![]() |
|
Option C |
APPLY TO ALL |
OPTION A: INFORMED CHOICEINFORMED CHOICE is a process where the Refundable booking is offered to customers in a single-page checkout and/or booking flow. The price is included within the section and the ‘Refundable’ selection is highlighted and ‘(Recommended)’. The customer must be provided with both a ‘REFUNDABLE’ and ‘NON-REFUNDABLE’ option and must select either one to proceed with the next step of the booking process.
WORDING
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. |
![]() |
OPTION B: NEXT STEPNEXT 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.
WORDING
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. |
![]() |
OPTION C: APPLY TO ALLAPPLY 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 and members simply insert the following text into their Terms and Conditions of sale: 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 terms and conditions above. To apply for a refund please contact our refund team at https://refunds.refundprotect.co/ Should your reason for refund not be found in the Refundable Terms and Conditions above, please get in contact with our standard customer service team . |
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), or you can embed the below code to display the live Refundable Terms within your own website.
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
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
Option B: Embed Refundable Terms & Conditions
To display the latest set of Refundable Terms within your own terms of sale page, you can insert the following code to display a live embed of the Refundable Terms.
Please use the title “Refundable Bookings” for this section within your Terms of Sale.
Embed code
|
|
![]() |
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 the details below.