Method: capture

Inicia a movimentação 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 dele precisará ser do tipo ErrorResponse.

Um exemplo de solicitação é semelhante a este:


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

Veja um exemplo de resposta:


{
  "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 à transação.
transactionDescription

string

OBRIGATÓRIO: é a descrição da transação que pode ser incluída na fatura do cliente. Localizado para a userLocale encontrada no requestHeader. Esse formato pode ser alterado sem aviso prévio e nunca pode 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: o contexto da captura.
Campo de união fopDetails. OBRIGATÓRIO: detalhes da FOP para esta 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 é necessário usar uma upcomingTransactionNotification.

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 ele não estiver presente, nenhuma autenticação poderá ser vinculada a essa captura.

Se esse atributo estiver presente, significa que o usuário foi autenticado imediatamente antes dessa chamada ou quando um calendário de pagamentos automatizado foi configurado.
otpVerification

object (OtpVerification)

OPCIONAL: dados necessários para verificar uma OTP gerada por sendOtp. Isso 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, esse identificador é incluído nos detalhes da remessa.
userMessage
(deprecated)

string

DESCONTINUADO: uma descrição do resultado que será mostrada ao usuário se o resultado não for SUCCESS.
result

enum (CaptureResultCode)

OBRIGATÓRIO: resultado da captura.
rawResult

object (RawResult)

OPCIONAL: resultado bruto dessa 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 optar por 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 recebido da rede VISA. Nesse caso, o valor de scope seria "visto". 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 pode gastar em uma transação (em micros). Isso é usado para análise de taxa de recusa e mensagens estruturadas voltadas ao usuário.

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). É usada para mensagens estruturadas e voltadas para o usuário.

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

MandateDetails

Detalhes sobre a autorização de captura.

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

string

OBRIGATÓRIO: o ID de autorização gerado pelo Google e enviado durante a chamada createMandate.

MandateWithNotificationDetails

Detalhes sobre a autorização de captura, além dos detalhes de notificações necessários.

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

string

OBRIGATÓRIO: o ID de autorização gerado pelo Google e enviado durante a chamada createMandate.
upcomingTransactionNotificationId

string

OBRIGATÓRIO: o requestId da chamada de upcomingTransactionNotification, feita para notificar previamente 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 estava na sessão, este campo ficará vazio. Se o contrato específico não estipular a necessidade desse campo, ele sempre ficará em branco.

CaptureResultCode

Códigos de resultados para captura.

Enums
UNKNOWN_RESULT Nunca defina esse valor padrão.
SUCCESS Captura bem-sucedida, entregue os produtos.
CHARGE_EXCEEDS_TRANSACTION_LIMIT O amount dessa solicitação de captura excede o limite por transação. Se esse código for usado, preencha o campo transactionLimit para fins de mensagens do usuário.
CHARGE_EXCEEDS_DAILY_LIMIT No momento, esta conta não pode ser usada para compras porque excedeu os limites diários.
CHARGE_EXCEEDS_MONTHLY_LIMIT No momento, esta conta não pode ser usada para compras porque excedeu os limites mensais.
CHARGE_UNDER_LIMIT O amount dessa solicitação de captura não atende ao 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 no 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 há suspeita de que a conta esteja assumida.

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 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 esse valor, o usuário precisa passar por um fluxo de atualização.
OTP_NOT_MATCHED A OTP não correspondeu 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 feita pelo integrador.

Essa é uma falha permanente para este 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 capaz de pagar pela transação.
FUNDING_SOURCE_UNAVAILABLE

O emissor ou a fonte de fundos subjacente não está disponível, e não vai ser possível tentar de novo com esse pagamento.

O Google repetirá os pagamentos quando um código de resposta 4xx ou 5xx for retornado por um parceiro. Por isso, os parceiros normalmente retornam um desses códigos de resposta quando uma nova tentativa do mesmo pagamento é bem-sucedida quando a fonte de fundos subjacente está disponível novamente. No entanto, se houver motivos técnicos em que o Google vai continuar falhando o pagamento, o parceiro poderá retornar "FUNDING_SOURCE_UNAVAILABLE" como forma de dizer ao Google que ele não deve repetir esse mesmo pagamento.

Observação: o Google ainda poderá tentar esse pagamento novamente, mas com um requestId diferente, mas essa 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 no Google.
UPCOMING_TRANSACTION_NOTIFICATION_EXPIRED A notificação enviada ao usuário referente a um pagamento de autorização recorrente expirou.