A plataforma da Central de ações oferece suporte a várias configurações para recebimento de pagamentos. O guia de ativação de pagamentos aborda os aspectos da integração comuns a todas as integrações de pagamentos, incluindo:
- Como configurar feeds para incluir informações de
tokenization_parameter
- Atualizando o servidor de agendamento para aceitar objetos
payment_method_token
- Uma visão geral das informações trocadas entre um usuário, a Central de ações, o parceiro / comerciante e o processador de pagamentos.
Neste guia, vamos abordar em mais detalhes como configurar seus feeds para especificar os tipos diferentes de configurações de pagamento aplicáveis aos seus comerciantes e serviços.
- Sem pagamentos / na chegada
- Pré-pagamento total
- Taxa de não comparecimento / taxa de cancelamento
- Problemas
Todos os casos de uso para pagamentos são extensões do caso de uso sem pagamento/pagamento na chegada, que não requer configuração de pagamento. Portanto, este tutorial começará descrevendo essa configuração e tratará as outras como extensões.
Cada seção também abrange os campos a serem acompanhados no servidor de reserva para aceitar a configuração de pagamento específica.
Sem pagamentos / na chegada
Para serviços que não exigem pagamento no momento do agendamento, não é necessária configuração de pagamentos no nível do comerciante ou do serviço. No entanto, os preços ainda são obrigatórios.
Essa é a configuração do valor de referência de um serviço, que contém nome, descrição e preço. Seria uma única mensagem de serviço
em um
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" } }
Nenhuma outra configuração além da implementação padrão é necessária no servidor de reserva para aceitar o pagamento na chegada.
Pré-pagamento
Essa configuração é usada para especificar que o valor do serviço precisa ser pago integralmente no momento da reserva.
O pré-pagamento é especificado no nível de serviço no campo prepayment_type
de Service
. Para exigir pagamentos por um serviço, defina como REQUIRED
, como no exemplo abaixo. Observe que
o preço é especificado da mesma maneira que no exemplo de pagamento na chegada. Aqui,
como definimos o tipo de pré-pagamento como obrigatório, um cartão de crédito será
coletado, e esse preço poderá ser cobrado no ato da compra.
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" }
Servidor de agendamento
Ao aceitar pré-pagamentos, um token de pagamento é transmitido ao servidor de reservas na chamada para CreateBooking
pelo campo payment_processing_parameters.unparsed_payment_method_token
.
É necessário cobrar exatamente o valor especificado no campo de preço dos feeds e usar a moeda especificada nos feeds. Essas cobranças precisam seguir o fluxo descrito
no
Guia de ativação de pagamentos.
Ao retornar um
CreateBookingResponse
,
o campo booking.payment_information
precisa ser definido para refletir
corretamente que o pré-pagamento foi fornecido e processado.
A especificação PaymentInformation
contém a documentação completa de todas as opções de informações de pagamento. Confira abaixo um exemplo mínimo de processamento de pré-pagamento. É importante que o preço
retornado no campo de preço corresponda exatamente ao especificado na
solicitação. Além disso, se uma taxa fiscal for especificada nos feeds/solicitação, ela também vai precisar ser incluída com exatidão.
Você também precisa fornecer um ID da transação. Esse ID precisa ser pelo menos exclusivo entre as transações realizadas com esse comerciante. Um bom candidato para o ID da transação é aquele fornecido a você pelo processador de pagamentos.
JSON
{ "prepayment_status": "PREPAYMENT_PROVIDED", "payment_processed_by": "PROCESSED_BY_PARTNER", "payment_transaction_id": "[this-transaction-id]", "price": { "price_micros": "200000000", "currency_code": "USD" } }
Taxa de não comparecimento
É possível cobrar taxas de não comparecimento se ele não comparecer à reserva ou se cancelar após a janela de cancelamento. Se nenhuma janela de cancelamento for especificada, o padrão será o horário de início do slot.
Para especificar uma taxa de não comparecimento, inclua o campo no_show_fee
no feed de serviço, conforme mostrado no exemplo abaixo:
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" } }
No exemplo acima, o parceiro ou comerciante está autorizado a cobrar uma taxa fixa de US $25, conforme especificado no campo no_show_fee.fee.price_micros
, se o titular do agendamento não comparecer. Essa taxa também poderá ser cobrada se o usuário cancelar até 4 horas (14.400 segundos) antes do horário, conforme especificado no campo scheduling_rules.min_advance_online_canceling
.
Para entender como as taxas de não comparecimento podem ser definidas no nível de disponibilidade, consulte esta seção.
Servidor de agendamento
Ao processar uma solicitação que inclui uma taxa de não comparecimento, um token de pagamento é transmitido ao servidor de reservas na chamada para CreateBooking
pelo campo payment_processing_parameters.unparsed_payment_method_token
.
Esse token é transmitido da mesma maneira que no caso de pré-pagamento. No entanto, como o token só é autorizado por um curto período, é necessário chamar a API relevante do processador de pagamentos para fazer upgrade desse token para uma versão que possa ser mantida para uso posterior. Isso é descrito na seção do guia "Como ativar pagamentos"
em
fluxo de token de taxa de não comparecimento.
Ao retornar um
CreateBookingResponse
,
o campo booking.payment_information
precisa ser definido para transmitir
corretamente o status da taxa de não comparecimento, como no exemplo abaixo.
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" } }
O no_show_fee
é definido para refletir o preço e
a estrutura da taxa que pode ser cobrada. Além disso, assim como no exemplo de pré-pagamentos, essa mensagem exige um transaction_id
.
Observe também que o booking_id
definido em
CreateBookingResponse
é um campo obrigatório para as atualizações em tempo real que precisam ser enviadas ao cobrar
uma taxa de não comparecimento. Espera-se que esse ID seja armazenado com as informações
sobre a reserva.
Atualizações em tempo real
Se um usuário não chegar para fazer a reserva programada ou cancelar após a janela de cancelamento (por exemplo, entrando em contato diretamente com você), será possível cobrar a taxa de não comparecimento especificada usando as informações de pagamento armazenadas no momento da reserva. Quando você cobra uma taxa de não comparecimento, é necessário enviar uma Atualização em tempo real especificando que essa taxa foi cobrada.
Para agendamentos criados por CreateBooking
, envie uma atualização para notification.partners.bookings.patch
. No corpo dessa solicitação, deve estar a reserva atualizada, com o status definido como NO_SHOW_PENALIZED
. Esse status informa ao Google que uma cobrança foi
feita.
Por exemplo, uma solicitação poderia ser enviada para:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/12345678/bookings/123123123?updateMask=status
Com um corpo de solicitação:
JSON
{ "name": "partners/12345678/bookings/123123123" "merchantId": "merchant-1" "serviceId": "service-2-b" "status": "NO_SHOW_PENALIZED" }
Problemas
Os depósitos são usados para coletar uma cobrança inicial como requisito para reserva. Os depósitos podem ser cobrados no momento da reserva ou posteriormente. Talvez seja necessário definir em quais termos um depósito será reembolsável e quando uma reserva pode ser cancelada on-line.
Para especificar um depósito, no feed de serviço, inclua o campo deposit
, como mostrado no exemplo abaixo:
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" } }
Nesse exemplo, min_advance_online_canceling
define a janela de cancelamento e deposit.min_advance_cancellation_sec
define quando o depósito é reembolsável. No exemplo acima, um depósito pode especificar um horário de cancelamento separado dos termos de reembolso. Nesse caso, o usuário pode cancelar o serviço on-line com até 24 horas de antecedência (86.400 segundos). Isso garante que o comerciante seja informado diretamente sobre cancelamentos tardios. No entanto, o usuário ainda pode
se qualificar para um reembolso no depósito com até 4 horas de antecedência
(14.400 segundos) antes da reserva (ao entrar em contato com você ou com o comerciante para cancelamento),
o que será mostrado nos termos na finalização da compra e no e-mail de confirmação.
Para ver como os depósitos podem ser definidos no nível de disponibilidade, consulte esta seção.
Servidor de agendamento
Ao processar uma solicitação que inclui um depósito, um token de pagamento é transmitido ao servidor de reservas na chamada para CreateBooking
pelo campo payment_processing_parameters.unparsed_payment_method_token
.
Esse token é transmitido da mesma forma que no caso de pré-pagamento. Se você
cobrar o depósito ou retirar a retenção no momento da reserva, poderá fazer isso
durante a solicitação.
Se você pretende cobrar o depósito mais tarde, já que o token só está autorizado por um curto período, chame a API relevante do seu processador de pagamentos para fazer upgrade desse token para uma versão que possa ser mantida para uso posterior. Isso é descrito na seção do guia de ativação de pagamentos sobre o fluxo de token de depósito.
Ao retornar um CreateBookingResponse
, o campo booking.payment_information
precisa retornar corretamente o status do depósito, como no exemplo abaixo.
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" } }
O depósito é definido para refletir o preço e a estrutura do depósito que será cobrado ou retido. Além disso, assim como no exemplo de pré-pagamentos, essa mensagem exige um transaction_id
.
Atualizações em tempo real
Se o usuário cancelar a reserva antes da janela de cancelamento do depósito, você vai precisar reembolsar qualquer depósito cobrado do cartão dele. Ao reembolsar um depósito, você precisa enviar uma Atualização em tempo real especificando que ele foi reembolsado.
Para agendamentos criados por CreateBooking
, envie uma atualização para notification.partners.bookings.patch
. No corpo dessa solicitação, deve estar a reserva atualizada, com o status definido como CANCELED
e o campo paymentInformation.prepaymentStatus
definido como PREPAYMENT_REFUNDED
. Isso informa ao Google que o depósito foi
reembolsado.
Por exemplo, uma solicitação poderia ser enviada para:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/12345678/bookings/123123123?updateMask=status
Com um corpo de solicitação:
JSON
{ "name": "partners/12345678/bookings/123123123" "merchantId": "merchant-1" "serviceId": "service-2-b" "status": "CANCELED" "paymentInformation": { "prepaymentStatus": "PREPAYMENT_REFUNDED" } }
Exigir cartão de crédito
Um serviço pode exigir um cartão de crédito como uma verificação adicional da identidade do usuário. No entanto, ele não deve ser usado para pré-pagamento, depósitos ou taxas de não comparecimento. Se esses casos de uso forem necessários, eles precisarão ser configurados explicitamente usando as etapas acima. Além disso, a exigência de um cartão de crédito costuma levar a uma queda significativa nas reservas desse serviço.
Para exigir um cartão de crédito na finalização da compra, defina o campo require_credit_card
como 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" }
Servidor de agendamento
Ao processar uma solicitação que inclui a exigência de cartão de crédito, um token de pagamento é transmitido ao servidor de reservas na chamada para CreateBooking
pelo campo payment_processing_parameters.unparsed_payment_method_token
.
Esse token é transmitido da mesma maneira que no caso de pré-pagamento. No entanto, como o token só é autorizado por um curto período, é necessário chamar a API relevante do processador de pagamentos para fazer upgrade desse token para uma versão que possa ser mantida para uso posterior.
Nenhuma outra informação é necessária na resposta do servidor de agendamento além daquela referente ao caso de uso de pagamento na chegada.
Substituição de preços no nível de disponibilidade
Em todos os exemplos acima, a estrutura de preço / taxa é especificada no nível de serviço. Na maioria dos casos, deve-se usar os preços no nível de serviço. Em alguns casos, no entanto, faz sentido alterar a estrutura de pagamentos para determinados slots de disponibilidade. Por exemplo, as situações a seguir podem ser tratadas com a modificação de preços / taxas no nível de disponibilidade:
- Os preços vão ser reduzidos às terças-feiras e aumentados aos sábados.
- As taxas de não exibição se aplicam à disponibilidade entre 17h e 19h.
A tabela abaixo lista o campo a ser usado no feed de disponibilidade para substituir a definição de nível de serviço para cada método de pagamento / taxa.
Tipo de pagamento | Definição de taxa / preço | Modificável? |
---|---|---|
Pagar na chegada | Service.price
|
Preço substituível por
Availability.payment_option_id fazendo referência a
Merchant.payment_option
|
Pré-pagamento | Service.price
|
O preço pode ser modificado usando
Availability.payment_option_id ao fazer referência a
Merchant.payment_option
|
Taxa de não comparecimento | Service.no_show_fee
|
Availability.no_show_fee
|
Problemas | Service.deposit
|
Availability.deposit
|
Exigir cartão de crédito | Service.require_credit_card
|
Availability.require_credit_card
|
Para substituir o preço no nível de disponibilidade, é preciso primeiro definir uma opção de pagamento no nível do comerciante. Além disso, para orientações sobre como adicionar janelas de cancelamento no nível de disponibilidade, consulte o guia Como adicionar janelas de cancelamento.