CyberSource · e-SiTef

Required credentials

As mentioned in "Overview - Required credentials", each institution has credentials that must be obtained for the integration. CyberSource's services demand credentials below:

Merchat ID (Merchant Code) - Merchant's key to access CyberSource's back office
Shared Secret - Merchant's key to access CyberSource's back office. If key is not registered, e-SiTef will not be able to query status CyberSource. In case any risk analysis transaction is with status pending, the decision configured by Merchant will be executed and e-SiTef will confirm or e-SiTef will cancel the transaction.
Key ID - Identification of the Shared Secret.
Org ID - * Key used to collect fingerprint data from the payer's browser.
p12 certificate - Security certification for orders analysis. The file should have the same name as Merchant ID in CyberSource system.

IMPORTANT: The credentials above should be obtained from CyberSource. It is recommended to contact CyberSource and receive guidance on how to obtain the credentials. Then, the merchant should contact e-SiTef support and send the credentials to register in e-SiTef.

To obtain the Shared Secret and the Key ID follow the instructions at:

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

To obtain the .p12 certificate, follow the instructions at:

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

Allowed card brands

Listed below the authorizers supported by 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)

Refund notification due to fraud

When canceling a payment due to fraud, you can notify Cybersource what happened and mark the transaction as fraudulent.

Currently, only the REST Cancellation interface can send complementary data to CyberSource. For this, it's necessary to send the following fields:

Field	Description
`anti_fraud`	Object with anti-fraud data.
`chargeback`	Informs whether the notification to Cybersource will be made or not. Allowed values: `true` ou `false` Default value: `false`
`marked_data`	Informs which fields will be relevant to notify to Cybersource that this transaction was a fraud attempt. This fields receives an array of values. For example: `"marked_data":["ship_address","customer_phone","customer_email"]`. Fields that can be informed: `account_key_hash` `customer_account_id` `customer_email` `customer_idaddress` `customer_phone` `device_fingerprint` `ship_address` If no content is sent, the default values assumed by Cybersource will be `account_key_hash`, `customer_email` and `ship_address`.

Example:

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

Anti-fraud parameter for CyberSource

Below is the list of anti-fraud parameters processed by CyberSource. Some parameters have different treatments depending on the institution and the "Additional detail" column that specifies CyberSource's treatment. For details of each parameter, see the anti-fraud parameters list.

Property e-SiTef	Property CyberSource	Additional detail
`currency`	`PurchaseTotals_currency`	-
`items`		Object json Array (Learn more)
`shipment`		Object json Array (Learn more)
`browser`		Object json (Learn more)
`travel`		Object json (Learn more). Required, if the item is an air ticket
`passengers`		Object json Array (Learn more)
`connections`		Object json Array (Learn more)
`mdd`		Object json Array (Learn more). The allowed values can be found here.

Object `items`

Property e-SiTef	Property CyberSource	Additional detail
`id`	`Item_#_ID`	-
`sku`	`Item_#_ productSKU`	Required
`title`	`Item_#_ productName`	-
`quantity`	`Item_#_Quantity`	-
`unit_price`	`Item_#_unitPrice`	-
`category_id`	`Item_#_productCode`	Allowed values: `adult_content` `default` `electronic_good` `electronic_software` `gift_certificate` `handling_only` `service` `shipping_and_handling` `shipping_only` `stored_value` `subscription` . Required. When the used value is not default, the fields `item_#_quantity`, `item_#_productName` e `item_#_productSKU` are mandatory!
`tax_amount`	`Item_#_taxAmount`	-

Object `shipment`

Property e-SiTef	Property CyberSource	Additional detail
`name`	`shipTo_firstName`	-
`surname`	`shipTo_lastName`	-
`address`		Object json (Learn more)
`phones`		Arrays de object json (Learn more)

Object `address` of `shipment`

Property e-SiTef	Property CyberSource	Additional detail
`street_name`	`shipto_street1`	Must send the street number and the complement. Use the keywords AP (apartment), APTO (apartment), LOTE (lot), CASA (house) or BLOCO (block).
`street_name2`	`shipto_street2`	Must send the street number and the complement. Use the keywords AP (apartment), APTO (apartment), LOTE (lot), CASA (house) or BLOCO (block).
`street_number`	`shipto_street1`	-
`apartment`	Will be appended to the `shipto_street2`	-
`complement`	Will be appended to the `shipto_street2`	-
`city`	`shipto_city`	-
`state`	`shipto_state`	-
`country`	`shipto_country`	Must use the ISO pattern
`zip_code`	`shipto_postalCode`	-
`building_number`	`shipto_building_number`	-

Object `phones` of `shipment`

Property e-SiTef	Property CyberSource	Additional detail
`ddi`	`shipTo_phoneNumber`	-
`ddd`	`shipTo_phoneNumber`	-
`number`	`shipTo_phoneNumber`	-

Object `browser`

Property e-SiTef	Property CyberSource	Additional detail
`ip_address`	`billTo_ipAddress`	If this field is not sent, the client's IP will be sent

Object `travel`

Property e-SiTef	Property CyberSource	Additional detail
`route`	`decisionManager_travelData_completeRoute`	-
`journey_type`	`decisionManager_travelData_journeyType`	-
`departure_date_time`	`decisionManager_travelData_journeyType`	-

Object `passengers`

Property e-SiTef	Property CyberSource	Additional detail
`id`	`item_#_passengerId`	-
`name`	`item_#_passengerFirstName`	Fill with passenger's first name
`last_name`	`item_#_passengerLastName`	Required
`frequente_flyer_card`	`item_#_passengerID`	The field `billTocustomerID` can hold the same information
`email`	`item_#_passengerEmail`	Must be unique, otherwise, the transaction will be refused by CyberSource with reason code `102`.
`status`	`item_#_passengerStatus`	-
`type`	`item_#_passengerType`	-
`unit_price`	`item_#_unitPrice`	-
`phones`		Object json Array (Learn more)

Object `phones` of `passengers`

Property e-SiTef	Property CyberSource	Additional detail
`ddi`	`item_#_passengerPhone`	-
`ddd`	`item_#_passengerPhone`	-
`number`	`item_#_passengerPhone`	-

Object `connections`

Property e-SiTef	Property CyberSource	Additional detail
`flight_date`	`decisionManager_travelData_departureDateTime`	the following formats are allowed: yyyy-MM-dd HH:mm z yyyy-MM-dd hh:mm a z yyyy-MM-dd hh:mma z Consider: `HH` = time in 24 hours format `hh` = time in 12 hours format `a` = am or pm (case insensitive) `z` = timezone of departure flight (if is the offset according to GMT, use the format: GMT-03:00)
`from`	`decisionManager_travelData_leg_#_origin`	Use this reference in order to get the airports codes.
`to`	`decisionManager_travelData_leg_#_destination`	Use this reference in order to get the airports codes. It's possible to consider the complete route with the field `decisionManager_travelData_completeRoute`. If all those fields are sent, the `completeRoute` field will be used.
`departure_date`	`decisionManager_travelData_departureDateTime`	-

Object `mdd`

Property e-SiTef	Property CyberSource	Additional detail
`id`	`merchantDefinedData_mddField_id`	It can range from 1 to 100 defined by the merchant in an agreement with Cybersource.
`value`	`merchantDefinedData_mddField_value`	Value of the field defined by the merchant in an agreement with Cybersource.

`mdd` values

The MDDs are additional data that help with the accuracy of Cybersource's anti-fraud analysis and sending them is highly recommended. There are three MDD ID ranges:

Between 1 to 4, refers to MDD that will be filled out by e-SiTef itself.
Between 5 and 20, refers to MDD that are independent of store activity.
Between 21 and 1000, refers to MDD that are dependent of the store's activity and the filling must follow the guidelines of Cybersource. The allowed values of id and the description of the value content are:

ID	Resume	Description
`5`	Sales channel	Sales channel of the product/service: `Web`, `App`, `Ticket Office`, etc.)
`6`	OS	Operational System used by the customer: `Android`, `iOS`, `Windows`, etc.
`7`	Application Version	Merchant's Application Version : `1.0.12`
`8`	Provisioned for future data	Provisioned for future data.
`9`	Provisioned for future data	Provisioned for future data.
`10`	Provisioned for future data	Provisioned for future data.
`11`	Name used in registration	Nome registrado no cadastro (Obs: em caso de compra guest`* não enviar valor por gentileza)
`12`	CPF used in registration	CPF registrado no cadastro.
`13`	Client register age in days	Tempo de cadastro do cliente em dias. Formato: `NNNNN`
`14`	Days since first order	Quantidade de dias passados desde o primeiro pedido. Formato: `NNNNN`
`15`	Days since last order	Quantidade de dias passados desde o último pedido. Formato: `NNNNN`
`16`	Total orders quantity	Quantidade total de pedidos realizados pelo CPF cadastrado. Formato: `NNNNN`
`17`	Days since last registration change	Quantidade de dias passados desde a última alteração cadastral. Formato: `NNNNN`
`18`	Provisioned for future data	Provisioned for future data.
`19`	Provisioned for future data	Provisioned for future data.
`20`	Provisioned for future data	Provisioned for future data.

Example

Example of HTML payment request with risk analysis on 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":"1",
               "value":"MDD_TESTE_1"
            },
            {
               "id":"2",
               "value":"MDD_TESTE_2"
            }
         ],
         "travel":{
            "route":"GIG-SFO:SFO-LAX",
            "departure_date_time":"2019-12-19T09:00:00",
            "journey_type":"Round_Trip"
         }
      }
   }
}

Response Codes

As explained in the chapter "Risk analysis response", the codes below are CyberSource's specific responses.

Code	Description
`100`	Transaction performed successfully and approved by the Decision Manager.
`101`	One or more of the required fields are missing in the request.
`102`	One or more of the required fields contains invalid data.
`150`	Error: General System Failure
`151`	Error: The request was received but timeout occurred. This error does not include timeout between client and server.
`152`	Error: The request was received, but a service did not finish in a timely manner.
`202`	Expired card

Required credentials

Allowed card brands

Refund notification due to fraud

Anti-fraud parameter for CyberSource

Object items

Object shipment

Object address of shipment

Object phones of shipment

Object browser

Object travel

Object passengers

Object phones of passengers

Object connections

Object mdd

mdd values