Como configurar pagamentos

A plataforma Reservar com o Google oferece suporte a várias configurações para receber pagamentos. O guia de ativação de pagamentos abrange os aspectos da integração que são comuns a todas as integrações de pagamentos, incluindo:

1. Como configurar feeds para incluir informações de tokenization_parameter
2. Atualizando o servidor de agendamento para aceitar objetos payment_method_token
3. Uma visão geral das informações trocadas entre um usuário, o Reservar com o Google, o parceiro / comerciante e o processador de pagamentos.

Neste guia, vamos mostrar em mais detalhes como configurar seus feeds para especificar quais tipos diferentes de configuração de pagamento são aplicáveis aos seus comerciantes e serviços.

1. Sem pagamentos / pagamento na chegada
2. Pré-pagamento total
3. Taxa de não comparecimento / taxa de cancelamento
4. Problemas

Todos os casos de uso para pagamentos são extensões do caso de uso sem pagamento / pagamento na chegada (que não exige configuração de pagamento). Portanto, este tutorial começará descrevendo essa configuração e tratará outras como extensões.

Cada seção também abordará os campos a serem rastreados no servidor de reservas para aceitar a configuração de pagamento específica.

Sem pagamentos / pagamento na chegada

Para serviços que não exigem pagamento no momento da reserva, nenhuma configuração de pagamento é necessária no nível do comerciante ou do serviço.

Essa é a configuração de referência para um serviço, que contém nome, descrição e preço. Essa seria uma única mensagem de serviço em uma ServiceFeed:

{
    "merchant_id": "merchant-1",
    "service_id": "reservation",
    "name": "reservation",
    "description": "Food reservation"
}

Nenhuma outra configuração além da implementação padrão é necessária no servidor de reserva para oferecer suporte ao pagamento na chegada.

Taxa de não comparecimento

As taxas de não comparecimento poderão ser cobradas de um usuário se ele não comparecer 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 como mostrado no exemplo abaixo:

{
    "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 tem autorização para 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 ao horário. Essa taxa também poderá ser cobrada se o usuário cancelar no prazo de quatro horas (14.400 segundos) antes do horário agendado, conforme especificado no campo scheduling_rules.min_advance_online_canceling.

Para ver como nenhuma taxa de exibição pode ser definida no nível de disponibilidade, consulte esta seção.

A taxa de não comparecimento pode ser configurada para ser cobrada por pessoa para a reserva. Nesse caso, no_show_fee.fee.fee_type pode ser definido como PER_PERSON.

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 forma 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 você possa manter para uso posterior. Isso é descrito na seção "Como ativar o pagamento em pagamentos" no fluxo do token de taxa de não comparecimento.

Ao retornar um CreateBookingResponse, o campo booking.payment_information precisa ser definido para retornar o status da taxa de não comparecimento, como no exemplo abaixo.

{
    "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. Observe também que, assim como no exemplo de pré-pagamentos, é necessário especificar um transaction_id nesta mensagem.

Observe também que o booking_id definido no CreateBookingResponse é um campo obrigatório para as atualizações em tempo real que precisam ser enviadas ao cobrar uma taxa de não comparecimento. É esperado que esse ID seja armazenado com informações sobre a reserva.

Atualizações em tempo real

Se um usuário não chegar para o horário agendado ou cancelar a reserva após o período 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. Ao cobrar uma taxa de não comparecimento, é necessário enviar uma Atualização em tempo real especificando que a taxa de não comparecimento foi cobrada.

Para agendamentos criados por CreateBooking, uma atualização precisa ser enviada para notification.partners.bookings.patch. No corpo desta 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 pode ser enviada para:

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

Com um corpo de solicitação:

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

Problemas

Os depósitos são usados para cobrar 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 é reembolsável, além de quando uma reserva pode ser cancelada on-line.

Para especificar um depósito, inclua o campo deposit no feed de serviço como mostrado no exemplo abaixo:

{
    "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 poderá 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 atrasados. No entanto, o usuário ainda pode se qualificar para um reembolso no depósito até quatro horas antes (14.400 segundos) antes da reserva (entrando em contato com você ou pelo comerciante para cancelamento), o que será exibido nos termos da 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.

Observe que, assim como taxas de não comparecimento, um depósito pode ser cobrado com uma taxa fixa ou por pessoa. Nesse caso, o depósito é uma taxa fixa de US $25, conforme especificado por "deposit_type": "FIXED_RATE_DEFAULT". Se a reserva incluir o número de pessoas, o depósito poderá ser especificado como um depósito por pessoa definindo "deposit_type": "PER_PERSON".

Servidor de agendamento

Ao processar uma solicitação que inclui um depósito, um token de pagamento é transmitido para seu servidor de reserva 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 essa solicitação.

Se você pretende cobrar o depósito mais tarde, porque o token só será autorizado por um curto período, será necessário chamar a API relevante do seu processador de pagamentos para fazer upgrade desse token para uma versão que você poderá manter para uso posterior. Isso é descrito na seção Como ativar o fluxo de token do guia de pagamentos.

Ao retornar um CreateBookingResponse, o campo booking.payment_information precisa mostrar o status do depósito corretamente, como no exemplo abaixo.

{
    "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 mantido. Observe também que, assim como no exemplo de pré-pagamentos, é necessário especificar um transaction_id nesta mensagem.

Atualizações em tempo real

Se um usuário cancelar a reserva antes da janela de cancelamento do depósito, será preciso reembolsar o depósito cobrado no cartão do usuário. Ao reembolsar um depósito, você precisa enviar uma atualização em tempo real especificando que o depósito foi reembolsado.

Para agendamentos criados por CreateBooking, uma atualização precisa ser enviada para notification.partners.bookings.patch. No corpo desta 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 pode ser enviada para:

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

Com um corpo de solicitação:

{
    "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 verificação adicional da identidade do usuário. No entanto, ela não deve ser usada para pré-pagamentos, depósitos ou taxas de não exibição. Se esses casos de uso forem necessários, configure-os explicitamente seguindo as etapas acima. Além disso, exigir um cartão de crédito geralmente leva a uma queda significativa nas reservas desse serviço.

Para exigir que um cartão de crédito seja fornecido na finalização da compra, defina o campo require_credit_card como REQUIRE_CREDIT_CARD_ALWAYS.

{
    "merchant_id": "merchant-1",
    "service_id": "reservation",
    "name": "reservation",
    "description": "Food reservation",
    "require_credit_card": "REQUIRE_CREDIT_CARD_ALWAYS"
}

Servidor de agendamento

Ao processar uma solicitação que inclui um requisito de cartão de crédito, um token de pagamento é transmitido para seu servidor de reserva na chamada para CreateBooking por meio do campo payment_processing_parameters.unparsed_payment_method_token. Esse token é transmitido da mesma forma 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 você possa manter para uso posterior.

Nenhuma informação adicional é necessária na resposta do servidor de reservas além do caso de uso de pagamento na chegada.

Como substituir 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, esses preços de nível de serviço precisam ser usados. No entanto, em alguns casos, faz sentido alterar a estrutura de pagamentos para determinados horários disponíveis. Por exemplo, as seguintes situações podem ser tratadas substituindo preços / taxas no nível de disponibilidade:

• Os preços são reduzidos às terças-feiras e aumentam aos sábados.
• Nenhuma taxa de exibição se aplica à disponibilidade entre 17h e 19h.
• Exija depósitos para grupos de festas maiores que 6.
• As reservas em um determinado quarto exigem um cartão de crédito.

A tabela abaixo lista, para cada método de pagamento / taxa, qual campo usar no feed de disponibilidade para substituir a definição de nível de serviço.

Para substituir o preço no nível de disponibilidade, defina uma opção de pagamento no nível do comerciante. Além disso, para orientação sobre como adicionar janelas de cancelamento no nível de disponibilidade, consulte o guia Como adicionar janelas de cancelamento.