CyberSource

Credenciais necessárias

Como mencionado no capítulo da "Visão Geral - Credenciais necessárias", cada instituição possui um conjunto de credenciais que devem ser obtida para a integração. Os serviços da CyberSource exigem as seguintes credenciais:

  • Merchant ID (Merchant Code) - chave do usuário do lojista no Portal da CyberSource
  • Shared Secret - Chave do lojista no Portal da CyberSource. Caso não seja informada a chave para cadastro, o e-SiTef não realizará consulta de status na CyberSource. Isso significa que se alguma análise de risco ficar pendente, a decisão cadastrada pelo lojista no Portal será ativada, confirmando ou desfazendo a transação.
  • Key ID - ID que identifica a Shared Secret.
  • Org ID - Chave utilizada coletar dados de fingerprint do browser do comprador.
  • Certificado p12 - certificado de segurança necessário para a análise dos pedidos. Este arquivo deve ter o nome do Merchant ID do lojista / integrador no sistema da CyberSource.

IMPORTANTE: As credenciais acima devem ser obtidas com a CyberSource. O lojista deve entrar em contato com a CyberSource e receber as devidas orientações de como obter cada uma dessas credenciais. Após conseguir as credenciais, o lojista deve entrar em contato com o suporte do e-SiTef e passar as credenciais para o cadastro no e-SiTef.

Para obter a Shared Secret e o Key ID siga as orientações em:

https://developer.cybersource.com/api/developer-guides/dita-gettingstarted/authentication/createSharedKey.html

Para obter o Certificado .p12, siga as orientações em:

https://support.cybersource.com/s/article/How-to-Generate-a-Simple-Order-API-Security-Key

Bandeiras permitidas

Seguem abaixo as bandeiras suportadas nas análises da CyberSource:

  • Visa
  • MasterCard
  • American Express
  • Discover
  • Diners Club
  • Carte Blanche
  • JCB
  • EnRoute
  • JAL
  • Delta
  • Dankort
  • Laser
  • Carte Bleue
  • Carta Si
  • Encoded account number
  • UATP
  • GE Money UK card
  • Style
  • Hipercard
  • Aura
  • Elo
  • Elo Débito (Auxílio Emergencial)

Aviso de cancelamento por fraude

Ao cancelar um pagamento por motivos de fraude, é possível avisar a CyberSource sobre o ocorrido e marcar como fraudulenta a transação realizada, consequentemente melhorando a análise de risco.

Atualmente, somente a interface Cancelamento REST pode enviar os dados complementares para a CyberSource. Para isso, é necessário enviar os seguintes campos:

CampoDescrição
anti_fraudObjeto com campos de anti-fraude.
chargebackInforma se o aviso para a CyberSource será realizado ou não.
Valores permitidos: true ou false
Valor default: false
marked_dataInforma quais campos serão relevantes para avisar a CyberSource que esta transação foi uma tentativa de fraude.

Este campo recebe uma lista de valores. Por exemplo: "marked_data":["ship_address","customer_phone","customer_email"].

Campos que podem ser informados:
  • account_key_hash
  • customer_account_id
  • customer_email
  • customer_idaddress
  • customer_phone
  • device_fingerprint
  • ship_address
Caso nenhum valor seja informado, os seguintes campos serão assumidos pela CyberSource: account_key_hash, customer_email e ship_address.

Exemplo:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "security_code":"123",
      "number":"5555555555555555",
      "expiry_date":"1222"
   },
   "amount":"1000",
   "anti_fraud":{
      "chargeback":"true",
      "marked_data":[
         "account_key_hash",
         "customer_account_id",
         "customer_email"
      ]
   }
}
--verbose

Parâmetros antifraude da CyberSource

Abaixo segue a relação de parâmetros antifraude processados pela CyberSource. Alguns parâmetros possuem tratamentos diferenciados dependendo da instituição e a coluna de "Detalhe adicional" especifica o tratalmento especial da CyberSource. Para detalhe de cada parametro, veja a lista de parametro de antifraude

Propriedades
e-SiTef		Propriedades
CyberSource		Detalhe adicional
currencyPurchaseTotals_currency-
itemsArrays de objeto json (Saiba mais)
shipmentArray de objeto json (Saiba mais)
browserObjeto json (Saiba mais)
travelObjeto json (Saiba mais). Obrigatório se o item for passagem aérea
passengersArray de objeto json (Saiba mais)
connectionsArray de objeto json (Saiba mais)
mddArray de objeto json (Saiba mais). Os valores permitidos podem ser consultados aqui.

Objeto items

Propriedades
e-SiTef		Propriedades
CyberSource		Detalhe adicional
idItem_#_ID-
skuItem_#_ productSKUPreenchimento obrigatório
titleItem_#_ productName-
quantityItem_#_Quantity-
unit_priceItem_#_unitPrice-
category_idItem_#_productCodePode receber os seguintes valores:
  • adult_content
  • default
  • electronic_good
  • electronic_software
  • gift_certificate
  • handling_only
  • service
  • shipping_and_handling
  • shipping_only
  • stored_value
  • subscription
. Preenchimento obrigatório.

Quando o valor enviado for diferente de default, os campos item_#_quantity; item_#_productName e item_#_productSKU passam a ser obrigatórios;
tax_amountItem_#_taxAmount-

Objeto shipment

Propriedades
e-SiTef		Propriedades
CyberSource		Detalhe adicional
nameshipTo_firstName-
surnameshipTo_lastName-
addressObjeto json (Saiba mais)
phonesArrays de objeto json (Saiba mais)

Objeto address do shipment

Propriedades
e-SiTef		Propriedades
CyberSource		Detalhe adicional
street_nameshipto_street1Enviar o número e o complemento. Lembrar de colocar o AP, APTO, LOTE, CASA ou BLOCO.
street_name2shipto_street2Enviar o número e o complemento. Lembrar de colocar o AP, APTO, LOTE, CASA ou BLOCO.
street_numbershipto_street1-
apartmentSerá concatenado em shipto_street2-
complementSerá concatenado em shipto_street2-
cityshipto_city-
stateshipto_state-
countryshipto_countryEnviar a sigla no padrão ISO
zip_codeshipto_postalCode-
building_numbershipto_building_number-

Objeto phones do shipment

Propriedades
e-SiTef		Propriedades
CyberSource		Detalhe adicional
ddishipTo_phoneNumber-
dddshipTo_phoneNumber-
numbershipTo_phoneNumber-

Objeto browser

Propriedades
e-SiTef		Propriedades
CyberSource		Detalhe adicional
ip_addressbillTo_ipAddressSe este campo não for enviado, será enviado o IP do cliente

Objeto travel

Propriedades
e-SiTef		Propriedades
CyberSource		Detalhe adicional
routedecisionManager_travelData_completeRoute-
journey_typedecisionManager_travelData_journeyType-
departure_date_timedecisionManager_travelData_journeyType-

Objeto passengers

Propriedades
e-SiTef		Propriedades
CyberSource		Detalhe adicional
iditem_#_passengerId-
nameitem_#_passengerFirstNamePreencher apenas com o primeiro nome
last_nameitem_#_passengerLastNamePreenchimento obrigatório
frequente_flyer_carditem_#_passengerIDO campo billTocustomerID pode abrigar a mesma informação
emailitem_#_passengerEmailSe não único entre os passageiros, a transação será recusada pela CyberSource, com código 102.
statusitem_#_passengerStatus-
typeitem_#_passengerType-
unit_priceitem_#_unitPrice-
phonesArrays de objeto json (Saiba mais)

Objeto phones do passengers

Propriedades
e-SiTef		Propriedades
CyberSource		Detalhe adicional
ddiitem_#_passengerPhone-
ddditem_#_passengerPhone-
numberitem_#_passengerPhone-

Objeto connections

Propriedades
e-SiTef		Propriedades
CyberSource		Detalhe adicional
flight_datedecisionManager_travelData_departureDateTimeOs seguintes formatos são aceitos:
  • yyyy-MM-dd HH:mm z
  • yyyy-MM-dd hh:mm a z
  • yyyy-MM-dd hh:mma z
Sendo:
  • HH = hora em formato de 24 horas
  • hh = hora em formato de 12 horas
  • a = am ou pm (case insensitive)
  • z = timezone do vôo de partida (no caso de offset em relação a GMT, siga este formato: GMT-03:00
fromdecisionManager_travelData_leg_#_originValor deve respeitar esta os códigos de aeroporto, desta referência.
todecisionManager_travelData_leg_#_destinationValor deve respeitar esta os códigos de aeroporto, desta referência. É possível também se considerar a rota completa com o campo decisionManager_travelData_completeRoute. Se todos estes campos forem enviados, o valor de completeRoute será preponderante.
departure_datedecisionManager_travelData_departureDateTime-

Objeto mdd

Propriedades
e-SiTef		Propriedades
CyberSource		Detalhe adicional
idmerchantDefinedData_mddField_idPode variar de 1 a 100 definidos pelo comércio em acordo com a Cybersource
valuemerchantDefinedData_mddField_valueValor dos campos definidos pelo comércio em acordo com a Cybersource

Valores de mdd

Os MDD's são dados adicionais que ajudam na acertividade da análise antifraude da Cybersource e o envio deles é altamente recomendado. Existem três intervalos de ID de MDD's:

  • Entre 1 até 4, são MDD que serão preenchidos pelo próprio e-SiTef.
  • Entre 5 até 20, são MDD independentes da atividade da loja.
  • Entre 21 até 1000, são MDD dependentes da atividade da loja e o preenchimento deve seguir as orientações da Cybersource. Os valores permitidos de id e a descrição do conteúdo value são:
IDResumoDescrição
5Canal de VendaCanal de Venda do produto/serviço. Exemplo de valor: Web, App, Guichê, etc.)
6SOSistema Operacional utilizado pelo cliente final. Exemplo de valor: Android, iOS, Windows, etc.
7Versão da AplicaçãoVersão da aplicação do cliente. Exemplo de valor: 1.0.12
8Provisionado para futuros dadosProvisionado para futuros dados.
9Provisionado para futuros dadosProvisionado para futuros dados.
10Provisionado para futuros dadosProvisionado para futuros dados.
11Nome utilizado no cadastroNome registrado no cadastro (Obs: em caso de compra guest, não enviar valor)
12CPF utilizado no cadastroCPF registrado no cadastro.
13Tempo de cadastro do cliente em diasTempo de cadastro do cliente em dias. Formato: NNNNN
14Dias desde primeiro pedidoQuantidade de dias passados desde o primeiro pedido. Formato: NNNNN
15Dias desde último pedidoQuantidade de dias passados desde o último pedido. Formato: NNNNN
16Quantidade total de pedidosQuantidade total de pedidos realizados pelo CPF cadastrado. Formato: NNNNN
17Dias desde última alteração cadastralQuantidade de dias passados desde a última alteração cadastral. Formato: NNNNN
18Provisionado para futuros dadosProvisionado para futuros dados.
19Provisionado para futuros dadosProvisionado para futuros dados.
20Provisionado para futuros dadosProvisionado para futuros dados.

Exemplo

Exemplo da request de pagamento HTML com análise de risco na CyberSource:

{
   "merchant_id":"CYBERSRCPERMI2",
   "merchant_usn":"803208495",
   "order_id":"866705726000010",
   "redirect":"A",
   "style":"N",
   "amount":"100000",
   "authenticate":"0",
   "transaction_type":"payment",
   "additional_data":{
      "currency":"BRL",
      "items":[
         {
            "title":"bola 1",
            "quantity":"1",
            "unit_price":"50000",
            "category_id":"default",
            "description":"bola para jogar 1",
            "weight":"200",
            "shipping_cost":"1000",
            "id":"1",
            "sku":"1234"
         },
         {
            "title":"bola 2",
            "quantity":"2",
            "unit_price":"25000",
            "category_id":"default",
            "description":"bola para jogar 2",
            "weight":"200",
            "shipping_cost":"1000",
            "id":"2",
            "sku":"123"
         }
      ],
      "payer":{
         "name":"Joaquim",
         "surname":"Severino",
         "email":"allison@confiavel.com",
         "city":"Rio de janeiro",
         "state":"RJ",
         "date_created":"2014-03-12T06:55:17.413-04:00",
         "born_date":"12/12/1900",
         "id":"68408639307",
         "address":{
            "zip_code":"55555000",
            "street_number":"123",
            "street_name":"Rua Jaragua",
            "floor":"123",
            "apartment":"123",
            "complement":"Loja 123",
            "district":"Darada",
            "city":"rio de janeiro",
            "state":"SP",
            "country":"br",
            "county":"Jardim Tottoro",
            "reference":"Esquina das alamedas"
         },
         "phones":[
            {
               "number":"998844551",
               "ddd":"11",
               "ddi":"55"
            }
         ],
         "documents":[
            {
               "type":"cpf",
               "number":"68408639307"
            }
         ]
      },
      "shipment":{
         "type":"1",
         "cost":"2000",
         "name":"Joaquim",
         "surname":"Silva",
         "address":{
            "zip_code":"12345678",
            "street_number":"123",
            "street_name":"Rua do Exemplo",
            "building_number":"55",
            "floor":"3",
            "complement":"CASA",
            "district":"Jardim do Exemplo",
            "city":"São Paulo",
            "state":"SP",
            "country":"br",
            "county":"jardins"
         },
         "phones":[
            {
               "number":"123123123",
               "ddd":"11",
               "ddi":"34"
            }
         ],
         "anti_fraud":"enabled_after_auth",
         "passengers":[
            {
               "id":"3354688841",
               "name":"Joaquim",
               "last_name":"Severino",
               "email":"allison@confiavel.com",
               "customer_class":"standard",
               "unit_price":"100000",
               "type":"ADT",
               "phone":{
                  "number":"998844551",
                  "ddd":"11",
                  "ddi":"55"
               }
            }
         ],
         "billing_data":{
            "client_id":"68408639307",
            "person":"1",
            "gender":"M",
            "name":"Joaquim Severino",
            "birth_date":"1990-02-19T10:00:00",
            "email":"allison@confiavel.com",
            "address":{
               "zip_code":"02932900",
               "street_number":"123",
               "street_name":"rua legal",
               "floor":"1",
               "apartment":"1200",
               "complement":"lala",
               "city":"rio de janeiro",
               "state":"RJ",
               "country":"Brazil",
               "county":"jardim lala",
               "reference":"shopping",
               "phones":[
                  {
                     "number":"123123123",
                     "ddd":"11",
                     "ddi":"34"
                  }
               ]
            },
            "phones":[
               {
                  "number":"123123123",
                  "ddd":"11",
                  "ddi":"34"
               }
            ]
         },
         "browser":{
            "ip_address":"187.75.228.107"
         },
         "mdd":[
            {
               "id":"5",
               "value":"Gichê"
            },
            {
               "id":"6",
               "value":"Linux"
            }
         ],
         "travel":{
            "route":"GIG-SFO:SFO-LAX",
            "departure_date_time":"2019-12-19T09:00:00",
            "journey_type":"Round_Trip"
         }
      }
   }
}

Lista de Códigos de Retorno

Conforme explicado no capítulo "Retorno da análise de risco", os códigos abaixo são as respostas específicas da CyberSource.

CódigoDescrição
100Transação efetuada com sucesso e aprovada pelo Decision Manager
101Um ou mais dos campos requeridos está faltando na requisição
102Um ou mais dos campos requeridos contém dados inválidos
150Erro: Falha geral de sistema
151Erro: A requisição foi recebida mas ocorreu timeout. Esse erro não inclui timeout entre cliente e servidor
152Erro: A requisição foi recebida, mas um serviço não finalizou no tempo de corrida
202Cartão expirado
← ClearSaleKonduto →