Imposta tipi di pagamento diversi

La piattaforma Centro Azioni supporta una varietà di configurazioni per l'esecuzione dei pagamenti. La guida all'attivazione dei pagamenti tratta gli aspetti dell'integrazione comuni a tutte le integrazioni dei pagamenti, tra cui:

1. Configurazione dei feed per includere le informazioni relative a tokenization_parameter
2. Aggiornamento del server di prenotazione in modo che accetti payment_method_token oggetti
3. Una panoramica delle informazioni scambiate tra un utente, il Centro azioni, il partner / commerciante e l'elaboratore dei pagamenti.

In questa guida illustreremo in maggiore dettaglio come configurare i feed per specificare quale dei diversi tipi di configurazione di pagamento è applicabile ai commercianti e ai servizi.

1. Nessun pagamento / pagamento all'arrivo
2. Pagamento anticipato totale
3. Tariffa per mancato arrivo / cancellazione
4. Deposito

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

In ogni sezione verranno trattati anche i campi da monitorare nel server di prenotazione per accettare la specifica configurazione di pagamento.

Nessun pagamento / pagamento all'arrivo

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

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

Nel server di prenotazione non è richiesta alcuna configurazione aggiuntiva oltre all'implementazione standard per supportare il pagamento all'arrivo.

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 di Service. Per richiedere i pagamenti per un servizio, questo deve essere impostato su REQUIRED come nell'esempio riportato di seguito. Tieni presente che il prezzo è specificato nello stesso modo dell'esempio di pagamento all'arrivo. In questo caso, poiché impostiamo il tipo di pagamento anticipato su obbligatorio, verrà riscossa una carta di credito e il prezzo potrà essere addebitato al momento del pagamento.

Punto chiave: se non diversamente specificato con cancellation_policy (utilizzo limitato, contatta il tuo POC di Google), si presume che annullabile significhi al 100% rimborsabile. Assicurati di aver impostato 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 pagamenti anticipati, un token di pagamento viene trasmesso 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 nel campo del prezzo nei feed e 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 correttamente per indicare che il pagamento anticipato è stato fornito ed elaborato.

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

Tieni inoltre presente che devi fornire un ID transazione. Questo ID transazione deve essere almeno univoco tra le transazioni effettuate con il commerciante. Un valido candidato per un ID transazione è l'ID transazione che ti viene 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 mancato arrivo

Le tariffe di mancato arrivo possono essere addebitate a un utente se non partecipa alla prenotazione o se annulla dopo il periodo di annullamento. Se non viene specificata alcuna finestra di annullamento, verrà utilizzata per impostazione predefinita l'ora di inizio dello slot.

Per specificare una tariffa per il mancato arrivo, devi includere nel feed di servizio 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 precedente, il partner o il commerciante è autorizzato ad addebitare un addebito a tariffa fissa di 25 $come specificato nel campo no_show_fee.fee.price_micros se il titolare dell'appuntamento non partecipa all'appuntamento. Questa tariffa può essere addebitata anche se l'utente annulla l'appuntamento entro le 4 ore (14.400 secondi) prima dell'appuntamento, come specificato nel campo scheduling_rules.min_advance_online_canceling.

Punto chiave: se non diversamente specificato con cancellation_policy (utilizzo limitato, contatta il tuo POC di Google), si presume che annullabile significhi al 100% rimborsabile. Assicurati di aver impostato correttamente la finestra di annullamento.

Per scoprire come è possibile definire le tariffe per mancato arrivo a livello di disponibilità, consulta questa sezione.

Server di prenotazione

Durante l'elaborazione di una richiesta che include una tariffa per mancato arrivo, un token di pagamento viene trasmesso al tuo server di prenotazione nella chiamata a CreateBooking tramite il campo payment_processing_parameters.unparsed_payment_method_token. Questo token viene trasmesso come nel caso del pagamento anticipato. Tuttavia, poiché il token è autorizzato solo per un breve periodo di tempo, devi chiamare l'API pertinente dell'elaboratore dei pagamenti per eseguire l'upgrade di questo token a una versione che puoi conservare per l'utilizzo in un secondo momento. Ciò è descritto nella sezione della guida all'abilitazione dei pagamenti sul flusso del token della tariffa per mancato arrivo.

Quando restituisci un valore CreateBookingResponse, il campo booking.payment_information deve essere impostato in modo da richiamare correttamente lo stato della tariffa per mancato arrivo, 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"
    }
    "no_show_fee": {
        "fee": {
            "price_micros": 25000000,
            "currency_code": "USD"
        }
        "fee_type": "FIXED_RATE_DEFAULT"
    }
}

Tieni presente che no_show_fee è impostato in modo da riflettere il prezzo e la struttura della commissione che potrebbe essere addebitata. Tieni inoltre presente che, come nell'esempio dei pagamenti anticipati, questo messaggio richiede un transaction_id.

Tieni inoltre presente che il booking_id impostato in CreateBookingResponse è un campo obbligatorio per gli aggiornamenti in tempo reale da inviare quando viene addebitata una tariffa per mancato arrivo. Si prevede che questo ID venga memorizzato insieme alle informazioni sulla prenotazione.

Aggiornamenti in tempo reale

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

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

Ad esempio, potrebbe essere inviata una richiesta a:

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

Con il corpo di una richiesta:

JSON

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

Deposito

I cauzioni vengono utilizzate per riscuotere l'addebito iniziale come requisito della prenotazione. I cauzioni possono essere addebitati al momento della prenotazione o in un secondo momento. Potrebbe essere necessario definire i termini in base ai quali un deposito cauzionale può essere rimborsato e quando una prenotazione può essere annullata online.

Per specificare un bonifico, devi includere nel feed di servizio il campo deposit, 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, min_advance_online_canceling definisce il periodo di annullamento, mentre deposit.min_advance_cancellation_sec definisce quando l'acconto è rimborsabile. Tieni presente che nell'esempio precedente un bonifico può specificare un orario di annullamento separatamente dai termini del rimborso. In questo caso, un utente potrà annullare il servizio online con un massimo di 24 ore di anticipo (86.400 secondi). In questo modo, il commerciante viene informato direttamente in caso di annullamenti in ritardo. Tuttavia, l'utente potrebbe comunque avere diritto a un rimborso dell'acconto fino a 4 ore di anticipo (14.400 secondi) prima della prenotazione (contattando te o il commerciante per la cancellazione), cosa che verrà mostrato nei termini al momento del pagamento e nell'email di conferma.

Punto chiave: se non diversamente specificato con cancellation_policy (utilizzo limitato, contatta il tuo PDC di Google) o deposit.min_advance_cancellation_sec, si presume che annullabile significhi al 100% rimborsabile. Assicurati di aver impostato correttamente la finestra di annullamento.

Per scoprire come definire i versamenti 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 trasmesso al server di prenotazione nella chiamata a CreateBooking tramite il campo payment_processing_parameters.unparsed_payment_method_token. Questo token viene trasmesso come nel caso del pagamento anticipato. Se addebiti l'acconto o ritira la trattenuta al momento della prenotazione, potrai farlo durante la richiesta.

Se intendi addebitare il deposito in un secondo momento, poiché il token viene autorizzato solo per un breve periodo di tempo, devi chiamare l'API pertinente dell'elaboratore dei pagamenti per eseguire l'upgrade di questo token a una versione che puoi conservare per l'utilizzo in un secondo momento. Ciò è descritto nella sezione della guida all'abilitazione dei pagamenti sul flusso di token di deposito.

Quando restituisci un CreateBookingResponse, il campo booking.payment_information deve richiamare correttamente lo stato del bonifico, 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 modo da riflettere il prezzo e la struttura del deposito che verrà addebitato o trattenuto. Tieni inoltre presente che, come nell'esempio dei pagamenti anticipati, questo messaggio richiede un transaction_id.

Aggiornamenti in tempo reale

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

Per le prenotazioni create da CreateBooking, deve essere inviato un aggiornamento all'indirizzo 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, comunicherai a Google che l'acconto è stato rimborsato.

Ad esempio, potrebbe essere inviata una richiesta a:

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

Con il corpo di una 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 pagamenti anticipati, cauzioni o commissioni per mancato arrivo. Se questi casi d'uso sono obbligatori, devono essere configurati esplicitamente utilizzando i passaggi precedenti. Tieni inoltre presente che spesso la richiesta di una carta di credito determina un calo significativo delle prenotazioni per questo servizio.

Per richiedere che venga fornita una carta di credito al momento del 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 il requisito della carta di credito, viene trasmesso un token di pagamento al tuo server di prenotazione nella chiamata a CreateBooking tramite il campo payment_processing_parameters.unparsed_payment_method_token. Questo token viene trasmesso come nel caso del pagamento anticipato. Tuttavia, poiché il token è autorizzato solo per un breve periodo di tempo, devi chiamare l'API pertinente dell'elaboratore dei pagamenti per eseguire l'upgrade di questo token a una versione che puoi conservare per l'utilizzo in un secondo momento.

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

Sostituzione di prezzi a livello di disponibilità

In tutti gli esempi precedenti, la struttura prezzo / tariffa è specificata a livello di servizio. Nella maggior parte dei casi, è necessario utilizzare questi prezzi a livello di servizio. Tuttavia, in alcuni casi ha senso modificare la struttura dei pagamenti per determinati slot di disponibilità. Ad esempio, le seguenti situazioni potrebbero essere gestite sostituendo prezzi / commissioni a livello di disponibilità:

• I prezzi vengono ridotti il martedì e aumentati il sabato.
• Non si applicano costi aggiuntivi sulla disponibilità dalle ore 17:00 alle ore 19:00.

La seguente tabella elenca, per ogni metodo di pagamento / tariffa, quale campo utilizzare nel feed di disponibilità per sostituire la definizione del livello di servizio.

Tipo di pagamento	Definizione di tariffa / prezzo	Ignorabile?
Paga all'arrivo	Service.price	Prezzo sostituibile tramite Availability.payment_option_id che fa riferimento a Merchant.payment_option
Pagamento anticipato	Service.price	È possibile sostituire il prezzo tramite Availability.payment_option_id che fa riferimento a Merchant.payment_option
Commissione per mancato arrivo	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 periodi di annullamento a livello di disponibilità, consulta la guida su come aggiungere finestre di annullamento.