🎰API Details

Header

Endpoint (Staging)	https://gw-dev.saladin.vn/api/v1/trip-insurance
Endpoint (Production)	​https://gw.saladin.vn/api/v1/trip-insurance
X-Sld-Timestamp	Request call time, in seconds
X-Sld-ClientKey	Client Key is issued to 3rd Party
X-Sld-Signature (param)	The signature is generated based on the request body

How to generate X-Sld-Signature

// request body
body = {
    "<field_name>": <field_value>,
    "<field_name>": <field_value>,
    "<field_name>": <field_value>,
}

payload = timestamp + "." + client_key + "." + json_stringify(data)
secret = "<client_secret>"
encoded_payload = base64_safeurl_encode_no_padding(payload)
signature = HMAC_SHA256(secret, payload)

API #01 - Calculate Premium v2

GET{{endpoint}}/vendor/accident-insurance/v2/premiums

• Purpose: Enable partners to access multiple insurance products with a single request.

• Trigger when: Users select to purchase the insurance for the trip.

Partners can also use an older version here; however, they can only retrieve one insurance product per API call

Headers

Name	Value
X-Sld-Timestamp	Timestamp when calling request in second
X-Sld-ClientKey	Client key which is given to partner
X-Sld-Signature	The code is generated according to the instructions in the 'How to generate X-Sld-Signature' section

Query parameters

Name	Type	Description
number_of-seat	interger
channel	enum	1 - Offline. 2 - Online.

Response

200

{
    "code": 0,
    "message": "OK",
    "data": {
        "products": [
            {
                "product_code": "e_trip_pa_04",
                "product_premium": "50000",
                "product_detail_url": "https://www.saladin.vn/bao-hiem-lien-ket/bao-hiem-chuyen-di-mtn200"
            },
            {
                "product_code": "e_trip_pa_05",
                "product_premium": "100000",
                "product_detail_url": "https://www.saladin.vn/bao-hiem-lien-ket/bao-hiem-chuyen-di-mtn400"
            }
        ]
    }
}

API #02 - Create Policy

Post: /vendor/accident-insurance/policies

• Purpose: The partner can request this API to create the insurance contract.

• Trigger when: After customers make payment successfully for their order.

Parameters

Body

Field	Data Type	Description	Required
order_id	string	The id of the order on the partner system.	Y
product_code	string	The product code which is returned by the API#1	N
channel	enum	1 - Offline. 2 - Online.	Y
buyer_name	string	Full name of the buyer	Y
buyer_phone	string	Phone number of the buyer	Y
buyer_email	string	email of the buyer	Y
bus_operator	string		Y
bus_phone_number	string		Y
bus_number_plate	string		N
driver_phone	string	Phone number of the driver	N
contract_date	timestamp	The time that the customer confirmed and made the payment for the insurance contract.	Y
trip_start_time	timestamp		Y
trip_end_time	timestamp		Y
from_city	string	e.g Thành phố Hồ Chí Minh	Y
to_city	string	e.g Thành phố Hồ Chí Minh	Y
from_address	string	e.g 135, Thành Thái, Quận 10, Thành phố Hồ Chí Minh	Y
to_address	string	e.g 135, Thành Thái, Quận 10, Thành phố Hồ Chí Minh	Y
ticket_number	string		Y
seat_numbers	array	e.g: A4, B5, ....	Y
price	number	Paid amount after the promotion/discount	Y
product_premium	string	1000000	Y
app_ref_id	string	A unique request ID from the partner to distinguish this request from others

Responses

200	OK

{
    "code": 0,
    "message": "OK",
    "data": {
        "policy_id": "string",
        "policy_number": "string",
        "claim_url": "string"
    }
}

API #03 - Cancel ticket

• Purpose: The partner can request this API to cancel the ticket of a policy.

• Trigger when: When the user makes canceling the ticket on the partner's tools.

Cancel ticket

put

Path parameters

policy_idstringRequired

order_idstringRequired

ticket_numberstringRequired

Header parameters

X-Sld-TimestampnumberRequired

Timestamp when calling request in second

X-Sld-ClientKeystringRequired

Client Key which is given to partner

X-Sld-SignaturestringRequired

Client Key which is given to partner

Body

cancellation_bystringRequired

cancellation_reasonstringRequired

seat_numbersstring[]Optional

customer_namestringRequired

customer_phonestringRequired

Responses

200

A successful response.

application/json

default

An unexpected error response.

application/json

put

HTTPcURLJavaScriptPython

PUT /vendor/accident-insurance/policies/{policy_id}/orders/{order_id}/tickets/{ticket_number} HTTP/1.1
Host: 
X-Sld-Timestamp: 1
X-Sld-ClientKey: text
X-Sld-Signature: text
Content-Type: application/json
Accept: */*
Content-Length: 126

{
  "cancellation_by": "text",
  "cancellation_reason": "text",
  "seat_numbers": [
    "text"
  ],
  "customer_name": "text",
  "customer_phone": "text"
}

{
  "code": 1,
  "message": "text"
}

API #04 - Create claim request

• Purpose: The partner system call to submit a claim request to Saladin when the customer cancels the trip and they eligible to participate in the program "Tri ân khách hàng".

• Trigger when: When the user cancels the trip and presses a CTA to submit a claim request.

Parameters

Body

Create claim

post

Header parameters

X-Sld-TimestampnumberRequired

Timestamp when calling request in second

X-Sld-ClientKeystringRequired

Client Key which is given to partner

X-Sld-SignaturestringRequired

Client Key which is given to partner

Body

policy_idstringOptional

ticket_numberstringOptional

order_idstringOptional

requested_bystringOptional

requested_datestring · int64Optional

seat_numbersstring[]Optional

customer_namestringOptional

customer_phonestringOptional

cancellation_reasonstringOptional

Responses

200

A successful response.

application/json

default

An unexpected error response.

application/json

post

HTTPcURLJavaScriptPython

POST /vendor/trip-insurance/claims HTTP/1.1
Host: 
X-Sld-Timestamp: 1
X-Sld-ClientKey: text
X-Sld-Signature: text
Content-Type: application/json
Accept: */*
Content-Length: 207

{
  "policy_id": "text",
  "ticket_number": "text",
  "order_id": "text",
  "requested_by": "text",
  "requested_date": "text",
  "seat_numbers": [
    "text"
  ],
  "customer_name": "text",
  "customer_phone": "text",
  "cancellation_reason": "text"
}

{
  "code": 1,
  "message": "text"
}

API #05 - Update Policy

PUT : /vendor/accident-insurance/policies/:policy_id

• Purpose: The partner can request this API to edit the insurance contract.

• Trigger when: Customer or Admin makes changes details of the order.

• Rules for update:

  • All changes are only accepted before the estimated time departure of the trip.

  • All of the fields on the API's body will be replaced on the insurance contract except channel.

  • If the insurance premium increases, the customer must pay more or the agent must collect the difference in the payment_amount field.

Parameters

Path

Field	Data Type	Description	Required
policy_id	string		Y

Body

Field	Data Type	Description	Required
order_id	string	The id of the order on the partner system.	Y
channel	enum	1 - Offline. 2 - Online.	Y
ticket_number	string		Y
buyer_name	string	Full name of the buyer	Y
buyer_phone	string	Phone number of the buyer	Y
buyer_email	string	email of the buyer	Y
bus_operator	string		Y
bus_phone_number	string		Y
bus_number_plate	string		N
driver_phone	string	Phone number of the driver	N
contract_date	date_time	The time that the customer confirmed and made the payment for the insurance contract.	Y
trip_start_time	date_time		Y
trip_end_time	date_time		Y
from_city	string	e.g Thành phố Hồ Chí Minh	Y
to_city	string	e.g Thành phố Hồ Chí Minh	Y
from_address	string	e.g 135, Thành Thái, Quận 10, Thành phố Hồ Chí Minh	Y
to_address	string	e.g 135, Thành Thái, Quận 10, Thành phố Hồ Chí Minh	Y
	string		Y
seat_numbers	array	e.g: A4, B5, ....	Y
price	number	Paid amount after the promotion/discount	Y

Responses

200	OK

{
  "code": "integer",​
  "message": "string",​
  "policy_id": "string"
  "policy_number": "string"
  "new_premium_amount": "integer"
  "payment_amount": "integer"
}

API #06 - Get policy information

• Purpose: The partner can call this API to check the status of the policy of the order.

Get Policy

get

Query parameters

order_idstringOptional

Header parameters

X-Sld-TimestampnumberRequired

Timestamp when calling request in second

X-Sld-ClientKeystringRequired

Client Key which is given to partner

X-Sld-SignaturestringRequired

Client Key which is given to partner

Responses

200

A successful response.

application/json

default

An unexpected error response.

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/trip-insurance/vendor/accident-insurance/policies HTTP/1.1
Host: 
X-Sld-Timestamp: 1
X-Sld-ClientKey: text
X-Sld-Signature: text
Accept: */*

{
  "code": 1,
  "message": "text",
  "data": {
    "order_id": "text",
    "channel": "CHANNEL_UNSPECIFIED",
    "buyer_name": "text",
    "buyer_phone": "text",
    "buyer_email": "text",
    "bus_operator": "text",
    "bus_phone_number": "text",
    "bus_number_plate": "text",
    "driver_phone": "text",
    "contract_date": 1,
    "trip_start_time": 1,
    "trip_end_time": 1,
    "from_city": "text",
    "to_city": "text",
    "from_address": "text",
    "to_address": "text",
    "ticket_number": "text",
    "seat_numbers": [
      "text"
    ],
    "price": 1,
    "product_premium": 1,
    "app_ref_id": "text",
    "policy_id": "text",
    "policy_number": "text",
    "claim_url": "text"
  }
}

API #07 - Cancel Policy

Purpose: The partner can call this API to cancel the policy.

Rules For Cancellation

• The policy is only canceled 48 hours before the estimated departure time of the trip

Cancel Policy

post

Path parameters

policy_idstringRequired

Header parameters

X-Sld-TimestampnumberRequired

Timestamp when calling request in second

X-Sld-ClientKeystringRequired

Client Key which is given to partner

X-Sld-SignaturestringRequired

Client Key which is given to partner

Body

cancellation_reasonstringRequired

Responses

200

A successful response.

application/json

default

An unexpected error response.

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/trip-insurance/vendor/cancel-policy/{policy_id} HTTP/1.1
Host: 
X-Sld-Timestamp: 1
X-Sld-ClientKey: text
X-Sld-Signature: text
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "cancellation_reason": "text"
}

{
  "code": 1,
  "message": "text"
}