Method: capture

Avvia il trasferimento di denaro tra l'account di un cliente in possesso di Google e l'elaboratore dei pagamenti. La combinazione di requestId nell'intestazione e paymentIntegratorAccountId è la chiave di idempotenza e identifica in modo univoco questa transazione. Tutte le mutazioni di questa transazione (rimborsi) completano il valore requestId nel campo captureRequestId.

Se l'endpoint rileva un errore durante l'elaborazione della richiesta, il corpo della risposta da questo endpoint deve essere di tipo ErrorResponse.

Una richiesta di esempio ha il seguente aspetto:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": "1502220196077"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "googlePaymentToken": "ZXhhbXBsZSB1bmlxdWUgcGF5bWVudCB0b2tlbiB2YWx1ZQ",
  "transactionDescription": "Google - Music",
  "currencyCode": "INR",
  "amount": "728000000",
  "captureContext": {}
}

Ecco un esempio di risposta:


{
  "responseHeader": {
    "responseTimestamp": "1481900013178"
  },
  "result": "SUCCESS",
  "paymentIntegratorTransactionId": "aW50ZWdyYXRvciB0cmFuc2FjdGlvbiBpZA"
}

Richiesta HTTP

POST https://www.integratorhost.example.com/v1/capture

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "paymentIntegratorAccountId": string,
  "transactionDescription": string,
  "currencyCode": string,
  "amount": string,
  "captureContext": {
    object (CaptureContext)
  },

  // Union field fopDetails can be only one of the following:
  "googlePaymentToken": string,
  "mandateDetails": {
    object (MandateDetails)
  },
  "mandateWithNotificationDetails": {
    object (MandateWithNotificationDetails)
  }
  // End of list of possible types for union field fopDetails.

  // Union field account_verification can be only one of the following:
  "authenticationRequestId": string,
  "otpVerification": {
    object (OtpVerification)
  }
  // End of list of possible types for union field account_verification.
}
Campi
requestHeader

object (RequestHeader)

REQUIRED: intestazione comune per tutte le richieste.
paymentIntegratorAccountId

string

REQUIRED: questo è l'identificatore dell'account dell'integratore dei pagamenti che identifica i vincoli contrattuali relativi a questa transazione.
transactionDescription

string

REQUIRED: questa è la descrizione della transazione che può essere inserita nell'estratto conto del cliente. Localizzazione nella userLocale trovata in requestHeader. Questo formato può essere modificato senza preavviso e non deve mai essere analizzato.
currencyCode

string

OBBLIGATORIO: codice valuta ISO 4217 di tre lettere
amount

string (Int64Value format)

OBBLIGATORIO: l'importo dell'acquisto espresso in micro dell'unità di valuta.
captureContext

object (CaptureContext)

OBBLIGATORIO: contesto relativo a questo screenshot.
Campo di unione fopDetails. REQUIRED: dettagli FOP per questa transazione Capture. fopDetails può essere solo uno dei seguenti:
googlePaymentToken

string

Token che entrambe le aziende utilizzeranno per identificare l'account per gli acquisti tra loro.
mandateDetails

object (MandateDetails)

Dettagli di pagamento specifici per i mandati.
mandateWithNotificationDetails

object (MandateWithNotificationDetails)

Dettagli di pagamento specifici per i mandati, in cui è richiesto un upcomingTransactionNotification.

Campo di unione account_verification.

account_verification può essere solo uno dei seguenti:
authenticationRequestId

string

FACOLTATIVO: requestId della richiesta di autenticazione associata. Se non è presente, non è possibile associare nessuna autenticazione all'acquisizione.

Se è presente, l'utente è stato autenticato immediatamente prima di questa chiamata o è stato autenticato al momento della configurazione di un calendario dei pagamenti automatico.
otpVerification

object (OtpVerification)

FACOLTATIVO: i dati necessari per verificare una OTP generata da sendOtp. È presente solo se l'utente ha seguito il percorso sendOtp.

Corpo della risposta

Oggetto risposta per il metodo di acquisizione.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "paymentIntegratorTransactionId": string,
  "userMessage": string,
  "result": enum (CaptureResultCode),
  "rawResult": {
    object (RawResult)
  },
  "transactionLimit": string,
  "currentBalance": string
}
Campi
responseHeader

object (ResponseHeader)

REQUIRED: intestazione comune per tutte le risposte.
paymentIntegratorTransactionId

string

FACOLTATIVO: questo identificatore è specifico per l'integratore e viene generato da quest'ultimo. Si tratta dell'identificatore con cui l'integratore conosce la transazione.

Per praticità, questo identificatore è incluso nei dettagli del versamento
userMessage
(deprecated)

string

OBSOLETO: una descrizione del risultato da mostrare all'utente se il risultato non è SUCCESS.
result

enum (CaptureResultCode)

OBBLIGATORIO: risultato di questo acquisizione.
rawResult

object (RawResult)

FACOLTATIVO: risultato non elaborato di questa acquisizione. Utilizzato per fornire informazioni utili al motore dei rischi e all'analisi di Google. Nelle situazioni in cui la mappatura del codice viene rifiutata, a volte i dati vanno persi. L'integratore può scegliere di fornire a Google un codice non elaborato. Ad esempio, un gateway della carta di credito (l'integratore) può utilizzare questo campo per comunicare a Google l'esatto codice di rifiuto ricevuto dalla rete VISA. In questo caso, scope corrisponde a "visa" e rawCode corrisponde a ciò che la rete VISA ha restituito.

Questo valore è obbligatorio se result non è SUCCESS.
transactionLimit

string (Int64Value format)

FACOLTATIVO: se il risultato è CHARGE_EXCEEDS_TRANSACTION_LIMIT, si tratta dell'importo massimo che l'utente può spendere per una transazione (in micro). Questa funzionalità viene utilizzata per i messaggi strutturati rivolti agli utenti e per l'analisi della percentuale di rifiuto.

Deve essere un limite relativo a currencyCode nella richiesta.
currentBalance

string (Int64Value format)

FACOLTATIVO: se il risultato è INSUFFICIENT_FUNDS, si tratta del saldo attuale disponibile nell'account dell'utente (in micro). Viene utilizzato per i messaggi strutturati rivolti agli utenti.

Questo valore deve essere nella stessa valuta di currencyCode nella richiesta.

MandateDetails

Dettagli sul mandato da cui eseguire l'acquisizione.

Rappresentazione JSON 
{
  "mandateId": string
}
Campi
mandateId

string

OBBLIGATORIO: l'ID mandato generato da Google, inviato durante la chiamata createMandate.

MandateWithNotificationDetails

Dettagli sul mandato da cui effettuare l'acquisizione, oltre ai dettagli delle notifiche richieste.

Rappresentazione JSON 
{
  "mandateId": string,
  "upcomingTransactionNotificationId": string
}
Campi
mandateId

string

OBBLIGATORIO: l'ID mandato generato da Google, inviato durante la chiamata createMandate.
upcomingTransactionNotificationId

string

OBBLIGATORIO: il numero requestId della chiamata upcomingTransactionNotification, che è stata effettuata per pre-inviare la notifica della transazione.

CaptureContext

Questo oggetto fornisce il contesto di come è stata richiesta l'acquisizione.

Rappresentazione JSON 
{
  "userIpAddress": string
}
Campi
userIpAddress

string

FACOLTATIVO: si tratta dell'indirizzo IP del dispositivo dell'utente se l'acquisto è stato effettuato da un utente nella sessione. Se l'utente non era presente nella sessione, questo campo vuoto. Se il contratto non prevede la necessità di questo campo, questo campo sarà sempre vuoto.

CaptureResultCode

Codici risultato per l'acquisizione.

Enum
UNKNOWN_RESULT Non impostare mai questo valore predefinito.
SUCCESS Acquisizione riuscita, consegna i prodotti.
CHARGE_EXCEEDS_TRANSACTION_LIMIT Il valore di amount di questa richiesta di acquisizione supera il limite per transazione. Se questo codice viene utilizzato, compila il campo transactionLimit per i messaggi per gli utenti.
CHARGE_EXCEEDS_DAILY_LIMIT Al momento questo account non può essere utilizzato per acquisti perché ha superato i limiti giornalieri.
CHARGE_EXCEEDS_MONTHLY_LIMIT Al momento questo account non può essere utilizzato per gli acquisti perché ha superato i limiti mensili.
CHARGE_UNDER_LIMIT Il valore di amount di questa richiesta di acquisizione non soddisfa l'importo minimo della transazione.
INSUFFICIENT_FUNDS Questo account non dispone di fondi sufficienti per garantire l'acquisizione.
ACCOUNT_DOES_NOT_SUPPORT_CURRENCY Questo account non supporta la valuta richiesta.
ACCOUNT_CLOSED

L'account dell'utente mantenuto presso l'integratore è stato chiuso.

Se restituisci questo valore, lo strumento dell'utente verrà chiuso con Google. L'utente dovrà aggiungere un nuovo strumento ripetendo la procedura di associazione.
ACCOUNT_CLOSED_ACCOUNT_TAKEN_OVER

L'account dell'utente con l'integratore è stato chiuso, sospetta violazione dell'account.

Se restituisci questo valore, lo strumento dell'utente verrà chiuso con Google. L'utente dovrà aggiungere un nuovo strumento ripetendo la procedura di associazione.
ACCOUNT_ON_HOLD L'account è sospeso.
ACCOUNT_CLOSED_FRAUD

L'account dell'utente mantenuto presso l'integratore è stato chiuso a causa di attività fraudolenta.

Se restituisci questo valore, lo strumento dell'utente verrà chiuso con Google. L'utente dovrà aggiungere un nuovo strumento ripetendo la procedura di associazione.
GOOGLE_PAYMENT_TOKEN_INVALIDATED_BY_USER

L'account è attivo, ma il GPT è stato invalidato dall'utente dal lato dell'integratore.

Se restituisci questo valore, lo strumento dell'utente verrà chiuso con Google. L'utente dovrà aggiungere un nuovo strumento ripetendo la procedura di associazione.
TOKEN_REFRESH_REQUIRED Per restituirlo, l'utente dovrà eseguire un flusso di aggiornamento.
OTP_NOT_MATCHED La OTP non corrisponde a ciò che ha inviato l'integratore.
OTP_ALREADY_USED OTP già utilizzata.
RISK_DECLINED

La transazione è stata rifiutata a causa di un controllo del rischio da parte dell'integratore.

Si tratta di un errore permanente di questo pagamento, ma non comporta la chiusura dello strumento dell'utente presso Google.
NO_GOOD_FUNDING_SOURCE_AVAILABLE Nel suo account non è configurata alcuna fonte di pagamento funzionante in grado di pagare la transazione.
FUNDING_SOURCE_UNAVAILABLE

L'emittente sottostante o la fonte di fondi non sono disponibili. Se si ritenta l'operazione, l'istituto di pagamento non andrà a buon fine.

Google riproverà i pagamenti quando un partner restituisce un codice di risposta 4xx o 5xx. Per questo motivo, i partner in genere devono restituire uno di questi codici di risposta se un nuovo tentativo di pagamento può avere esito positivo quando la fonte di fondi sottostante torna disponibile. Tuttavia, se sussistono motivi tecnici per cui un nuovo tentativo di pagamento da parte di Google non andrà a buon fine, il partner può restituire il messaggio "FUNDING_SOURCE_UNAVAILABLE" per comunicare a Google che non deve ritentare lo stesso pagamento.

Nota: Google potrebbe comunque riprovare a eseguire questo pagamento, ma solo con un ID richiesta diverso, ma la richiesta di pagamento verrà contrassegnata come Rifiutata.
MANDATE_NOT_ACTIVE Il mandato utilizzato per questa acquisizione non è più attivo. Questo valore restituito comporterà la chiusura dello strumento di autorizzazione dell'utente con Google.
UPCOMING_TRANSACTION_NOTIFICATION_EXPIRED La notifica che è stata inviata all'utente per un pagamento ricorrente del mandato è scaduta.