Checkout API

1-CP Corporate Checkout API

Overview

This documentation provides a detailed guide on how to use the Client API to create transactions. The API uses a POST endpoint and is authenticated using Basic Auth with base64 encoding of the client ID and the client secret.

Authentication

Authentication Details

When accessing the Client API, authentication is handled through Basic Auth. This requires the combination of your client ID and client secret, which must be converted into a base64 string. The resulting encoded string is then used as the value of the Authorization header in the format shown below:

Authorization: Basic base64(client_id:client_secret)

Here's a step-by-step process to prepare the Authorization header:

1. Combine: Concatenate your client ID and client secret with a colon, like this: client_id:client_secret.

2. Encode: Convert this string to its base64 representation.

3. Insert: Place the base64 string into the Authorization header with the "Basic" prefix.

This method securely transmits your credentials to allow API access. Always ensure that your base64 encoded string is correctly formatted to avoid authentication errors.

The API uses Basic Auth for authentication. The client ID and secret should be encoded in base64 and included in the Authorization header.

Example:

Authorization: Basic base64(client_id:client_secret)

Endpoint :

1- POST /transactions

Request Body

The request body should be a JSON object that matches the CorporateCheckout the structure described below.

CorporateCheckout Object

Property	Type	Required	Description
refIDs	Map		External identifiers associated with the CorporateCheckout.
title	string		Title of the CorporateCheckout.
currency	string		Currency code for the CorporateCheckout.
items	array of Item		List of items included in the CorporateCheckout.
attachments	Attachments		List of attachments associated with the CorporateCheckout.
note	string		Additional notes about the CorporateCheckout. (Internal note only - not visible to the customer)
email	CheckoutEmail		Email content Subject and recipients which will be recieve the contract email.

Item Object

This is the basic item properties:

Property	Type	Required	Description
stockId	string		Extenal Stock identifier for the item.
name	string		Name of the item.
category	enum		Item Category.
description	string		Description of the item.
price	number		Price of the item.
quantity	Quantity		Quantity details of the item.
totalTax	number		Total tax applicable to the item. This value will be calculated based on the taxes in case it is not provided(exp. 10)
total	number		Total cost of the item including taxes. This value will be calculated based on the taxes and the price in case it is not provided(exp. 1350)
taxes	array of Tax		List of taxes applicable to the item
co2	number		Carbon dioxide pollution.
cancellationPolicy	CancellationPolicy		cancellation policy applicable to the item.

There are nine types of items that need additional properties in addition to the basic properties.

Accommodation

Property	Type	Required	Description
period	Period		Time period for which the item is valid.
location	Location		Location address.
locationName	string		Location name (property name)
accommodationType	enum		AccommodationType
roomType	enum		RoomType

Rail

Property	Type	Required	Description
period	Period		Time period for which the item is valid.
departure	Location		Location address.
destination	Location		Location address.
serviceClass	enum		FIRST_CLASS, BUSINESS_CLASS, ECONOMY_CLASS, OTHER

Rental car

Property	Type	Required	Description
period	Period		Time period for which the item is valid.
pickUpLocation	Location		Pick-up location.
dropOffLocation	Location		Drop off location.
classificationCode	string		Classification code

Taxi shuttle

Property	Type	Required	Description
period	Period		Time period for which the item is valid.
pickUpLocation	Location		Pick-up location.
dropOffLocation	Location		Drop off location.

Flight

Property	Type	Required	Description
period	Period		Time period for which the item is valid.
flightNumber	string		Flight number.
departure	string		Departure - 3-letter IATA airport code. e.g. FRA
destination	string		Destination - 3-letter IATA airport code. e.g. MUC
airline	string		Airline - 3-letter ICAO or 2-letter IATA airline code. e.g. LH
serviceClass	enum		FIRST_CLASS, BUSINESS_CLASS, ECONOMY_CLASS, OTHER
fareClass	string		Fare class

Parking

Property	Type	Required	Description
period	Period		Time period for which the item is valid.

Other Travel

Property	Type	Required	Description
period	Period		Time period for which the item is valid.

Travel Agency

Property	Type	Required	Description
period	Period		Time period for which the item is valid.

Public Transportation

Property	Type	Required	Description
period	Period		Time period for which the item is valid.

The items will be arranged in the order in which they appear. The first item is considered the main item.

Types

Category Type

// Travel Categories
FLIGHT
RENTAL_CAR
TAXI_SHUTTLE
ACCOMMODATION
EVENT
SERVICE
PUBLIC_TRANSPORTATION
MICRO_MOBILITY
PARKING 
FUEL 
FEE
F_AND_B
OTHER
RAIL
CONFERENCE
TRAVEL_AGENCY
OTHER_TRAVEL

// Sales & Marketing Categories
ADVERTISING
MARKET_RESEARCH
CONFERENCE_NOT_TRAVEL
SUBSCRIPTION

// Research & Development Categories
LAP_SUPPLY
CONSULTING

// Technology & Subscriptions Categories
HARDWARE
SOFTWARE_AND_IT
SOFTWARE_SUBSCRIPTION
TELECOM

// General & Administrative Categories
OFFICE_SUPPLY
OFFICE_EQUIPMENT_AND_FURNITURE
RENT_AND_LEASE
UTILITIES
INSURANCE
LEGAL_FEE
ADMINISTRATIVE_SERVICE
RETAIL

Tax Type

NET_PRICE                                     
VAT
BED_TAX
CITY_HOTEL_FEES
COUNTRY_TAX
CITY_TAX
ENERGY_CHARGE
FEDERAL_TAX
GST
INCLUSION
LODGING_TAX
MAINTENANCE_FEE
OCCUPANCY_TAX
PACKAGE_RATE_FEE
ROOM_TAX
RESORT_FEES
SALES_TAX
STATE_PROVINCE_TAX
SURCHARGE
SERVICE_CHARGE
OTHER_TAX
TOURISM_TAX

Accommodation Type

 RESORT
 HOSTEL
 HOTEL
 INN
 LODGE 
 MOTEL
 LOVE_HOTEL
 KP_BUSINESS_HOTEL
 CAPSULE_HOTEL
 APARTMENT
 BED_BREAKFAST
 CAMPING
 CHALET
 BOAT
 FARM_STAY
 TENTED
 VILLA
 GUEST_HOUSE
 APART_HOTEL
 RIAD 
 RYOKAN
 HOME_STAY
 HOLIDAY_HOME
 COUNTRY_HOUSE
 HOLIDAY_PARK

Room Type

APARTMENT
QUADRUPLE
SUITE
TRIPLE
TWIN
DOUBLE
SINGLE
STUDIO
FAMILY
TWIN_DOUBLE
DORMITORY_ROOM
BEDINDORMITORY
BUNGALOW
CHALET
HOLIDAY_HOME
VILLA
MOBILE_HOME
TENT

Location Object

Property	Type	Required	Description
street	string		Street name.
house	string		Number of Apartment.
postCode	string		ZipCode.
city	string		City name.
country	string		Country name
lat	string		Latitude of the Location.
lng	string		Longitude of the Location.

Either street/house combination or latitude/longitude combination must be present

Period Object

Property	Type	Required	Description
start	date time		Start Date/time using the ISO 8601 localized to the time zone at origin/ start.
end	date time		End Date/time using the ISO 8601 localized to the time zone at destination/ end.

Item Quantity Object

Property	Type	Required	Description
amount	number		Amount of the quantity. Min is 1
unit	enum		Unit of the quantity : FLAT_FEE, PER_HOUR PER_DAY, PER_NIGHT, PER_WEEK, PER_MONTH, PER_YEAR, PER_PERSON . Default value FLAT_FEE

Item Tax Object

Property	Type	Required	Description
type	enum		Type of the tax.see Tax type. Default VAT
value	number		Value of the tax based on the unit used (if the unit provided is AMOUNT, we expect the value to be based on the currency used in the CorporateCheckout).
unit	enum		Unit of the tax value. AMOUNT, PERCENT . Default PERCENT
basis	enum		Basis of the tax calculation: FLAT_FEE, PER_QUANTITY. Default PER_QUANTITY
applyTo	enum		Indicates what the tax applies to. Tax type

Attachment Object

Property	Type	Required	Description
url	string		URL to the file. (File size is limited to 10MB if uploaded to our system; otherwise, the URL must be publicly available and accessible at all times.)
type	string		Type of the attachment: INVOICE, PROPOSAL, TERMS_CONDITIONS, PICTURES, HEADER_IMAGE, OTHER.

The first image will beHEADER_IMAGEand the rest will be PICTURES.

CheckoutEmail Object

Property	Type	Required	Description
recipients	Recipient emails		List of recipients associated with the CorporateCheckout.
subject	string		The email subject that well be send to the Recipient list
content	string		The email content that well be send to the Recipient list

SetUp Cancellation of Item

• If sent item does not have a cancellation policy, the cancellation policy will be determined based on the configuration of the service provider company.

• If there are no applicable config for the service provider company, the policy will remain empty, and the items get created without a Cancelation Policy and Always refund the full amount (default 1-CP Policy will applied).

• Basically we have two reference date to do cancellation:

  1. Start period date (it is used with items that have a period property only)

  2. Payment date (it is used with all items)

you can determine the refrence date through CncellationPolicy.reference property.

Cancellation Policy

Property	Type	Required	Description
description	string	no	Description of applicable penalty
reference	enum	yes	Type of refrence Enum: [PAYMENT_DATE, START_PERIOD]
penalties	array of Penalty	yes	List of penalties applicable to the item.

Penalties types

• There are two models for determining the penalty:

1. DatePenalty: based on dates explicitly

2. OffsetPenalty: based on offsets relative to the reference

• The CancellationPolicy.penalties should be of one type, either DatePenalty or OffsetPenalty. Not both types together.

DatePenalty

Property	Type	Required	Description
type	enum	yes	Type of Penalty Enum: [DATE_PENALTY]
value	CancellationPenaltyValue	yes	Value of Penalty
until	Date	yes	The date after which the penalty will be applied

OffsetPenalty

Property	Type	Required	Description
type	enum	yes	Type of Penalty Enum: [OFFSET_PENALTY]
value	CancellationPenaltyValue	yes	Value of Penalty
offset	CancellationPenaltyOffset	yes	The time offset which will be applied
condition	string	no	Penalty Condition

CancellationPenaltyValue

Property	Type	Required	Description
amount	number	yes	Penalty amount
unit	enum	yes	Penalty value unit Enum: [FIXED_AMOUNT, PERCENTAGE]

CancellationPenaltyOffset

Property	Type	Required	Description
amount	number	yes	Penalty amount
unit	enum	yes	Penalty offset unit Enum:[DAYS, HOURS, MONTHS]

If the penalties of item is empty array then the default default 1-CP Policy will applied.

Example Request

{
    "refIDs": {
        "provider-id": "667999d063824b596cf82155sdfwew334435"
    },
    "title": "Off site event",
    "currency": "EUR",
    "items": [
        {
            "stockId": "12345", // items id form the provider
            "name": "Flight",
            "category": "FLIGHT",
            "description": "Description of first item in CorporateCheckout",
            "period": {
                "start": "2024-04-16T12:07:05.159Z",
                "end": "2024-04-16T12:07:05.159Z"
            },
            "price": 450,
            "totalTax": 10,
            "total": 1350,
            "taxes": [
                {
                    "type": "VAT",
                    "value": 100,
                    "unit": "PERCENT",
                    "basis": "PER_QUANTITY",
                    "applyTo": "NET_PRICE"
                }
            ],
            "departure": "FRA",
            "destination": "MUC",
            "airline": "LH",
            "serviceClass": "FIRST_CLASS",
            "cancellationPolicy": {
                "description": "cancellation Policy",
                "reference": "PAYMENT_DATE",
                "penalties": [
                    {
                        "type": "OFFSET_PENALTY",
                        "offset": {
                            "amount": 2,
                            "unit": "DAYS"
                        },
                        "value": {
                            "amount": 20,
                            "unit": "FIXED_AMOUNT"
                        },
                        "condition": "AFTER_PAYMENT"
                    },
                    {
                        "type": "OFFSET_PENALTY",
                        "offset": {
                            "amount": 3,
                            "unit": "DAYS"
                        },
                        "value": {
                            "amount": 80,
                            "unit": "FIXED_AMOUNT"
                        },
                        "condition": "AFTER_PAYMENT"
                    }
                ]
            }
        }
    ],
    "recipients": ["[e-mail]"],
    "attachments": [
        {
            "url": "http://file_url.pdf",
            "type": "INVOICE"
        }
    ]
}

Response

The response will contain the created transaction ID, as the following:

{
    "transactionId": "1234567890"
}

Error Handling In Post Transaction Request

If there are any errors in the request, the API will return an appropriate error message with a status code indicating the type of error.

Example:

{
    "message": [
        "currency should not be empty", 
        "items.0.price should not be empty"
    ],
    "error": "Bad Request",
    "statusCode": 400
}