O que é 3DS 2.0?

Para maiores detalhes sobre o 3DS 2.0, acesse: https://developercielo.github.io/manual/3ds

Passo 1 - Solicitação de Token de Acesso

A solução é composta pelo passo de solicitação de token de acesso via API e solicitação de autenticação a partir do APP.

Ambiente Endpoint Authorization
SANDBOX https://mpisandbox.braspag.com.br Basic (Authorization)
O valor do Authorization deve ser obtido concatenando-se o valor do “ClientID”, sinal de dois-pontos (“:”) e “ClientSecret”
Ex. dba3a8db-fa54-40e0-8bab-7bfb9b6f2e2e:D/ilRsfoqHlSUChwAMnlyKdDNd7FMsM7cU/vo02REag=
e na sequência, codificar o resultado na base 64.
Com isso, será gerado um código alphanumérico que será utilizado na requisição de access token. Para efeitos de teste, utilize os dados abaixo:
ClientID: dba3a8db-fa54-40e0-8bab-7bfb9b6f2e2e
ClientSecret: D/ilRsfoqHlSUChwAMnlyKdDNd7FMsM7cU/vo02REag=
PRODUÇÃO https://mpi.braspag.com.br Solicite os dados “ClientID” e “ClientSecret” à equipe de suporte após concluir o desenvolvimento em sandbox.

Request

{
  "EstablishmentCode": "1006993069",
  "MerchantName": "Loja Exemplo Ltda",
  "MCC": "5912"
}
Campo Descrição Tipo/Tamanho
EstablishmentCode Código do Estabelecimento do Cielo E-Commerce 3.0 Numérico [10 posições]
MerchantName Nome do estabelecimento registrado na Cielo Alfanumérico [até 25 posições]
MCC Código de Categoria do estabelecimento Numérico [4 posições]

Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfbmFtZSI6IlFBXzNEU19BdXRoZW50aWNhdG9yIiwiY2xpZW50X2lkIjoiZGJhM2E4ZGItZmE1NC00MGUwLThiYWItN2JmYjliNmYyZTJlIiwic2NvcGVzIjoie1wiU2NvcGVcIjpcIjNEU0F1dGhlbnRpY2F0b3JcIixcIkNsYWltc1wiOlt7XCJOYW1lXCI6XCJNZXJjaGFudE5hbWVcIixcIlZhbHVlc1wiOFwiVmFsdWVzXCI6W1wiNTU1NVwiXX0se1wiTmFtZVwiOlwiUmVmZXJlbmNlSWRcIixcIlZhbHVlc1wiOltcImY3MjE1YmQ3LWM0OTQtNGQ5Yi1NzEyfQ.daMqXko3dZOV0TzNFQ2vSsVSKqOsrwuswg7RB82ecAASSSSSSSSSSSSFFFFFFFFFFFFFGGGGGGGGGGGGGGGGGGGGGGGG",
  "token_type": "bearer",
  "expires_in": "2018-07-23T11:29:32"
}
Campo Descrição Tipo/Tamanho
access_token Token necessário para realizar a autenticação. Alfanumérico [tamanho variável]
token_type Fixo "bearer" Alfanumérico
expires_in Tempo em minutos para expirar o token Numérico

Passo 2 - Utilizando o SDK

Importar

Para utilizar o SDK é necessário adicioná-lo como dependência ao build.gradle do module que irá utilizá-lo:

dependecies {
  ...
  implementation 'br.com.braspag:braspag3ds:LATEST_VERSION'
}

Instanciar

Em seguida é necessário informar o ambiente que deseja ao instanciar o Braspag3ds:

  val braspag3dsSdk = Braspag3ds(Environment.SANDBOX)

Customizar

braspag3ds.customize(
  toolbarCustomization = CustomToolbar(
      backgroundColor = "#00c1eb",
      buttonText = "Cancel",
      headerText = "BRASPAG 3DS",
      textColor = "#ffffff",
      textFontName = "font/amaticsc.ttf",
      textFontSize = 16
  ),
  textBoxCustomization = CustomTextBox(
      borderColor = "#1f567d",
      borderWidth = 10,
      cornerRadius = 25,
      textColor = "#000000",
      textFontName = "font/amaticsc.ttf",
      textFontSize = 24
  ),
  labelCustomization = CustomLabel(
      headingTextColor = "#404040",
      headingTextFontName = "font/amaticsc.ttf",
      headingTextFontSize = 24,
      textColor = "#404040",
      textFontName = "font/amaticsc.ttf",
      textFontSize = 16
  ),
  buttons = listOf(
      CustomButton(
          textColor = "#ffffff",
          backgroundColor = "#5ea9d1",
          textFontName = "font/amaticsc.ttf",
          cornerRadius = 25,
          textFontSize = 16,
          type = ButtonType.VERIFY
      ),
      CustomButton(
          textColor = "#ffffff",
          backgroundColor = "#5ea9d1",
          textFontName = "font/amaticsc.ttf",
          cornerRadius = 25,
          textFontSize = 16,
          type = ButtonType.CONTINUE
      ),
      CustomButton(
          textColor = "#ffffff",
          backgroundColor = "#5ea9d1",
          textFontName = "font/amaticsc.ttf",
          cornerRadius = 25,
          textFontSize = 16,
          type = ButtonType.NEXT
      ),
      CustomButton(
          textColor = "#5ea9d1",
          backgroundColor = "#ffffff",
          textFontName = "font/amaticsc.ttf",
          cornerRadius = 25,
          textFontSize = 16,
          type = ButtonType.RESEND
      ),
      CustomButton(
          textColor = "#ff0000",
          backgroundColor = "#00c1eb",
          textFontName = "font/amaticsc.ttf",
          cornerRadius = 25,
          textFontSize = 20,
          type = ButtonType.CANCEL
      )
  )
)

Fonts precisam ser adicionadas na aplicação e o caminho deve ser informado na customização.

Autenticar

Em seguida é necessário utilizar o método authenticate, informando o access_token gerado no passo anterior, os dados do comprador e o callback que receberá a resposta:

braspag3dsSdk.authenticate(
    accessToken = "ACCESS_TOKEN",
    orderData = OrderData(
        orderNumber = "123456",
        currencyCode = "986",
        totalAmount = 1000L,
        paymentMethod = PaymentMethod.credit,
        transactionMode = TransactionMode.eCommerce,
        installments = 3,
        merchantUrl = "https://www.exemplo.com.br"
    ),
    cardData = CardData(
        number = "4000000000001091",
        expirationMonth = "01",
        expirationYear = "2023"
    ),
    authOptions = OptionsData(
        notifyOnly = false,
        suppressChallenge = false
    ),
    shipToData = ShipToData(
        sameAsBillTo = true,
        addressee = "Rua do Meio, 666",
        city = "Praia Grande",
        country = "BR",
        email = "contato@email.com",
        state = "SP",
        shippingMethod = "lowcost",
        zipCode = "11726000"
    ),
    recurringData = RecurringData(
        frequency = RecurringFrequency.MONTHLY
    ),
    userData = UserData(
        newCustomer = false,
        authenticationMethod = AuthenticationMethod.noAuthentication
    ),
    activity = this@MainActivity,
    callback = myCallback
)

Parâmetros de entrada do método authenticate

Campo Tipo Descrição Obrigatório
orderData OrderData Dados do pedido de pagamento Sim
cardData CardData Dados do cartão Sim
authOptions OptionsData? Configurações adicionais ao processo de 3DS Não
billToData BillToData? Dados de cobrança do portador Não
shipToData ShipToData? Dados da entrega Não
cart [CartItemData]? Array com itens do carrinho Não
deviceData [DeviceData]? Configurações adicionais ao processo de 3DS Não
userData UserData? Dados do usuário na sua loja Não
airlineData AirlineData? Dados da passagem aérea Não
mdd MddData? Dados extras enviados pelo lojista Não
recurringData RecurringData? Dados da recorrência Não
deviceIpAddress String? Endereço IP do dispositivo Não

Descrição dos Status do Callback

Status Descrição
success É retornado quando o cartão é elegível e teve o processo de autenticação finalizado com sucesso. Neste caso, as variáveis CAVV, XID e ECI serão retornados. Estes dados devem ser enviados na requisição no momento da autorização. Neste cenário, se a transação é autorizada, o liability shift é transferido ao emissor.
unenrolled É retornado quando o cartão não é elegível, ou seja, o portador e/ou emissor não participam do programa de autenticação. Neste caso, somente a variável ECI será retornado. Caso haja a decisão de seguir com a autorização mesmo assim, o ECI deverá ser enviado no momento da requisição. Neste cenário, se a transação é autorizada, o liability shift permanece com o estabelecimento.
failure É retornado quando o cartão é elegível, porém não teve o processo de autenticação falhou por algum motivo. Neste caso, somente a variável ECI será retornado. Caso haja a decisão de seguir com a autorização mesmo assim, o ECI deverá ser enviado no momento da requisição. Neste cenário, se a transação é autorizada, o liability shift permanece com o estabelecimento.
error É retornado quando o processo de autenticação recebeu um erro sistêmico. Neste cenário, se a transação é autorizada, o liability shift permanece com o estabelecimento.
unsupportedBrand É retornado quando a bandeira do cartão não é suportado pelo 3DS 2.0

Descrição dos campos do AuthenticationResponse

Saída Descrição Tipo/Tamanho
cavv Dado que representa assinatura da autenticação Texto
xid ID que representa a requisição da autenticação Texto
eci Código indicador do e-commerce, que representa o resultado da autenticação Numérico [até 2 posições]
version Versão do 3DS aplicado Numérico [1 posição]1 – 3DS 1.02 – 3DS 2.0
referenceID ID que representa a requisição de autenticação GUID [36 posições]
returnCode Código de retorno da requisição de autenticação Alfanumérico [até 5 posições]
returnMessage Mensagem de retorno da requisição de autenticação Alfanumérico [varivável]

Nota: No caso de uma transação submetida como Data Only (bpmpi_auth_notifyonly como true), mesmo que bem-sucedida, não serão retornados os campos CAVV e XID (campos não necessários para uma transação no modelo Data Only).

Detalhamento dos objetos da requisição

Para facilitar o uso somente daquilo que o lojista precisa enviar, a requisição é separada em diversos objetos com contexto de dados bem definido conforme a tabela dos parâmetros de entrada do authenticate mostra. Abaixo vamos detalhar cada um dos objetos utilziados.

OptionsData

Propriedade Descrição Tipo/Tamanho Obrigatório
notifyonly Booleano que indica se a transação com cartão será submetida no modo “somente notificação” - Data Only. Neste modo, o processo de autenticação não será acionado, porém, os dados serão submetidos à bandeira. VÁLIDO SOMENTE PARA CARTÕES MASTERCARD Booleano:
true – modo somente notificação;
false – modo com autenticação		 Não
suppresschallenge Booleano que indica se ignora ou não o desafio quando houver. Se uma transação autorizada após ignorar o desafio, o liability permanece com o estabelecimento. Booleano:
true – ignorar desafios se houver;
false – apresentar desafio se houver		 Não

OrderData

Propriedade Descrição Tipo/Tamanho Obrigatório
orderNumber Código do pedido no estabelecimento Alphanumérico [até 50 posições] Sim
currencyCode Código da moeda Fixo "BRL" Sim
totalAmount Valor total da transação, enviado em centavos Numérico [até 15 posições] Sim
paymentMethod Tipo do cartão a ser autenticado. No caso do cartão múltiplo, deverá especificar um dos tipos, Credit ou Debit PaymentMethod
CREDIT – Cartão de Crédito
DEBIT – Cartão de Débito		 Sim
installments Número de parcelas da transação Numérico [até 2 posições] Sim
recurrence Indica se é um pedido que gera recorrências futuras Booleano
true
false		 Não
productCode Tipo da compra ProductCode
GOODSPURCHASE: compra de mercadorias
CHECKACCEPTANCE: Check acceptance
FINANCEACCOUNT: Financiamento de conta
QUASIMONEYTRANSACTION: Transação quase-dinheiro
RECHARGE: recarga
 Sim
countLast24Hours Quantidade de pedidos efetuados por este comprador nas últimas 24h Numérico [até 3 posições] Não
countLast6Months Quantidade de pedidos efetuados por este comprador nos últimos 6 meses Numérico [até 4 posições] Não
countLast1Year Quantidade de pedidos efetuados por este comprador no último ano Numérico [até 3 posições] Não
cardAttemptsLast24Hours Quantidade de transações com o mesmo cartão nas últimas 24h Numérico [até 3 posições] Não
marketingOptIn Indica se o comprador aceitou receber ofertas de marketing Booleano
true – sim
false – não		 Não
marketingSource Identifica a origem da campanha de marketing Alfanumérico [até 40 posições] Não
transactionMode Identifica o canal que originou a transação M: MOTO
R: Varejo
S: E-Commerce
P: Mobile
T: Tablet		 Não
merchantUrl Endereço do site do estabelcimento Alphanumérico [100] Exemplo: http://www.exemplo.com.br Sim

CardData

Propriedade Descrição Tipo/Tamanho Obrigatório
number Número do Cartão Numérico [até 19 posições] Sim
expirationMonth Mês do vencimento do cartão Numérico [2 posições] Sim
cardexpirationYear Ano do vencimento do cartão Numérico [4 posições] Sim
cardAlias Alias do cartão Alphanumérico [até 128 posições] Não
defaultCard Indica se é um cartão padrão do cliente na loja Booleano
true - sim
false - não		 Não

BillToData

Propriedade Descrição Tipo/Tamanho Obrigatório
customerId Identifica o CPF/CNPJ do comprador Numérico [11 a 14 posições]
99999999999999		 Não
contactName Nome do contato do endereço de cobrança Alfanumérico [até 120] Sim
phoneNumber Telefone de contato do endereço de cobrança Numérico [até 15 posições], no formato: 5511999999999 Sim
email E-mail do contato do endereço de cobrança Alfanumérico [até 255], no formato nome@exemplo.com Sim
street1 Logradouro e Número do endereço de cobrança Alfanumérico [até 60] Sim
street2 Complemento e bairro do endereço de cobrança Alfanumérico [até 60] Sim
city Cidade do endereço de cobrança Alfanumérico [até 50] Sim
state Sigla do estado do endereço de cobrança Texto [2 posições] Sim
zipCode CEP do endereço de cobrança Alfanumérico [até 8 posições], no formato: 99999999 Sim
country País do endereço de cobrança Texto [2 posições] Ex. BR Sim

ShipToData

Propriedade Descrição Tipo/Tamanho Obrigatório
sameAsBillTo Indica se utiliza o mesmo endereço fornecido para endereço de cobrança Booleano
true
false		 Não
addressee Nome do contato do endereço de entrega Alfanumérico [até 60] Não
phoneNumber Telefone de contato do endereço de entrega Numérico [até 15 posições], no formato: 5511999999999 Não
email E-mail do contato do endereço de entrega Alfanumérico [até 255], no formato nome@exemplo.com Não
street1 Logradouro e Número do endereço de entrega Alfanumérico [até 60] Não
street2 Complemento e bairro do endereço de entrega Alfanumérico [até 60] Não
city Cidade do endereço de entrega Alfanumérico [até 50] Não
state Sigla do estado do endereço de entrega Texto [2 posições] Não
zipCode CEP do endereço de entrega Alfanumérico [até 8 posições], no formato: 99999999 Não
country País do endereço de cobrança Texto [2 posições] Ex. BR Não
shippingMethod Tipo do método de envio ShippingMethodEnum
LOWCOST: envio econômico
SAMEDAY: envio no mesmo dia
ONEDAY: envio no dia seguinte
TWODAY: envio em dois dias
THREEDAY: envio em três dias
PICKUP: retirada na loja
OTHER: outrosnone: não há envio		 Não
firstUsageDate Indica a data de quando houve a primeira utilização do endereço de entrega Texto
AAAA-MM-DD – data da criação		 Não

CartItemData

Propriedade Descrição Tipo/Tamanho Obrigatório
description Descrição do item Alfanumérico [até 255 posições] Não
name Nome do item Alfanumérico [até 255 posições] Sim
sku SKU do item Alfanumérico [até 255 posições] Não
quantity Quantidade do item no carrinho Numérico [até 10 posições] Não
unitprice Valor unitário do item do carrinho em centavos Numérico [até 10 posições] Não

DeviceData

Propriedade Descrição Tipo/Tamanho Obrigatório
fingerprint Id retornado pelo Device Finger Print Alfanumérico [sem limitação] Não
provider Nome do provedor do Device Finger Print Alfanumérico [até 32 posições] cardinal
inauth
threatmetrix		 Não

UserData

Propriedades Descrição Tipo/Tamanho Obrigatório
guest Indica se o comprador é um comprador sem login (guest) Booleano
true – sim
false – não		 Não
createdDate Indica a data de quando houve a criação da conta do comprador Texto
AAAA-MM-DD – data da criação		 Não
changedDate Indica a data de quando houve a última alteração na conta do comprador Texto
AAAA-MM-DD – data da última alteração		 Não
passwordChangedDate Indica a data de quando houve a alteração de senha da conta do comprador Texto
AAAA-MM-DD – data da última alteração de senha		 Não
authenticationMethod Método de autenticação do comprador na loja AuthenticationMethod
NOAUTHENTICATION - Não houve autenticação
OWNSTORELOGIN - Login da própria loja
FEDERATEDLOGIN - Login com ID federado
FIDOAUTHENTICATOR - Login com autenticador FIDO		 Não
authenticationProtocol Dado que representa o protocolo de login efetuado na loja Alfanumérico [até 2048 posições] Não
authenticationTimestamp A data e hora que o login foi efetuado na loja Texto [19 posições] YYYY-MM-ddTHH:mm:SS Não
newCustomer Identifica se um comprador novo na loja Booleano
true – sim
false – não		 Não

AirlineData

Propriedades Descrição Tipo/Tamanho Obrigatório
numberOfPassengers Número de passageiros Numérico [3 posições] Não
billToPassportCountry Código do país que emitiu o passaporte (ISO Standard Country Codes) Texto [2 posições] Não
billtoPassportNumber Número do passaporte Alfanumérico [40 posições] Não
travelLeg Trecho da viagem TravelLeg Não
passenger Dados do passageiro Passenger Não

TravelLeg

Propriedades Descrição Tipo/Tamanho Obrigatório
carrier Código IATA para o trecho Alfanumérico [2 posições] Não
departureDate Data de partida Texto
AAAA-MM-DD		 Não
origin Código IATA do aeroporto de origem Alfanumérico [5 posições] Não
destination Código IATA do aeroporto de destino Alfanumérico [5 posições] Não

Passenger

Propriedades Descrição Tipo/Tamanho Obrigatório
name Nome do passageiro Alfanumérico [até 60 posições] Não
ticketPrice O valor da passagem em centavos Numérico [até 15 posições],
exemplo: R$ 125,54 = 12554		 Não

MDD

Proriedades Descrição Tipo/Tamanho Obrigatório
mdd1 Dado Extra definido pelo lojista Alfanumérico [até 255 posições] Não
mdd2 Dado Extra definido pelo lojista Alfanumérico [até 255 posições] Não
mdd3 Dado Extra definido pelo lojista Alfanumérico [até 255 posições] Não
mdd4 Dado Extra definido pelo lojista Alfanumérico [até 255 posições] Não
mdd5 Dado Extra definido pelo lojista Alfanumérico [até 255 posições] Não

RecurringData

Proriedades Descrição Tipo/Tamanho Obrigatório
endDate Identifica a data de término da recorrência Texto (AAAA-MM-DD) Não
frequency Indica a frequência da recorrência RecurringFrequencyEnum
MONTHLYBIMONTHLY
QUARTERLY
TRIANNUAL
SEMIANNUAL
YEARLY		 Não
originalPurchaseDate Identifica a data da 1ª transação que originou a recorrência Texto (AAAA-MM-DD) Não

Demais parâmetros

Proriedades Descrição Tipo/Tamanho Obrigatório
ipAddress Endereço IP da máquina do comprador Alfanumérico [até 45] Não

ECI (E-commerce Indicator)

E-Commerce Indicator (ECI) é retornado no processo de autenticação. Este código é um indicador do que exatamente ocorreu no processo de autenticação da transação. Por meio do ECI, pode-se verificar se a transação foi autenticada e quem foi o agente responsável por aquela autenticação. Confira a tabela de ECI.

Cartões de Teste

Utilize os cartões de teste abaixo para simular diversos cenários no ambiente de SANDBOX.

Cartões de Teste com Desafio

Cartões de Teste com Desafio

CARTÃO BANDEIRA RESULTADO DESCRIÇÃO
4000000000001091
5200000000001096
6505050000001091		 VISA
MASTER
ELO		 SUCCESS Autenticação com desafio e portador autenticou com sucesso
4000000000001109
5200000000001104
6505050000001109		 VISA
MASTER
ELO		 FAILURE Autenticação com desafio e portador autenticou com falha
4000000000001117
5200000000001112
6505050000001117		 VISA
MASTER
ELO		 UNENROLLED Autenticação com desafio indisponível no momento
4000000000001125
5200000000001120
6505050000001125		 VISA
MASTER
ELO		 UNENROLLED Erro de sistema durante a etapa de autenticação

Cartões de Teste sem Desafio

CARTÃO BANDEIRA RESULTADO DESCRIÇÃO
4000000000001000
5200000000001005
6505050000001000		 VISA
MASTER
ELO		 SUCCESS Autenticação sem desafio e portador autenticou com sucesso
4000000000001018
5200000000001013
6505050000001018		 VISA
MASTER
ELO		 FAILURE Autenticação sem desafio e portador autenticou com falha

Autorização com Autenticação

Após autenticação ser concluída, submete-se ao processo de autorização, enviando os dados de autenticação no modelo de "autenticação externa" (nó ExternalAuthentication ). Veja maiores detalhes em: https://developercielo.github.io/manual/autorizacao-com-autenticacao

Últimas atualizações

Para visualizar as últimas atualizações do manual, clique aqui

Documentações e tutoriais
Contato
GitHub