Definir diferentes tipos de pagamento

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:

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

1. Sem pagamentos / 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 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.

Importante:a menos que o contrário seja especificado com cancellation_policy (uso limitado, fale com seu contato de operações de parceiro do Google), presume que cancelável significa 100% reembolsável. Verifique se você configurou 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 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.

Importante:a menos que o contrário seja especificado com cancellation_policy (uso limitado, fale com seu contato de operações de parceiro do Google), presume que cancelável significa 100% reembolsável. Verifique se você configurou corretamente a janela de cancelamento.

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.

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 "cancelável" significa 100% reembolsável. Verifique se você configurou 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 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.