Definir diferentes tipos de pagamento

A plataforma da Central de ações oferece suporte a várias configurações para receber pagamentos. O Guia de ativação de pagamentos aborda 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. Como atualizar o servidor de agendamento para aceitar objetos payment_method_token
3. Visão geral das informações trocadas entre um usuário, o Centro de ações, o parceiro / comerciante e o processador de pagamentos.

Neste guia, vamos abordar em mais detalhes como configurar seus feeds para especificar quais dos diferentes tipos de configurações 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. Depósito

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

Cada seção também vai abordar os campos a serem rastreados no servidor de agendamento 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 pagamentos é 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 de um serviço, que contém nome, descrição e preço. Essa 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 configuração além da implementação padrão é necessária no servidor de reservas 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 de serviço pelo campo prepayment_type do Service. Para exigir pagamentos por um serviço, defina como REQUIRED, conforme o exemplo abaixo. O preço é especificado da mesma forma que o exemplo de pagamento na chegada. Aqui, como estamos definindo o tipo de pré-pagamento como obrigatório, um cartão de crédito será coletado e esse preço poderá ser cobrado no momento do pagamento.

Importante:a menos que seja especificado o contrário com cancellation_policy (uso limitado, verifique com seu POC do Google), considera-se que "reembolsá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 pré-pagamentos, um token de pagamento é transmitido ao seu servidor de agendamento na chamada para CreateBooking pelo campo payment_processing_parameters.unparsed_payment_method_token. Você precisa 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 para 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 alíquota de tributos for especificada nos feeds/solicitações, ela também precisará ser incluída exatamente.

Além disso, é necessário fornecer um ID da transação. Esse ID de transação precisa ser, no mínimo, exclusivo entre as transações com esse comerciante. Um bom candidato para um ID de transação é o ID de transação 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 podem ser cobradas de um usuário 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 período.

Para especificar uma taxa de não comparecimento, no feed de serviços, inclua o campo no_show_fee, 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 o 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 pode ser cobrada se o usuário cancelar até quatro horas (14.400 segundos) antes do horário agendado, conforme especificado no campo scheduling_rules.min_advance_online_canceling.

Importante:a menos que seja especificado o contrário com cancellation_policy (uso limitado, verifique com seu POC do Google), considera-se que "reembolsável" significa 100% reembolsável. Verifique se você está definindo corretamente a janela de cancelamento.

Para saber 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 para o servidor de agendamento 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 atualizar esse token para uma versão que possa ser usada mais tarde. Isso é descrito na seção do guia de ativação de pagamentos sobre o fluxo de token de taxa de não comparecimento.

Ao retornar um CreateBookingResponse, o campo booking.payment_information precisa ser definido para refletir 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, semelhante ao exemplo de pré-pagamentos, um transaction_id é necessário nesta mensagem.

Além disso, 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. Esse ID precisa ser armazenado com informações sobre a reserva.

Atualizações em tempo real

Se um usuário não comparecer à reserva programada ou cancelar após o período de cancelamento (por exemplo, entrando em contato diretamente com você), você poderá 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, você precisa enviar uma atualização em tempo real especificando que a taxa foi cobrada.

Para reservas criadas por CreateBooking, uma atualização precisa ser enviada para notification.partners.bookings.patch. No corpo desta solicitação, deve haver 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"
}

Depósito

Os depósitos são usados para coletar uma cobrança inicial como um requisito para a reserva. Os depósitos podem ser cobrados no momento da reserva ou em um momento posterior. Talvez seja necessário definir em quais termos um depósito é reembolsável, bem como quando uma reserva pode ser cancelada on-line.

Para especificar um depósito, no feed de serviços, inclua o campo deposit, 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": 86400,
    }
    "deposit": {
        "deposit": {
            "price_micros": 25000000,
            "currency_code": USD,
            "min_advance_cancellation_sec": 14400,
        }
        "deposit_type": "FIXED_RATE_DEFAULT"
    }
}

Neste exemplo, o min_advance_online_canceling define a janela de cancelamento, e o deposit.min_advance_cancellation_sec define quando o depósito é reembolsável. No exemplo acima, um depósito pode especificar um tempo 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 receber um reembolso do depósito até 4 horas antes da reserva (contando com o contato com você ou o comerciante para o cancelamento), o que será mostrado nos termos no momento do pagamento e no e-mail de confirmação.

Importante:a menos que especificado de outra forma com cancellation_policy (uso limitado, verifique com seu POC do Google) ou deposit.min_advance_cancellation_sec, presume-se que "reembolsável" significa 100% reembolsável. Verifique se você está definindo corretamente a janela de cancelamento.

Para saber 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 essa solicitação.

Se você pretende cobrar o depósito mais tarde, porque o token só está autorizado por um curto período, é necessário chamar a API relevante do processador de pagamentos para atualizar esse token para uma versão que possa ser usada mais tarde. Isso é descrito na seção do guia "Ativar pagamentos" sobre o fluxo de tokens de depósito.

Ao retornar um CreateBookingResponse, o campo booking.payment_information precisa refletir 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, semelhante ao exemplo de pré-pagamentos, um transaction_id é necessário nesta mensagem.

Atualizações em tempo real

Se um usuário cancelar a reserva antes da janela de cancelamento do depósito, você vai precisar 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 reservas criadas por CreateBooking, uma atualização precisa ser enviada para notification.partners.bookings.patch. No corpo da solicitação, deve haver 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 uma verificação adicional da identidade do usuário. No entanto, ele não deve ser usado para pré-pagamentos, 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 geralmente leva a uma queda significativa nas reservas desse serviço.

Para exigir que um cartão de crédito seja fornecido durante a 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 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 atualizar esse token para uma versão que possa ser usada mais tarde.

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

Como substituir o preço no nível de disponibilidade

Em todos os exemplos acima, a estrutura de preço / taxa é especificada no nível do serviço. Na maioria dos casos, esse preço do nível de serviço precisa ser usado. No entanto, em alguns casos, faz sentido alterar a estrutura de pagamentos para determinados intervalos de disponibilidade. Por exemplo, as seguintes situações podem ser resolvidas substituindo preços / taxas no nível de disponibilidade:

• Os preços são reduzidos às terças-feiras e aumentados aos sábados.
• As taxas de não comparecimento se aplicam à 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 do nível de serviço.

Tipo de pagamento	Definição de taxa / preço	Pode ser substituído?
Pagamento na chegada	Service.price	O preço pode ser substituído por Availability.payment_option_id referenciando Merchant.payment_option
Pré-pagamento	Service.price	O preço pode ser substituído por Availability.payment_option_id referenciando Merchant.payment_option
Taxa de não comparecimento	Service.no_show_fee	Availability.no_show_fee
Depósito	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, primeiro é necessário 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.