Eseguire un pagamento

Un pagamento è l'operazione principale: una vendita, un rimborso, una pre-autorizzazione o un completamento. Tutti passano attraverso un metodo — sendPaymentRequest — e si seleziona il tipo di pagamento con il campo paymentType. Questa guida copre il pagamento regolare; le varianti differiscono solo in paymentType e sono indicate alla fine.

Prerequisito: una sessione attiva. Vedi Ciclo di vita della sessione e del login — senza un login riuscito, una richiesta di pagamento viene ignorata.

La chiamata

viewModelScope.launch {
    clientSDK.sendPaymentRequest(
        RetailerMessageArguments.PaymentRequestMessageArguments
            .RegularPaymentRequestMessageArguments(
                saleTransactionId = "Sale001",
                paymentAmounts = PaymentAmounts(
                    currency = "EUR",
                    amount = BigDecimal("10.00")
                ),
                paymentType = PaymentType.NORMAL
            )
    )
}

I tre campi di cui hai bisogno:

• saleTransactionId — il tuo riferimento per la vendita. Deve essere alfanumerico e di 35 caratteri o meno. Se lo ricavi da un UUID, rimuovi i trattini — un UUID grezzo è di 36 caratteri e verrà rifiutato.
• paymentAmounts — un PaymentAmounts. Al minimo currency (deve corrispondere alla valuta configurata nel terminale) e amount (un BigDecimal). Può anche contenere tipAmount, cashbackAmount e paidAmount — consulta la documentazione API per l'elenco completo dei campi.
• paymentType — un PaymentType. NORMAL per una vendita standard.

Lettura del risultato

L'esito arriva nel tuo interceptor come un sottotipo di RetailerPaymentResponse:

when (message) {
    is SuccessRetailerPaymentResponse -> { /* approvato — leggere i dati POI, gli importi */ }
    is ErrorRetailerPaymentResponse   -> { /* rifiutato o fallito */ }
    is PartialRetailerPaymentResponse -> { /* esito parziale — gestire esplicitamente */ }
    is RetailerDisplayRequest         -> { /* aggiornamento di progresso durante l'elaborazione */ }
}

Gestisci gli esiti del supertipo, non solo il successo — vedi Come funziona il modello dei messaggi per il motivo. I messaggi RetailerDisplayRequest arrivano durante l'elaborazione per segnalare cosa sta facendo il terminale; non sono il risultato finale.

Il POITransactionID è importante in seguito. Una risposta di pagamento riuscita contiene un POITransactionID nei suoi dati POI. Se potresti aver bisogno di annullare questo pagamento, cattura ora quell'ID — l'annullamento ne ha bisogno. Vedi Guida: annullare una transazione.

Le varianti di pagamento

Non chiami un metodo diverso per rimborsi o pre-autorizzazioni — cambi il paymentType. Si applicano gli stessi tipi di richiesta e risposta; non ci sono sottotipi di risposta separati per rimborso/pre-autorizzazione. Un RetailerDisplayRequest durante l'elaborazione indica quale operazione è in corso.

PaymentType definisce 13 valori in totale (inclusi rate, ricorrenti, anticipo contanti e altri). I quattro sopra sono i più comuni; l'enum completo è nella documentazione API. Usa la costante enum esatta — i valori sono in maiuscolo (NORMAL, non Normal).

Annullare un pagamento in corso

Un pagamento iniziato ma non ancora autorizzato dall'host può essere annullato con sendAbortRequest(). Dopo l'autorizzazione è troppo tardi per annullare — usa invece un annullamento. Vedi Guida: annullare una transazione e Risoluzione problemi: l'annullamento non ha effetto dopo l'autorizzazione.

Correlati

• Quickstart — la prima guida al pagamento.
• Come funziona il modello dei messaggi — gestire correttamente la risposta.
• Guida: annullare una transazione — annullare un pagamento completato.
• Guida: acquisizione carta e pagamenti in due fasi — pre-lettura della carta, poi completamento.
• Documentazione API (sdk-doc.zip) — campi completi di PaymentAmounts e l'enum completo PaymentType.