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:
- Configurazione dei feed per includere le informazioni relative a
tokenization_parameter
- Aggiornamento del server di prenotazione in modo che accetti
payment_method_token
oggetti - 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.
- Nessun pagamento / pagamento all'arrivo
- Pagamento anticipato totale
- Tariffa per mancato arrivo / cancellazione
- 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.
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
.
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.
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.