Checkout – Bókun developer documentation

The checkout is performed in two steps:

Get checkout options.

Describes the checkout options available (e.g. partial payment, affiliate checkout, etc.)

Lists the payment methods available (card, cash, etc.)

Lists all questions that the customer needs to answer.

Send checkout request.

Specify which checkout option you want,

what payment method to use,

answers to questions, etc.

Process checkout response

If dynamic currency conversion quote is offered, then the next step must be to respond to that.

Else, if using card payment and provider type is REDIRECT, then redirect the customer to the secure external payment page.

Else, if payment method RESERVE_FOR_EXTERNAL_PAYMENT was used, then the reserved booking must be confirmed.

Else, access the booking details and the travel documents

The JSON schemas for the checkout options, checkout request, and checkout response are described next.

Reserving for external payment ("reserve then confirm") - 2 step booking process

Generally, when creating a booking via the Bokun API, you submit a booking checkout and get a confirmation immediately. However, sometimes it makes sense to do this in 2 steps instead of one:

Reserve: This will create a booking in the "reserved" state, holding all booked availability for a maximum of 30 minutes.

Confirm: This will confirm the reserved booking.

The most common cause for this is holding availability while you process payment. For example, if you are not using Bokun to process payment for your booking (i.e. you will handle charging the customer's card directly yourself), then you may find yourself in the following scenarios:

Creating a booking via Bokun API, but then charging the card fails.

Charging the card first, but then confirming the booking via Bokun fails because the product is no longer available.

To use the "reserve then confirm" workflow in the Bokun booking API, you would:

Call the Submit checkout (shopping cart or direct booking request) service, with paymentMethod as RESERVE_FOR_EXTERNAL_PAYMENT.

Charge the card outside Bokun API, using your payment provider.

Call the Confirm reserved booking (after external payment) service, specifying the amount paid.

Checkout Options Response Schema

The checkout options response schema has the following structure (see the schema online here:

https://bokun.github.io/api-docs/schemas/Checkout.html

The questions schema is described in detail in the "Questions schema" section. Let's have a look at the options in more detail:

Each checkout option has the following fields:

type: Specifies what type of checkout this option represents. Not all these types will be available, it depends on who is performing the checkout (e.g. customer on public website, vs user signed in on extranet, vs agent user, etc.). Will be one of the following values:

CUSTOMER_FULL_PAYMENT : End customer is paying the full amount at checkout.

CUSTOMER_PARTIAL_PAYMENT : End customer is paying a partial payment at checkout (e.g. a deposit).

CUSTOMER_NO_PAYMENT : End customer is booking, without paying. Booking will be confirmed, but marked as not paid.

AGENT_AFFILIATE : Checkout is performed by end customer via an agent. The agent is acting as an affiliate, which means that payment will go directly to the seller, and the agent will be owed commission for facilitating the booking - an affiliate invoice will be created. Only available if the affiliate checkout has been enabled for the agent.

AGENT_RESELLER : Agent user is performing the checkout, and accepting payment from end customer offline (e.g. hotel concierge taking cash directly from the customer). The agent will be invoiced for the net rate (total minus commission) - an agent invoice will be created. Only available if the reseller checkout has been enabled for the agent, AND the agent has money to spend on their account (via deposits or overdraft).

AGENT_CUSTOMER : Agent is performing the checkout as customer, paying the net rate during checkout.

label : A user friendly label for this checkout option.

questions : An optional list of questions that apply specifically for this checkout option.

amount: The amount to be paid if this checkout option is used.

currency : The currency of the amount to be paid if this checkout option is used.

formattedAmount : A string showing the amount and currency formatted in a human readable format.

partialPayment : This will be true if this checkout option represents partial payment.

minPartialAmount: If this checkout option represents partial payment, then this will hold the minimum amount payable. Note that this field should be ignored if partialPayment is false.

formattedMinPartialAmount: This is simply the minimum payable partial amount formatted with the currency. Note that this field should be ignored if partialPayment is false.

invoice : Shows the customer invoice with line items for this checkout option.

paymentMethods :

allowedMethods: The payments methods that are allowed for this checkout option. Note that all of the options will not always be available. This will depend on who is booking, and how. Will be an array containing one or more of the following options:

CARD : Payment online via credit or debit card.

CASH : Payment is taken offline.

VOUCHER : Paid via voucher from an external reseller.

RESERVE_FOR_EXTERNAL_PAYMENT: This is used for 2-step booking: Process checkout to reserve the booking, then accept payment externally, and finally call Bokun API to confirm the reserved booking.

cardProvider: If CARD is one of the allowed payment methods, then a card provider (payment processor) will be specified.

title: Name of the card payment provider

description: brief description of the card provider

logo: URL to the logo of this card payment provider

providerId: Unique ID of this card provider

providerType: will be one of the following options:

TOKEN: Payment will be done via embedded payment token form provided by the card payment provider. Card details are never passed to Bokun API. Instead a token returned by the card provider will be passed to Bokun during the checkout request.

REDIRECT: Customer will have to be redirected to an external secure webpage to enter their card details. The card payment provider will then send a callback to Bokun when payment is successfully processed, after which the booking will be confirmed.

SERVER_TO_SERVER: Card details are sent in the checkout request to the Bokun API, and Bokun will then communicate directly with the card provider on the server side.

uti: this stands for "Unique transaction identifier", and should be provided in the checkout request.

token: This is a token which is provided if provider type is TOKEN. Should be passed to the card provider payment form.

questions: Optional list of questions that the card payment provider requires the customer to answer.

Checkout Request Schema

The checkout request schema has the following structure (see the schema online here:

https://bokun.github.io/api-docs/schemas/CheckoutRequest.html

checkoutOption : specifies which checkout option to use (must be on of the options specified in the previously returned checkout options response)

paymentMethod : specifies which payment method to use

source: specifies the source of the product bookings:

SHOPPING_CART: bookings should be taken from the shopping cart

DIRECT_REQUEST: bookings are specified in a direct booking request attached

shoppingCart : Only relevant if source is SHOPPING_CART.

uuid: Specifies the UUID (session ID) of the shopping cart being used

bookingAnswers: Answers to any booking questions that were asked in the checkout options response.

externalBookingReference: Optional. Specifies a reference to the booking from an external system.

externalBookingEntityName: Optional. Specifies the name of the external booking entity that created the booking. Max 255 characters.

externalBookingEntityCode: Optional. Specifies the code/ID of the external booking entity that created the booking. Max 100 characters.

directBooking : Only relevant if source is DIRECT_REQUEST (not using shopping cart)

See the Booking Request schema for details.

sendNotificationToMainContact: Specifies whether to send notification (email, etc.) to the main contact after confirming the booking. Defaults to false if not specified.

showPricesInNotification: Only relevant if sendNotificationToMainContact is true. Then it is possible to specify here whether to show prices in the notification that is sent.

amount: This is only relevant if this is a checkout using a partial payment. In that case this field specifies the partial amount being paid. Else amount is always assumed to be the full due amount.

currency: This is only relevant if this is a checkout using a partial payment. Specifies the currency for the amount being paid.

uti: The unique transaction identifier for the payment, simply copied from the uti supplied in the checkout options response.

paymentToken: This is only relevant when paymentMethod is CARD and providerType is TOKEN.

token: the payment token supplied by the card payment processor

paymentCard: This is only relevant when paymentMethod is CARD and providerType is SERVER_TO_SERVER.

name: full name of the card holder

cardNumber: the credit card number

expiryMonth: the month when the card expires

expiryYear: the year when the card expires

cvc: the CVC number usually found on the back side of the card

transactionDetails: If paymentMethod is not CARD (payment handled outside of Bokun), then you can supply transaction details here.

transactionDate: The date when the transaction was performed. Format: yyyy-MM-dd HH:mm:ss

transactionId: The ID of the transaction in the external payment system.

cardBrand: The brand of the card used for payment (e.g. VISA)

last4: The last 4 digits of the card number used for payment.

successUrl: Only relevant when paymentMethod is CARD and providerType is REDIRECT. Tells the external payment page where to send the customer after successful payment.

errorUrl: Only relevant when paymentMethod is CARD and providerType is REDIRECT. Tells the external payment page where to send the customer after unsuccessful payment.

cancelUrl: Only relevant when paymentMethod is CARD and providerType is REDIRECT. Tells the external payment page where to send the customer after a cancelled payment.

acceptDccQuote: Only relevant when paymentMethod is CARD and if you previously received a checkout response containing a DCC quote. Specifies whether to accept that quote.

providerPaymentParameters: Only relevant when paymentMethod is CARD. An optional map of parameters to be sent to the card payment provider.

cardPaymentProviderAnswers: Only relevant when paymentMethod is CARD. Answers to any questions that were asked in checkoutOption.paymentMethods.cardProvider.questions in the checkout options response.

checkoutOptionAnswers: Answers to any questions that were asked in checkoutOption.questions in the checkout options response.

Checkout Response Schema

The checkout response schema has the following structure (see the schema online here:

https://bokun.github.io/api-docs/schemas/CheckoutResponse.html

redirectRequest: Only relevant if you specified paymentMethodCARD and providerType was REDIRECT. Then this holds information about how to redirect the customer to the secure external payment page.

url: The URL to redirect to

method: The HTTP method to use (either post or get)

parameters: a list of name/value pairs to post as parameters in the request to the external page

dccQuote: Only relevant if you specified paymentMethodCARD. If a DCC (Dynamic Currency Conversion) quote is specified here, it means that the booking has not yet been processed, since a DCC offer must be presented to the customer before proceeding. This should be presented, and then the checkout request should be resent, specifying whether the customer accepted the DCC quote in the acceptDccQuote field of the checkout request.

booking: a full description of the booking, if it was processed

bookingHash: a unique hash for the booking, reserved for future use

travelDocuments: invoice and tickets/vouchers for the booking

Tickets and Barcodes

The platform will either generate ticket and barcode

per product booking (one ticket & one barcode, irrespective of the number of passengers), or

per pricing category booking (one ticket & barcode per each passenger in the booking).

This is determined by the following field in the product configuration (you can see how to get the activity configuration details here: Get product details):

ticketPerPerson: if this is TRUE, then ticket & barcode is generated per pricing category booking (passenger booked), else it will be per product booking

To get the barcodes from the CheckoutResponse:

If ticketPerPerson is FALSE (barcode per product booking), then you can get the barcode from the object in CheckoutResponse.booking.activityBookings[].barcode

If ticketPerPerson is TRUE (barcode per pricing category booking), then you can get the barcode from the object in CheckoutResponse.booking.activityBookings[].pricingCategoryBookings[].barcode

The barcode object has the following fields:

barcodeType : will be one of QR_CODE (by far the most common), CODE_128, PDF_417, DATA_MATRIX, AZTEC

value : the actual value in the bar code

To get the tickets from the CheckoutResponse, you can loop through the CheckoutResponse.travelDocuments.activityTickets[] array. Each TicketReference object in the array has the following fields:

bookingId : The ID of the parent booking (i.e. CheckoutResponse.booking.bookingId)

productTitle : The title of the product booked.

productConfirmationCode : The confirmation code for the product booking.

ticket : the download path for the ticket PDF file.

Note: if ticketPerPerson is TRUE, then the PDF file for the product booking will contain multiple pages, with one per pricing category booking (passenger booking).

Booking Confirmation Schema

The booking confirmation schema has the following structure (see the schema online here:

https://bokun.github.io/api-docs/schemas/BookingConfirmation.html

Checkout Options for Shopping Cart

Use case : Get the available checkout options, along with questions and payment methods, for the shopping cart with the UUID supplied.

GET /checkout.json/options/shopping-cart/{cartUUID}

The response will be of the schema described under "Checkout Options Response Schema". You can specify the payment currency as a query string parameter, e.g.:

/checkout.json/options/shopping-cart/{cartUUID}?currency=USD

If you do not specify currency, then the default currency will be used. Please note that the booking channel settings specify which payment currencies are allowed, and if you specify a currency outside of the allowed range, then the default currency will be used.

Checkout Options for Booking Request

Use case : Get the available checkout options, along with questions and payment methods, for the Booking Request in the body.

POST /checkout.json/options/booking-request

The request body should contain Booking Request JSON. The response will be of the schema described under "Checkout Options Response Schema". You can specify the payment currency as a query string parameter, e.g.:

/checkout.json/options/booking-request?currency=USD

Submit checkout (shopping cart or direct booking request)

Use case : Process the checkout to finish the booking process.

POST /checkout.json/submit

The request body should contain Checkout Request JSON as specified in "Checkout Request Schema". The response will be of the schema described under "Checkout Response Schema". Note that you use this service to checkout either:

A shopping cart

The source should be SHOPPING_CART

The shopping cart details should be specified in shoppingCart

A direct booking request

The source should be DIRECT_REQUEST

The booking details should be specified in directBooking

You can specify the payment currency as a query string parameter, e.g.: /checkout.json/submit?currency=USD

Confirm reserved booking (after external payment)

Use case : Confirm a reserved booking which was created by submitting checkout using the RESERVE_FOR_EXTERNAL_PAYMENT payment method.

POST /checkout.json/confirm-reserved/{confirmationCode}

The confirmationCode specified in the request path is the code received on the reserved booking from submitting the checkout previously. The request body should contain Booking Confirmation JSON as specified in "Booking Confirmation Schema". The response will be of the schema described under "Checkout Response Schema".

Abort reserved booking

Use case : After reserving a booking, payment fails (or similar situation) - and you want to abort the reservation rather than confirm it.

POST /booking.json/{bookingConfirmationCode}/abort-reserved