O que é 3DS 2.0?

Para maiores detalhes sobre o 3DS 2.0, acesse:https://braspag.github.io/manualp/emv3ds#o-que-%C3%A9-3ds-2.0?

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": "barear",
      "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

Para utilizar o SDK é necessário realizar a importação do módulo Braspag3dsSdk:

import Braspag3dsSdk

Em seguida é necessário passar para o lado cliente(APP) o access_token gerado no passo anterior:

let braspag3ds = Braspag3ds(accessToken: "[Access_Token gerado no passo 1]", environment: Environment.production)

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

braspag3ds.authenticate(orderData: OrderData(...),
                        cardData: CardData(...),
                        authOptions: OptionsData(...),
                        billToData: BillToData(...),
                        shipToData: ShipToData(...),
                        cart: [CartItemData(...),
                        deviceData: DeviceData(...),
                        userData: UserData(...),
                        airlineData: AirlineData(...),
                        mdd: MddData(...),
                        recurringData: RecurringData(...),
                        deviceIpAddress: "0.0.0.0"){ (status, authenticationResponse) in
                        
                        switch(status){
                        case .success:
                          ...
                        case .unenrolled:
                          ...
                        case failure:
                          ...
                        case error:
                          ...
                        case unsupportedBrand:
                          ...
                        }                  
  }

Versão mínima do SDK

O SDK utiliza a versão mínima 9.0

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 Alfanumérico [28 posições]
xid ID que representa a requisição da autenticação Alfanumérico [28 posições]
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]

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”. 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
hotel: Hotelaria
financeAccount: Financiamento de conta
checkAcceptance: Check acceptance
digitalGoods: Digital Goods
cashDispenser: Dispensação de dinheiro
fuel: Combustível
retail: Varejo geral
luxuryGoods: Artigos de luxo
recharge: recarga
goodsPurchase: compra de mercadorias
quasiMoneyTransaction: Transação quase-dinheiro
carRental: Alugue de Carros
restaurant: Restaurante
services: Serviços
other: Outros
turism: Turismo
Não
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

Cartões de Teste

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

Cartão Resultado Descrição
4000000000001000 SUCCESS Autenticação Silenciosa e portador autenticou com sucesso
4000000000001018 FAILURE Autenticação Silenciosa e portador finalizou com falha
4000000000001034 UNENROLLED Cartão não elegível para autenticação
4000000000001091 SUCCESS Autenticação com desafio e portador autenticou com sucesso
4000000000001117 UNENROLLED Autenticação com desafio e Cartão não elegível
4000000000001109 FAILURE Autenticação com desafio e portador falhou na autenticação

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://braspag.github.io/manual/autorizacao-com-autenticacao

Últimas atualizações

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