Configuring Payments

The Reserve with Google platform supports a variety of configurations for taking payments. The Enabling Payments Guide covers the aspects of the integration that are common to all payments integration, including:

  1. Configuring feeds to include tokenization_parameter information
  2. Updating the booking server to accept payment_method_token objects
  3. An overview of the information exchanged between a user, Reserve with Google, the partner / merchant, and the payment processor.

In this guide we will cover in more detail how to configure your feeds to specify which of the different types of payment configurations is applicable to your merchants and services.

  1. No Payments / Pay on Arrival
  2. Full Prepayment
  3. No Show Fee / Cancellation Fee
  4. Deposit

All of the use cases for payments are extensions of the no payments / pay-on-arrival use case (which requires no payment configuration) so this tutorial will begin by describing that configuration and treat other configurations as extensions.

Each section will also cover the fields to track in the booking server in order to accept the particular payment configuration.

No Payments / Pay on Arrival

For services which do not require any payment at the time of booking, no payments configuration is required at the merchant or service level. However, prices are still required for non-dining services.

This is the baseline configuration for a service, which contains a name, description, and price. This would be a single Service message within a ServiceFeed:

JSON

{
    "merchant_id": "merchant-1",
    "service_id": "service-1-a",
    "name": "Men's haircut",
    "description": "One of our stylists will cut your hair",
    "price": {
        "price_micros": 15000000,
        "currency_code": "USD"
    }
}

No additional configuration beyond the standard implementation is required in the booking server to support pay on arrival.

Prepayment

This configuration is used to specify that the amount for the service must be paid in full at the time of booking.

Prepayment is specified on the service level through the prepayment_type field. To require payments for a service this should be set to "REQUIRED" as in the example below. Note that the price is specified in the same way as the pay-on-arrival example. Here, because we are setting the prepayment type to required, a credit card will be collected and this price can be charged at the time of checkout.

JSON

{
    "merchant_id": "merchant-1",
    "service_id": "service-2-b",
    "name": "Spa Treatment",
    "description": "A full spa treatment",
    "price": {
        "price_micros": "200000000",
        "currency_code": "USD"
    }
    "prepayment_type": "REQUIRED"
}

Booking Server

When accepting prepayments, a payment token is passed to your booking server in the call to CreateBooking or CreateOrder through the field payment_processing_parameters.unparsed_payment_method_token. You are required to charge exactly the amount specified through the price field in the feeds and you are required to use the currency specified in the feeds. These charges should follow the flow described in the Enabling Payments Guide.

When returning a CreateBookingResponse or CreateOrderResponse the booking.payment_information field must be set to properly reflect that prepayment has been provided and processed.

The PaymentInformation specification contains full documentation for all payment information options. A minimal example for processing prepayment is provided below. It is important that the price returned in the price field exactly match that which is specified in the request. Additionally if a tax rate is specified in the feeds/request, it must also be included exactly.

Also note that you must provide a transaction id. This transaction id must, at a minimum, be unique among transactions with that merchant. A good candidate for a transaction id is the transaction id provided to you by the payment processor.

JSON

{
    "prepayment_status": "PREPAYMENT_PROVIDED",
    "payment_processed_by": "PROCESSED_BY_PARTNER",
    "payment_transaction_id": "[this-transaction-id]",
    "price": {
        "price_micros": "200000000",
        "currency_code": "USD"
    }
}

No-show Fee

No-show fees can be charged to a user if they do not attend their reservation, or if they cancel after the cancellation window. If no cancellation window is specified, it will default to the start time of the slot.

To specify a no show fee, in the service feed, you should include the no_show_fee field as shown in the example below:

JSON

{
    "merchant_id": "merchant-1",
    "service_id": "service-2-b",
    "name": "Spa Treatment",
    "description": "A full spa treatment",
    "price": {
        "price_micros": 200000000,
        "currency_code": "USD"
    }
    "scheduling_rules": {
        "min_advance_online_canceling": 14400,
    }
    "no_show_fee": {
        "fee": {
            "price_micros": 25000000,
            "currency_code": "USD"
        }
        "fee_type": "FIXED_RATE_DEFAULT"
    }
}

In the example above, the partner or the merchant is authorized to charge a fixed rate charge of $25 as specified in the no_show_fee.fee.price_micros field if the appointment holder does not attend the appointment. This fee may also be charged if the user cancels within the 4 hours (14400 seconds) before the appointment, as specified in the scheduling_rules.min_advanced_online_canceling field.

In the case where a reservation is made for a specified party size, for example in a dining reservation, then the no-show-fee can optionally be configured to be charged per person for the reservation. In this case no_show_fee.fee.fee_type can be set to "PER_PERSON".

Booking Server

When processing a request that includes a no-show fee, a payment token is passed to your booking server in the call to CreateBooking or CreateOrder through the field payment_processing_parameters.unparsed_payment_method_token. This token is passed in the same manner as in the prepayment case. However, because the token is only authorized for a short period of time, you must call the relevant API of your payment processor to upgrade this token into a version that you can persist for use at a later time. This is described in the Enabling Payments guide section on No-Show Fee token flow.

When returning a CreateBookingResponse or CreateOrderResponse the booking.payment_information field must be set to properly echo back the status of the no show fee as in the example below.

JSON

{
    "prepayment_status": "PREPAYMENT_PROVIDED",
    "payment_processed_by": "PROCESSED_BY_PARTNER",
    "payment_transaction_id": "[this-transaction-id]",
    "price": {
        "price_micros": "200000000",
        "currency_code": "USD"
    }
    "no_show_fee": {
        "fee": {
            "price_micros": 25000000,
            "currency_code": "USD"
        }
        "fee_type": "FIXED_RATE_DEFAULT"
    }
}

Note that the no_show_fee is set to reflect the price and structure of the fee that may be charged. Also note that, similar to the prepayments example, a transaction id is required in this message.

Also note that the booking_id or order_id set in the CreateBookingResponse or CreateOrderResponse is a required field for the real-time updates that must be sent when charging a no show fee. It is expected that this id is stored alongside information about the booking

Real-Time Updates

If a user does not arrive for their scheduled booking, or cancels after the cancellation window, you may optionally charge the specified no-show fee using the payment information you stored at the time of booking. When you charge a no-show fee, you are required to send a Real Time Update specifying that the no show fee was charged.

For bookings created by CreateBooking, an update should be sent to notification.partners.bookings.patch. In the body of this request should be the updated booking, with the status set to "NO_SHOW_PENALIZED". This status informs Google that a charge was made.

For example a request could be sent to:

PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/12345678/bookings/123123123?updateMask=status

With a request body:

JSON

{
    "name": "partners/12345678/bookings/123123123"
    "merchantId": "merchant-1"
    "serviceId": "service-2-b"
    "status": "NO_SHOW_PENALIZED"
}

A similar real-time update should be sent to notification.partners.orders.patch if a no-show fee is charged for an order.

Deposit

Deposits are used to collect an initial charge as a requirement for booking. Deposits can be charged at the time of booking or at a later time. You may decide that deposits are refundable with sufficient cancellation window.

To specify that a deposit is required for a booking you must set the deposit field in the services feed as shown in the example below:

JSON

{
    "merchant_id": "merchant-1",
    "service_id": "service-2-b",
    "name": "Spa Treatment",
    "description": "A full spa treatment",
    "price": {
        "price_micros": 200000000,
        "currency_code": "USD"
    }
    "scheduling_rules": {
        "min_advance_online_canceling": 14400,
    }
    "deposit": {
        "deposit": {
            "price_micros": 25000000,
            "currency_code": USD,
            "min_advance_cancellation_sec": 28800,
        }
        "deposit_type": "FIXED_RATE_DEFAULT"
    }
}

Note that in the example above a deposit can specify a cancellation time separately from the scheduling rules. In this case, a user will be able to cancel the service online up to 4 hours in advance (14400 seconds) but will not receive a refund on their deposit unless they cancel at least 8 hours in advance (28800 seconds).

Also note that, like no-show fees, a deposit can be charged either at a fixed rate, or at a per-person rate. In this case, the deposit is a fixed rate of $25, as specified by "deposit_type": "FIXED_RATE_DEFAULT". If the booking includes a party size, the deposit could be specified as a per person deposit by setting "deposit_type": "PER_PERSON".

Booking Server

When processing a request that includes a deposit, a payment token is passed to your booking server in the call to CreateBooking or CreateOrder through the field payment_processing_parameters.unparsed_payment_method_token. This token is passed in the same manner as in the prepayment case. If you charge the deposit or take out the hold at the time of booking, you can do so during this request.

If you intend to charge the deposit at a later time, because the token is only authorized for a short period of time, you must call the relevant API of your payment processor to upgrade this token into a version that you can persist for use at a later time. This is described in the Enabling Payments guide section on deposit token flow.

When returning a CreateBookingResponse or CreateOrderResponse the booking.payment_information field must properly echo back the status of the deposit, as in the example below.

JSON

{
    "prepayment_status": "PREPAYMENT_PROVIDED",
    "payment_processed_by": "PROCESSED_BY_PARTNER",
    "payment_transaction_id": "[this-transaction-id]",
    "price": {
        "price_micros": "200000000",
        "currency_code": "USD"
    }
    "deposit": {
        "deposit": {
            "price_micros": 25000000,
            "currency_code": USD,
            "min_advance_cancellation_sec": 28800,
        }
        "deposit_type": "FIXED_RATE_DEFAULT"
    }
}

Note that the deposit is set to reflect the price and structure of the deposit that will be charged or held. Also note that, similar to the prepayments example, a transaction id is required in this message.

Real-Time Updates

If a user cancels their booking before the deposit cancellation window, you must refund any deposit that you have charged to the users card. When refunding a deposit, you are required to send a Real Time Update specifying that the deposit was refunded.

For bookings created by CreateBooking, an update should be sent to notification.partners.bookings.patch. In the body of this request should be the updated booking, with the status set to "CANCELED" and the paymentInformation.prepaymentStatus field set to "PREPAYMENT_REFUNDED". This informs Google that the deposit was refunded.

For example a request could be sent to:

PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/12345678/bookings/123123123?updateMask=status

With a request body:

JSON

{
    "name": "partners/12345678/bookings/123123123"
    "merchantId": "merchant-1"
    "serviceId": "service-2-b"
    "status": "CANCELED"
    "paymentInformation": {
      "prepaymentStatus": "PREPAYMENT_REFUNDED"
    }
    
}

A similar real-time update should be sent to notification.partners.orders.patch if a deposit is refunded for an order.

Require Credit Card

A service may require a credit card on file. This card can be used to charge for the service at the time of the service or as an additional verification of the user’s identity. However, it should not be used for prepayment, deposits, or no show fees. If those use cases are required, they should be configured explicitly using the steps above. Also please note that requiring a credit card will often lead to a significant drop in bookings for this service.

To require that a credit card be provided during checkout you must set the field require_credit_card to "REQUIRE_CREDIT_CARD_ALWAYS".

JSON

{
    "merchant_id": "merchant-1",
    "service_id": "service-1-a",
    "name": "Men's haircut",
    "description": "One of our stylists will cut your hair",
    "price": {
        "price_micros": 15000000,
        "currency_code": "USD"
    }
    "scheduling_rules": {
        "min_advance_online_canceling": 7200,
    }
    "require_credit_card": "REQUIRE_CREDIT_CARD_ALWAYS"
}

Booking Server

When processing a request that includes a credit card requirement, a payment token is passed to your booking server in the call to CreateBooking or CreateOrder through the field payment_processing_parameters.unparsed_payment_method_token. This token is passed in the same manner as in the prepayment case. However, because the token is only authorized for a short period of time, you must call the relevant API of your payment processor to upgrade this token into a version that you can persist for use at a later time.

No additional information is required in the Booking server response beyond that of the pay-on-arrival use case.

Overriding Pricing at the Availability Level

In all of the examples above, the price / fee structure is specified at the Service level. In most cases this service-level pricing should be used. In some cases, however, it makes sense to alter the payments structure for certain availability slots. For example, the following situations could be handled by overriding prices / fees at the availability level:

  • Prices are reduced on Tuesdays and increased on Saturdays.
  • No show fees apply to availability between 5:00 PM and 7:00 PM.
  • Require deposits for party sizes greater than 6.
  • Bookings in a certain room require a credit card.

The table below lists, for each payment / fee method, what field to use in the availability feed to override the service level definition.

Payment Type Fee / Price Definition Overridable?
Pay on Arrival Service.price Price overridable through Availability.payment_option_id referencing Merchant.payment_option
Prepayment Service.price Price is overridable through Availability.payment_option_id referencing Merchant.payment_option
No show fee Service.no_show_fee Availability.no_show_fee
Deposit Service.deposit Availability.deposit
Require credit card Service.require_credit_card Availability.require_credit_card

Note that to override price at the availability level, you must first define a payment option at the merchant level. Addtionally, for guidance on adding cancellation windows at the availability level, please see the guide How to Add Cancellation Windows.