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. No entanto, os preços ainda são obrigatórios.

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:

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 oferecer suporte ao 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 do serviço por meio do campo prepayment_type do Service. Para exigir pagamentos por um serviço, defina-o como REQUIRED, como no exemplo abaixo. O preço é especificado da mesma forma que o exemplo do pagamento na chegada. Como estamos configurando o tipo de pré-pagamento como obrigatório, vamos coletar um cartão de crédito e cobrar esse valor no momento da finalização da compra.

Importante: a menos que especificado de outra forma com o cancellation_policy (uso limitado, verifique com seu contato de operações de parceiro do Google), supõe-se que ser cancelável significa 100% reembolsável. Verifique se você está definindo corretamente a janela de cancelamento.

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 os pré-pagamentos, um token de pagamento é transmitido para seu servidor de reserva 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 nos 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. Veja a seguir um exemplo mínimo para processar o 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 de imposto for especificada nos feeds/solicitação, ela também precisará ser incluída exatamente.

É necessário fornecer um ID de transação. Esse ID precisa ser exclusivo entre as transações com esse comerciante. Um bom candidato para um ID de transação é o ID fornecido 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

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:

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

Importante: a menos que especificado de outra forma com o cancellation_policy (uso limitado, verifique com seu contato de operações de parceiro do Google), supõe-se que ser cancelável significa 100% reembolsável. Verifique se você está definindo corretamente a janela de cancelamento.

Para ver como nenhuma taxa de exibição pode ser definida 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 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.

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. 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:

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

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

Importante: a menos que especificado de outra forma com cancellation_policy (uso limitado, verifique com seu contato de operações de parceiro do Google) ou deposit.min_advance_cancellation_sec, presume-se que seja possível cancelar a capacidade de reembolso por 100%. Verifique se você está definindo corretamente a janela de cancelamento.

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

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

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

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

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.

Tipo de pagamento	Definição de taxa / preço	Substituível?
Pagar na chegada	Service.price	Preço substituível usando Availability.payment_option_id com referência a Merchant.payment_option
Pré-pagamento	Service.price	O preço pode ser substituído usando as Availability.payment_option_id referências Merchant.payment_option
Sem taxa de exibição	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, 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.