Introduction
Welcome to the 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 new platform account and is at hand to support you along the way, contact us at [email protected]
About the API
We use a REST SERVICE with UTF-8 encoding.
We have produced a Postman collection where you can 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:
Our 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
- Confirm 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 protected and are not invoiced, you can send through as many test transactions as you need. We recommend a minimum of 10 test transactions before moving to the Live Production Platform across 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
The request header has 2 parts:
X-RefundProtect-VendorId
Your unique VendorID (UAT VendorID will be replaced with a production VendorID once testing has been verified)
X-RefundProtect-AuthToken
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 |
|
Postman Collections Please find examples of the Request Header structure in our Postman Collections here. |
|
Post
What does this do?
We need to receive all transactions in the format provided below. We also need to know when the customer chooses not to select a Refundable Booking as this helps us to improve commercial performance 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. |
Patch
What does this do?
The Patch is used to update our platform of changes in value and/or end date when the customer makes changes to their booking.
The initial transaction will be made with the method "Post". If you'd like to amend this transaction value or end date you can send a second transaction with the exact same reference number with the method "Patch".
PATCH is treated as additional to what is already there; it doesn't replace the data that is already there.
| 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. |
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":"2021-07-27T07:42:36+01:00",
"customerFirstName": "John",
"customerLastName": "Doe",
"products": [
{
"productCode": "HTL",
"currencyCode": "USD",
"productPrice": 100,
"premiumRate": 8.0,
"offeringMethod": "OPT-OUT",
"sold": true,
"insuranceEndDate": "2022-01-15T07:42:36+01:00"
}
]
} |
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 for the service (e.g 8). |
| 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.
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 in one of the ways described in this section.
For the best commercial performance we will work with you on the best front-end sales process to incorporate within your booking flow. You MUST consider the local consumer sales regulations of the countries you trade in as this sales process is your responsibility.
Our refund program is presented as a white label service to your customers, and it is essential that you follow the instructions to ensure that it is not presented to customers in the way that an insurance proposition might be.
Option A |
INFORMED CHOICE |
||
Option B |
APPLY TO ALL |
OPTION A: INFORMED CHOICEThe 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.
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/extended/en For a personalised Refundable URL with your brand included, please contact your Protect Group Manager. |
 |
Terms of Sale
To add the latest version of the Refundable Terms into your existing terms of sale, you can insert a section of text which directs customers to the external Refundable Terms URL which we will provide during the integration process.
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 sales methods wording:
To make any changes to your booking or where it is cancelled or changed by the provider, please contact our Customer Service Team at ……
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.
APPLY TO ALL sales method wording:
To make any changes to your booking or where it is cancelled or changed by the provider, please contact our Customer Service Team at ……
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.
|
Booking Confirmation Email