{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-demand/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Displaying payments","siteUrl":"https://developers.booking.com","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"displaying-payments","__idx":0},"children":["Displaying payments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use these guidelines to correctly display payment information in your application using data from the Demand API."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payment information is returned across multiple endpoints, including:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["/search and /availability → payment timing overview."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["/orders/preview → full payment schedule with detailed breakdown (dates and amounts)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this data to clearly communicate:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["✓ What the traveller pays now.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","✓ What the traveller pays later.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","✓ What is paid at the property or pick-up.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","✓ Any deposits, guarantees, or extra charges."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"why-it-matters","__idx":2},"children":["Why it matters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Accurate presentation of payment information:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Improves booking conversion."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reduces customer support queries."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Builds traveller trust."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Prevents unexpected charges at fulfilment."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example"]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A car rental shows €129.99 online, but also requires a €300 deposit at pick-up."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the deposit is not clearly displayed:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Travellers may abandon checkout."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Support requests increase."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["on-site disputes may occur."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The same applies to accommodation bookings with property-collected charges."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-mapping-rules","__idx":3},"children":["Payment mapping rules"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"map-payment-timing-to-ui-labels","__idx":4},"children":["Map payment timing to UI labels"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timing"]}," to determine how payment is presented in the UI."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Timing"},"children":["Timing"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Recommended UI label"},"children":["Recommended UI label"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pay_online_now"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pay now"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pay_online_later"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pay later"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pay_at_the_property"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pay at property"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pay_at_pickup"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pay at pick-up"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pay_partial_online"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pay part now"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Avoid exposing raw API values directly."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-breakdown-rules-orderspreview","__idx":5},"children":["Payment breakdown rules (orders/preview)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When using /orders/preview, always display all payment events from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dates"]}," array."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each event contains:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["at"]}," - When the payment occurs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["price"]}," (accommodation) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," (car) - The amount to be charged."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Group payments into:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Upfront payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pre-arrival payment (if any)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["On-site payment (check-in or pick-up)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not assume a single payment event."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"separate-payment-types-clearly","__idx":6},"children":["Separate payment types clearly"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always distinguish between:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Charges paid online."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Charges paid at property or pick-up."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deposits and guarantees."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not merge these into a single total without explanation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"display-vs-pay-model","__idx":7},"children":["Display vs pay model"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each monetary value may include:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Price"},"children":["Price"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Rules"},"children":["Rules"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pay"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Actual amount charged."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use pay for all backend charging logic."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["display"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Amount shown in the UI in Booker's currency."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["display"]}," for UI presentation only."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["They may differ due to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Currency conversion."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Rounding rules."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Supplier-specific pricing formats."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"clearly-communicate-extra-charges","__idx":8},"children":["Clearly communicate extra charges"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some charges are not included in upfront payment totals since they are not paid online."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These may include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tourist taxes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Security deposits"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Damage excess"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Service or local fees."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Display rules:"]}," ","✓ Always show them separately from base price.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","✓ Clearly indicate when and where they are paid.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","✓ Do not merge them into upfront totals unless they are charged online."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"maintain-consistency-across-the-booking-flow","__idx":9},"children":["Maintain consistency across the booking flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payment information must remain consistent across:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Search results."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Product page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Checkout / order preview."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Differences between endpoints (e.g. /availability vs /orders/preview) must be handled carefully to avoid confusion."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"display-examples","__idx":10},"children":["Display examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-split-payment-car-rental","__idx":11},"children":["Example: Split payment (car rental)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API data:"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["€129.99 → pay_online_now"," ","€300 → pay_at_pickup (deposit)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Recommended UI:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pay now: €129.99"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pay at pick-up: €300 deposit (not charged now)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-pay-later-accommodation","__idx":12},"children":["Example: Pay later (accommodation)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API data:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Booking: €0"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Before cancellation deadline: €200"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check-in: €5 (taxes)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Recommended UI:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pay later: €200"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pay at property: €5"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-pay-at-property","__idx":13},"children":["Example: Pay at property"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API data:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Booking: €0"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check-in: €205"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Recommended UI:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pay at property: €205"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-missing-or-partial-data","__idx":14},"children":["Handling missing or partial data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If payment schedule data is incomplete:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not infer or estimate missing payments."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Avoid displaying misleading totals."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fall back to timing-only messaging (e.g. “Pay at property”)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-mistakes-to-avoid","__idx":15},"children":["Common mistakes to avoid"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Hiding deposits or extra charges."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Showing only the upfront amount."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Assuming one payment per booking."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Mixing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["display"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pay"]}," inconsistently."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Showing incorrect timing labels."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Exposing unsupported payment options."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"implementation-checklist","__idx":16},"children":["Implementation checklist"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before going live, ensure:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["All ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dates"]}," entries are displayed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["All payment timings are mapped to UI labels."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deposits and extra charges are clearly separated."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Totals match the sum of displayed payment events."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Payment information is consistent across all pages."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Curious to know more?"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For additional information:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/demand/docs/payments/payments-schedules"},"children":["Payment schedules"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/demand/docs/payments/payments-timings"},"children":["Payment timings"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/demand/docs/payments/payments-methods"},"children":["Payment methods"]}]}]}]}]},"headings":[{"value":"Displaying payments","id":"displaying-payments","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Why it matters","id":"why-it-matters","depth":3},{"value":"Payment mapping rules","id":"payment-mapping-rules","depth":2},{"value":"Map payment timing to UI labels","id":"map-payment-timing-to-ui-labels","depth":3},{"value":"Payment breakdown rules (orders/preview)","id":"payment-breakdown-rules-orderspreview","depth":2},{"value":"Separate payment types clearly","id":"separate-payment-types-clearly","depth":3},{"value":"Display vs pay model","id":"display-vs-pay-model","depth":3},{"value":"Clearly communicate extra charges","id":"clearly-communicate-extra-charges","depth":3},{"value":"Maintain consistency across the booking flow","id":"maintain-consistency-across-the-booking-flow","depth":3},{"value":"Display examples","id":"display-examples","depth":2},{"value":"Example: Split payment (car rental)","id":"example-split-payment-car-rental","depth":3},{"value":"Example: Pay later (accommodation)","id":"example-pay-later-accommodation","depth":3},{"value":"Example: Pay at property","id":"example-pay-at-property","depth":3},{"value":"Handling missing or partial data","id":"handling-missing-or-partial-data","depth":2},{"value":"Common mistakes to avoid","id":"common-mistakes-to-avoid","depth":2},{"value":"Implementation checklist","id":"implementation-checklist","depth":2}],"frontmatter":{"seo":{"title":"Displaying payments"}},"lastModified":"2026-04-24T13:21:15.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/demand/docs/payments/payments-display","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}