Example payment scenarios

This example demonstrates how Payments enables you to support multiple payment scenarios, using a small and consistent set of endpoints and JSON data structures.

Suppose that your application provides an online travel service:

• Your partner agreement authorises you to use online payments and wallet payments.
• You provide services for both private and corporate travellers.
• You also run a loyalty scheme.

A traveller uses your application, finds a suitable property and product, and decides to book it. At this point you call /orders/preview, and the response contains the following payment object.

...
    "payment": {
        "pay_at_the_property": {
            ...
            "method_required": true,
            "methods": {
                "airplus": false,
                "wallet": false,
                "cards": [1,2]
            }
        },
        "pay_online_later": null,                   
        "pay_online_now": {
            ...
            "method_required": true,
            "methods": {
                "airplus": false,
                "wallet": true,
                "cards": [1,2,3,4,5,7,11,44]
            }
            }
        },
...

This response shows that, for the selected property and product, with your authorised payment features, you can use either of the following options to pay for the booking:

• pay_at_the_property: The traveller must provide one of the specified payment cards now to secure the booking (as method_required is true), then pay at the property.

  Note: The pay_at_the_property.methods.cards field only lists cards that can be used to secure the booking.

  To return the payment methods (cards and/or cash) that the traveller can use to pay at the property, call /accommodations/details. The response will contain information like this:

...
    "payment": {
        "methods": {
            "cards": [1,2,3,5,7,10,11,19,44],
            "cash": true
        },
        "timings": [
            "pay_at_the_property",
            "pay_online_later",
            "pay_online_now"
        ]
    },
...

• pay_online_now: You can pay for the booking now, using either one of the specified payment cards, or your wallet.

The following examples show four different use cases that your application could support in this scenario, with different travellers making different payment choices. Each example also shows the payment structure that you would need to provide in the /orders/create request.

Example 1: Pay at the property

The traveller decides to pay at the property. They provide their credit card to guarantee the booking. You provide the card details to Booking.com, who in turn forward them to the property. The property will charge the card when the traveller stays.

The payment field in your /orders/create request will look like this:

...
    "payment": {
        "card": {
        "cardholder": "xxxx",
        "cvc": "123",
        "expiry_date": "2030-10",
        "number": "1234123412341234"
        },
        "method": "card",
        "timing": "pay_at_the_property"
    }
...

Example 2: Pay online with credit card

The traveller decides to pay online now with their credit card. You provide the card details to Booking.com, who charges the card. Booking.com pays the property.

The payment field in the /orders/create request will look like this:

...
    "payment": {
        "card": {
        "authentication": {
            "3d_secure": {
                "cavv": "xxxx",
                "eci": "xxxx"
            }
        },
        "cardholder": "xxxx",
        "cvc": "123",
        "expiry_date": "2030-10",
        "number": "1234123412341234"
        },
        "include_receipt": true,
        "method": "card",
        "timing": "pay_online_now"
    }
...

Example 3: Pay online with wallet

The traveller is a member of your loyalty scheme and exchanges points to pay you for the booking. The traveller decides to pay online now with their credit card. You have a wallet set up, so use funds from the wallet to pay Booking.com. Booking.com pays the property.

The payment field in the /orders/create request will look like this:

...
    "payment": {
        "include_receipt": true,
        "method": "wallet",
        "timing": "pay_online_now"
    }
...

Example 4: A business traveller

The traveller is a company employee and makes a booking for a business trip. You forward a virtual credit card (VCC), and details of what charges are allowed, to Booking.com. Booking.com sends an authorisation form with this information to the property, so that it can charge the card appropriately when the traveller stays.

The payment field in the /orders/create request will look like this:

...
   "payment": {
      "business_information": {
          "authorisation_form": {
              "chargeable_items": ["breakfast","food_beverage","internet"],
              "billing": {
                  "address_line": "Road-1, house-2",
                  "city": "Amsterdam",
                  "country": "NL",
                  "post_code": "12345"
              },
              "email": "test.name@example.com",
              "vat": "12345"
              "company": "xxxxxxxx"
          }
      },
      "card": {
        "cardholder": "xxxx",
        "cvc": "123",
        "expiry_date": "2030-10",
        "number": "1234123412341234"
      },
      "method": "card",
      "timing": "pay_at_the_property"
    }
   }
...