Impostare tipi di pagamento diversi

La piattaforma Actions Center supporta una serie di configurazioni per l'accettazione dei pagamenti. La guida all'attivazione dei pagamenti illustra gli aspetti dell'integrazione comuni a tutte le integrazioni dei pagamenti, tra cui:

1. Configurare i feed in modo da includere le informazioni su tokenization_parameter
2. Aggiornamento del server di prenotazione per accettare oggetti payment_method_token
3. Una panoramica delle informazioni scambiate tra un utente, il Centro azioni, il partner / il commerciante e l'elaboratore dei pagamenti.

In questa guida illustreremo più dettagliatamente come configurare i feed per specificare quale dei diversi tipi di configurazioni di pagamento è applicabile ai tuoi commercianti e servizi.

1. Nessun pagamento / pagamento all'arrivo
2. Pagamento anticipato totale
3. No Show Fee / Cancellation Fee
4. Deposito

Tutti i casi d'uso per i pagamenti sono estensioni del caso d'uso senza pagamenti/pagamento all'arrivo (che non richiede la configurazione dei pagamenti), pertanto questo tutorial inizierà descrivendo questa configurazione e tratterà le altre configurazioni come estensioni.

Ogni sezione illustrerà anche i campi da monitorare nel server di prenotazione per accettare la particolare configurazione di pagamento.

Nessun pagamento / pagamento all'arrivo

Per i servizi che non richiedono alcun pagamento al momento della prenotazione, non è richiesta alcuna configurazione dei pagamenti a livello di commerciante o servizio. Tuttavia, i prezzi sono comunque obbligatori.

Questa è la configurazione di base per un servizio, che contiene nome, descrizione e prezzo. Si tratta di un singolo messaggio di servizio all'interno di un 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"
    }
}

Per supportare il pagamento al momento dell'arrivo non è necessaria alcuna configurazione aggiuntiva oltre all'implementazione standard nel server di prenotazione.

Pagamento anticipato

Questa configurazione viene utilizzata per specificare che l'importo del servizio deve essere pagato per intero al momento della prenotazione.

Il pagamento anticipato viene specificato a livello di servizio tramite il campo prepayment_type del Service. Per richiedere pagamenti per un servizio, questo valore deve essere impostato su REQUIRED, come nell'esempio riportato di seguito. Tieni presente che il prezzo viene specificato nello stesso modo dell'esempio di pagamento all'arrivo. Qui, poiché abbiamo impostato il tipo di pagamento anticipato come obbligatorio, verrà raccolta una carta di credito e questo prezzo potrà essere addebitato al momento del pagamento.

Punto chiave: a meno che non sia specificato diversamente con cancellation_policy (utilizzo limitato, rivolgiti al tuo punto di contatto Google), si presume che annullabile significhi rimborsabile al 100%. Assicurati di impostare correttamente la finestra di annullamento.

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"
}

Server di prenotazione

Quando accetti i pagamenti anticipati, un token di pagamento viene passato al tuo server di prenotazione nella chiamata a CreateBooking tramite il campo payment_processing_parameters.unparsed_payment_method_token. Devi addebitare esattamente l'importo specificato tramite il campo del prezzo nei feed e devi utilizzare la valuta specificata nei feed. Questi addebiti devono seguire il flusso descritto nella guida all'attivazione dei pagamenti.

Quando restituisci un CreateBookingResponse il campo booking.payment_information deve essere impostato in modo da riflettere correttamente che l'anticipo è stato fornito ed elaborato.

La specifica PaymentInformation contiene la documentazione completa di tutte le opzioni per i dati di pagamento. Di seguito è riportato un esempio minimo per l'elaborazione del pagamento anticipato. È importante che il prezzo riportato nel campo del prezzo corrisponda esattamente a quello specificato nella richiesta. Inoltre, se nei feed/nella richiesta è specificata un'aliquota fiscale, deve essere inclusa anche esattamente.

Tieni inoltre presente che devi fornire un ID transazione. Questo ID transazione deve essere almeno univoco tra le transazioni con il commerciante in questione. Un buon candidato per un ID transazione è l'ID transazione fornito dall'elaboratore dei pagamenti.

JSON

{
    "prepayment_status": "PREPAYMENT_PROVIDED",
    "payment_processed_by": "PROCESSED_BY_PARTNER",
    "payment_transaction_id": "[this-transaction-id]",
    "price": {
        "price_micros": "200000000",
        "currency_code": "USD"
    }
}

Tariffa per mancata partecipazione

Le spese per mancato arrivo possono essere addebitate a un utente se non si presenta alla prenotazione o se annulla la prenotazione dopo il periodo di cancellazione. Se non viene specificata alcuna finestra di annullamento, verrà utilizzata per impostazione predefinita l'ora di inizio della fascia oraria.

Per specificare una tariffa per mancata presentazione, nel feed del servizio devi includere il campo no_show_fee come mostrato nell'esempio seguente:

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"
    }
}

Nell'esempio riportato sopra, il partner o il commerciante è autorizzato ad addebitare una tariffa fissa di 25 $, come specificato nel campo no_show_fee.fee.price_micros, se il titolare dell'appuntamento non si presenta. Questa commissione può essere addebitata anche se l'utente annulla l'appuntamento entro 4 ore (14400 secondi) prima dell'appuntamento, come specificato nel campo scheduling_rules.min_advance_online_canceling.

Punto chiave: a meno che non sia specificato diversamente con cancellation_policy (utilizzo limitato, rivolgiti al tuo punto di contatto Google), si presume che annullabile significhi rimborsabile al 100%. Assicurati di impostare correttamente la finestra di annullamento.

Per scoprire come definire le commissioni per mancata presentazione a livello di disponibilità, consulta questa sezione.

Server di prenotazione

Durante l'elaborazione di una richiesta che include una tariffa per mancata presentazione, un token di pagamento viene passato al server di prenotazione nella chiamata a CreateBooking tramite il campo payment_processing_parameters.unparsed_payment_method_token. Questo token viene passato nello stesso modo come nel caso del pagamento anticipato. Tuttavia, poiché il token è autorizzato solo per un breve periodo di tempo, devi chiamare l'API pertinente del tuo elaboratore dei pagamenti per eseguire l'upgrade di questo token in una versione che puoi conservare per utilizzarla in un secondo momento. Questo è descritto nella sezione della guida all'attivazione dei pagamenti dedicata al flusso del token per le commissioni relative ai casi di mancata presentazione.

Quando restituisci un valore CreateBookingResponse, il campo booking.payment_information deve essere impostato in modo da rispecchiare correttamente lo stato della tariffa per mancato arrivo, come nell'esempio seguente.

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"
    }
}

Tieni presente che no_show_fee è impostato in base al prezzo e alla struttura della commissione che potrebbe essere addebitata. Tieni inoltre presente che, come nell'esempio di prepagamenti, in questo messaggio è obbligatorio un transaction_id.

Tieni inoltre presente che il valore booking_id impostato in CreateBookingResponse è un campo obbligatorio per gli aggiornamenti in tempo reale che devono essere inviati al momento dell'addebito di una tariffa per mancato arrivo. È previsto che questo ID venga memorizzato insieme alle informazioni sulla prenotazione.

Aggiornamenti in tempo reale

Se un utente non si presenta per la prenotazione programmata o annulla dopo il periodo di annullamento (ad es. contattandoti direttamente), puoi facoltativamente addebitare la tariffa per il mancato arrivo specificata utilizzando i dati di pagamento memorizzati al momento della prenotazione. Quando addebiti una tariffa per mancata presentazione, devi inviare un aggiornamento in tempo reale specificando che è stata addebitata la tariffa per mancata presentazione.

Per le prenotazioni create da CreateBooking, è necessario inviare un aggiornamento a notification.partners.bookings.patch. Nel corpo di questa richiesta deve essere riportata la prenotazione aggiornata, con lo stato impostato su NO_SHOW_PENALIZED. Questo stato informa Google che è stato effettuato un addebito.

Ad esempio, una richiesta potrebbe essere inviata a:

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

Con un corpo della richiesta:

JSON

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

Deposito

I depositi vengono utilizzati per addebitare un importo iniziale come requisito per la prenotazione. I depositi possono essere addebitati al momento della prenotazione o in un secondo momento. Potresti dover definire i termini in base ai quali un deposito è rimborsabile, nonché quando una prenotazione può essere annullata online.

Per specificare un deposito, nel feed del servizio devi includere il deposit campo come mostrato nell'esempio seguente:

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"
    }
}

In questo esempio, il valore min_advance_online_canceling definisce la finestra di annullamento e il valore deposit.min_advance_cancellation_sec definisce quando il deposito è rimborsabile. Tieni presente che nell'esempio riportato sopra un deposito può specificare un termine di annullamento separatamente dai termini di rimborso. In questo caso, un utente potrà annullare il servizio online con un preavviso massimo di 24 ore (86400 secondi). In questo modo, il commerciante viene informato direttamente di eventuali cancellazioni in ritardo. Tuttavia, l'utente potrebbe avere ancora diritto a un rimborso del deposito fino a 4 ore (14400 secondi) prima della prenotazione (contatta te o il commerciante per la cancellazione), come indicato nei termini al momento del pagamento e nell'email di conferma.

Punto chiave: a meno che non sia specificato diversamente con cancellation_policy (utilizzo limitato, rivolgiti al tuo punto di contatto Google) o deposit.min_advance_cancellation_sec, si presume che annullabile significhi rimborsabile al 100%. Assicurati di impostare correttamente la finestra di annullamento.

Per scoprire come definire i depositi a livello di disponibilità, consulta questa sezione.

Server di prenotazione

Durante l'elaborazione di una richiesta che include un deposito, un token di pagamento viene passato al server di prenotazione nella chiamata a CreateBooking tramite il campo payment_processing_parameters.unparsed_payment_method_token. Questo token viene passato nello stesso modo che nel caso del pagamento anticipato. Se vuoi addebitare l'acconto o effettuare la preautorizzazione al momento della prenotazione, puoi farlo durante questa richiesta.

Se intendi addebitare l'acconto in un secondo momento, perché il token è autorizzato solo per un breve periodo di tempo, devi chiamare l'API pertinente del tuo elaboratore dei pagamenti per eseguire l'upgrade di questo token in una versione che puoi conservare per utilizzarla in un secondo momento. Come descritto nella sezione della guida all'attivazione dei pagamenti relativa al flusso dei token di deposito.

Quando restituisci un CreateBookingResponse, il campo booking.payment_information deve rispecchiare correttamente lo stato del deposito, come nell'esempio riportato di seguito.

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"
    }
}

Tieni presente che il deposito è impostato in base al prezzo e alla struttura del deposito che verrà addebitato o trattenuto. Tieni inoltre presente che, come nell'esempio di prepagamenti, in questo messaggio è obbligatorio un transaction_id.

Aggiornamenti in tempo reale

Se un utente annulla la prenotazione prima del periodo di annullamento del deposito, devi rimborsare l'eventuale deposito addebitato sulla carta dell'utente. Quando rimborsi un deposito, devi inviare un aggiornamento in tempo reale specificando che il deposito è stato rimborsato.

Per le prenotazioni create da CreateBooking, è necessario inviare un aggiornamento a notification.partners.bookings.patch. Nel corpo di questa richiesta deve essere presente la prenotazione aggiornata, con lo stato impostato su CANCELED e il campo paymentInformation.prepaymentStatus impostato su PREPAYMENT_REFUNDED. In questo modo, Google viene informata del rimborso del deposito.

Ad esempio, una richiesta potrebbe essere inviata a:

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

Con un corpo della richiesta:

JSON

{
    "name": "partners/12345678/bookings/123123123"
    "merchantId": "merchant-1"
    "serviceId": "service-2-b"
    "status": "CANCELED"
    "paymentInformation": {
      "prepaymentStatus": "PREPAYMENT_REFUNDED"
    }
    
}

Richiedi carta di credito

Un servizio potrebbe richiedere una carta di credito come verifica aggiuntiva dell'identità dell'utente. Tuttavia, non deve essere utilizzato per prepagamenti, depositi o commissioni per mancata presentazione. Se questi casi d'uso sono obbligatori, devono essere configurati esplicitamente seguendo i passaggi riportati sopra. Tieni inoltre presente che la richiesta di una carta di credito spesso comporta un calo significativo delle prenotazioni per questo servizio.

Per richiedere che venga fornita una carta di credito durante il pagamento, devi impostare il campo require_credit_card su 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"
}

Server di prenotazione

Durante l'elaborazione di una richiesta che include un requisito relativo alla carta di credito, un token di pagamento viene passato al server di prenotazione nella chiamata a CreateBooking tramite il campo payment_processing_parameters.unparsed_payment_method_token. Questo token viene passato nello stesso modo come nel caso del pagamento anticipato. Tuttavia, poiché il token è autorizzato solo per un breve periodo di tempo, devi chiamare l'API pertinente del tuo elaboratore dei pagamenti per eseguire l'upgrade di questo token in una versione che puoi conservare per utilizzarla in un secondo momento.

Nella risposta del server di prenotazione non sono richieste informazioni aggiuntive oltre a quelle del caso d'uso di pagamento all'arrivo.

Sostituzione dei prezzi a livello di disponibilità

In tutti gli esempi precedenti, la struttura di prezzo / tariffa è specificata a livello di servizio. Nella maggior parte dei casi, devono essere utilizzati questi prezzi a livello di servizio. In alcuni casi, però, ha senso modificare la struttura dei pagamenti per determinati intervalli di disponibilità. Ad esempio, le seguenti situazioni potrebbero essere gestite sostituendo i prezzi / le tariffe a livello di disponibilità:

• I prezzi sono ridotti i martedì e aumentati i sabati.
• Non vengono applicate commissioni per la visualizzazione tra le 17:00 e le 19:00.

La tabella seguente elenca, per ogni metodo di pagamento / tariffa, il campo da utilizzare nel feed di disponibilità per eseguire l'override della definizione del livello di servizio.

Tipo di pagamento	Definizione di tariffa / prezzo	Sostituibile?
Paga all'arrivo	Service.price	Prezzo sostituibile tramite Availability.payment_option_id che fa riferimento Merchant.payment_option
Pagamento anticipato	Service.price	Il prezzo è sostituibile tramite Availability.payment_option_id che fa riferimento Merchant.payment_option
Nessuna commissione per la mancata pubblicazione	Service.no_show_fee	Availability.no_show_fee
Deposito	Service.deposit	Availability.deposit
Richiedi carta di credito	Service.require_credit_card	Availability.require_credit_card

Tieni presente che per sostituire il prezzo a livello di disponibilità, devi prima definire un'opzione di pagamento a livello di commerciante. Inoltre, per indicazioni su come aggiungere finestre di annullamento a livello di disponibilità, consulta la guida Come aggiungere finestre di annullamento.