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:
- Configuring feeds to include
tokenization_parameter
information - Updating the booking server to accept
payment_method_token
objects - 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.
- No Payments / Pay on Arrival
- Full Prepayment
- No Show Fee / Cancellation Fee
- 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
:
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 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.
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
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.
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_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.
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
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:
JSON
{ "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:
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": 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.
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" } }
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
.
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" }, "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.
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.