PCI/Charge/Authenticate (PCI)
Integração do modo especialista
Documentação de referência, para ver como integrá-la, está aqui: Serviço de autenticação de portador (modo especialista)
Configurações de entrada
amount
Valor da transação para autenticar. O valor deve ser um inteiro positivo, apresentado na menor unidade monetária da moeda.
Exemplo: 30050 para 300,50 EUR.
Formato
currency
Moeda da transação para autenticar. Código alfabético em maiúscula conforme a norma ISO 4217 (ex: “EUR” para o euro ).
Formato
transactionCategory
Categoria da transação. Terá geralmente o valor de PAYMENT, para um pagamento clássico.
Valores possíveis
| valores | Descrição |
|---|---|
| ADD_CARD | Adição de um cartão em um wallet. |
| PAYMENT | Pagamento clássico (inclui os pagamentos recorrentes ou em x-vezes). |
Formato
productType
Tipo de produto concernido pela transação.
Valores possíveis
| valores | Descrição |
|---|---|
| ACCOUNT_FUNDING | Transferência para uma conta |
| CHECK_ACCEPTANCE | Verificação de aceitação |
| GOODS_OR_SERVICE_PURCHASE | Compra de bem ou de serviço. Valor usado se o campo não foi enviado na solicitação. |
| PREPAID_ACTIVATION_AND_LOAD | Ativação e carregamento de um cartão pré-pago |
| QUASI_CASH_TRANSACTION | Transação em quase-dinheiro (ex: vale férias, bilhete de loteria, etc.) |
Formato
merchant.name
Nome do Estabelecimento Comercial.
Formato
merchant.mid
Número de contrato Estabelecimento Comercial.
Formato
merchant.tid
Terminal ID. Código da loja definida na afiliação de aprovação.
Este campo é somente usado na Colômbia para escolher entre REDEBAN e CREDIBANCO .
Formato
merchant.mcc
Código específico do DS emissor que descreve o tipo de atividade, produto ou serviço do estabelecimento comercial. (Código de categoria do comerciante = MCC)
Formato
networkPreference
Caminho: paymentForm.networkPreference
Nome da rede preferencial recomendada pelo EC.
Valores possíveis
| VALOR | Descrição |
|---|---|
| AMEX | Rede American Express (Safekey) |
| CB | Rede Cartão |
| MASTERCARD | Bandeira Mastercard |
| VISA | Rede Visa |
| ELO | Rede Elo (Brasil) |
| DINERS | Rede Diners |
| DISCOVER | Rede Discover |
| OSB | Rede OSB |
Formato
accountType
Caminho: paymentForm.accountType
Tipo de cartão. Este campo é obrigatório no Brasil
Valores possíveis
| valores | Descrição |
|---|---|
| DEBIT | Cartão de débito |
| CREDIT | Cartão de crédito |
Formato
paymentForm.pan
O PAN (Primary Account Number) é o número principal do cartão geralmente formado de 16 números).
Formato
expiryMonth
Caminho: paymentForm.expiryMonth
Mês de vencimento com 2 dígitos. Exemplo: "09" para setembro.
Formato
expiryYear
Caminho: paymentForm.expiryYear
Ano de vencimento com 2 dígitos. Exemplo: "25" para 2025.
Formato
cardHolderName
Caminho: paymentForm.cardHolderName
Sobrenome e nome do portador do cartão
Formato
installmentNumber
Caminho: paymentForm.installmentNumber
Quantidade de parcelas.
Formato
customer.reference
Código de identificação do comprado para o Estabelecimento Comercial.
Formato
customer.email
Endereço e-mail do comprador.
- Especificações de estrutura de e-mail: RFC-2822
Formato
address
Caminho: customer.billingDetails.address
Endereço de faturamento.
Advertência: Os símbolos > e < não são autorizados.
Formato
address2
Caminho: customer.billingDetails.address2
Informações complementares sobre o endereço de faturamento.
Advertência: Os símbolos > e < não são autorizados.
Formato
category
Caminho: customer.billingDetails.category
Tipo de cliente.
Formato
Valores possíveis
| valores | Descrição |
|---|---|
| PRIVATE | Cliente de tipo Pessoa física |
| COMPANY | Cliente de tipo Pessoa Jurídica |
cellPhoneNumber
Caminho: customer.billingDetails.cellPhoneNumber
Telefone mobile do comprador.
Aceita todos os formatos:
Exemplos:
0623456789 +33623456789 0033623456789 (+34) 824 65 43 21 87 77 12 34
Formato
city
Caminho: customer.billingDetails.city
Cidade de faturamento.
Formato
country
Caminho: customer.billingDetails.country
País do comprador (em maiúscula, conforme à norma ISO 3166-1 alfa-2).
Formato
Valores possíveis
Exemplos de valores possíveis:
| País | Código |
|---|---|
| ÁUSTRIA | AT |
| Brasil | BR |
| CORSEGA | FR |
| COSTA DO MARFIM | CI |
| FRANÇA | FR |
| GUADALUPE | GP |
| ÍNDIA | IN |
| MARTINICA | MQ |
| NOVA-CALEDONIA | NC |
| ST-PIERRE-ET-MIQUELON | PM |
| POLINÉSIA FRANCESA | PF |
district
Caminho: customer.billingDetails.district
Bairro do endereço de faturamento.
Formato
firstName
Caminho: customer.billingDetails.firstName
Nome do comprador.
Formato
identityCode
Caminho: customer.billingDetails.identityCode
CPF/CNPJ. Possibilita identificar de maneira única cada cidadão dentro de um país.
Formato
identityType
Caminho: customer.billingDetails.identityType
Tipo de documento de identidade.
Formato
language
Caminho: customer.billingDetails.language
Código do idioma do comprador, conforme a norma ISO 639-1.
Permite especificar o idioma de envio dos e-mails de confirmação de pagamento.
Formato
Valores possíveis
Exemplos de valores possíveis:
| Idioma | Código |
|---|---|
| Alemão (Alemanha) | DE |
| Inglês (Reino-Unido) | EN |
| Inglês (Estados-Unidos) | EN |
| Chinês (Tradicional) | ZH |
| Espanhol (Espanha) | ES |
| Espanhol (Chile) | ES |
| Francês (França) | FR |
| Italiano (Itália) | IT |
| Japonês (Japão) | JP |
| Holandês (Holanda) | NL |
| Polonês (Polônia) | PL |
| Português (Brasil) | PT |
| Português (Portugal) | PT |
| Russo (Rússia) | RU |
lastName
Caminho: customer.billingDetails.lastName
Sobrenome do comprador.
Formato
legalName
Caminho: customer.billingDetails.legalName
Razão social.
Formato
phoneNumber
Caminho: customer.billingDetails.phoneNumber
Número de telefone do comprador.
Aceita todos os formatos:
Exemplos:
0123456789 +33123456789 0033123456789 - (00.571) 638.14.00
40 41 42 42
Formato
state
Caminho: customer.billingDetails.state
Região (estado) do endereço de faturamento. Recomendado mas não obrigatório passar o valor em ISO-3166-2.
Formato
streetNumber
Caminho: customer.billingDetails.streetNumber
Número de rua do endereço de faturamento.
Carateres aceites:
- Caracteres alfabéticos (de "A" a "Z" e de "a" a "z")
- Espaço
Formato
title
Caminho: customer.billingDetails.title
Estado civil do comprador.
Exemplos:
- Sr.
- Sr.
- Sra.
Formato
zipCode
Caminho: customer.billingDetails.zipCode
CEP do endereço de faturamento.
Formato
address
Caminho: customer.shippingDetails.address
Endereço de entrega.
Advertência: Os símbolos > e < não são autorizados.
Formato
address2
Caminho: customer.shippingDetails.address2
Segunda linha do endereço de entrega.
Advertência: Os símbolos > e < não são autorizados.
Formato
category
Caminho: customer.shippingDetails.category
Tipo de cliente.
Formato
Valores possíveis
| valores | Descrição |
|---|---|
| PRIVATE | Cliente de tipo Pessoa física |
| COMPANY | Cliente de tipo Pessoa Jurídica |
city
Caminho: customer.shippingDetails.city
Cidade de entrega.
Formato
country
Caminho: customer.shippingDetails.country
País de entrega (em maiúscula, conforme a norma ISO 3166-1 alfa-2).
Formato
Valores possíveis
Exemplos de valores possíveis:
| País | Código |
|---|---|
| ÁUSTRIA | AT |
| Brasil | BR |
| CORSEGA | FR |
| COSTA DO MARFIM | CI |
| FRANÇA | FR |
| GUADALUPE | GP |
| ÍNDIA | IN |
| MARTINICA | MQ |
| NOVA-CALEDONIA | NC |
| ST-PIERRE-ET-MIQUELON | PM |
| POLINÉSIA FRANCESA | PF |
deliveryCompanyName
Caminho: customer.shippingDetails.deliveryCompanyName
Nome da empresa que entrega o produto.
Formato
district
Caminho: customer.shippingDetails.district
Bairro do endereço de faturamento.
Formato
firstName
Caminho: customer.shippingDetails.firstName
Nome do destinatário.
Formato
identityCode
Caminho: customer.shippingDetails.identityCode
CPF/CNPJ. Possibilita identificar de maneira única cada cidadão dentro de um país.
Formato
lastName
Caminho: customer.shippingDetails.lastName
Sobrenome do comprador.
Formato
legalName
Caminho: customer.shippingDetails.legalName
Razão social para uma entrega em uma empresa.
Formato
phoneNumber
Caminho: customer.shippingDetails.phoneNumber
Número de telefone do comprador.
Aceita todos os formatos:
Exemplos:
0123456789 +33123456789 0033123456789 - (00.571) 638.14.00
40 41 42 42
Formato
shippingMethod
Caminho: customer.shippingDetails.shippingMethod
Modo de entrega.
Formato
Valores possíveis
| VALOR | Descrição |
|---|---|
| RECLAIM_IN_SHOP | Retirada de mercadoria na loja. |
| RELAY_POINT | Utilização de uma rede de pontos de entrega terceirizados (Kiala, Alveol, etc). |
| RECLAIM_IN_STATION | Retirada em um aeroporto, uma agência de viagens ou outros. |
| PACKAGE_DELIVERY_COMPANY | Entrega por transportadora (Colissimo, UPS, etc). |
| ETICKET | Emissão de uma passagem eletrônica, download de produtos virtuais. |
| CARD_HOLDER_ADDRESS | Entrega no endereço do comprador. Reservado para um uso futuro. |
| VERIFIED_ADDRESS | Entrega em um endereço verificado. Reservado para um uso futuro. |
| NOT_VERIFIED_ADDRESS | Entrega em um endereço não verificado. Reservado para um uso futuro. |
| SHIP_TO_STORE | Entrega na loja. Reservado para um uso futuro. |
| DIGITAL_GOOD | Entrega digital. Reservado para um uso futuro. |
| ETRAVEL_OR_ETICKET | Passagem eletrônica. Reservado para um uso futuro. |
| OTHER | Outros Reservado para um uso futuro. |
| PICKUP_POINT | Entrega em ponto de retirada. Reservado para um uso futuro. |
| AUTOMATED_PICKUP_POINT | Entrega em ponto de retirada automático. Reservado para um uso futuro. |
shippingSpeed
Caminho: customer.shippingDetails.shippingSpeed
Prazo de entrega.
Formato
Valores possíveis
Exemplos de valores possíveis:
| VALOR | Descrição |
|---|---|
| STANDARD | Entrega padrão. |
| EXPRESS | Entrega em menos de 24h. |
| PRIORITY | Entrega prioritária (Click & Collect) |
state
Caminho: customer.shippingDetails.state
Região do endereço de faturamento.
Formato
streetNumber
Caminho: customer.shippingDetails.streetNumber
Número de rua do endereço de entrega.
Carateres aceites:
- Caracteres alfabéticos (de "A" a "Z" e de "a" a "z")
- Espaço
Formato
zipCode
Caminho: customer.shippingDetails.zipCode
CEP do endereço de faturamento.
Formato
insuranceAmount
Caminho: customer.shoppingCart.insuranceAmount
Valor do seguro para a totalidade do pedido expresso na sua menor unidade monetária (o centavo para o Euro).
Exemplo: 30050 para 300,50 EUR.
Formato
shippingAmount
Caminho: customer.shoppingCart.shippingAmount
Montante do frete para o total do pedido, na menor unidade monetária da moeda (o centavo para o Real). Ex: 1234 para 12,34 BRL.
Exemplo: 30050 para 300,50 EUR.
Formato
taxAmount
Caminho: customer.shoppingCart.taxAmount
Valor dos impostos para a totalidade do pedido expresso na sua menor unidade monetária (o centavo para o Euro).
Exemplo: 30050 para 300,50 EUR.
Formato
cartItemInfo
Caminho: customer.shoppingCart.cartItemInfo
cardItemInfo é uma lista de objetos Customer/ShoppingCartItemInfo.
Permite descrever cada artigo do carrinho.
Formato
productAmount
Caminho: customer.shoppingCart.cartItemInfo.productAmount
Valor do produto expresso na sua menor unidade monetária (o centavo para o Euro).
Exemplo: 30050 para 300,50 EUR.
Formato
productLabel
Caminho: customer.shoppingCart.cartItemInfo.productLabel
Nome do produto.
Formato
productQty
Caminho: customer.shoppingCart.cartItemInfo.productQty
Quantidade de produto.
Formato
productRef
Caminho: customer.shoppingCart.cartItemInfo.productRef
Referência produto.
Formato
productType
Caminho: customer.shoppingCart.cartItemInfo.productType
Tipo de produto.
Valores possíveis
| VALOR | Descrição |
|---|---|
| FOOD_AND_GROCERY | Produtos alimentares e de mercadinho |
| AUTOMOTIVE | Automóvel / Moto |
| ENTERTAINMENT | Lazer / Cultura |
| HOME_AND_GARDEN | Casa e jardim |
| HOME_APPLIANCE | Equipamentos para a casa |
| AUCTION_AND_GROUP_BUYING | Leilões e compras em grupo |
| FLOWERS_AND_GIFTS | Flores e presentes |
| COMPUTER_AND_SOFTWARE | Computadores e softwares |
| HEALTH_AND_BEAUTY | Saúde e beleza |
| SERVICE_FOR_INDIVIDUAL | Serviços para pessoa física |
| SERVICE_FOR_BUSINESS | Serviços para pessoa jurídica |
| SPORTS | Esportes |
| CLOTHING_AND_ACCESSORIES | Roupas e acessórios |
| TRAVEL | Viagem |
| HOME_AUDIO_PHOTO_VIDEO | Som, imagem e vídeo |
| TELEPHONY | Telefonia |
Formato
productVat
Caminho: customer.shoppingCart.cartItemInfo.productVat
Tipo de produto.
Valor do imposto sobre o produto (apresentado na menor unidade da moeda).
Valores possíveis
| VALOR | Descrição |
|---|---|
| Um número inteiro | Valor da transação. O valor dela deve ser um número inteiro positivo (ex: 1234 para 12,34 EUR). |
| Um número decimal, inferior a 100 | Percentagem aplicada sobre o valor. Exemplos: 20.0 ou 19.6532 |
Para mencionar uma percentagem aplicada sobre o valor do produto em questão, o valor deve ter no máximo 4 dígitos após a virgula. A decimal é obrigatória para mencionar uma percentagem. A decimal é marcada pelo símbolo ".".
Formato
device.deviceType
Tipo de dispositivo nos quais a autenticação é realizada.
Valores possíveis
| VALOR | Descrição |
|---|---|
| BROWSER | a autenticação ocorre em um navegador |
Formato
device.acceptHeader
Conteúdo exato do header HTTP accept como foi enviado pelo navegador do cliente.
Formato
device.userAgent
Conteúdo exato do cabeçalho HTTP "user-agent" enviado pelo navegador. Deve ser truncado se o valor ultrapassa 2048 dígitos.
Obtida do navegador cliente via a propriedade “navigator.userAgent”.
Código javascript que permite recuperar o valor:
const language = navigator.userAgent;
Formato
device.ip
Endereço IP do navegador como foi enviado nos cabeçalhos HTTP pelo cliente. Formato IPV4 (ex: 1.12.123.255) ou IPV6 (ex: 2011:0db8:85a3:0101:0101:8a2e:0370:7334). Comprimento variável até 45 dígitos.
Formato
device.javaEnabled
Boolean que representa a capacidade do navegador para executar Java. O valor corresponde ao valor retornado pela função “navigator.javaEnabled()” e pode ser true ou false.
Código javascript que permite recuperar o valor:
const javaEnabled = navigator.javaEnabled();
Formato
device.language
Obtida do navegador cliente via a propriedade “navigator.language”.
Exemplos: “en”, “en-US”, “de”, “fr”, etc.
Código javascript que permite recuperar o valor:
const language = navigator.language;
Formato
device.colorDepth
Valor representando a escala da paleta de cores usada para exibir as imagens, em bits por pixel.
Obtida do navegador cliente via a propriedade “screen.colorDepth”.
Código javascript que permite recuperar o valor:
const colorDepth = screen.colorDepth;
Formato
device.screenHeight
A altura total da tela do cliente em pixeis. O valor é aquele que foi retornado pela propriedade “screen.height”. De 1 a 6 dígitos.
Código javascript que permite recuperar o valor:
const screenHeight = screen.height;
Formato
device.screenWidth
A largura total da tela do cliente em pixeis. O valor é aquele que foi retornado pela propriedade “screen.width”. De 1 a 6 dígitos.
Código javascript que permite recuperar o valor:
const screenWidth = screen.width;
Formato
timeZoneOffset
Caminho: device.timeZoneOffset
Diferença de tempo entre a hora UTC e a hora local do navegador cliente, em minutos. Seu valor é de -120 para um usuário no fuso horário UTC+2 e de 570 para o fuso horário UTC−09:30.
Código javascript que permite recuperar o valor:
const timeZoneOffset = new Date().getTimezoneOffset();
Formato
id
token único de autenticação, no formato UUID.
Null na primeira chamada.
Quando mais de uma chamada ao WebService PCI/Charge/Authenticate forem necessárias para realizar a autenticação de um comprador, o valor do ID enviado deverá ser o mesmo em toda chamada para a mesma autenticação Será então preciso retomar o ID fornecido na resposta anterior.
Formato
name
Caminho: instructionResult.name
Nome da instrução
Valores possíveis
| VALOR | Descrição |
|---|---|
| CHALLENGE | Instrução Challenge, que permite a autenticação interativa do usuário com o ACS |
| FINGERPRINT | Instrução Fingerprint, que permite identificar o usuário com o ACS |
Formato
value
Caminho: instructionResult.value
Resultado como uma string JWT ou um código de erro de texto simples em caso de erro (timeout por exemplo).
Formato
challengePreference
Caminho: instructionResult.protocol.challengePreference
Indica se o EC solicitou um challenge ou não.
Valores possíveis
| VALOR | Cartão 3DS2 | |
|---|---|---|
| NO_PREFERENCE | A escolha da preferência será delegada ao emissor do cartão. | |
| NO_CHALLENGE_REQUESTED | Permite solicitar uma autenticação sem interação (frictionless). | |
| CHALLENGE_REQUESTED | Permite solicitar uma autenticação forte para a transação. | |
| CHALLENGE_MANDATED | Permite indicar que uma autenticação forte é requerida para a transação por razões legais. | |
| DATA_ONLY | Permite solicitar uma autenticação sem interação, assumida pelo DS no lugar do ACS do banco emissor.A transação não se beneficiará com a transferência de responsabilidade. A autenticação será desativada se a rede não for compatível com esta funcionalidade. O serviço PCI/Charge/Authenticate retorna um código de erro INT_808, se o campotransactionCategorynão tem o valor dePAYMENT. |
Formato
name
Caminho: instructionResult.protocol.name
Nome do protocolo de autenticação do portador do cartão.
Valores possíveis
| VALOR | Descrição |
|---|---|
| THREEDS | Protocolo 3D Secure |
Formato
network
Caminho: instructionResult.protocol.network
Rede na qual o cartão foi autenticado.
Esse campo é obrigatório para gerenciar o timeout no 3ds method, quando o campo instructionResult.value é definido como TIMEOUT.
Redes atualmente suportadas
| VALOR |
|---|
| CB |
| VISA |
| MASTERCARD |
| AMEX_SAFEKEY |
| PROTECTBUY |
Formato
simulation
Caminho: instructionResult.protocol.simulation
Booleano que indica se a autenticação deve ser realizada em modo simulação. Se você valorizar este campo obrigatório como:
true, você ativa o modo simulação.false, você não ativa o modo simulação.
Este modo permite realizar a integração EC sem estar em produção ou usando cartões reais.
Formato
version
Caminho: instructionResult.protocol.version
Versão do protocolo de autenticação do portador do cartão.
Versões suportadas atualmente
| VALOR | Descrição |
|---|---|
| 1.0.2 | Versão 1.0.2 |
| 2.1.0 | Versão 2.1.0 |
| 2.2.0 | Versão 2.2.0 |
Formato
protocolRequest.name
Nome do protocolo de autenticação do portador do cartão.
Valores possíveis
| VALOR | Descrição |
|---|---|
| THREEDS | Protocolo 3D Secure |
Formato
version
Caminho: protocolRequest.version
Permite forçar a versão do protocolo de autenticação a ser usado.
Versões suportadas atualmente
| VALOR | Descrição |
|---|---|
| 2 |
Formato
challengePreference
Caminho: protocolRequest.challengePreference
Indica se o EC solicitou um challenge ou não.
Valores possíveis
| VALOR | Cartão 3DS2 | |
|---|---|---|
| NO_PREFERENCE | A escolha da preferência será delegada ao emissor do cartão. | |
| NO_CHALLENGE_REQUESTED | Permite solicitar uma autenticação sem interação (frictionless). | |
| CHALLENGE_REQUESTED | Permite solicitar uma autenticação forte para a transação. | |
| CHALLENGE_MANDATED | Permite indicar que uma autenticação forte é requerida para a transação por razões legais. | |
| DATA_ONLY | Permite solicitar uma autenticação sem interação, assumida pelo DS no lugar do ACS do banco emissor.A transação não se beneficiará com a transferência de responsabilidade. A autenticação será desativada se a rede não for compatível com esta funcionalidade. O serviço PCI/Charge/Authenticate retorna um código de erro INT_808, se o campotransactionCategorynão tem o valor dePAYMENT. |
Formato
recurring.expiryDate
Data de vencimento da recorrência. Exemplo: 24/12/2019
Formato
unit
Caminho: recurring.frequency.unit
Unidade de freqüência da recorrência
Valores possíveis
| valores | Descrição |
|---|---|
| DAY | Em dias |
| MONTH | Em meses |
| YEAR | Em anos |
Formato
value
Caminho: recurring.frequency.value
Valor da frequência da recorrência, apresentada em unidade de frequência. Exemplo: 12
Formato
Referência da resposta
Mais de uma resposta são possíveis em função do contexto:
| Resposta | Contexto |
|---|---|
| AuthenticationResponseData | Objeto contendo o resultado da autenticação |
Ver a referência de cada resposta para maiores detalhes.