Prerequisites
To complete this guide, you must have completed the following:
- Understanding of our Payment Policies.
- Completed the Export Feeds portion of your E2E Integration.
The following are supported payment types for this add-on:
- Prepayment
- No Show Fee / Cancellation Fee
- Deposit
- Credit Card Required
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.
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 availability
level through the payment field of the Avaibility feed.
{
"availability": [{
"merchant_id": "dining-A",
"service_id": "reservation",
"start_sec": 1535853600,
"duration_sec": 2700,
"spots_total": 2,
"spots_open": 2,
"resources": {
"room_id": "A-dining-room",
"room_name": "Wine Tasting Room",
"party_size": 2,
"prepayment": {
"price_info": {
"price": {
"price_micros": 200000000,
"currency_code": "USD",
},
"price_type": "PER_PERSON"
}
}
}
}]
}
No-show Fee
No-show fees can be charged to a user if they don't 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 following example:
{
"merchant_id": "merchant-1",
"service_id": "service-2-b",
"name": "Reservation",
"description": "A dining reservation",
"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, 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 in the availability feed, see Overriding Pricing at The Availability Level.
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.
Deposit
Deposits are used to collect an initial charge as a requirement for a 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 following example:
{
"merchant_id": "merchant-1",
"service_id": "service-2-b",
"name": "Reservation",
"description": "A dining reservation",
"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 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 Overriding Pricing at The Availability Level.
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".
Require Credit Card
A service may require a credit card as an additional way to verify identity. However, it shouldn't be used for prepayment, deposits, or no show fees. If those use cases are required, they should be configured explicitly. 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": "reservation",
"name": "reservation",
"description": "Food reservation",
"require_credit_card": "REQUIRE_CREDIT_CARD_ALWAYS"
}
Override Pricing at the Availability Level
The price and fee structure is specified at the Service level. In most cases this service-level pricing should be used. However, it makes sense to alter the payments structure for certain availability slots. For example, the following situations could be handled by overriding prices or 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 payment type table lists, for each payment / fee method, what field to use in the availability feed to override the service level definition.
| Payment Type | Feed Definition | Overrideable? |
|---|---|---|
| Prepayment | Availability.prepayment | Not Overriable |
| No Show Fee | Service.no_show_fee | Availability.no_show_fee |
| Deposit | Service.deposit | Availability.deposit |