Method: capture

Inicia o movimento de dinheiro entre a conta de um cliente mantida no Google e o processador de pagamentos. A combinação de requestId no cabeçalho e paymentIntegratorAccountId é a chave de idempotência e identifica essa transação de maneira exclusiva. Todas as mutações nesta transação (reembolsos) preenchem o valor requestId no campo captureRequestId.

Se o endpoint encontrar um erro ao processar a solicitação, o corpo da resposta desse endpoint precisará ser do tipo ErrorResponse.

Este é um exemplo de solicitação:


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

Um exemplo de resposta é semelhante a:


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

Solicitação HTTP

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

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação 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.
}
Campos
requestHeader

object (RequestHeader)

OBRIGATÓRIO: cabeçalho comum para todas as solicitações.
paymentIntegratorAccountId

string

OBRIGATÓRIO: é o identificador da conta do integrador de pagamentos que identifica as restrições contratuais relacionadas a essa transação.
transactionDescription

string

OBRIGATÓRIO: a descrição da transação que pode ser incluída no extrato do cliente. Localizado para o userLocale encontrado no requestHeader. Esse formato pode ser mudado sem aviso prévio e nunca deve ser analisado.
currencyCode

string

OBRIGATÓRIO: código de moeda ISO 4217 de três letras
amount

string (Int64Value format)

OBRIGATÓRIO: o valor da compra em micros da unidade monetária.
captureContext

object (CaptureContext)

OBRIGATÓRIO: contexto sobre a captura.
Campo de união fopDetails. OBRIGATÓRIO: detalhes da FOP para essa transação de captura. fopDetails pode ser apenas de um dos tipos a seguir:
googlePaymentToken

string

Token que as duas empresas usarão para identificar a conta para compras entre si.
mandateDetails

object (MandateDetails)

Detalhes de pagamento específicos das autorizações.
mandateWithNotificationDetails

object (MandateWithNotificationDetails)

Detalhes de pagamento específicos para autorizações, em que um upcomingTransactionNotification é necessário.

Campo de união account_verification.

account_verification pode ser apenas de um dos tipos a seguir:
authenticationRequestId

string

OPCIONAL: requestId da solicitação de autenticação associada. Se esse atributo não estiver presente, nenhuma autenticação poderá ser vinculada a essa captura.

Se estiver presente, o usuário foi autenticado imediatamente antes desta chamada ou quando um calendário de pagamentos automático foi configurado.
otpVerification

object (OtpVerification)

OPCIONAL: dados necessários para verificar uma OTP gerada por sendOtp. Só estará presente se o usuário tiver passado pelo caminho sendOtp.

Corpo da resposta

Objeto de resposta para o método de captura.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação JSON 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "paymentIntegratorTransactionId": string,
  "userMessage": string,
  "result": enum (CaptureResultCode),
  "rawResult": {
    object (RawResult)
  },
  "transactionLimit": string,
  "currentBalance": string
}
Campos
responseHeader

object (ResponseHeader)

OBRIGATÓRIO: cabeçalho comum para todas as respostas.
paymentIntegratorTransactionId

string

OPCIONAL: esse identificador é específico para o integrador e gerado por ele. O integrador conhece essa transação pelo identificador.

Para facilitar, este identificador está incluído nos detalhes da remessa
userMessage
(deprecated)

string

OBSOLETO: uma descrição do resultado a ser exibida ao usuário se o resultado não for SUCCESS.
result

enum (CaptureResultCode)

REQUIRED: resultado da captura.
rawResult

object (RawResult)

OPTIONAL: resultado bruto da captura. Usado para ajudar a informar o mecanismo de risco e as análises do Google. Em situações de recusa de mapeamento de código, os dados às vezes são perdidos. O integrador pode fornecer um código bruto ao Google. Por exemplo, um gateway de cartão de crédito (o integrador) pode usar esse campo para comunicar ao Google o código de recusa exato que foi recebido da rede VISA. Nesse caso, scope seria "visa" e rawCode seria o que a rede VISA retornasse.

Esse valor será obrigatório se result não for SUCCESS.
transactionLimit

string (Int64Value format)

OPCIONAL: se o Resultado for CHARGE_EXCEEDS_TRANSACTION_LIMIT, esse será o valor máximo que o usuário poderá gastar em uma transação (em micros). Isso é usado para mensagens estruturadas voltadas ao usuário e análise da taxa de recusa.

Precisa ser um limite relativo ao currencyCode na solicitação.
currentBalance

string (Int64Value format)

OPCIONAL: se o Resultado for INSUFFICIENT_FUNDS, esse será o saldo atual disponível na conta do usuário (em micros). Isso é usado em mensagens estruturadas voltadas para o usuário.

Esse valor precisa estar na mesma moeda que currencyCode na solicitação.

MandateDetails

Detalhes sobre a autorização da qual fazer a captura.

Representação JSON 
{
  "mandateId": string
}
Campos
mandateId

string

OBRIGATÓRIO: o ID da autorização gerado pelo Google que foi enviado durante a chamada createMandate.

MandateWithNotificationDetails

Detalhes sobre a autorização da captura, além dos detalhes obrigatórios das notificações.

Representação JSON 
{
  "mandateId": string,
  "upcomingTransactionNotificationId": string
}
Campos
mandateId

string

OBRIGATÓRIO: o ID da autorização gerado pelo Google que foi enviado durante a chamada createMandate.
upcomingTransactionNotificationId

string

OBRIGATÓRIO: o requestId da chamada de upcomingTransactionNotification que foi feita para receber uma notificação prévia sobre essa transação.

CaptureContext

Esse objeto fornece contexto sobre como a captura foi solicitada.

Representação JSON 
{
  "userIpAddress": string
}
Campos
userIpAddress

string

OPCIONAL: é o endereço IP do dispositivo do usuário se a compra tiver sido feita por um usuário na sessão. Se o usuário não estiver em sessão, esse item ficará vazio. Se o contrato específico não determinar a necessidade desse campo, ele estará sempre em branco.

CaptureResultCode

Códigos de resultado da captura.

Enums
UNKNOWN_RESULT Nunca defina esse valor padrão.
SUCCESS Capturar bem, entregar os produtos.
CHARGE_EXCEEDS_TRANSACTION_LIMIT O amount desta solicitação de captura excede o limite por transação. Se esse código for usado, preencha o campo transactionLimit para enviar mensagens ao usuário.
CHARGE_EXCEEDS_DAILY_LIMIT Esta conta não pode ser usada para compras no momento porque excedeu os limites diários.
CHARGE_EXCEEDS_MONTHLY_LIMIT Esta conta não pode ser usada para compras no momento porque excedeu os limites mensais.
CHARGE_UNDER_LIMIT O amount dessa solicitação de captura não atinge o valor mínimo da transação.
INSUFFICIENT_FUNDS Esta conta não tem fundos suficientes para garantir esta captura.
ACCOUNT_DOES_NOT_SUPPORT_CURRENCY Esta conta não é compatível com a moeda solicitada.
ACCOUNT_CLOSED

A conta do usuário mantida com o integrador foi encerrada.

Se esse valor for retornado, o instrumento do usuário será fechado com o Google. O usuário será forçado a adicionar um novo instrumento passando pelo fluxo de associação novamente.
ACCOUNT_CLOSED_ACCOUNT_TAKEN_OVER

A conta do usuário com o integrador foi encerrada, e a conta é suspeita.

Se esse valor for retornado, o instrumento do usuário será fechado com o Google. O usuário será forçado a adicionar um novo instrumento passando pelo fluxo de associação novamente.
ACCOUNT_ON_HOLD A conta está em espera.
ACCOUNT_CLOSED_FRAUD

A conta do usuário mantida no integrador foi encerrada devido a uma fraude.

Se esse valor for retornado, o instrumento do usuário será fechado com o Google. O usuário será forçado a adicionar um novo instrumento passando pelo fluxo de associação novamente.
GOOGLE_PAYMENT_TOKEN_INVALIDATED_BY_USER

A conta está ativa, mas a GPT foi invalidada pelo usuário no lado do integrador.

Se esse valor for retornado, o instrumento do usuário será fechado com o Google. O usuário será forçado a adicionar um novo instrumento passando pelo fluxo de associação novamente.
TOKEN_REFRESH_REQUIRED Para retornar isso, o usuário precisa passar por um fluxo de atualização.
OTP_NOT_MATCHED A OTP não corresponde ao que o integrador enviou.
OTP_ALREADY_USED A OTP já foi usada.
RISK_DECLINED

A transação foi recusada devido a uma verificação de risco do integrador.

Essa é uma falha permanente para esse pagamento, mas não faz com que o instrumento do usuário seja encerrado no Google.
NO_GOOD_FUNDING_SOURCE_AVAILABLE O usuário não tem nenhuma fonte de financiamento ativa configurada na conta para pagar a transação.
FUNDING_SOURCE_UNAVAILABLE

O emissor ou a origem dos fundos não está disponível, e uma nova tentativa de pagamento não terá êxito.

O Google vai tentar realizar os pagamentos novamente quando um código de resposta 4xx ou 5xx for retornado por um parceiro. Por isso, os parceiros normalmente devem retornar um desses códigos de resposta se uma nova tentativa do mesmo pagamento for bem-sucedida quando a fonte de fundos subjacente estiver disponível novamente. No entanto, se houver motivos técnicos que impeçam o pagamento de uma nova tentativa de pagamento, o parceiro pode retornar "FUNDING_SOURCE_UNAVAILABLE" para informar ao Google que ele não deve repetir o pagamento.

Observação: o Google ainda pode tentar realizar o pagamento de novo, mas com um requestId diferente, mas a solicitação de pagamento será marcada como "Recusada".
MANDATE_NOT_ACTIVE A autorização usada para esta captura não está mais ativa. Esse valor de retorno fará com que o instrumento de autorização do usuário seja encerrado com o Google.
UPCOMING_TRANSACTION_NOTIFICATION_EXPIRED A notificação enviada ao usuário para um pagamento de autorização recorrente expirou.