Creating Custom Checkout Experiences
By leveraging our API's public event, checkout, and payments endpoints, you can incorporate all vivenu features into your own client side checkout process with your UI. Additionally, multi-event checkout and seat reservations are also available via the API.
In this guide, we will walk through the process of creating a custom checkout experience by first getting information on the event and its availabilities, then creating and continuously updating the checkout object, and lastly, by going through the payment process.
By clicking on an endpoint you will be redirected to its more detailed documentation.
The Checkout Process
The checkout process on the client side usually follows these steps:
More information on the checkout process:
Step 1: Choosing the Right Entry Point
It is important to choose the right entry point for your use case. This can be fetching a list of all upcoming events, getting a pre-set event directly, skipping the event display part and going straight to the checkout, or any other way you find appropriate.
A common way to start is to fetch all upcoming events. This can look something like this.
get
/api/events/public/listings
export async function getEvents() {
return await (
await fetch(
API_BASE_URL() +
"/api/events/public/listings?sellerId=" +
SELLER_ID() +
"&startMin=" +
new Date().toISOString(),
)
).json()
}
As an alternative entry point or after an event has been selected we can fetch the event. There are two different public endpoints for doing so. To get general information about an event, use the first one. To get additional ticket availabilities, use the second one.
get
/api/public/event/{id}
get
/api/events/info/{id}
To check whether checkouts are still accepted, poll the endpoint below periodically.
get
/api/events/public/{id}/availabilities
Response
application/json
[{"_id": "string","url": "string","name": "string","image": "string","slogan": "string","sellerId": "string","start": "2030-01-23T23:00:00.123Z","end": "2030-01-23T23:00:00.123Z","locationName": "string","locationStreet": "string","locationCity": "string","locationPostal": "string","locationCountry": "string","styleOptions": {"headerStyle": "default","hideLocationMap": false,"hideLocationAddress": false,"categoryAlignment": 0,"showAvailabilityIndicator": false,"availabilityIndicatorThresholds": [0.3,0.7]},"accountSettings": {"_id": "string","enforceAccounts": true,"enforceAuthentication": "DISABLED"},"meta": {},"eventType": "SINGLE","childEvents": ["string"],"daySchemeId": "string","rootId": "string","seoSettings": {"_id": "string","tags": ["string"],"noIndex": true,"title": "string","description": "string"},"customSettings": {},"ticketSettings": {},"underShopId": "string","startingPrice": "string","showStartDate": true,"showEndDate": true,"showTimeRangeInListing": true,"availabilityIndicator": "green","currency": "EUR","saleStatus": "onSale","timezone": "string","category": "string","subCategory": "string","resell": {"saleActive": true,"offerActive": true}}]
Response
application/json
{"_id": "string","name": "string","start": "2030-01-23T23:00:00.123Z","end": "2030-01-23T23:00:00.123Z","url": "string","slogan": "string","description": "string","locationName": "string","posDiscounts": [{"_id": "string","name": "string","discountType": "fix","value": 10.5}],"categories": [{"_id": "string","name": "string","description": "string","seatingReference": "string","ref": "string","amount": 10.5,"recommendedTicket": "string","maxAmountPerOrder": 10.5,"listWithoutSeats": true}],"groups": [{"_id": "string","name": "string","tickets": ["string"]}],"cartAutomationRules": [{"_id": "string","name": "string","triggerType": "hasBeenAdded","triggerTargetGroup": "string","thenType": "autoAdd","thenTargets": [{"_id": "string","thenTargetGroup": "string","thenTargetMin": 10.5,"thenTargetMax": 10.5}]}],"discountGroups": [{"_id": "string","name": "string","rules": [{"_id": "string","group": "string","type": "ticketGroups","min": 10.5,"max": 10.5}],"discountType": "fix","value": 10.5}],"extraFields": [{"_id": "string","name": "string","description": "string","required": true,"collectInCheckout": true,"deleted": true,"type": "text","options": ["string"],"onlyForCertainTicketTypes": true,"allowedTicketTypes": [],"printable": true,"conditions": [{"_id": "string","baseSlug": "string","value": [],"operator": "equals"}]}],"ticketExtraFields": [{"_id": "string","name": "string","description": "string","required": true,"collectInCheckout": true,"deleted": true,"type": "text","options": ["string"],"onlyForCertainTicketTypes": true,"allowedTicketTypes": [],"printable": true,"conditions": [{"_id": "string","baseSlug": "string","value": [],"operator": "equals"}]}],"image": "string","styleOptions": {"headerStyle": "default","hideLocationMap": false,"hideLocationAddress": false,"categoryAlignment": 0,"showAvailabilityIndicator": false,"availabilityIndicatorThresholds": [0.3,0.7]},"video": {"youtubeID": "string"},"gallery": [{"_id": "string","title": "string","description": "string","copyright": "string","index": 10.5,"image": "string"}],"checkinInformation": {"_id": "string","checkinStarts": "2030-01-23T23:00:00.123Z"},"accentColor": "#006DCC","sellerId": "string","sellStart": "2030-01-23T23:00:00.123Z","ticketShopHeader": "string","hardTicketSettings": {"_id": "string","enabled": true,"fulfillmentType": "self","printingMethod": "preprinted","hardTicketOuterCharge": 10.5,"hardTicketInnerCharge": 10.5,"hardTicketPreviewURL": "string","promotionName": "string","promotionText": "string","requiredDays": 1},"tracking": {"facebookPixel": {"active": true,"pixelId": "string"},"tagging": {"enabled": true,"tags": ["string"]}},"accountSettings": {"_id": "string","enforceAccounts": true,"enforceAuthentication": "DISABLED"},"dataRequestSettings": {"requiresPersonalization": false,"requiresExtraFields": false,"repersonalization": false,"posPersonalization": "noPersonalization"},"seoSettings": {"_id": "string","tags": ["string"],"noIndex": true,"title": "string","description": "string"},"soldOutFallback": {"_id": "string","soldOutFallbackType": "default","soldOutFallbackLink": "string"},"reservationSettings": {"option": "noReservations"},"customTextConfig": {"_id": "string","buyTicketsCTA": "string"},"customSettings": {},"upsellSettings": {"_id": "string","active": true,"productStream": "string","headerImage": "string","crossSells": {"eventIds": ["string"]}},"useTimeSlots": true,"saleStatus": "onSale","underShopId": "string","unlockMode": "none","channelId": "string","seating": true,"seatingEventId": "string","seatingChildEventIds": ["string"],"seatingConfigurations": {},"contingents": ["string"],"theme": "string","taxRate": 10.5,"max": 10.5,"min": 10.5,"v": 10.5,"cXv": 10.5,"cXf": 10.5,"ccXf": 10.5,"startingPrice": "string","showTimeRangeInTicket": true,"showTimeRangeInListing": true,"showCountdown": true,"showOtherEvents": true,"accountsModule": true,"stripe_api_key": "string","currency": "EUR","seller": {"name": "string","description": "string","image": "string","documentImage": "string","url": "string","supportUrl": "string","customLogo": "string","defaultLanguage": "string"},"timezone": "string","location": {"locationName": "string","locationStreet": "string","locationCity": "string","locationPostal": "string","locationCountry": "string","geoCode": {"_id": "string","lat": 10.5,"lng": 10.5}},"slots": [{"_id": "string","start": "string","amount": 1,"offers": {}}],"timeSlots": [{"_id": "string","startTime": {"hour": 1,"minute": 1},"v": 10.5,"startingPrice": 10.5,"categories": [{"categoryRef": "string","v": 10.5}],"ticketTypes": [{"ticketTypeId": "string","v": 10.5}],"availabilityIndicator": "green"}],"ticketShopHeaderText": "string","tickets": [{"id": "string","v": 10.5,"name": "string","price": 10.5,"color": "string","description": "string","active": true,"categoryRef": "string","requiresPersonalization": true,"sortingKey": 10.5,"enableHardTicketOption": true,"forceHardTicketOption": true,"maxAmountPerOrder": 10.5,"minAmountPerOrder": 10.5,"minAmountPerOrderRule": 10.5,"taxRate": 10.5,"styleOptions": {},"ignoreForMaxAmounts": true,"conditionalAvailability": true,"conditionalAvailabilityMode": "blockAddToCart","rules": [{"_id": "string","ticketGroup": "string","min": 10.5,"max": 10.5}],"outerChargeFix": 10.5,"innnerChargeFix": 10.5,"dynamicFees": [{}],"salesStart": {"target": "string","unit": "hours","offset": 1},"salesEnd": {"target": "string","unit": "hours","offset": 1},"subscriptionSettings": {},"priceTableTypeId": "string","meta": {},"resellSettings": {"enabled": "ENABLED"}}],"resell": {"saleActive": true,"offerActive": true}}
Response
application/json
{"checkout": {"allowed": true}}
Step 2: Managing the Checkout Object
After our customer has selected the tickets they want to add to their cart from the first event, it's time to create the checkout. After the initial creation of the checkout object, we can continuously add, remove, and update all items in the checkout even from multiple events.
Checkout Items vs. Cart Items
The checkout object consists of checkout items which each represent all items from a single event. The attribute name is items.
So if the items property of a checkout object contains two elements, then the customer has items from two different events in their cart.
Items from a single event are called cart items. The attribute names are tickets, products, and additionalItems. Each checkout item can contain multiple cart items.
When the checkout completes, each checkout item is converted into a transaction.
Creating and Updating the Checkout Object
To create and update the checkout object we use these two endpoints below. Updating a checkout item works like a put request, we need to attach every cart item even if we are not updating it. Because to remove an item, we need to update the checkout item and attach every cart item except the one we want to remove.
post
/api/checkout
post
/api/checkout/{id}/items
Finalizing the Checkout
Before the payment can occur we need to post the customer's details. In order to know if we can omit collecting address information or if we have to collect extra fields, we get the details form through the first endpoint below. Then we can collect and post the details.
get
/api/checkout/{id}/detailsform
post
/api/checkout/{id}/details
post
/api/checkout
{"type": "transaction","eventId": "string","coupons": ["string"],"vouchers": ["string"],"shopId": "string","items": [{"_id": "string","type": "ticket","amount": 1,"ticketTypeId": "string","seatingInfo": {"_id": "string","_type": 6,"categoryId": "string","statusId": "string","name": "string","seatType": "handicapped","sectionName": "string","groupName": "string","rowName": "string","seatName": "string","gate": "string"},"slotInfo": {"slotId": "string","slotStartTime": "string"},"asHardTicket": true,"listingId": "string","triggeredBy": "string","triggeredAutomations": true,"meta": {},"bundleInfo": {"bundleId": "string","componentId": "string","optionId": "string"}}],"seatingReservationToken": "string","channelId": "string","salesChannelId": "string","preferredLanguage": "de","meta": {}}
Response
application/json
{"_id": "string","secret": "string","status": "NEW","type": "transaction","company": "string","firstname": "string","lastname": "string","name": "string","phone": "string","customerId": "string","address": {"street": "string","line2": "string","postal": "string","city": "string","country": "string","state": "string"},"deliveryAddress": {"street": "string","line2": "string","postal": "string","city": "string","country": "string","state": "string","name": "string"},"sellerId": "string","items": [{"_id": "string","eventId": "string","shopId": "string","channelId": "string","redeemedVouchers": {"totalRedeemedAmount": 10.5,"vouchers": [{"_id": "string","code": "string","redeemedAmount": 10.5}]},"appliedCoupons": [{"_id": "string","code": "string"}],"appliedDiscountInfo": {"items": [{"_id": "string","itemId": "string","amount": 10.5,"regularPrice": 10.5,"price": 10.5,"varDiscounts": [{"_id": "string","discountId": "string","category": "coupon","name": "string","type": "fix","value": 10.5,"allowedItems": ["string"]}],"fixDiscounts": [{"_id": "string","discountId": "string","category": "coupon","name": "string","type": "fix","value": 10.5,"allowedItems": ["string"]}]}],"discounts": [{"_id": "string","discountId": "string","category": "coupon","name": "string","type": "fix","value": 10.5,"allowedItems": ["string"],"maxItemsInCart": 10.5,"maxAbsoluteValue": 10.5,"absoluteDiscountValue": 10.5}]},"regularPrice": 10.5,"realPrice": 10.5,"innerFeeComponents": {"_id": "string","fix": [{"_id": "string","amount": 10.5,"value": 10.5,"total": 10.5,"type": "onTicket","name": "string","publicName": "string","exposed": true,"scheme": {"schemeId": "string","feeId": "string"}}],"var": [{"_id": "string","amount": 10.5,"value": 10.5,"total": 10.5,"type": "onTicket","name": "string","publicName": "string","exposed": true,"scheme": {"schemeId": "string","feeId": "string"}}]},"innerCharge": 10.5,"outerFeeComponents": {"_id": "string","fix": [{"_id": "string","amount": 10.5,"value": 10.5,"total": 10.5,"type": "onTicket","name": "string","publicName": "string","exposed": true,"scheme": {"schemeId": "string","feeId": "string"}}],"var": [{"_id": "string","amount": 10.5,"value": 10.5,"total": 10.5,"type": "onTicket","name": "string","publicName": "string","exposed": true,"scheme": {"schemeId": "string","feeId": "string"}}]},"outerCharge": 10.5,"tickets": [{"type": "ticket","_id": "string","name": "string","amount": 1,"netPrice": 10.5,"price": 10.5,"taxRate": 10.5,"triggeredBy": "string","bundleInfo": {"bundleId": "string","componentId": "string","optionId": "string"},"ticketTypeId": "string","categoryRef": "string","seatingInfo": {"_id": "string","_type": 6,"categoryId": "string","statusId": "string","name": "string","seatType": "handicapped","sectionName": "string","groupName": "string","rowName": "string","seatName": "string","gate": "string"},"slotInfo": {"slotId": "string","slotStartTime": "string"},"asHardTicket": true,"listingId": "string","triggeredAutomations": true,"meta": {},"addOns": [{"productId": "string","productVariantId": "string","name": "string"}],"capabilities": [{"type": "self_service_return","settings": {"returnRelatedItems": true,"phases": [{"condition": {"target": "string","unit": "hours","offset": 1},"refundPercentage": 10.5}]}}],"taxInfo": {"serviceTypeId": "string","exceptionId": "string","proceedsAccountId": "string","proceedsAccountCode": "string","taxItems": [{"name": "string","taxTypeId": "string","rate": 10.5,"perUnit": 10.5,"total": 10.5,"netTotal": 10.5,"netPerUnit": 10.5,"taxPayableAccountId": "string","taxPayableAccountCode": "string"}]}}],"products": [{"type": "product","_id": "string","name": "string","amount": 1,"netPrice": 10.5,"price": 10.5,"taxRate": 10.5,"triggeredBy": "string","bundleInfo": {"bundleId": "string","componentId": "string","optionId": "string"},"productVariantId": "string","isFulfillable": true,"taxInfo": {"serviceTypeId": "string","exceptionId": "string","proceedsAccountId": "string","proceedsAccountCode": "string","taxItems": [{"name": "string","taxTypeId": "string","rate": 10.5,"perUnit": 10.5,"total": 10.5,"netTotal": 10.5,"netPerUnit": 10.5,"taxPayableAccountId": "string","taxPayableAccountCode": "string"}]}}],"additionalItems": [],"seatingReservationToken": "string","subscriptionId": "string"}],"realPrice": 10.5,"currency": "EUR","redeemedVouchers": {"totalRedeemedAmount": 10.5,"vouchers": [{"_id": "string","code": "string","redeemedAmount": 10.5}]},"preferredLanguage": "de","origin": "yourticket","channel": "online","salesChannelId": "string","posId": "string","userId": "string","extraFields": {},"expiresAt": "2030-01-23T23:00:00.123Z","createdAt": "2030-01-23T23:00:00.123Z","updatedAt": "2030-01-23T23:00:00.123Z"}
post
/api/checkout/{id}/items
{"secret": "string","eventId": "string","coupons": ["string"],"shopId": "string","items": [{"_id": "string","type": "ticket","amount": 1,"ticketTypeId": "string","seatingInfo": {"_id": "string","_type": 6,"categoryId": "string","statusId": "string","name": "string","seatType": "handicapped","sectionName": "string","groupName": "string","rowName": "string","seatName": "string","gate": "string"},"slotInfo": {"slotId": "string","slotStartTime": "string"},"asHardTicket": true,"listingId": "string","triggeredBy": "string","triggeredAutomations": true,"meta": {},"bundleInfo": {"bundleId": "string","componentId": "string","optionId": "string"}}],"seatingReservationToken": "string","channelId": "string"}
Response
application/json
{"_id": "string","secret": "string","status": "NEW","type": "transaction","company": "string","firstname": "string","lastname": "string","name": "string","phone": "string","customerId": "string","address": {"street": "string","line2": "string","postal": "string","city": "string","country": "string","state": "string"},"deliveryAddress": {"street": "string","line2": "string","postal": "string","city": "string","country": "string","state": "string","name": "string"},"sellerId": "string","items": [{"_id": "string","eventId": "string","shopId": "string","channelId": "string","redeemedVouchers": {"totalRedeemedAmount": 10.5,"vouchers": [{"_id": "string","code": "string","redeemedAmount": 10.5}]},"appliedCoupons": [{"_id": "string","code": "string"}],"appliedDiscountInfo": {"items": [{"_id": "string","itemId": "string","amount": 10.5,"regularPrice": 10.5,"price": 10.5,"varDiscounts": [{"_id": "string","discountId": "string","category": "coupon","name": "string","type": "fix","value": 10.5,"allowedItems": ["string"]}],"fixDiscounts": [{"_id": "string","discountId": "string","category": "coupon","name": "string","type": "fix","value": 10.5,"allowedItems": ["string"]}]}],"discounts": [{"_id": "string","discountId": "string","category": "coupon","name": "string","type": "fix","value": 10.5,"allowedItems": ["string"],"maxItemsInCart": 10.5,"maxAbsoluteValue": 10.5,"absoluteDiscountValue": 10.5}]},"regularPrice": 10.5,"realPrice": 10.5,"innerFeeComponents": {"_id": "string","fix": [{"_id": "string","amount": 10.5,"value": 10.5,"total": 10.5,"type": "onTicket","name": "string","publicName": "string","exposed": true,"scheme": {"schemeId": "string","feeId": "string"}}],"var": [{"_id": "string","amount": 10.5,"value": 10.5,"total": 10.5,"type": "onTicket","name": "string","publicName": "string","exposed": true,"scheme": {"schemeId": "string","feeId": "string"}}]},"innerCharge": 10.5,"outerFeeComponents": {"_id": "string","fix": [{"_id": "string","amount": 10.5,"value": 10.5,"total": 10.5,"type": "onTicket","name": "string","publicName": "string","exposed": true,"scheme": {"schemeId": "string","feeId": "string"}}],"var": [{"_id": "string","amount": 10.5,"value": 10.5,"total": 10.5,"type": "onTicket","name": "string","publicName": "string","exposed": true,"scheme": {"schemeId": "string","feeId": "string"}}]},"outerCharge": 10.5,"tickets": [{"type": "ticket","_id": "string","name": "string","amount": 1,"netPrice": 10.5,"price": 10.5,"taxRate": 10.5,"triggeredBy": "string","bundleInfo": {"bundleId": "string","componentId": "string","optionId": "string"},"ticketTypeId": "string","categoryRef": "string","seatingInfo": {"_id": "string","_type": 6,"categoryId": "string","statusId": "string","name": "string","seatType": "handicapped","sectionName": "string","groupName": "string","rowName": "string","seatName": "string","gate": "string"},"slotInfo": {"slotId": "string","slotStartTime": "string"},"asHardTicket": true,"listingId": "string","triggeredAutomations": true,"meta": {},"addOns": [{"productId": "string","productVariantId": "string","name": "string"}],"capabilities": [{"type": "self_service_return","settings": {"returnRelatedItems": true,"phases": [{"condition": {"target": "string","unit": "hours","offset": 1},"refundPercentage": 10.5}]}}],"taxInfo": {"serviceTypeId": "string","exceptionId": "string","proceedsAccountId": "string","proceedsAccountCode": "string","taxItems": [{"name": "string","taxTypeId": "string","rate": 10.5,"perUnit": 10.5,"total": 10.5,"netTotal": 10.5,"netPerUnit": 10.5,"taxPayableAccountId": "string","taxPayableAccountCode": "string"}]}}],"products": [{"type": "product","_id": "string","name": "string","amount": 1,"netPrice": 10.5,"price": 10.5,"taxRate": 10.5,"triggeredBy": "string","bundleInfo": {"bundleId": "string","componentId": "string","optionId": "string"},"productVariantId": "string","isFulfillable": true,"taxInfo": {"serviceTypeId": "string","exceptionId": "string","proceedsAccountId": "string","proceedsAccountCode": "string","taxItems": [{"name": "string","taxTypeId": "string","rate": 10.5,"perUnit": 10.5,"total": 10.5,"netTotal": 10.5,"netPerUnit": 10.5,"taxPayableAccountId": "string","taxPayableAccountCode": "string"}]}}],"additionalItems": [],"seatingReservationToken": "string","subscriptionId": "string"}],"realPrice": 10.5,"currency": "EUR","redeemedVouchers": {"totalRedeemedAmount": 10.5,"vouchers": [{"_id": "string","code": "string","redeemedAmount": 10.5}]},"preferredLanguage": "de","origin": "yourticket","channel": "online","salesChannelId": "string","posId": "string","userId": "string","extraFields": {},"expiresAt": "2030-01-23T23:00:00.123Z","createdAt": "2030-01-23T23:00:00.123Z","updatedAt": "2030-01-23T23:00:00.123Z"}
Response
application/json
{"skipAddressInfo": true,"extraFields": [{"name": "string","description": "string","required": true,"deleted": true,"onlyForCertainTicketsTypes": true,"allowedTicketTypes": ["string"],"printable": true,"applyToCustomer": true}],"enforceCompany": true,"ticketExtraFields": {}}
post
/api/checkout/{id}/details
{"secret": "string","company": "string","prename": "string","lastname": "string","street": "string","postal": "string","city": "string","country": "string","state": "string","deliveryAddress": {"street": "string","line2": "string","postal": "string","city": "string","country": "string","state": "string","name": "string"},"phone": "string","password": "string","passwordRepeat": "string","createAccount": true,"extraFields": {},"fulfillmentTypes": [{"type": "fulfillmentType","_id": "string","name": "string","amount": 1,"netPrice": 10.5,"price": 10.5,"taxRate": 10.5,"triggeredBy": "string","bundleInfo": {"bundleId": "string","componentId": "string","optionId": "string"},"data": {"fulfillmentTypeId": "string","cartItemIds": ["string"],"discountable": true}}]}
Response
application/json
{"_id": "string","secret": "string","status": "NEW","type": "transaction","company": "string","firstname": "string","lastname": "string","name": "string","phone": "string","customerId": "string","address": {"street": "string","line2": "string","postal": "string","city": "string","country": "string","state": "string"},"deliveryAddress": {"street": "string","line2": "string","postal": "string","city": "string","country": "string","state": "string","name": "string"},"sellerId": "string","items": [{"_id": "string","eventId": "string","shopId": "string","channelId": "string","redeemedVouchers": {"totalRedeemedAmount": 10.5,"vouchers": [{"_id": "string","code": "string","redeemedAmount": 10.5}]},"appliedCoupons": [{"_id": "string","code": "string"}],"appliedDiscountInfo": {"items": [{"_id": "string","itemId": "string","amount": 10.5,"regularPrice": 10.5,"price": 10.5,"varDiscounts": [{"_id": "string","discountId": "string","category": "coupon","name": "string","type": "fix","value": 10.5,"allowedItems": ["string"]}],"fixDiscounts": [{"_id": "string","discountId": "string","category": "coupon","name": "string","type": "fix","value": 10.5,"allowedItems": ["string"]}]}],"discounts": [{"_id": "string","discountId": "string","category": "coupon","name": "string","type": "fix","value": 10.5,"allowedItems": ["string"],"maxItemsInCart": 10.5,"maxAbsoluteValue": 10.5,"absoluteDiscountValue": 10.5}]},"regularPrice": 10.5,"realPrice": 10.5,"innerFeeComponents": {"_id": "string","fix": [{"_id": "string","amount": 10.5,"value": 10.5,"total": 10.5,"type": "onTicket","name": "string","publicName": "string","exposed": true,"scheme": {"schemeId": "string","feeId": "string"}}],"var": [{"_id": "string","amount": 10.5,"value": 10.5,"total": 10.5,"type": "onTicket","name": "string","publicName": "string","exposed": true,"scheme": {"schemeId": "string","feeId": "string"}}]},"innerCharge": 10.5,"outerFeeComponents": {"_id": "string","fix": [{"_id": "string","amount": 10.5,"value": 10.5,"total": 10.5,"type": "onTicket","name": "string","publicName": "string","exposed": true,"scheme": {"schemeId": "string","feeId": "string"}}],"var": [{"_id": "string","amount": 10.5,"value": 10.5,"total": 10.5,"type": "onTicket","name": "string","publicName": "string","exposed": true,"scheme": {"schemeId": "string","feeId": "string"}}]},"outerCharge": 10.5,"tickets": [{"type": "ticket","_id": "string","name": "string","amount": 1,"netPrice": 10.5,"price": 10.5,"taxRate": 10.5,"triggeredBy": "string","bundleInfo": {"bundleId": "string","componentId": "string","optionId": "string"},"ticketTypeId": "string","categoryRef": "string","seatingInfo": {"_id": "string","_type": 6,"categoryId": "string","statusId": "string","name": "string","seatType": "handicapped","sectionName": "string","groupName": "string","rowName": "string","seatName": "string","gate": "string"},"slotInfo": {"slotId": "string","slotStartTime": "string"},"asHardTicket": true,"listingId": "string","triggeredAutomations": true,"meta": {},"addOns": [{"productId": "string","productVariantId": "string","name": "string"}],"capabilities": [{"type": "self_service_return","settings": {"returnRelatedItems": true,"phases": [{"condition": {"target": "string","unit": "hours","offset": 1},"refundPercentage": 10.5}]}}],"taxInfo": {"serviceTypeId": "string","exceptionId": "string","proceedsAccountId": "string","proceedsAccountCode": "string","taxItems": [{"name": "string","taxTypeId": "string","rate": 10.5,"perUnit": 10.5,"total": 10.5,"netTotal": 10.5,"netPerUnit": 10.5,"taxPayableAccountId": "string","taxPayableAccountCode": "string"}]}}],"products": [{"type": "product","_id": "string","name": "string","amount": 1,"netPrice": 10.5,"price": 10.5,"taxRate": 10.5,"triggeredBy": "string","bundleInfo": {"bundleId": "string","componentId": "string","optionId": "string"},"productVariantId": "string","isFulfillable": true,"taxInfo": {"serviceTypeId": "string","exceptionId": "string","proceedsAccountId": "string","proceedsAccountCode": "string","taxItems": [{"name": "string","taxTypeId": "string","rate": 10.5,"perUnit": 10.5,"total": 10.5,"netTotal": 10.5,"netPerUnit": 10.5,"taxPayableAccountId": "string","taxPayableAccountCode": "string"}]}}],"additionalItems": [],"seatingReservationToken": "string","subscriptionId": "string"}],"realPrice": 10.5,"currency": "EUR","redeemedVouchers": {"totalRedeemedAmount": 10.5,"vouchers": [{"_id": "string","code": "string","redeemedAmount": 10.5}]},"preferredLanguage": "de","origin": "yourticket","channel": "online","salesChannelId": "string","posId": "string","userId": "string","extraFields": {},"expiresAt": "2030-01-23T23:00:00.123Z","createdAt": "2030-01-23T23:00:00.123Z","updatedAt": "2030-01-23T23:00:00.123Z"}
Step 3: Completing the Payment
To now complete the payment we first need to get all payment methods and available payment gateways.
Then we create the payment request and get the processor information for every paymentGatewayId we want to serve.
Checkouts that have a realPrice of 0 will be completed directly after the payment request has been created.
get
/api/public/sellers/{id}/payment-methods
post
/api/payments/requests
post
/api/payments/requests/{id}/processor
Now you can use your payment gateway integration to complete the payment. After the payment has been confirmed through your server, the client can verify it and show an order summary to the customer.
post
/api/payments/requests/{id}/confirm
post
/api/payments/requests/{id}/verify
If you want to update the payment status after the payment request has been completed, you can use the endpoint below. This is useful when the payment status initially was set to PENDING while confirming the payment request.
post
/api/payments/requests/{id}/payment-status
Response
application/json
[{"paypal": true,"klarna": true,"ideal": true,"sepa": true,"creditcard": true,"mobilepay": true,"gateways": [{"_id": "string","name": "string","type": "stripe","data": {}}]}]
post
/api/payments/requests
{"checkoutId": "string","transactionId": "string","secret": "string"}
Response
application/json
{"_id": "string","secret": "string","amount": 10.5,"currency": "EUR","checkoutId": "string","subscriptionId": "string","paymentPlanId": "string","paymentGatewayId": "string","reference": "string","processors": [{"payentGatewayType": "stripe","paymentGatewayId": "string","reference": "string","redirectUrl": "string","data": [],"createdAt": "2030-01-23T23:00:00.123Z"}],"status": "NEW","history": [{"type": "payment_request.created","date": "2030-01-23T23:00:00.123Z","data": []}],"applications": [{"amount": 10.5,"method": "deposit"}],"customer": {"customerId": "string","country": "string"},"sellerId": "string","expiresAt": "2030-01-23T23:00:00.123Z","createdAt": "2030-01-23T23:00:00.123Z","updatedAt": "2030-01-23T23:00:00.123Z"}
post
/api/payments/requests/{id}/processor
{"paymentGatewayId": "string","returnUrl": "string"}
Response
application/json
{"payentGatewayType": "stripe","paymentGatewayId": "string","reference": "string","redirectUrl": "string","data": [],"createdAt": "2030-01-23T23:00:00.123Z"}
post
/api/payments/requests/{id}/confirm
{"gatewaySecret": "string","reference": "string","paymentStatus": "SUCCEEDED","paymentMethod": "visa","paymentMethodVariant": "applepay"}
Response
application/json
{"_id": "string","secret": "string","amount": 10.5,"currency": "EUR","checkoutId": "string","subscriptionId": "string","paymentPlanId": "string","paymentGatewayId": "string","reference": "string","processors": [{"payentGatewayType": "stripe","paymentGatewayId": "string","reference": "string","redirectUrl": "string","data": [],"createdAt": "2030-01-23T23:00:00.123Z"}],"status": "NEW","history": [{"type": "payment_request.created","date": "2030-01-23T23:00:00.123Z","data": []}],"applications": [{"amount": 10.5,"method": "deposit"}],"customer": {"customerId": "string","country": "string"},"sellerId": "string","expiresAt": "2030-01-23T23:00:00.123Z","createdAt": "2030-01-23T23:00:00.123Z","updatedAt": "2030-01-23T23:00:00.123Z"}
post
/api/payments/requests/{id}/verify
{"paymentGatewayId": "string","data": []}
Response
application/json
{"_id": "string","secret": "string","amount": 10.5,"currency": "EUR","checkoutId": "string","subscriptionId": "string","paymentPlanId": "string","paymentGatewayId": "string","reference": "string","processors": [{"payentGatewayType": "stripe","paymentGatewayId": "string","reference": "string","redirectUrl": "string","data": [],"createdAt": "2030-01-23T23:00:00.123Z"}],"status": "NEW","history": [{"type": "payment_request.created","date": "2030-01-23T23:00:00.123Z","data": []}],"applications": [{"amount": 10.5,"method": "deposit"}],"customer": {"customerId": "string","country": "string"},"sellerId": "string","expiresAt": "2030-01-23T23:00:00.123Z","createdAt": "2030-01-23T23:00:00.123Z","updatedAt": "2030-01-23T23:00:00.123Z"}
Working with Seating
If the event you want to service requires our seat map, we recommend you use vivenu's Seating.JS.
Be sure to pass your event's seatingEventId as the required eventId and to pass your event's categories and ticketTypes in the options attribute on .initSeatSelector().
You also need to populate the onObjectSelected and onObjectDeselected callbacks with the below endpoints to freeze and unfreeze the seats your customers selected.
After a selection was made you can initialize or update a checkout object with your seatingReservationToken and the corresponding ticket.
post
/api/public/event/{id}/reserve
post
/api/public/event/{id}/free
Adding Coupons vs. Vouchers
It is your decision if, where, and how prominently to feature the coupon entry area. Vouchers should always be accessible, due to them representing a real cash value that may have already been paid for. With the below endpoint, you can get information on both coupons and vouchers. It is recommended to first get information on the coupon/voucher before trying to update the checkout item.
get
/api/coupon/{code}/info
Response
application/json
{"message": "notYetValid","coupon": {"code": "string","couponId": "string","name": "string","canBeCombined": true,"discountType": "fix","discountValue": 10.5,"discountMaxValue": 10.5,"allowAllTickets": true,"allowedTickets": ["string"],"allowAllEvents": true,"limitMaxTicketsInCart": true,"maxTicketsInCart": 10.5,"maxTickets": 10.5,"revealAllowedTickets": true},"voucher": {"_id": "string","code": "string","balance": 10.5},"type": "voucher"}