📋 Corporate Checkout Schema

CorporateCheckout

This is the main object for creating a Corporate Checkout transaction. It includes all the information needed to process a transaction through the One-CP platform.

Property	Type	Required	Description
refIDs	Map	No	External identifiers associated with the CorporateCheckout.
title	string	Yes	Title of the CorporateCheckout.
currency	string	Yes	Currency code for the CorporateCheckout.
items	array	Yes	List of items included in the CorporateCheckout.
attachments	array	No	List of attachments associated with the CorporateCheckout.
note	string	No	Additional notes about the CorporateCheckout. (Internal note only - not visible to the customer)
email	object	No	Email content Subject and recipients which will receive the contract email.
restrictedMethods	array	No	Payment methods that the provider has deactivated

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

Rental car

Taxi shuttle

Flight

Parking

Other Travel

Travel Agency

Public Transportation

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

Accommodation Type

Room Type

Location Object

Property	Type	Required	Description
street	string		Street name.
house	string		Number of Apartment.
zipCode	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 will be sent to the Recipient list.
content	string		The email content that will be sent to the Recipient list.

Payment Method Restriction

Merchant can declare which methods to disable when initializing a transaction. For example to restrict Visa and Klarna from use during contract checkout:

restrictedMethods: ['VIS', 'KLN']

Payment Method Name	Payment Method Code
MasterCard	ECA
Visa	VIS
American Express	AMX
China Union Pay	CUP
Diners Club	DIN
Discover	DIS
JCB	JCB
EPS	EPS
iDEAL	DEA
Klarna	KLN
MobilePay	MBP
PayPal	PAP
BanContact	BCN
Przelewy24	P24

Set Up Cancellation of Item

• The cancellationPolicy must be either a fully detailed object or a text.

• 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 Cancellation 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 reference date through CancellationPolicy.reference property.

Cancellation Policy

Property	Type	Required	Description
description	string	no	Description of applicable penalty
reference	enum	yes	Type of reference 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]

CancellationReq

Request body for the cancel and refund endpoint.

Property	Type	Required	Description
contractId	string	Yes	ID of the contract to cancel.
itemsOrder	number[]	Yes	Array of item order numbers to cancel.
amount	number	No	Specific refund amount. If not provided, the maximum refundable amount will be calculated based on cancellation policy.
invoiceNumber	string	No	Invoice number to associate with the cancellation.
invoiceTitle	string	No	Title of the invoice.

ValidationError

Describes the error response when request validation fails.

Property	Type	Description
message	string[] | string	Array of error messages or a single message.
error	string	General error type (e.g., "Bad Request").
statusCode	number	HTTP status code.

Update Corporate checkout

Some properties of the Transaction can be updated to reflect changes such as title. These updates are restricted to specific fields to ensure the transaction’s consistency.

Property	Type	Description	example
title	string	Title of the transaction.	Booking
note	string	Note of the transaction.	note text
externalIds	object	External ids of the transaction	{ "sap_id": "12345"}
attachments	object	Attachment associated with transaction	See attachment above