Set Different Payment Types

The Actions Center 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, the Actions Center, 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.

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:

{
    "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 of the Service. 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.

{
    "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 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 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.

{
    "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:

{
    "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_advance_online_canceling field.

To see how no show fees can be defined at the availability level, see this section.

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 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 the booking.payment_information field must be set to properly echo back the status of the no show fee as in the example below.

{
    "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 set in the CreateBookingResponse 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 (e.g. by contacting you directly), 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:

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

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 will need to define under which terms a deposit is refundable as well as when a booking can be cancelled online.

To specify a deposit, in the service feed, you should include the deposit field as shown in the example below:

{
    "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": 86400,
    }
    "deposit": {
        "deposit": {
            "price_micros": 25000000,
            "currency_code": USD,
            "min_advance_cancellation_sec": 14400,
        }
        "deposit_type": "FIXED_RATE_DEFAULT"
    }
}

In this example, the min_advance_online_canceling defines the cancellation window and the deposit.min_advance_cancellation_sec defines when the deposit is refundable. Note that in the example above a deposit can specify a cancellation time separately from the refund terms. In this case, a user will be able to cancel the service online up to 24 hours in advance (86400 seconds). This ensures that the merchant is directly informed of any late cancellations. However, the user may still be eligible for a refund on their deposit up until 4 hours in advance (14400 seconds) before the booking (by contacting you or the merchant for cancellation), which will be shown in the terms at checkout and in the confirmation email.

To see how deposits can be defined at the availability level, see this section.

Booking Server

When processing a request that includes a deposit, a payment token is passed to your booking server in the call to CreateBooking 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 the booking.payment_information field must properly echo back the status of the deposit, as in the example below.

{
    "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:

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

Require Credit Card

A service may require a credit card 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.

{
    "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"
    },
    "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 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.

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

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.