e-SiTef

Pagamento REST

Visão Geral

O e-SiTef possui duas interfaces para integração com a loja virtual, POST/HTML e Web Services (REST ou SOAP), possibilitando a maneira adequada de interação da loja com o e-SiTef, conforme a linguagem e plataforma de execução da loja virtual.

Na interface REST, a coleta dos dados do cartão e do pagamento será realizada pela Loja Virtual e o e-SiTef apenas se encarregará de efetuar o pagamento com a instituição financeira.

Nessa interface estão disponíveis os pagamentos com cartão de crédito, débito ou voucher. Para pagamentos via banco como transferência bancária, boleto, utilize a interface POST/HTML.

Comunicação

Para realizar uma transação Web Service, toda a comunicação será realizada via HTTPS/SSL. É importante que o servidor do lojista suporte criptografia com no mínimo 128 bits. O servidor da loja deverá realizar chamadas em endereços específicos para transações REST.

Cada serviço deve ser chamado utilizando a URL base concatenada do recurso desejado (veja o capítulo referente ao serviço a ser consumido). O método HTTP (GET, POST ou PUT) indica a ação esperada sobre o recurso escolhido. Abaixo estão as URLs base do e-SiTef:

URL base de Produção:

https://esitef-ec.softwareexpress.com.br/e-sitef/api

URL base de Homologação:

https://esitef-homologacao.softwareexpress.com.br/e-sitef/api

Todas as chamadas realizadas para os serviços serão respondidas de forma síncrona.

Atenção:

Nunca utilize o IP ao invés do domínio esitef-ec.softwareexpress.com.br. O IP pode mudar a qualquer momento e sem aviso prévio, portanto é importante a utilização do domínio para acesso ao e-SiTef.

Importante:

Além dos parâmetros de retorno dos serviços descritos nesta especificação o e-SiTef poderá devolver outros parâmetros sem aviso prévio.

É importante que o aplicativo esteja preparado para receber os parâmetros desconhecidos além dos parâmetros já especificados e simplesmente desprezá-los.

Fluxo

O fluxo de pagamento será iniciado pelo aplicativo da loja virtual após o cliente finalizar a compra e preencher suas informações de pagamento.

Existem dois tipos de fluxo de pagamento: com confirmação automática, onde o e-SiTef se responsabiliza por confirmar o pagamento com as Redes Adquirentes e com confirmação tardia, onde a aplicação se responsabiliza por confirmar o pagamento, consumindo o serviço de confirmação.

A confirmação tardia geralmente é utilizada quando o aplicativo da loja virtual permite o pagamento com mais de um cartão ou se realiza alguma validação antes de efetuar o pagamento.

Pagamento com confirmação automática

Descrição do fluxo:

1. O lojista cria uma transação no e-SiTef passando informações como código da loja, número de parcelas e código de pedido e obtém como resposta um NIT (Número Identificador de Transação).
2. A loja virtual prossegue então consumindo o serviço de efetivação do pagamento, passando o NIT e os dados do cartão do comprador. Em caso de sucesso, a transação de pagamento mudará seu status para CON (confirmada).

Pagamento com confirmação tardia

Descrição do fluxo:

1. Assim como no fluxo de pagamento com confirmação automática, o lojista cria uma transação no e-SiTef passando os dados do pagamento. Adicionalmente, ele deve enviar o parâmetro postpone_confirmation com valor true.
2. A loja virtual prossegue então consumindo o serviço de efetivação do pagamento, passando o NIT e os dados do cartão do comprador. Em caso de sucesso, a transação de pagamento mudará seu status para PPC (pagamento pendente de confirmação).
3. Concluindo, a loja virtual chama o serviço de confirmação do pagamento, passando o NIT novamente e o parâmetro confirm com valor true, resultando numa transação com status CON (confirmada). Também existe a possibilidade do lojista desfazer a transação em vez de confirmar. Para isso, o parâmetro confirm deve ser enviado com valor false, o que resultará numa transação com status PPN (desfeita).

Quick start

Este guia mostra o processo de efetivação de um pagamento à vista, utilizando a interface web service REST do e-SiTef.

O que você precisará

• Cadastro ativo no ambiente de homologação do e-SiTef (obtido com nossa equipe de suporte)
• Uma ferramenta capaz de realizar chamadas HTTP, como Postman, REST Client ou cURL

Criando a transação

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

JSON

cURL

{
   "merchant_usn":"12042142155",
   "order_id":"12042142155",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"1"
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"12042142155",
   "order_id":"12042142155",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"1"
}
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "status": "NOV",
        "nit": "<nit>",
        "order_id": "12042142155",
        "merchant_usn": "12042142155",
        "amount": "1"
    }
}

Saiba mais sobre esse serviço.

Efetuando o pagamento

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/<nit>

Preencha o campo <nit> na URL acima com o NIT obtido na resposta da fase anterior de criação da transação.

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

JSON

cURL

{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"601"
   }
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/<nit>"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"601"
   }
}
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "Transacao OK",
        "status": "CON",
        "nit": "<nit>",
        "order_id": "12042142155",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "1005",
        "acquirer_name": "Redecard",
        "authorizer_date": "13/04/2018T10:56",
        "authorization_number": "132324",
        "merchant_usn": "12042142155",
        "esitef_usn": "180413005038220",
        "sitef_usn": "132324",
        "host_usn": "999132324   ",
        "amount": "1",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000005",
        "payment_date": "13/04/2018T10:56"
    }
}

Saiba mais sobre esse serviço.

Verificando o estado do pagamento

Tipo de requisição: GET

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions/<nit>

Preencha o campo <nit> na URL acima com o NIT obtido na resposta da fase de criação da transação.

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

cURL

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions/<nit>"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "Transacao OK",
        "status": "CON",
        "nit": "<nit>",
        "order_id": "12042142155",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "1005",
        "acquirer_name": "Redecard",
        "authorizer_date": "13/04/2018T10:56",
        "authorization_number": "132324",
        "merchant_usn": "12042142155",
        "esitef_usn": "180413005038220",
        "sitef_usn": "132324",
        "host_usn": "999132324   ",
        "amount": "1",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000005",
        "payment_date": "13/04/2018T10:56"
    }
}

Saiba mais sobre esse serviço.

Serviço de criação da transação

O consumo do serviço de criação de transação é obrigatório nos fluxos de pagamento e agendamento. Como resultado dessa operação, o lojista obterá um NIT (pagamento) e/ou um SID (agendamento) que serão necessários para os próximos passos do fluxo, assim como a utilização do serviço de consulta de transações.

O NIT e o SID possuem um tempo limite para sua utilização. Este prazo está configurado no e-SiTef, e caso seja excedido, a transação passará do status NOV (nova) para EXP (expirada), que impede futuras operações com essa transação, tornando necessário consumir novamente o serviço de criação de transação.

Detalhes da chamada

• Recurso: /v1/transactions
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de criação de transações utilizando a ferramenta cURL.

Criação de pagamento com confirmação automática

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"12042142155",
   "order_id":"12042142155",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"1000"
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "status":"NOV",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"12042142155",
      "merchant_usn":"12042142155",
      "amount":"1000"
   }
}

Criação de pagamento com confirmação tardia

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"12050620649",
   "order_id":"12050620649",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"1000",
   "additional_data":{
      "postpone_confirmation":"true"
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "status":"NOV",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"12050620649",
      "merchant_usn":"12050620649",
      "amount":"1000"
   }
}

Criação de pagamento com agendamento

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"12053724147",
   "order_id":"12053724147",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"1000",
   "schedule":{
      "amount":"900",
      "initial_date":"03/08/2017",
      "number_of_times":"3",
      "interval":"1",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   },
   "additional_data":{
      "payer":{
         "store_identification":"98253053045"
      }
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "status":"NOV",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"12053724147",
      "merchant_usn":"12053724147",
      "amount":"1000"
   },
   "schedule":{
      "status":"NOV",
      "sid":"qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
      "amount":"900",
      "order_id":"12053724147",
      "merchant_usn":"12053724147"
   }
}

Criação de agendamento sem pagamento

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"12055523043",
   "order_id":"12055523043",
   "authorizer_id":"2",
   "schedule":{
      "amount":"900",
      "do_payment_now":"false",
      "initial_date":"03/08/2017",
      "number_of_times":"3",
      "interval":"1",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   },
   "additional_data":{
      "payer":{
         "store_identification":"98253053045"
      }
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "schedule":{
      "status":"NOV",
      "sid":"qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
      "amount":"900",
      "order_id":"12055523043",
      "merchant_usn":"12055523043"
   }
}

Criação de pagamento com análise de risco Cielo e-Commerce

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"12042142155",
   "order_id":"12042142155",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"1000",
   "additional_data":{
      "payer":{
         "name":"Comprador",
         "surname":"credito AF",
         "email":"compradorteste@live.com",
         "city":"Rio de Janeiro",
         "state":"RJ",
         "address_street_name":"Rua Jupiter",
         "address_street_number":"174",
         "address_zip_code":"21241140",
         "born_date":"1991-01-02T08:30:00",
         "address_street_complement":"AP 201",
         "address_country":"BRA"
      },
      "shipment":{
         "method":"LOW_COST",
         "name":"Sr Comprador Teste",
         "phones":[
            {
               "number":"21114740",
               "ddd":"16",
               "ddi":"55"
            }
         ],
         "receiver_address":{
            "complement":"AP 201",
            "city":"Rio de Janeiro",
            "state":"RJ",
            "country":"BRA",
            "zip_code":"21241140",
            "street_number":"174",
            "street_name":"Rua Jupiter"
         }
      },
      "connections":[
         {
            "from":"RAO",
            "to":"SAO",
            "flight_date":"2020-01-02T20:15:00"
         }
      ],
      "gift":"false",
      "browser":{
         "email":"compradorteste@live.com",
         "agent":"Chrome",
         "cookies_accepted":"false",
         "host_name":"Teste",
         "ip_address":"200.190.150.350"
      },
      "items":[
         {
            "title":"ItemTeste",
            "quantity":"1",
            "id":"1487337308522",
            "risk":"HIGH",
            "hedge":{
               "time":"NORMAL",
               "host":"OFF",
               "nonSensical":"OFF",
               "obscenities":"OFF",
               "phone":"OFF",
               "velocity":"HIGH"
            },
            "passenger":{
               "name":"Comprador accept",
               "email":"compradorteste@live.com",
               "rating":"ADULT",
               "phone":{
                  "number":"999994444",
                  "ddd":"11",
                  "ddi":"55"
               },
               "legal_document":"1234567890",
               "customer_class":"Gold"
            },
            "unit_price":"1000",
            "category_id":"other",
            "gift_category":"OFF"
         }
      ],
      "extra_param":{
         "acquirer_params":[
            {
               "key":"95",
               "value":"Eu defini isso"
            }
         ]
      },
      "anti_fraud":"enabled_before_auth",
      "anti_fraud_institution":"AUTHORIZER",
      "anti_fraud_criteria":"ALWAYS",
      "finger_print_id":"074c1ee676ed4998ab66491013c565e2",
      "returns_accepted":"true",
      "journey_type":"OUTWARD"
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "status":"NOV",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"12042142155",
      "merchant_usn":"12042142155",
      "amount":"1000"
   }
}

Criação de pagamento com análise de risco (utlizando o anti fraude Konduto)

Para mais informações verifique nossa seção específica da Konduto

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"2423423434",
   "order_id":"2432342343",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"1300",
   "additional_data":{
      "anti_fraud":"enabled_before_auth",
      "visitor_id":"XKhas09jcks",
      "items":[
         {
            "title":"title1",
            "quantity":"1",
            "unit_price":"1111",
            "description":"description1",
            "id":"id1",
            "discount_amount":"111",
            "sku":"sku1",
            "creation_date":"11/01/2011"
         }
      ],
      "payer":{
         "name":"Marcos",
         "surname":"da Silva",
         "email":"marocs@dasilva.com",
         "born_date":"1990-01-01T11:11:11",
         "creation_date":"02/03/2004",
         "is_new_client":"true",
         "is_vip_client":"true",
         "phones":[
            {
               "number":"333333333",
               "ddd":"22",
               "ddi":"11"
            },
            {
               "number":"666666666",
               "ddd":"55",
               "ddi":"44"
            }
         ],
         "identification_number":"47764543004"
      },
      "shipment":{
         "name":"Fernando",
         "surname":"Bezerra",
         "address":{
            "zip_code":"98764312",
            "street_number":"987",
            "street_name":"Rua Shipment",
            "complement":"ap. 587",
            "city":"São Shipment",
            "state":"MA",
            "country":"BRA"
         }
      },
      "passengers":[
         {
            "name":"Miguel",
            "last_name":"Herrera",
            "frequent_flyer_card":"frequentFlyerCard",
            "legal_document_type":"1",
            "legal_document":"12312312312",
            "birth_date":"1980-07-28T10:40:00",
            "customer_class":"customerClass",
            "nationality":"BRA",
            "is_frequent_traveler":"true",
            "is_with_special_needs":"true"
         }
      ],
      "connections":[
         {
            "company":"Verde",
            "class":"first",
            "from":"GRU",
            "to":"CGH",
            "departure_date":"2023-09-07T07:09:00",
            "journey_type":"OUTWARD",
            "origin_city":"San Juan",
            "destination_city":"Homero Lopez",
            "class_code":"VIP"
         },
         {
            "company":"Rosa",
            "class":"economy",
            "from":"BSB",
            "to":"VCP",
            "departure_date":"2022-10-21T16:39:00",
            "journey_type":"RETURN",
            "origin_city":"San Pablo",
            "destination_city":"Juanito Cruz",
            "class_code":"ECONOMY"
         }
      ],
      "hotel_reservations":[
         {
            "hotel":"Hotel Green Tree",
            "address":{
               "zip_code":"83392019",
               "street_number":"529",
               "street_name":"Rua Hoteleira",
               "complement":"ap. 019",
               "city":"San Hotel",
               "state":"AC",
               "country":"EN"
            },
            "rooms":[
               {
                  "number":"902",
                  "code":"ROOM902",
                  "type":"King Size",
                  "check_in_date":"2020-01-09T12:30:00",
                  "check_out_date":"2020-01-19T13:00:00",
                  "number_of_guests":"1",
                  "board_basis":"Vegan",
                  "guests":[
                     {
                        "name":"José Aníbal",
                        "document":"98798798712",
                        "document_type":"cpf",
                        "birth_date":"12/03/1970",
                        "nationality":"BRA"
                     }
                  ]
               }
            ],
            "category":"categoryhotel"
         }
      ],
      "billing_data":{
         "address":{
            "zip_code":"12341234",
            "street_number":"666",
            "street_name":"Rua Billing",
            "complement":"ap. 2369",
            "city":"São Billing",
            "state":"AM",
            "country":"BRA"
         }
      },
      "travel":{
         "transport_type":"flight",
         "expiration_date":"2022-02-14T01:30:00"
      },
      "discount_info":"Informações de desconto",
      "events":[
         {
            "name":"Evento de Rock",
            "date":"2021-11-22T09:28:00",
            "type":"show",
            "subtype":"music",
            "venue":{
               "name":"Debicard Hall",
               "street_name":"Rua do Evento",
               "street_number":"928",
               "city":"Jardinópolis",
               "state":"MS",
               "country":"DO",
               "capacity":"300"
            },
            "tickets":[
               {
                  "id":"12h374612h4h",
                  "category":"social",
                  "section":"Seção 1",
                  "premium":"true",
                  "attendee":{
                     "name":"Daniel Almeida",
                     "document":"71728293945",
                     "document_type":"other",
                     "birth_date":"03/10/1990"
                  }
               }
            ]
         }
      ]
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "status":"NOV",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"12042142155",
      "merchant_usn":"2432342343",
      "amount":"1300"
   }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de criação de transações:

Parâmetro	Descrição	Formato	Obrigatório
merchant_usn	Número sequencial único para cada pedido, criado pela loja. O NSU será utilizado em toda a comunicação com a loja, de forma a identificar o pedido. Como se trata de uma possível chave para acesso do lado da loja, apesar de ser opcional para o e-SiTef, é fortemente recomendado que o campo seja formatado e enviado pela aplicação da loja.	< 12 N	NÃO
order_id	Código do pedido para ser exibido ao comprador, definido pelo lojista. É aconselhável que seja diferente a cada pedido para que facilite a rastreabilidade. Se a integração da Loja com as redes adquirentes (Cielo, Redecard, etc) for com e-SiTef e SiTef, o campo orderId que tem o tamanho máximo de 40 caracteres, será reduzido a 12 caracteres, devido a uma restrição do SiTef. Essa redução será realizada mantendo os caracteres da esquerda para direita (ex.: se um código de pedido inserido for 12345678901234567890 no e-SiTef, no SiTef ele será apenas 123456789012).	< 40 AN	NÃO
installments	Número de parcelas. Envie ‘1’ para transações à vista.	< 2 N	SIM
installment_type	Tipo de financiamento do parcelamento: valor 3 = parcelamento com juros da administradora do cartão. valor 4 = parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista). Valor 6 = parcelamento com juros da administradora (IATA). valor 7 = parcelamento realizado pela loja e sem juros (IATA). O parcelamento IATA é utilizado somente por empresas do seguimento de transporte aéreo.	< 2 N	SIM
authorizer_id	Código da autorizadora no e-SiTef. Saiba mais.	< 3 N	NÃO
amount	Valor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto.	< 12 N	SIM
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais	< 30 AN	NÃO
authorizer_authentication	Este campo deve ser enviado com valor true caso se deseje um pagamento com autenticação. Essa funcionalidade só está disponível para Cielo e-Commerce e e.Rede REST.	< 5 T/F	NÃO
encrypted_card	Este campo deve ser enviado com valor true caso o número do cartão a ser enviado na próxima etapa do fluxo use a criptografia do SiTef. A opção de envio do cartão criptografado só será possível com roteamento via SiTef e é necessário a configuração prévia do SiTef em questão	< 5 T/F	NÃO
iata	Este elemento contém campos específicos de transações IATA.
departure_tax	Taxa de embarque em centavos.	< 12 N	SIM apenas para installment_type = 6 ou 7
first_installment	Entrada em transações IATA em centavos. Funcionalidade disponível apenas para o adquirente Rede.	< 12 N	NÃO
schedule	O envio do elemento schedule implica no uso da funcionalidade de agendamento de recorrência. Nenhum de seus campos é obrigatório caso se deseje apenas fazer um pagamento simples.
amount	Valor em centavos dos pagamentos recorrentes. Caso esse campo não seja enviado, será utilizado o valor do pagamento.	< 12 N	SIM
initial_date	Data de execução do primeiro pagamento agendado. Essa data deve ter pelo menos dois dias à frente do dia atual e dias 29, 30 e 31 nunca são permitidos. O formato da data a ser seguido é: DD/MM/AAAA Exemplo: 20/04/2021	= 10 D	SIM
number_of_times	Número de pagamentos agendados a serem executados. Caso esse campo não seja enviado, agendamento ficará ativo infinitamente.	< 3 N	NÃO
interval	Intervalo em meses entre cada pagamento agendado. Caso esse campo não seja enviado, assume-se o valor 1 (execuções mensais).	< 2 N	NÃO
do_payment_now	Enviar esse campo com valor false caso se deseje realizar um agendamento sem pagamento imediato. No caso deste campo ser ausente ou para qualquer valor diferente de false, será criado um agendamento COM pagamento imediato.	< 5 T/F	NÃO
installments	Número de parcelas de cada pagamento agendado. Caso esse campo não seja enviado, assume-se o valor 1.	<2 N	NÃO
installment_type	Tipo de financiamento do parcelamento de cada pagamento agendado: Valor 3 = parcelamento com juros da administradora do cartão. Valor 4 = parcelamento realizado pela loja e sem juros. (Adotar este valor como padrão/default para transações à vista). Caso esse campo não seja enviado, assume-se o valor 4.	< 2 N	NÃO
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais	< 30 AN	NÃO
show_times_invoice	Para agendamentos por tempo finito, enviar esse campo com valor true caso se deseje acrescentar ao final do campo soft_descriptor o número de execuções/total de execuções (exemplo: Assinatura 3/12).	< 5 T/F	NÃO
additional_data	Elemento para envio de dados adicionais.
postpone_confirmation	Esse campo deve ser enviado com valor true caso se deseje um pagamento com confirmação tardia.	< 5 T/F	NÃO
financing_plan	Código de plano de financiamento. Necessário apenas para pagamentos parcelados com juros roteados pela Via Certa Financiadora via SiTef.	< 4 N	COND.
additional_data.payer	Elemento para envio de dados referentes ao comprador.
identification_number	Documento de identificação do comprador (CPF/RG).	< 20 AN	NÃO
store_identification	Identificação do comprador para armazenamento de cartão. Esta identificação deve ser única para cada usuário da loja. Mas atenção, essa garantia de unicidade é de total responsabilidade da loja, o e-SiTef não realizará nenhuma validação.	< 20 AN	SIM para agendamento
additional_data.merchant	Elemento para envio de dados referentes ao lojista.
email	Endereço de e-mail do lojista.	< 1024 AN	NÃO
additional_data. extra_param.prefixes	Elemento para envio de prefixos do SiTef, como CICLOS, CPLANO e VLRADD. Caso o prefixo enviado não seja suportado pelo cartão enviado, o e-SiTef invalidará a transação, impedindo que se dê uma falsa impressão do uso de uma determinada funcionalidade. Exemplo: { "key" : "value" } -> { "CICLOS" : "01" }
key	Nome do prefixo.	< 1024 AN	NÃO
value	Valor do prefixo.	< 1024 AN	NÃO

Na tabela abaixo está a descrição dos parâmetros adicionais que devem ser enviados num pagamento com análise de fraude (por enquanto disponível apenas para Cielo e-Commerce):

Parâmetro	Descrição	Formato	Obrigatório
	additional_data
anti_fraud_institution	Instituição que efetuará a análise de fraude para a loja. Deve ser enviado com o valor ‘AUTHORIZER’.	= 10 AN	SIM para análise de fraude
anti_fraud	Habilita o serviço de análise de fraude. Valores permitidos: enabled_before_auth – a análise de fraude será realizada ANTES da autorização do pagamento. Caso a análise seja rejeitada, o pagamento não será iniciado. enabled_after_auth – a análise de fraude será realizada APÓS a autorização do pagamento. Caso a análise seja rejeitada, o pagamento que já foi autorizado será cancelado.	< 19 AN	SIM para análise de fraude
anti_fraud_criteria	Critério de execução da análise de fraude. Valores permitidos: ON_SUCCESS – só realiza a análise se tiver sucesso na transação. ALWAYS – sempre realiza a análise.	< 10 AN	NÃO
finger_print_id	Identificador utilizado para cruzar informações obtidas pelo Browser do internauta com os dados enviados para análise. Maiores detalhes em http://apidocs.braspag.com.br/#CriandoumavendacomAnalisedeFraude.	< 50 AN	NÃO
gift	Indica se o pedido é para presente ou não.	< 5 T/F	NÃO
returns_accepted	Define se devoluções são aceitas para o pedido.	< 5 T/F	NÃO
journey_type	Tipo de viagem. Valores permitidos: ROUND_TRIP – ida e volta. OUTWARD – ida. RETURN – volta.	< 10 AN	NÃO
	additional_data.payer
name	Nome do comprador. Obs.: a concatenação de nome com o sobrenome não pode ultrapassar 255 caracteres.	< 200 AN	NÃO
surname	Sobrenome do comprador. Obs.: a concatenação do nome com o sobrenome não pode ultrapassar 255 caracteres.	< 200 AN	NÃO
email	E-mail do comprador.	< 255 AN	NÃO
born_date	Data de nascimento do comprador, no formato YYYY-MM-DDTHH:MM:SS. Ex.: 1991-01-02T08:30:00.	= 19 AN	NÃO
adress_street_name	Endereço do comprador.	< 255 AN	NÃO
adress_street_number	Número do endereço do comprador.	< 15 AN	NÃO
adress_street_complement	Complemento do endereço do comprador.	< 50 AN	NÃO
adress_zip_code	CEP do endereço do comprador. Ex.: 21241140.	< 9 AN	NÃO
city	Cidade do endereço do comprador.	< 50 AN	NÃO
state	Estado do endereço do comprador. Ex.: SP.	= 2 AN	NÃO
address_country	País do endereço do comprador. Ex.: BRA.	< 35 AN	NÃO
	additional_data.shipment.receiver_address
street_name	Endereço de entrega.	< 255 AN	NÃO
street_number	Número do endereço de entrega.	< 15 AN	NÃO
complement	Complemento do endereço de entrega.	< 50 AN	NÃO
zip_code	CEP do endereço de entrega. Ex.: 21241-140.	< 9 AN	NÃO
city	Cidade do endereço de entrega.	< 50 AN	NÃO
state	Estado do endereço de entrega.	= 2 AN	NÃO
country	País do endereço de entrega seguindo a AN 3166-1. Ex.: BRA	= 3 AN	NÃO
	additional_data.browser
cookies_accepted	Identifica se o browser do cliente aceita cookies. Enviar true caso positivo.	< 5 T/F	NÃO
email	E-mail registrado no browser do comprador.	< 100 AN	NÃO
host_name	Nome do host onde o comprador estava antes de entrar no site da loja.	< 60 AN	NÃO
ip_address	Endereço IP do comprador. É altamente recomendável o envio deste campo.	< 15 AN	NÃO
agent	Nome do browser utilizado pelo comprador. Ex.: Chrome.	< 40 AN	NÃO
	additional_data.items[]
gift_category	Campo que avaliará os endereços de cobrança e entrega para diferentes cidades, estados ou países. Pode assumir os seguintes valores: OFF – Ignora a análise de risco para endereços divergentes. YES – Em caso de divergência entre endereços de cobrança e entrega, marca com risco pequeno. NO – Em caso de divergência entre endereços de cobrança e entrega, marca com risco alto.	< 3 AN	NÃO
risk	Nível do risco do produto. Pode assumir os seguintes valores: LOW – O produto tem um histórico de poucos chargebacks. NORMAL – O produto tem um histórico de chargebacks considerado normal. HIGH – O produto tem um histórico de chargebacks acima da média.	< 6 AN	NÃO
title	Nome do produto.	< 255 AN	NÃO
quantity	Quantidade do produto a ser adquirido.	< 15 N	NÃO
id	Código comerciante identificador do produto.	< 255 AN	NÃO
unit_price	Preço unitário do produto em centavos.	< 15 N	NÃO
category_id	Tipo do produto. Pode assumir os seguintes valores: art, baby, coupon, donation, computing, camera, video_game, television, car_electronic, electronic, automotive, entertainment, fashion, game, home, musical, phone, service, learning, ticket, travel, virtual_good, physical, other, adult_content, gift_certificate, handling, shipping, shipping_and_handling ou subscription.	< 21 AN	NÃO
	additional_data.items[].hedge
time	Nível de importância da hora do dia do pedido do cliente. Pode assumir os seguintes valores: LOW – Baixa importância no horário do dia em que foi feita a compra, para a análise de risco. NORMAL – Média importância no horário do dia em que foi feita a compra, para a análise de risco. HIGH – Alta importância no horário do dia em que foi feita a compra, para a análise de risco. OFF – O horário da compra não afeta a análise de risco.	< 6 AN	NÃO
host	Nível de importância do e-mail e endereços IP dos clientes em risco de pontuação. Pode assumir os seguintes valores: LOW – Baixa importância do e-mail e endereço IP na análise de risco. NORMAL – Média importância do e-mail e endereço IP na análise de risco. HIGH – Alta importância do e-mail e endereço IP na análise de risco. OFF – E-mail e endereço IP não afetam a análise de risco.	< 6 AN	NÃO
non_sensical	Nível dos testes realizados sobre os dados do comprador com pedidos recebidos sem sentido. Pode assumir os seguintes valores: LOW – Baixa importância da verificação feita sobre o pedido do comprador, na análise de risco. NORMAL – Média importância da verificação feita sobre o pedido do comprador, na análise de risco. HIGH – Alta importância da verificação feita sobre o pedido do comprador, na análise de risco. OFF – Verificação do pedido do comprador não afeta a análise de risco.	< 6 AN	NÃO
obscenities	Nível de obscenidade dos pedidos recebidos. Pode assumir os seguintes valores: LOW – Baixa importância da verificação sobre obscenidades do pedido do comprador, na análise de risco. NORMAL – Média importância da verificação sobre obscenidades do pedido do comprador, na análise de risco. HIGH – Alta importância da verificação sobre obscenidades do pedido do comprador, na análise de risco. OFF – Verificação de obscenidade no pedido do comprador não afeta a análise de risco.	< 6 AN	NÃO
phone	Nível dos testes realizados com os números de telefones. Pode assumir os seguintes valores: LOW – Baixa importância nos testes realizados com números de telefone. NORMAL – Média importância nos testes realizados com números de telefone. HIGH – Alta importância nos testes realizados com números de telefone. OFF – Testes de números de telefone não afetam a análise de risco.	< 6 AN	NÃO
velocity	Nível de importância de frequência de compra do cliente. Pode assumir os seguintes valores: LOW – Baixa importância no número de compras realizadas pelo cliente nos últimos 15 minutos. NORMAL – Média importância no número de compras realizadas pelo cliente nos últimos 15 minutos. HIGH – Alta importância no número de compras realizadas pelo cliente nos últimos 15 minutos. OFF – A frequência de compras realizadas pelo cliente não afeta a análise de fraude.	< 6 AN	NÃO
	additional_data.items[].passenger
email	E-mail do passageiro.	< 255 AN	NÃO
legal_document	Id do passageiro a quem o bilhete foi emitido.	< 32 AN	NÃO
name	Nome do passageiro.	< 120 AN	NÃO
rating	Classificação do passageiro. Pode assumir os seguintes valores: ADULT – Passageiro adulto. CHILD – Passageiro criança. INFANT – Passageiro infantil. YOUTH – Passageiro adolescente. STUDENT – Passageiro estudante. SENIOR_CITIZEN – Passageiro idoso. MILITARY – Passageiro militar.	< 14 AN	NÃO
customer_class	Classificação da empresa aérea. Pode-se usar valores como Gold ou Platina.	< 32 AN	NÃO
	additional_data.items[].passenger.phone
ddi	Código do país do telefone do passageiro. Para pedidos fora dos E.U.A., é recomendável o envio deste campo.	< 3 N	NÃO
ddd	Código da área do telefone do passageiro.	< 3 N	NÃO
number	Número de telefone do passageiro.	< 9 N	NÃO
	additional_data.extra_param.acquirer_params[]
key	Id das informações adicionais a serem enviadas. Maiores detalhes sobre o envio desse campo em https://developercielo.github.io/Webservice-3.0/#merchant-defined-data.	< 1024 N	NÃO
value	Valor das informações adicionais a serem enviadas.	< 1024 AN	NÃO
	additional_data.shipment
name	Nome do destinatário da entrega.	< 255 AN	NÃO
method	Tipo de serviço de entrega do produto. Pode assumir os seguintes valores: SAME_DAY – Serviço de entrega no mesmo dia. ONE_DAY – Serviço de entrega noturna ou no dia seguinte. TWO_DAY – Serviço de entrega em dois dias. THREE_DAY – Serviço de entrega em três dias. LOW_COST – Serviço de entrega de baixo custo. PICKUP – Produto retirado na loja. OTHER – Outro método de entrega. NONE – Sem serviço de entrega, pois é um serviço ou assinatura.	< 9 AN	NÃO
	additional_data.shipment.phones[]
ddi	Código do país do telefone do destinatário da entrega. Para pedidos fora dos E.U.A., é recomendável o envio deste campo.	< 3 N	NÃO
ddd	Código da área do telefone do destinatário da entrega.	< 3 N	NÃO
number	Número de telefone do destinatário da entrega.	< 9 N	NÃO
	additional_data.connections[]
flight_date	Data, hora e minuto de partida do voo no formato YYYY-MM-DDTHH:MM:SS. Ex.: 1991-01-02T08:30:00.	= 19 AN	NÃO
from	Código do aeroporto do ponto de origem da viagem. Ex.: CGH.	= 3 AN	NÃO
to	Código do aeroporto do ponto de destino da viagem. Ex.: GYN.	= 3 AN	NÃO

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 201. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de criação de transações:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0 significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	payment
status	Status da transação de pagamento no e-SiTef. Saiba mais.	= 3 AN
nit	Identificador da transação de pagamento no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N
amount	Valor da compra especificado pela loja (em centavos) na criação da transação.	< 12 N
	schedule
sid	Identificador da transação de agendamento no e-SiTef.	= 64 AN
amount	Valor dos pagamentos agendados especificado pela loja (em centavos) na criação da transação.	< 12 N
status	Status do agendamento no e-SiTef. Saiba mais.	= 3 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N

Serviço de efetivação de pagamento

Após consumir o serviço de criação de transação e obter um NIT, é possível prosseguir para a próxima etapa do fluxo: a chamada ao serviço de efetivação de pagamento. Esta operação deve ser consumida também em fluxos de pagamento com agendamento. Nesse caso, o e-SiTef garante que o agendamento só será ativado caso o pagamento seja confirmado.

Detalhes da chamada

• Recurso: /v1/payments/{nit}
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de efetivação de pagamento utilizando a ferramenta cURL.

Pagamento com captura automática

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"123"
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13034649671",
      "customer_receipt":"====CUPOM COMPRADOR====",
      "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"13/07/2017T15:52",
      "authorization_number":"132030",
      "merchant_usn":"13034649671",
      "esitef_usn":"170713097340300",
      "sitef_usn":"132030",
      "host_usn":"999132030",
      "payment_date":"13/07/2017T15:52",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   }
}

Pagamento com confirmação tardia

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"123"
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"PPC",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13035748930",
      "customer_receipt":"==== CUPOM COMPRADOR ====",
      "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"13/07/2017T15:58",
      "authorization_number":"132031",
      "merchant_usn":"13035748930",
      "esitef_usn":"170713097340340",
      "sitef_usn":"132031",
      "host_usn":"999132031   ",
      "payment_date":"13/07/2017T15:58",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   }
}

Pagamento com agendamento

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"123"
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13040222890",
      "customer_receipt":"==== CUPOM COMPRADOR ====",
      "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"13/07/2017T16:03",
      "authorization_number":"132032",
      "merchant_usn":"13040222890",
      "esitef_usn":"170713097340360",
      "sitef_usn":"132032",
      "host_usn":"999132032   ",
      "payment_date":"13/07/2017T16:03",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   },
   "schedule":{
      "status":"ATV",
      "sid":"qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
      "schedule_usn":"170713000000020",
      "amount":"900",
      "initial_date":"03/08/2017",
      "next_date":"03/08/2017",
      "number_of_times":"3",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   }
}

Pagamento com cartão armazenado

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "token":"g16hJtpdU6XEN3FP-ApQ9pKTGII5Fa9Y12tRX-qfyC-+BUCV5OaFn807zwwOR6rDtKoRnIJg0QbikaJqJqosyQ=="  
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13034649671",
      "customer_receipt":"====CUPOM COMPRADOR====",
      "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"13/07/2017T15:52",
      "authorization_number":"132030",
      "merchant_usn":"13034649671",
      "esitef_usn":"170713097340300",
      "sitef_usn":"132030",
      "host_usn":"999132030",
      "payment_date":"13/07/2017T15:52",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   }
}

Pagamento com planos de financiamento Via Certa Financiadora

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "expiry_date":"1222",
      "security_code":"123",
      "number":"5555555555555555"
   },
   "acquirer":{
      "financing_plan":"0302"
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"21105507366",
      "customer_receipt":"====CUPOM COMPRADOR====",
      "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
      "authorizer_id":"313",
      "acquirer_id":"1313",
      "acquirer_name":"Via Certa Financiadora",
      "authorizer_date":"21/11/2017T10:55",
      "authorization_number":"211982",
      "merchant_usn":"21105507366",
      "esitef_usn":"171121108905101",
      "sitef_usn":"211982",
      "host_usn":"999211982   ",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"0000000000000313",
      "payment_date":"21/11/2017T10:55"
   }
}

Pagamento com prefixos

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "expiry_date":"1222",
      "security_code":"123",
      "number":"5555555555555555"
   },
   "acquirer":{
      "prefixes":{
         "TRAT":"1"
      }
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"21105507366",
      "customer_receipt":"====CUPOM COMPRADOR====",
      "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"21/11/2017T10:55",
      "authorization_number":"211981",
      "merchant_usn":"21105507366",
      "esitef_usn":"171121108905100",
      "sitef_usn":"211981",
      "host_usn":"999211981   ",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005",
      "payment_date":"21/11/2017T10:55"
   }
}

Pagamento split para roteamentos BIN e Sipag via SiTef

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"123"
   },
   "acquirer":{
      "submerchant_split":[
         {
            "submerchant_code":"empresa01",
            "submerchant_amount":"10"
         },
         {
            "submerchant_code":"empresa02",
            "submerchant_amount":"20"
         },
         {
            "submerchant_code":"empresa03",
            "submerchant_amount":"20"
         },
         {
            "submerchant_code":"empresa04",
            "submerchant_amount":"30"
         },
         {
            "submerchant_code":"empresa05",
            "submerchant_amount":"30"
         }
      ]
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code": "000",
      "authorizer_message": "APROVADA",
      "status": "CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "authorizer_id": "1",
      "acquirer_id": "229",
      "acquirer_name": "Bin",
      "authorizer_date": "29/03/2019T13:26",
      "authorization_number": "000058",
      "merchant_usn": "20180809",
      "esitef_usn": "190329026585100",
      "sitef_usn": "000058",
      "host_usn": "003000058   ",
      "amount": "13000",
      "payment_type": "C",
      "issuer": "1",
      "authorizer_merchant_id": "000000000000000",
      "payment_date": "29/03/2019T13:26"
   }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de efetivação de pagamento:

Parâmetro	Descrição	Formato	Obrigatório
authorizer_id	Código da autorizadora no e-SiTef. Saiba mais. Caso este campo não tenha sido enviado na etapa de criação da transação, ele passa a ser obrigatório ao consumir o serviço de efetivação do pagamento.	< 3 N	COND.
customer_postal_code	Código postal (CEP no Brasil) do usuário. Este deve ser enviado para transações roteadas iCards via SiTef, caso a coleta deste for indicada no serviço de consulta de cartão pelo campo is_customer_postal_code_required.	< 8 N	COND.
mcc	O MCC (Merchant Category Code) é um código que classifica um negócio pelo tipo de bens ou produtos fornecidos.	< 4 N	NÃO
subacquirer_merchant_id	Identificação da loja na subadquirente.	< 22 N	NÃO
card	Dados do cartão.
number	Número do cartão do comprador (PAN).	< 19 N	SIM
expiry_date	Data de vencimento do cartão no formato MMAA. Sua obrigatoriedade depende do adquirente escolhido. Na maioria dos casos, esse campo é obrigatório.	= 4 N	COND.
security_code	Código de segurança. Este campo pode não ser obrigatório se a empresa possuir um acordo no contrato firmado com as redes adquirentes, somente para o pagamento de determinados seguimentos. Importante: um pagamento com agendamento implica no armazenamento dos dados do cartão do comprador no ambiente do e-SiTef. Porém, por questões de segurança, o código de segurança não pode ser armazenado. Por isso, os pagamentos agendados sempre serão executados sem o envio do código de segurança.	< 5 N	COND.
holder	Nome do portador do cartão. Obrigatório apenas para pagamentos com e-Rede, GetNet WS e VR (SmartNet).	< 30 AN	COND.
token	HASH de um cartão armazenado no e-SiTef. Não é permitido enviar um número de cartão aberto (campo number) e um cartão armazenado (campo token) na mesma requisição.	= 88 AN	NÃO
wallet_transaction_id	ID de uma transação de carteiras digitais. Por enquanto, essa funcionalidade está disponível apenas para as autorizadoras Visa Checkout, VEE (via CardSE-SiTef) e Google Pay. Não é permitido enviar um número de cartão aberto (campo number), um cartão armazenado (campo token) e um wallet_transaction_id na mesma requisição.	< 25 AN	NÃO
initial_wallet_transaction_id	Informa se o Wallet ID (wallet_transaction_id) está sendo utilizado pela primeira vez. Se for a primeira vez, enviar true, caso contrário enviar false.	< 5 T/F	NÃO
external_authentication	Este elemento recebe campos de resultados de autenticação MPI.
eci	Eletronic Commerce Indicator – indica o nível de segurança da transação com autenticação do dono do cartão	< 3 N	NÃO
xid	Identificador da transação de autenticação do dono do cartão, feita em serviço externo ao e-SiTef	< 40 N	NÃO
cavv	Cardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão.	< 40 N	NÃO
acquirer	Dados específicos necessários dependendo da adquirente/roteamento.
financing_plan	Código de plano de financiamento. Necessário apenas para pagamentos parcelados com juros roteados pela Via Certa Financiadora via SiTef.	< 4 N	NÃO
special_code	Código de uso geral da Conductor/Renner.	< 6 N	NÃO
recurrency	Flag que define se o pagamento é ou não recorrente. Aceito para todos os roteamentos via SiTef, Cielo e-Commerce, Stone WS, Global Payments WS, SafraPay, e.Rede REST e GetnetWS. No caso de recorrência via Stone WS, é obrigatório o envio adicional de apenas um dos campos abaixo, is_first_recurring OU is_subsequent_recurring.	< 5 T/F	NÃO
recurrency_tid	TID da primeira transação da recorrência. Identificador que diferencia a primeira recorrência das subsequentes. Só é utilizado quando for uma recorrência. Campo utilizado somente no roteamento e.Rede REST para as bandeiras Visa e Mastercard e roteamento GetnetWS.	< 18 AN	NÃO
is_first_recurring	Flag usada apenas para roteamento StoneWS. Indica que a transação é a primeira de uma série de transações recorrentes.	< 5 T/F	COND.
is_subsequent_recurring	Flag usada apenas para roteamento StoneWS. Indica que a transação é a segunda ou n-ésima de uma série de transações recorrentes, onde n > 2.	< 5 T/F	COND.
product_code	Códido de produto. É obrigatório em roteamento via Marisa.	< 6 N	COND.
terminal	Terminal SiTef que se deseja usar. Se não for enviado, o e-SiTef gerará um terminal aleatório.	= 14 N	Não
company_code	Código de empresa SiTef que se deseja usar. Se não for enviado, o e-SiTef enviará o código de empresa cadastrado na loja.	= 8 N	Não
acquirer.vouchers_filter[]	Filtro de Vouchers - Escolha dos vouchers que não serão aceitos. Opções de "Vouchers": 01 - Alimentação, 02 - Refeição 03 - Cultura, 04 - Combustível, 05 - Benefício. Exemplo: Não se quer aceitar Vouchers: Cultura, Combustível, Benefício. Deve enviar: "vouchers_filter": [ "03", "04", "05" ]
acquirer.prefixes	Elemento para envio de prefixos do SiTef, como CICLOS, CPLANO e VLRADD. Caso o prefixo enviado não seja suportado pelo cartão enviado, o e-SiTef invalidará a transação, impedindo que se dê uma falsa impressão do uso de uma determinada funcionalidade. Exemplo: { "key" : "value" } -> { "CICLOS" : "01" }
key	Nome do prefixo.	< 1024 AN	NÃO
value	Valor do prefixo.	< 1024 AN	NÃO
acquirer.submerchant_split[]	Consiste em um array para pagamentos split, exclusivos para roteamentos BIN e Sipag, ambos via SiTef. Permite a divisão de partes do valor total do pagamento entre outras empresas. O máximo de itens permitido neste array é de 5 itens. Cada item é composto pelos campos submechant_code e submerchant_amount.
submerchant_code	código de estabelecimento BIN/Sipag	< 51 AN	NÃO
submerchant_amount	valor de transação referente ao estabelecimento	< 12 N	NÃO

ATENÇÃO: Os parâmetros terminal e company_code deverão ser usados somente para roteamentos via SiTef e devem ser enviados simultaneamente.
É necessário também solicitar à equipe de atendimento do e-SiTef a permissão Permite envio de Empresa e Terminal Sitef via REST.

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 201. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de efetivação de pagamento:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0 significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	payment
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
status	Status da transação de pagamento no e-SiTef. Saiba mais.	= 3 AN
nit	Identificador da transação de pagamento no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N
amount	Valor da compra especificado pela loja (em centavos) na criação da transação.	< 12 N
sitef_usn	Número sequencial único da transação de pagamento no SiTef.	= 6 N
esitef_usn	Número sequencial único da transação de pagamento no e-SiTef.	= 15 N
customer_receipt	Cupom (via cliente).	< 4000 AN
merchant_receipt	Cupom (via estabelecimento).	< 4000 AN
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N
acquirer_id	Código do adquirente utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente utilizado na transação.	< 100 AN
authorizer_date	Data de efetivação do pagamento retornada pelo autorizador no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
authorization_number	Número de autorização.	< 6 AN
host_usn	NSU da autorizadora.	< 15 AN
tid	ID da transação no adquirente. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
eci	Eletronic Commerce Indicator (indicador do nível de segurança da transação do pagamento via Cielo e-Commerce).	< 3 AN
payment_date	Data de efetivação do pagamento no e-SiTef no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
xid	Campo XID retornado em autenticações 3DS ou certos adquirentes.	< 40 AN
authentication_url	URL de autenticação retornada em fluxos de pagamento com autenticação. Disponível apenas para Cielo e-Commerce.	< 56 AN
balance	Saldo disponível após pagamentos com cartões tipo Gift.	< 12 N
recurrency_tid	Id de transação (TID) da bandeira, referente à primeira transação da recorrência. Só é retornado quando for uma recorrência. Campo utilizado somente no roteamento e.Rede REST para as bandeiras Visa e Mastercard.	< 16 AN
	payment.analysis
code	Código de resposta da operação de análise de fraude.	< 4 N
message	Mensagem de resposta da operação de análise de fraude.	< 200 AN
status	Status da transação de análise de fraude do e-SiTef. Este campo pode assumir os seguintes valores: NOV – Nova. EXP – Expirada. ACC – Aceita REJ – Rejeitada REV – Em revisão INV – Inválida	= 3 AN
	schedule
status	Status do agendamento no e-SiTef. Saiba mais.	= 3 AN
sid	Identificador da transação de agendamento no e-SiTef.	= 64 AN
schedule_usn	Número sequencial único do agendamento no e-SiTef.	= 15 N
authorizer_id	Código da autorizadora a ser utilizada nos pagamentos agendados.	= 4 N
amount	Valor dos pagamentos agendados especificado pela loja (em centavos) na criação da transação.	< 12 N
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N
initial_date	Data de execução do primeiro pagamento agendado no formato DD/MM/AAAA.	= 10 D
next_date	Data de execução do próximo pagamento agendado no formato DD/MM/AAAA.	= 10 D
number_of_times	Número total de pagamentos agendados.	< 3 N
installments	Número de parcelas a ser utilizado nos pagamentos agendados.	< 2 N
installment_type	Tipo de financiamento a ser utilizado nos pagamentos agendados.	< 2 N
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador.	< 30 AN
show_times_invoice	Para agendamentos por tempo finito, caso esse campo tenha valor true acrescenta ao final do campo soft_descriptor o número de execuções/total de execuções (exemplo: Assinatura 3/12).	< 5 T/F
terminal_id	Código do terminal utilizada na transação	< 8 AN

Serviço de confirmação de pagamento

Após criar e efetuar um pagamento pendente de confirmação, o lojista deve chamar o serviço de confirmação para confirmar ou desfazer o pagamento utilizando o mesmo NIT obtido na primeira etapa do fluxo.

Detalhes da chamada

• Recurso: /v1/payments/{nit}
• Método HTTP: PUT
• Formato da requisição: query string
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM

Exemplo

Abaixo está um exemplo de chamada do serviço de confirmação de pagamento utilizando a ferramenta cURL.

Requisição:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr?confirm=true"
--header "merchant_id:xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "status":"CON"
   }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de confirmação de pagamento:

Parâmetro	Descrição	Formato	Obrigatório
confirm	Este campo deve ser enviado com o valor true caso se deseje confirmar a transação, ou false, caso queira desfazer o pagamento.	< 5 T/F	SIM
amount	Valor a ser capturado. Deve ser menor ou igual ao autorizado. Confirmações com valor menor só são suportadas por roteamentos não-SiTef. Caso este campo não seja enviado, é utilizado o valor total da transação.	< 12 N	NÃO

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de confirmação de pagamento:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0 significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	payment
status	Status da transação de pagamento no e-SiTef. Saiba mais.	= 3 AN
payment_date	Data de efetivação do pagamento no e-SiTef no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
host_usn	NSU da autorizadora.	< 15 AN

Serviço de consulta de transação

Estes serviços podem ser chamados para obter os dados da transação de pagamento, cancelamento ou agendamento. É essencial o uso dessa operação em casos de erro de comunicação para verificar o status atual da transação, que pode ter sido efetuada ou não recebida pelo e-SiTef.

O e-SiTef disponibiliza um serviço para consulta a partir do NIT (pagamento/cancelamento) e um serviço para consulta a partir do SID (agendamento). No caso de pagamento com agendamento, as consultas retornarão os dados das duas transações.

Atenção:

A consulta de transação no e-SiTef NÃO efetua uma consulta do status da transação no adquirente / autorizador. Este serviço retorna o status da transação na base de dados do e-SiTef.

Exemplo: Caso uma transação de pagamento seja confirmada no e-SiTef, mas seja estornada via telefone diretamente no adquirente / autorizador, este estorno não será necessariamente refletido no serviço de consulta de transação do e-SiTef.

Detalhes da chamada

Consulta por NIT

• Recurso: /v1/transactions/{nit}
• Método HTTP: GET
• Formato da requisição: não há parâmetros de requisição
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM

Consulta por SID

• Recurso: /v1/schedules/{sid}
• Método HTTP: GET
• Formato da requisição: não há parâmetros de requisição
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM

Exemplos

Abaixo estão alguns exemplos de chamada dos serviços de consulta utilizando a ferramenta cURL.

Consulta de pagamento

Requisição:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13064421440",
      "customer_receipt":"==== CUPOM COMPRADOR ====",
      "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"13/07/2017T18:44",
      "authorization_number":"132048",
      "merchant_usn":"13064421441",
      "esitef_usn":"170713097341620",
      "sitef_usn":"132048",
      "host_usn":"999132048   ",
      "payment_date":"13/07/2017T18:44",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   }
}

Consulta de agendamento

Requisição:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "schedule":{
      "status":"ATV",
      "sid":"qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
      "schedule_usn":"170713000000050",
      "authorizerId":"2",
      "amount":"900",
      "initial_date":"03/08/2017",
      "next_date":"03/08/2017",
      "number_of_times":"3",
      "current_times":"0",
      "installments":"1",
      "installment_type":"4",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   }
}

Consulta por NIT de pagamento com agendamento

Requisição:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13065054564",
      "customer_receipt":"==== CUPOM COMPRADOR ====",
      "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"13/07/2017T18:51",
      "authorization_number":"132050",
      "merchant_usn":"13065054565",
      "esitef_usn":"170713097341630",
      "sitef_usn":"132050",
      "host_usn":"999132050   ",
      "payment_date":"13/07/2017T18:51",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   },
   "schedule":{
      "status":"ATV",
      "sid":"qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
      "schedule_usn":"170713000000060",
      "authorizerId":"2",
      "amount":"900",
      "initial_date":"03/08/2017",
      "next_date":"03/10/2017",
      "number_of_times":"3",
      "current_times":"2",
      "installments":"1",
      "installment_type":"4",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false",
      "nits":[
         "123412341234111",
         "123412341234222"
      ]
   }
}

Consulta por SID de agendamento com pagamento

Requisição:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13065054564",
      "customer_receipt":"==== CUPOM COMPRADOR ====",
      "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"13/07/2017T18:51",
      "authorization_number":"132050",
      "merchant_usn":"13065054565",
      "esitef_usn":"170713097341630",
      "sitef_usn":"132050",
      "host_usn":"999132050   ",
      "payment_date":"13/07/2017T18:51",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   },
   "schedule":{
      "status":"ATV",
      "sid":"qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
      "schedule_usn":"170713000000060",
      "authorizerId":"2",
      "amount":"900",
      "initial_date":"03/08/2017",
      "next_date":"03/10/2017",
      "number_of_times":"3",
      "current_times":"2",
      "installments":"1",
      "installment_type":"4",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false",
      "nits":[
         "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqs",
         "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqt"
      ]
   }
}

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de consulta de transações:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0 significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	payment
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
status	Status da transação de pagamento no e-SiTef. Saiba mais.	= 3 AN
nit	Identificador da transação de pagamento no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N
amount	Valor da compra especificado pela loja (em centavos) na criação da transação.	< 12 N
sitef_usn	Número sequencial único da transação de pagamento no SiTef.	= 6 N
esitef_usn	Número sequencial único da transação de pagamento no e-SiTef.	= 15 N
customer_receipt	Cupom (via cliente).	< 4000 AN
merchant_receipt	Cupom (via estabelecimento).	< 4000 AN
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N
acquirer_id	Código do adquirente utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente utilizado na transação.	< 100 AN
authorizer_date	Data de efetivação do pagamento retornada pelo autorizador no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
authorization_number	Número de autorização.	< 6 AN
host_usn	NSU da autorizadora.	< 15 AN
tid	ID da transação no adquirente. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
eci	Eletronic Commerce Indicator (indicador do nível de segurança da transação do pagamento via Cielo e-Commerce).	< 3 AN
payment_date	Data de efetivação do pagamento no e-SiTef no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
xid	Campo XID retornado em autenticações 3DS ou certos adquirentes.	< 40 AN
balance	Saldo disponível após pagamentos com cartões tipo Gift.	< 12 N
	payment.analysis
code	Código de resposta da operação de análise de fraude.	< 4 N
message	Mensagem de resposta da operação de análise de fraude.	< 200 AN
status	Status da transação de análise de fraude do e-SiTef. Este campo pode assumir os seguintes valores: NOV – Nova. EXP – Expirada. ACC – Aceita REJ – Rejeitada REV – Em revisão INV – Inválida	= 3 AN
	schedule
status	Status do agendamento no e-SiTef. Saiba mais.	= 3 AN
sid	Identificador da transação de agendamento no e-SiTef.	= 64 AN
schedule_usn	Número sequencial único do agendamento no e-SiTef.	= 15 N
authorizer_id	Código da autorizadora a ser utilizada nos pagamentos agendados.	= 4 N
amount	Valor dos pagamentos agendados especificado pela loja (em centavos) na criação da transação.	< 12 N
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N
initial_date	Data de execução do primeiro pagamento agendado no formato DD/MM/AAAA.	= 10 D
next_date	Data de execução do próximo pagamento agendado no formato DD/MM/AAAA.	= 10 D
number_of_times	Número total de pagamentos agendados.	< 3 N
current_times	Número de pagamentos agendados já executados.	< 3 N
installments	Número de parcelas a ser utilizado nos pagamentos agendados.	< 2 N
installment_type	Tipo de financiamento a ser utilizado nos pagamentos agendados.	< 2 N
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador.	< 30 AN
show_times_invoice	Para agendamentos por tempo finito, caso esse campo tenha valor true acrescenta ao final do campo soft_descriptor o número de execuções/total de execuções (exemplo: Assinatura 3/12).	< 5 T/F
nits	NITs dos últimos seis pagamentos agendados já executados.	= 64 AN[]
	cancellation
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
status	Status da transação de cancelamento no e-SiTef. Saiba mais.	= 3 AN
nit	Número identificador da transação de cancelamento no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N
amount	Valor do cancelamento especificado pela loja (em centavos).	< 12 N
sitef_usn	Número sequencial único da transação de cancelamento no SiTef.	= 6 N
esitef_usn	Número sequencial único da transação de cancelamento no e-SiTef.	= 15 N
customer_receipt	Cupom (via cliente).	< 4000 AN
merchant_receipt	Cupom (via estabelecimento).	< 4000 AN
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N
acquirer_id	Código do adquirente utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente utilizado na transação.	< 100 AN
authorizer_date	Data de efetivação do cancelamento retornada pelo autorizador no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
authorization_number	Número de autorização.	< 6 AN
host_usn	NSU da autorizadora.	< 15 AN
tid	ID da transação no adquirente. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
esitef_date	Data de efetivação do cancelamento no e-SiTef no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
is_host_cancel	Este campo retornará o valor true em caso de cancelamento via host.	< 5 T/F
terminal_id	Código do terminal utilizada na transação	< 8 AN

Consulta de transações em um grupo de lojas

O e-SiTef exige que as credenciais (merchant_id e merchant_key) sejam as mesmas utilizadas na transação a ser consultada. No entanto, caso o lojista precise, o e-SiTef pode permitir consultas com credenciais de outras lojas de um mesmo grupo. Para isso, basta solicitar às nossas equipes de suporte e produção para que façam essa liberação.

Serviço de consulta de múltiplas transações

Estes serviços podem ser chamados para obter os dados de múltiplas transações para uma loja ou grupo da loja. É essencial o uso dessa operação em casos de erro de comunicação para verificar o status atual de transações, que podem ter sido efetuada ou não recebida pelo e-SiTef.

Atenção:

A consulta de transações no e-SiTef NÃO efetua uma consulta do status da transações no adquirente / autorizador. Este serviço retorna o status da transação na base de dados do e-SiTef.

Exemplo: Caso uma transação de pagamento seja confirmada no e-SiTef, mas seja estornada via telefone diretamente no adquirente / autorizador, este estorno não será necessariamente refletido no serviço de consulta de transação do e-SiTef.

Detalhes da chamada

• Recurso: /v1/transactions
• Método HTTP: GET
• Formato da requisição: query string
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
group_id	Código do grupo de loja no e-SiTef. Caso seja enviado, será feito uma busca pelo grupo da loja. É necessário que o código da loja esteja dentro do grupo.	< 38 N	NÃO

• Parâmetros de requisição:

Parâmetro	Descrição	Formato	Obrigatório
start_date	Data inicial das transações a serem listadas. Formato: dd/MM/aaaa	= 10 AN	SIM
end_date	Data final das transações a serem listadas. Período máximo: 5 dias (configurável). Formato: dd/MM/aaaa	= 10 AN	SIM
status	Filtro de status de transações. Ex.: "CON"	= 3 N	NÃO
page	Página da listagem. A primeira página tem valor "0". Caso não seja enviada, assumiremos o valor "0".	< 1000 N	NÃO
limit	Número máximo de registros por página. Caso não seja enviado, assumiremos o valor máximo 1000 de transações por vez (configurável).	< 4 N	NÃO
payment_link	Filtro para indicar a busca por transações de pagamento por link. Apenas ativo no caso de valor true	< 5 T/F	NÃO

Exemplos

Abaixo estão alguns exemplos de chamada dos serviços de consulta utilizando a ferramenta cURL.

Consulta de múltiplas transações

Requisição:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions?start_date=25/11/2020&end_date=27/11/2020&status=CON&page=0&limit=50"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--header "group_id: 12345"
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "current_page":"0",
   "total_pages":"1",
   "count":"2",
   "transactions":[
      {
         "type":"P",
         "authorizer_code":"000",
         "authorizer_message":"Transacao OK",
         "status":"CON",
         "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
         "order_id":"13064421440",
         "customer_receipt":"==== CUPOM COMPRADOR ====",
         "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
         "authorizer_id":"2",
         "acquirer_id":"1005",
         "acquirer_name":"Redecard",
         "authorizer_date":"13/07/2017T18:44",
         "authorization_number":"132048",
         "merchant_usn":"13064421441",
         "esitef_usn":"170713097341620",
         "sitef_usn":"132048",
         "host_usn":"999132048   ",
         "payment_date":"13/07/2017T18:44",
         "amount":"1000",
         "payment_type":"C",
         "issuer":"2",
         "authorizer_merchant_id":"000000000000005",
         "merchant_id": "xxxxxxxxxxxxxxx",
         "creation_date": "13/07/2017T18:43",
         "installments": "1"
      },
      {
         "type":"F",
         "authorizer_code":"000",
         "authorizer_message":"Transacao OK",
         "status":"CON",
         "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
         "order_id":"13064421440",
         "customer_receipt":"==== CUPOM COMPRADOR ====",
         "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
         "authorizer_id":"2",
         "acquirer_id":"1005",
         "acquirer_name":"Redecard",
         "authorizer_date":"13/07/2017T18:44",
         "authorization_number":"132048",
         "merchant_usn":"13064421441",
         "esitef_usn":"170713097341620",
         "sitef_usn":"132048",
         "host_usn":"999132048   ",
         "payment_date":"13/07/2017T18:44",
         "amount":"1000",
         "payment_type":"C",
         "issuer":"2",
         "authorizer_merchant_id":"000000000000005",
         "merchant_id": "xxxxxxxxxxxxxxx",
         "creation_date": "13/07/2017T18:42",
         "installments": "3"
      }
   ]
}

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de consulta de múltiplas transações:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0 significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
current_page	Página atual dos registros.	< 4 N
total_pages	Número total de páginas.	< 4 N
count	Contagem total de registros.	< 4 N
transactions[]	Lista de transações encontradas para os filtros selecionados. Retornaremos apenas os campos em comum entre os vários tipos de transação, além do novo campo "type", que explicita qual é o tipo da transação.
type	Tipo da transação. G = Captura de Pré-Autorização, A = Consulta AVS, E = Estorno, P = Pagamento, F = Pré-Autorização, R = Recarga	< 1 A
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
status	Status da transação de pagamento no e-SiTef. Saiba mais.	= 3 AN
nit	Identificador da transação de pagamento no e-SiTef.	= 64 AN
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N
amount	Valor da compra especificado pela loja (em centavos) na criação da transação.	< 12 N
sitef_usn	Número sequencial único da transação de pagamento no SiTef.	= 6 N
esitef_usn	Número sequencial único da transação de pagamento no e-SiTef.	= 15 N
customer_receipt	Cupom (via cliente).	< 4000 AN
merchant_receipt	Cupom (via estabelecimento).	< 4000 AN
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N
acquirer_id	Código do adquirente utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente utilizado na transação.	< 100 AN
authorizer_date	Data de efetivação do pagamento retornada pelo autorizador no formato dd/MM/aaaa'T'HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
authorization_number	Número de autorização.	< 6 AN
host_usn	NSU da autorizadora.	< 15 AN
tid	ID da transação no adquirente. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
payment_date	Data de efetivação do pagamento no e-SiTef no formato dd/MM/aaaa'T'HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
payment_type	Tipo do pagamento da autorizadora escolhida. Ex.: C = Crédito, D = Débito	< 1 A
creation_date	Data da criação da transação no e-SiTef, no formato dd/MM/aaaa'T'HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
installments	Número de parcelas da transação	< 2 N

Serviço de consulta de cartão

A partir de um NIT de pagamento com status NOV (novo), é possível realizar uma consulta do BIN do cartão (seis primeiros dígitos) no SiTef para obter dados sobre suas capacidades (possibilidade de pagamento parcelado, máximo de parcelas, exigência de código de segurança, etc.), ou ainda, saber qual autorizadora da loja é a mais adequada para a realização do pagamento.

No caso de transações com Visa Checkout, este serviço também retornará dados do cartão e do usuário retornados pelo Visa.

Fluxo

Descrição do fluxo:

1. O lojista cria uma transação no e-SiTef passando informações como código da loja, número de parcelas e código de pedido e obtém como resposta um NIT (Número Identificador de Transação).
2. O lojista envia o NIT obtido na etapa anterior e os dados do cartão a ser consultado. Com isso, o e-SiTef retorna dados sobre as capacidades do cartão enviado.
3. A loja virtual prossegue então consumindo o serviço de efetivação do pagamento, passando o NIT e os dados do cartão do comprador. Em caso de sucesso, a transação de pagamento mudará seu status para CON (confirmada).

Detalhes da chamada

• Recurso: /v1/payments/{nit}/cards
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM

Obs.: apesar de se tratar de uma consulta, o método POST foi escolhido por questões de segurança.

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de consulta de cartão utilizando a ferramenta cURL.

Consulta de cartão com envio de autorizadora

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555"
   },
   "authorizer_id":"1"
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "status":"NOV"
   },
   "card":{
      "acquirer_name":"Redecard",
      "authorizer_id":"1",
      "authorizer_response_code":"000",
      "is_customer_id_required":"false",
      "is_expiry_date_required":"true",
      "is_installment_funding_enabled":"true",
      "is_security_code_required":"true",
      "is_spot_sale_enabled":"true",
      "is_with_interest_sale_enabled":"true",
      "is_without_interest_sale_enabled":"true",
      "max_installments_with_interest":"12",
      "min_installments_with_interest":"01",
      "prefixes":{
         "TRAT":"2",
         "PERIFERICO":"1",
         "CSEG":"2"
      }
   }
}

Consulta de cartão sem envio de autorizadora

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"6543210987654321"
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "status":"NOV"
   },
   "card":{
      "acquirer_name":"Redecard",
      "authorizer_id":"1",
      "authorizer_response_code":"000",
      "is_customer_id_required":"false",
      "is_expiry_date_required":"true",
      "is_installment_funding_enabled":"true",
      "is_security_code_required":"true",
      "is_spot_sale_enabled":"true",
      "is_with_interest_sale_enabled":"true",
      "is_without_interest_sale_enabled":"true",
      "max_installments_with_interest":"12",
      "min_installments_with_interest":"01",
      "prefixes":{
         "TRAT":"2",
         "PERIFERICO":"1",
         "CSEG":"2"
      }
   }
}

Consulta de cartão Visa Checkout

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "wallet_transaction_id":"4444444444444444444"
   },
   "authorizer_id":"406"
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "status":"NOV"
   },
   "card":{
      "acquirer_name":"Redecard",
      "authorizer_id":"406",
      "authorizer_response_code":"000",
      "is_customer_id_required":"false",
      "is_expiry_date_required":"true",
      "is_installment_funding_enabled":"true",
      "is_security_code_required":"true",
      "is_spot_sale_enabled":"true",
      "is_with_interest_sale_enabled":"true",
      "is_without_interest_sale_enabled":"true",
      "max_installments_with_interest":"12",
      "min_installments_with_interest":"01",
      "prefixes":{
         "TRAT":"2",
         "PERIFERICO":"1"
      },
      "visa_checkout_data":{
         "payment_request":{
            "currency_code":"BRL",
            "subtotal":"115.5",
            "total":"115.5",
            "order_id":"09387",
            "source_id":"LOJAVISACHECK"
         },
         "user_data":{
            "user_first_name":"Comprador",
            "user_last_name":"Esitef",
            "user_full_name":"Comprador Esitef",
            "user_name":"esitef2@gmail.com",
            "user_email":"esitef2@gmail.com",
            "enc_user_id":"c5DmPXTXC3VwZywsFESEGAqiLM5PXSZG7hgyQgRv0j8=",
            "user_personal_id":"12345678909"
         },
         "creation_time_stamp":1502206049403,
         "payment_instrument":{
            "id":"AWUU0/rQrmKCMx+C740kBefZP2GNsdAMYUTXAzCPk+M=",
            "last_four_digits":"1010",
            "bin_six_digits":"406897",
            "verification_status":"VERIFIED",
            "expired":"false",
            "issuer_bid":"10029901",
            "nick_name":"Cartão PAN",
            "name_on_card":"aaaaaaaaaa vvvvvvvvvv",
            "card_first_name":"aaaaaaaaaa",
            "card_last_name":"vvvvvvvvvv",
            "payment_type":{
               "card_brand":"VISA",
               "card_type":"CREDIT"
            },
            "billing_address":{
               "person_name":"aaaaaaaaaa vvvvvvvvvv",
               "first_name":"aaaaaaaaaa",
               "last_name":"vvvvvvvvvv",
               "line1":"qqqqqqqqqq",
               "line2":"eeeeee",
               "line3":"wwwwwwwww",
               "city":"cccccccc",
               "state_province_code":"SP",
               "postal_code":"01238010",
               "country_code":"BR",
               "phone":"987654321",
               "default":"false"
            },
            "card_arts":{
               "card_art":[
                  {
                     "base_image_file_name":"https://sandbox.secure.checkout.visa.com/VmeCardArts/lg_visa_card.png",
                     "height":105,
                     "width":164
                  }
               ]
            },
            "expiration_date":{
               "month":"11",
               "year":"2022"
            }
         },
         "risk_data":{
            "advice":"UNAVAILABLE",
            "score":0,
            "avs_response_code":"0",
            "cvv_response_code":"0",
            "age_of_account":"704"
         },
         "visa_checkout_guest":"false"
      }
   }
}

Consulta de cartão com planos de financiamento

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"6543210987654321"
   },
   "authorizer_id":"313"
}
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "status": "NOV"
    },
    "card": {
        "acquirer_name": "Via Certa Financiadora",
        "authorizer_id": "313",
        "authorizer_response_code": "000",
        "is_customer_id_required": "false",
        "is_expiry_date_required": "true",
        "is_installment_funding_enabled": "true",
        "is_security_code_required": "true",
        "is_spot_sale_enabled": "true",
        "is_with_interest_sale_enabled": "true",
        "is_without_interest_sale_enabled": "true",
        "max_installments_with_interest": "99",
        "min_installments_with_interest": "00",
        "prefixes": {
            "CADSENHA": "11",
            "NPSAQ": "0199",
            "ECHO": "MIG3DH00000"
        },
        "financing_plan_list": [
            {
                "cod_plano": "0201",
                "tipo_plano": "02",
                "desc_plano": "Plano de Teste para CDC 01                        ",
                "parc_plano": "99"
            },
            {
                "cod_plano": "0301",
                "tipo_plano": "03",
                "desc_plano": "Plano de Teste para Saque e CDC 01                ",
                "parc_plano": "99"
            },
            {
                "cod_plano": "0201",
                "tipo_plano": "02",
                "desc_plano": "Plano de Teste para CDC 01                        ",
                "parc_plano": "99"
            },
            {
                "cod_plano": "0202",
                "tipo_plano": "02",
                "desc_plano": "Plano de Teste para CDC 02                        ",
                "parc_plano": "99"
            },
            {
                "cod_plano": "0301",
                "tipo_plano": "03",
                "desc_plano": "Plano de Teste para Saque e CDC 01                ",
                "parc_plano": "99"
            },
            {
                "cod_plano": "0302",
                "tipo_plano": "03",
                "desc_plano": "Plano de Teste para Saque e CDC 02                ",
                "parc_plano": "99"
            },
            {
                "cod_plano": "0303",
                "tipo_plano": "03",
                "desc_plano": "Plano de Teste para Saque e CDC 03                ",
                "parc_plano": "99"
            }
        ]
    }
}

Consulta de cartão com dados adicionais para roteamento iCards via SiTef

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"6543210987654321"
   },
   "authorizer_id":"38"
}
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "card": {
        "acquirer_name": "iCards",
        "authorizer_id": "38",
        "authorizer_response_code": "000",
        "is_customer_id_required": "true",
        "is_expiry_date_required": "true",
        "is_installment_funding_enabled": "true",
        "is_security_code_required": "true",
        "is_spot_sale_enabled": "true",
        "is_with_interest_sale_enabled": "true",
        "is_without_interest_sale_enabled": "true",
        "max_installments_with_interest": "12",
        "min_installments_with_interest": "01",
        "prefixes": {
            "NPSAQ": "0299",
            "CAPTPPRE": "1",
            "XCAPPREAUT": "11"
        },
        "is_customer_postal_code_required": "true",
        "is_card_holder_required": "true"
    },
    "payment": {
        "status": "NOV"
    }
}

Consulta de cartão com dados adicionais para roteamento IPG

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
  "card":{
    "number":"4036952187654321"
  },
  "routing_id":"414"
}
--verbose

Resposta:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "status": "NOV"
  },
  "details": [
    {
      "brand": "VISA",
      "brand_product_id": "VI",
      "card_function": "CREDIT",
      "issuer_country": "USA",
      "issuer_name": "Simulation"
    },
    {
      "brand": "VISA",
      "brand_product_id": "VI",
      "card_function": "DEBIT",
      "issuer_country": "BRA",
      "issuer_name": "Simulation"
    }
  ]
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de consulta de cartão:

Parâmetro	Descrição	Formato	Obrigatório
authorizer_id	Código da autorizadora no e-SiTef. Saiba mais. Este campo só é obrigatório caso o campo wallet_transaction_id seja enviado. Se esse campo não é enviado, o e-SiTef assume que se trata de um cartão de crédito	< 3 N	COND.
routing_id	Código do roteamento no e-SiTef. Este campo só é obrigatório para obter dados adicionais pela IPG.	< 3 N	COND.
	card
number	Número do cartão do comprador (PAN).	< 19 N	SIM
token	HASH de um cartão armazenado no e-SiTef. Não é permitido enviar um número de cartão aberto (campo number) e um cartão armazenado (campo token) na mesma requisição.	= 88 AN	NÃO
wallet_transaction_id	ID de uma transação de carteiras digitais. Por enquanto, essa funcionalidade está disponível apenas para a autorizadora Visa Checkout (authorizer_id:406). Não é permitido enviar um número de cartão aberto (campo number), um cartão armazenado (campo token) e um wallet_transaction_id na mesma requisição.	< 25 AN	NÃO
do_par_inquiry	Informa se a chamada para o VISA PAR Inquiry será realizada. O Valor resposta será retornado no campo par do do retorno da chamada. Valores permitidos: true - Requisição de PAR será realizada false - Requisição de PAR não será realizada. Valor default: false	< 5 A	NÃO

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de consulta de cartão:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0 significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	payment
status	Status da transação de pagamento no e-SiTef. Saiba mais.	= 3 AN
	card
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
acquirer_name	Nome do roteamento. Ex.: Cielo	< 256 AN
authorizer_id	Código da autorizadora (utilizar este ID ao realizar o pagamento).	< 3 N
is_customer_id_required	Indica a obrigatoriedade da coleta do documento do cliente.	< 5 T/F
is_expiry_date_required	Indica a obrigatoriedade da coleta da data de validade do cartão do comprador.	< 5 T/F
is_installment_funding_enabled	Indica se o parcelamento está habilitado.	< 5 T/F
is_security_code_required	Indica a obrigatoriedade da coleta do código de segurança.	< 5 T/F
is_spot_sale_enabled	Indica se o pagamento à vista está habilitado.	< 5 T/F
is_with_interest_sale_enabled	Indica se o pagamento com juros está habilitado.	< 5 T/F
is_without_interest_sale_enabled	Indica se o pagamento sem juros está habilitado.	< 5 T/F
max_installments_with_interest	Parcelamento máximo com juros.	< 2 N
min_installments_with_interest	Parcelamento mínimo com juros.	< 2 N
visa_checkout_data	Objeto com os dados retornados pela Visa Checkout.	O
financing_plan_list	Objeto que consiste em um array de planos de financiamento apresentados em roteamento Via Certa Financiadora. Um plano de financiamento consiste dos seguintes campos: cod_plano: código de identificação do plano de financiamento, que deve ser enviado no momento da efetivação do pagamento; tipo_plano: código do tipo do plano de financiamento; desc_plano: descrição do plano, que pode ser apresentado ao comprador; parc_plano: número máximo de parcelas possíveis para o plano.	O
is_customer_postal_code_required	Indica a obrigatoriedade da coleta do código postal do usuário (CEP no Brasil).	< 5 T/F
par	Valor do PAR retornado pela VISA caso o campo do_par_inquiry seja enviado com o valor true na requisição.	< 32 AN
card.prefixes[]	Este campo contém os prefixos (dados adicionais) retornados pelo SiTef.
key	Nome do prefixo.	< 1024 AN
value	Valor do prefixo.	< 1024 AN
details[]	Este campo contém detalhamentos retornados pelo roteamento IPG
brand	A bandeira do cartão. The card brand.	< 1024 AN
brand_product_id	ID de produto da bandeira do cartão. The product ID of the brand.	< 1024 AN
card_function	Função do cartão. Card function.	CREDIT, DEBIT, PREPAID, VOUCHER, UNDEFINED
commercialCard	Indica se o cartao é corporativo ou nao-corporativo. Indicates whether it is a corporate or non-corporate card.	CORPORATE, NON_CORPORATE
issuer_country	O país da emissora do cartão. The country of the issuer.	< 1024 AN
issuer_name	O nome da emissora do cartão. The name of the issuer.	< 1024 AN

Roteamentos que permitem consulta de cartão.

Cód.	Roteamento	Possui consulta de cartão
1004	VisaNet via SiTef (rede:4)
1005	Redecard via SiTef (rede:5)
1018	Standby (Excard) via SiTef (rede:18)
1019	Edmcard via SiTef (rede:19)
1021	Vero via SiTef (rede:21)
1026	CCCWeb (Master/Visa/Amex) via SiTef (rede:26)
1029	Softway via SiTef (rede:29)
1030	Multicheque via SiTef (rede:30)
70	Ticket via SiTef (rede:41)
430	Senff via SiTef (rede:43)
1045	Coopercred via SiTef (rede:45)
1047	Sorocred via SiTef (rede:47)
1051	Hipercard via SiTef (rede:51)
1052	Tricard via SiTef (rede:52)
1054	Policard via SiTef (rede:54)
1057	CCC (Master/Visa) via SiTef (rede:57)
1059	Telenet via SiTef (rede:59)
1061	Brasilcard via SiTef (rede:61)
1064	CCC (Amex) via SiTef (rede:64)
1068	Banese via SiTef (rede:68)
1072	Bigcard via SiTef (rede:72)
1077	Valecard via SiTef (rede:77)
1081	Supercard via SiTef (rede:81)
1182	GetNet via SiTef (rede:82)
1086	Marisa via SiTef (rede:86)
1087	Maxicred via SiTef (rede:87)
1089	Expansiva via SiTef (rede:89)
1091	Leader II via SiTef (rede:91)
1093	Cetelem via SiTef (rede:93)
1094	Cabal via SiTef (rede:94)
1095	Credsystem via SiTef (rede:95)
1096	BBVA via SiTef (rede:96)
1102	Check Check (Smart Shop) via SiTef (rede:102)
1103	Dacasa via SiTef (rede:103)
1104	Bradesco Private Label via SiTef (rede:104)
1105	Platinum (Credimais) via SiTef (rede:105)
1111	Tredenexx via SiTef (rede:111)
1113	Credishop via SiTef (rede:113)
1115	IBI via SiTef (rede:115)
1118	Oboe via SiTef (rede:118)
1121	Hot Card via SiTef (rede:121)
1122	PAN via SiTef (rede:122)
1125	Cielo via SiTef (rede:125)
1127	Marisa Cartao Presente via SiTef (rede:127)
1128	Cooplife via SiTef (rede:128)
1129	BOD via SiTef (rede:129)
1144	Accredito (ACSP) via SiTef (rede:144)
1149	Fidelidade Mais via SiTef (rede:149)
160	Orbitall via SiTef (rede:160)
1161	iCards via SiTef (rede:161)
1165	Banco Ge (Tivit) via SiTef (rede:165)
1169	Banescard via SiTef (rede:169)
1181	GetNet Lac via SiTef (rede:181)
1187	Sicredi - nao usar, usar o bin via SiTef (rede:187)
1192	AVISTA via SiTef (rede:192)
1193	Algorix via SiTef (rede:193)
1194	Amex EMV via SiTef (rede:194)
1006	Amex EMV via SiTef (rede:194)
1201	SmartNet via SiTef (rede:201)
1203	Peela via SiTef (rede:203)
1206	GlobalPayments via SiTef (rede:206)
1207	Elavon via SiTef (rede:207)
218	Hug via SiTef (rede:218)
225	Fidelity via SiTef (rede:225)
1229	Bin via SiTef (rede:229)
1236	Conductor via SiTef (rede:236)
1249	Riachuelo PL via SiTef (rede:249)
1257	Bradescard via SiTef (rede:257)
1265	Stone via SiTef (rede:265)
1266	DM Card via SiTef (rede:266)
1271	CardSE via SiTef (rede:271)
1279	Sodexo via SiTef (rede:279)
1280	Kredilig via SiTef (rede:280)
1283	ConductorDUP via SiTef (rede:283)
1296	Safra via SiTef (rede:296)
1297	Rede Ticket via SiTef (rede:297)
1303	SiPag via SiTef (rede:303)
1309	ADIQ via SiTef (rede:309)
1313	Via Certa Financiadora via SiTef (rede:313)

Serviço de efetivação de pagamento com múltiplos meios de pagamento

Após consumir o serviço de criação de transação e obter um NIT, é possível prosseguir para a próxima etapa do fluxo: a chamada ao serviço de efetivação de pagamento.

Isso pode ser feito informando apenas um meio de pagamento (veja o documento "Serviço de efetivação de pagamento") ou 2 (dois) meios de pagamento.

Neste capítulo, trataremos dos pagamentos que são feitos com 2 (dois) meios de pagamento, o qual chamamos de Pagamento com múltiplos meios de pagamento.

Para usar esta funcionalidade, entre em contato com o nosso suporte e solicite a ativação da mesma em sua loja.

Fluxo

O fluxo de um pagamento com múltiplos meios de pagamento possui diferenças importantes quando o comparamos com o pagamento tradicional.

A primeira diferença é que temos duas transações para uma mesma chamada e cada uma delas é usada para efetuar o pagamento de um dos meios de pagamento informados. A primeira transação é criada na chamada de criação de transação no e-SiTef e a segunda transação é criada indiretamente na chamada de pagamento com múltiplos meios de pagamento.

A segunda diferença é que, por causa disso, alguns dados da primeira transação são modificados durante a efetivação do pagamento. Inicialmente, a primeira transação possui o valor total da compra, as parcelas e o tipo de financiamento próprios. Quando a chamada de pagamento com múltiplos pagamentos é feita, seu valor é alterado para ser igual ao do primeiro meio de pagamento e o mesmo ocorre com as parcelas e o tipo de financiamento, caso estes sejam informados na requisição. Já a segunda transação terá o valor, as parcelas e o tipo de financiamento informados pelo segundo meio de pagamento. Mas, no caso da segunda transação não informar dados de parcelamento e tipo de financiamento, ela herdará essas configurações da primeira transação original. A soma dos valores da primeira e da segunda transações deve ser igual ao valor informado na criação da primeira transação no e-SiTef.

A terceira diferença é que a resposta de múltiplos pagamentos é composta pelas respostas de cada uma das transações. Sendo assim, haverá situações em que a resposta de uma transação afetará a resposta da outra.

A seguir, iremos abordar os cenários previstos no e-SiTef com mais detalhes.

Fluxo de pagamento com confirmação automática

O fluxo de pagamento com confirmação automática nos pagamentos com múltiplos meios de pagamentos possui uma peculiaridade que é dividir o pagamento em 3 (três) etapas: atualização/inicialização das transações; pagamentos; confirmações.

Em caso de falha em qualquer uma das transações, o e-SiTef não prossegue para a etapa seguinte e faz tratamentos que serão explicados a seguir nos casos de falhas.

Caso de sucesso

Caso de falha no pagamento da primeira transação

Quando o primeiro pagamento falha, a segunda transação será cancelada e não será disparada para a Autorizadora. Uma ocorrência é gerada para a equipe de suporte do e-SiTef e o lojista, caso deseje, pode entrar em contato.

Exemplo de resposta

{
    "code": "1013",
    "message": "Error processing multiple payment methods",
    "payments": [
        {
            "authorizer_code": "014",
            "authorizer_message": "14 Cartao Inval.",
            "status": "NEG",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "1609964926966",
            "authorizer_id": "1",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "06/01/2021T17:28",
            "authorization_number": "080384",
            "merchant_usn": "16114726760",
            "esitef_usn": "210106064204400",
            "sitef_usn": "606060",
            "host_usn": "707070",
            "amount": "1254785",
            "payment_type": "C",
            "issuer": "1",
            "authorizer_merchant_id": "00000005",
            "terminal_id": "ES000036"
        },
        {
            "status": "CAN"
        }
    ]
}

Caso de falha no pagamento da segunda transação

Quando o segundo pagamento falha, a primeira transação será desfeita. Uma ocorrência é gerada para a equipe de suporte do e-SiTef e o lojista, caso deseje, pode entrar em contato.

Exemplo de resposta

{
    "code": "1013",
    "message": "Error processing multiple payment methods",
    "payments": [
        {
            "authorizer_code": "000",
            "authorizer_message": "Transacao Aprov.",
            "status": "PPN",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "25053142469",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "1",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "25/03/2020T17:31",
            "authorization_number": "252490",
            "merchant_usn": "25053142469",
            "esitef_usn": "200325048537130",
            "sitef_usn": "252490",
            "host_usn": "999252490   ",
            "amount": "100",
            "payment_type": "C",
            "issuer": "1",
            "authorizer_merchant_id": "000000000000005",
            "payment_date": "25/03/2020T17:31"
        },
        {
            "authorizer_code": "255",
            "authorizer_message": "(2)Cartao invalido",
            "status": "NEG",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "25053142469",
            "authorizer_id": "2",
            "acquirer_name": "REDE",
            "merchant_usn": "25053142469",
            "esitef_usn": "200325048537140"
        }
    ]
}

Caso de falha na confirmação da primeira transação

Quando a primeira confirmação falha, a segunda transação será desfeita. Uma ocorrência é gerada para a equipe de suporte do e-SiTef e o lojista, caso deseje, pode entrar em contato.

Exemplo de resposta

{
    "code": "1013",
    "message": "Error processing multiple payment methods",
    "payments": [
        {
            "authorizer_code": "200",
            "authorizer_message": "Success. [Cód.: 00]",
            "status": "PEN",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "1609965604696",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "2",
            "acquirer_id": "202",
            "acquirer_name": "e.Rede REST",
            "authorizer_date": "06/01/2021T17:40",
            "authorization_number": "177013",
            "merchant_usn": "16114726760",
            "esitef_usn": "210106064204470",
            "host_usn": "304123216",
            "tid": "210106064204470",
            "amount": "47",
            "payment_type": "C",
            "payment_date": "06/01/2021T17:40"
        },
        {
            "authorizer_code": "200",
            "authorizer_message": "Success. [Cód.: 00]",
            "status": "PPN",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "1609965604696",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "2",
            "acquirer_id": "202",
            "acquirer_name": "e.Rede REST",
            "authorizer_date": "06/01/2021T17:40",
            "authorization_number": "962291",
            "merchant_usn": "16114726760",
            "esitef_usn": "210106064204480",
            "host_usn": "487097429",
            "tid": "210106064204480",
            "amount": "510",
            "payment_type": "C",
            "payment_date": "06/01/2021T17:40"
        }
    ]
}

Caso de falha na confirmação da segunda transação

Quando a segunda confirmação falha, a primeira transação já está confirmada e o cancelamento, caso seja desejado, deve ser feito manualmente, seja usando o cancelamento REST ou o Portal do Lojista. Uma ocorrência é gerada para a equipe de suporte do e-SiTef e o lojista, caso deseje, pode entrar em contato.

Exemplo de resposta

{
    "code": "1013",
    "message": "Error processing multiple payment methods",
    "payments": [
        {
            "authorizer_code": "200",
            "authorizer_message": "Function performed error-free [Cód.: 00]",
            "status": "CON",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "20030404545",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "2",
            "acquirer_id": "414",
            "acquirer_name": "IPG",
            "authorizer_date": "25/03/2020T17:48",
            "authorization_number": "488040",
            "merchant_usn": "20030404545",
            "esitef_usn": "200325048537190",
            "host_usn": "572994560",
            "tid": "SIM64194442",
            "amount": "102",
            "payment_type": "C",
            "payment_date": "25/03/2020T17:48"
        },
        {
            "authorizer_code": "200",
            "authorizer_message": "Function performed error-free [Cód.: 00]",
            "status": "PEN",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "20030404545",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "2",
            "acquirer_id": "414",
            "acquirer_name": "IPG",
            "authorizer_date": "25/03/2020T17:48",
            "authorization_number": "454463",
            "merchant_usn": "20030404545",
            "esitef_usn": "200325048537200",
            "host_usn": "108829897",
            "tid": "SIM45823552",
            "amount": "103",
            "payment_type": "C",
            "payment_date": "25/03/2020T17:48"
        }
    ]
}

Fluxo de pagamento com confirmação tardia

O fluxo de pagamento com confirmação tardia nos pagamentos com múltiplos meios de pagamentos possui uma peculiaridade que é dividir o pagamento em 2 (duas) fases: atualização/inicialização das transações; pagamentos.

Em caso de falha em qualquer uma das transações, o e-SiTef não prossegue para a etapa seguinte e faz tratamentos que serão explicados a seguir nos casos de falhas.

Caso de sucesso

Caso de falha no pagamento da primeira transação

Quando o primeiro pagamento falha, a segunda transação será cancelada e não será disparada para a Autorizadora.

Exemplo de resposta

{
    "code": "1013",
    "message": "Error processing multiple payment methods",
    "payments": [
        {
            "authorizer_code": "19",
            "authorizer_message": "19 Refaca Trans.",
            "status": "NEG",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "25052428543",
            "authorizer_id": "1",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "25/03/2020T17:24",
            "authorization_number": "080384",
            "merchant_usn": "25052428543",
            "esitef_usn": "200325048537090",
            "sitef_usn": "606060",
            "host_usn": "707070",
            "amount": "1254784",
            "payment_type": "C",
            "issuer": "1",
            "authorizer_merchant_id": "00000005"
        },
        {
            "status": "CAN"
        }
    ]
}

Caso de falha no pagamento da segunda transação

Quando o segundo pagamento falha, a primeira transação será desfeita.

Exemplo de resposta

{
    "code": "1013",
    "message": "Error processing multiple payment methods",
    "payments": [
        {
            "authorizer_code": "000",
            "authorizer_message": "Transacao Aprov.",
            "status": "PPN",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "25053142469",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "1",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "25/03/2020T17:31",
            "authorization_number": "252490",
            "merchant_usn": "25053142469",
            "esitef_usn": "200325048537130",
            "sitef_usn": "252490",
            "host_usn": "999252490   ",
            "amount": "100",
            "payment_type": "C",
            "issuer": "1",
            "authorizer_merchant_id": "000000000000005",
            "payment_date": "25/03/2020T17:31"
        },
        {
            "authorizer_code": "255",
            "authorizer_message": "(2)Cartao invalido",
            "status": "NEG",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "25053142469",
            "authorizer_id": "2",
            "acquirer_name": "REDE",
            "merchant_usn": "25053142469",
            "esitef_usn": "200325048537140"
        }
    ]
}

Detalhes da chamada

• Recurso: /v1/payments/multiple/{nit}
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de efetivação de pagamento utilizando a ferramenta cURL.

Pagamento

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/multiple/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "multiple_payment_methods": [
        {
            "number": "45518201234512345",
            "expiry_date": "1222",
            "security_code": "123",
            "authorizer_id": "218",
            "installments": "1",
            "installment_type": "4",
            "amount": "512"
        },
        {
            "number": "45518201234512345",
            "expiry_date": "1222",
            "security_code": "123",
            "authorizer_id": "218",
            "installments": "1",
            "installment_type": "4",
            "amount": "510"
        }
    ]
}
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payments": [
        {
            "authorizer_code": "000",
            "authorizer_message": "Transacao Aprov.",
            "status": "PPC",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "20125445982",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "1",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "20/03/2020T14:32",
            "authorization_number": "202650",
            "merchant_usn": "16013439434",
            "esitef_usn": "200320048363850",
            "sitef_usn": "202650",
            "host_usn": "999202650   ",
            "amount": "512",
            "payment_type": "C",
            "issuer": "1",
            "authorizer_merchant_id": "000000000000005",
            "payment_date": "20/03/2020T14:32"
        },
        {
            "authorizer_code": "000",
            "authorizer_message": "Transacao Aprov.",
            "status": "PPC",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "20125445982",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "2",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "20/03/2020T14:32",
            "authorization_number": "202651",
            "merchant_usn": "16013439434",
            "esitef_usn": "200320048363860",
            "sitef_usn": "202651",
            "host_usn": "999202651   ",
            "amount": "510",
            "payment_type": "C",
            "issuer": "2",
            "authorizer_merchant_id": "000000000000005",
            "payment_date": "20/03/2020T14:32"
        }
    ]
}

Pagamento com cartão armazenado

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "multiple_payment_methods": [
        {
            "token": "g16hJtpdU6XEN3FP-ApQ9pKTGII5Fa9Y12tRX-qfyC-+BUCV5OaFn807zwwOR6rDtKoRnIJg0QbikaJqJqosyQ==",
            "authorizer_id": "1",
            "installments": "1",
            "installment_type": "4",
            "amount": "512",
            "security_code": "123"
        },
        {
            "token": "g16hJtpdU6XEN3FP-ApQ9pKTGII5Fa9Y12tRX-qfyC-+BUCV5OaFn807zwwOR6rDtKoRnIJg0QbikaJqJqosyQ==",
            "authorizer_id": "2",
            "installments": "1",
            "installment_type": "3",
            "amount": "510",
            "security_code": "321"
        }
    ]
}
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payments": [
        {
            "authorizer_code": "000",
            "authorizer_message": "Transacao Aprov.",
            "status": "PPC",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "20125445982",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "1",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "20/03/2020T14:32",
            "authorization_number": "202650",
            "merchant_usn": "16013439434",
            "esitef_usn": "200320048363850",
            "sitef_usn": "202650",
            "host_usn": "999202650   ",
            "amount": "512",
            "payment_type": "C",
            "issuer": "1",
            "authorizer_merchant_id": "000000000000005",
            "payment_date": "20/03/2020T14:32"
        },
        {
            "authorizer_code": "000",
            "authorizer_message": "Transacao Aprov.",
            "status": "PPC",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "20125445982",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "2",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "20/03/2020T14:32",
            "authorization_number": "202651",
            "merchant_usn": "16013439434",
            "esitef_usn": "200320048363860",
            "sitef_usn": "202651",
            "host_usn": "999202651   ",
            "amount": "510",
            "payment_type": "C",
            "issuer": "2",
            "authorizer_merchant_id": "000000000000005",
            "payment_date": "20/03/2020T14:32"
        }
    ]
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de efetivação de pagamento com múltiplos meios de pagamento:

Parâmetro	Descrição	Formato	Obrigatório
multiple_payment_methods[]	Consiste em um array para pagamentos com múltiplos meios de pagamento em que cada item representa um meio de pagamento. Devem ser informados exatamente 2 (dois) itens, os quais são compostos pelos campos descritos abaixo.
authorizer_id	Código da autorizadora no e-SiTef. Saiba mais. Caso este campo não tenha sido enviado na etapa de criação da transação, ele passa a ser obrigatório ao consumir o serviço de efetivação do pagamento.	< 3 N	SIM
installments	Número de parcelas. Caso não seja informado, será usado o valor passado na inicialização da transação no e-SiTef.	< 2 N	NÃO
installment_type	Tipo de financiamento. Caso não seja informado, será usado o valor passado na inicialização da transação no e-SiTef.	< 2 N	NÃO
amount	Valor da compra especificado pela loja para este meio de pagamento (em centavos).	< 12 N	SIM
number	Número do cartão do comprador (PAN).	< 19 N	SIM
expiry_date	Data de vencimento do cartão no formato MMAA. Sua obrigatoriedade depende do adquirente escolhido. Na maioria dos casos, esse campo é obrigatório.	= 4 N	COND.
token	HASH de um cartão armazenado no e-SiTef. Não é permitido enviar um número de cartão aberto (campo number) e um cartão armazenado (campo token) na mesma requisição.	= 88 AN	NÃO
security_code	Código de segurança. Este campo pode não ser obrigatório se a empresa possuir um acordo no contrato firmado com as redes adquirentes, somente para o pagamento de determinados seguimentos. Importante: um pagamento com agendamento implica no armazenamento dos dados do cartão do comprador no ambiente do e-SiTef. Porém, por questões de segurança, o código de segurança não pode ser armazenado. Por isso, os pagamentos agendados sempre serão executados sem o envio do código de segurança.	< 5 N	COND.

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 201. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de efetivação de pagamento:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef para a operação de múltiplos meios de pagamento. Qualquer código diferente de 0 significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef para a operação de múltiplos meios de pagamento.	< 500 AN
payments[]	Consiste em um array para pagamentos com múltiplos meios de pagamento no qual cada item representa a resposta correspondente a um dos meios de pagamentos. Os itens são compostos pelos campos descritos abaixo.
code	Código de resposta do e-SiTef para a operação de pagamento de um dos meios de pagamento. Qualquer código diferente de 0 significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef para a operação de pagamento de um dos meios de pagamento.	< 500 AN
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
status	Status da transação de pagamento no e-SiTef. Saiba mais.	= 3 AN
nit	Identificador da transação de pagamento no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 20 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N
amount	Valor da compra especificado pela loja para este meio de pagamento (em centavos).	< 12 N
sitef_usn	Número sequencial único da transação de pagamento no SiTef.	= 6 N
esitef_usn	Número sequencial único da transação de pagamento no e-SiTef.	= 15 N
customer_receipt	Cupom (via cliente).	< 4000 AN
merchant_receipt	Cupom (via estabelecimento).	< 4000 AN
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N
acquirer_id	Código do adquirente utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente utilizado na transação.	< 100 AN
authorizer_date	Data de efetivação do pagamento retornada pelo autorizador no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
authorization_number	Número de autorização.	< 6 AN
host_usn	NSU da autorizadora.	< 15 AN
tid	ID da transação no adquirente. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
eci	Eletronic Commerce Indicator (indicador do nível de segurança da transação do pagamento via Cielo e-Commerce).	< 3 AN
payment_date	Data de efetivação do pagamento no e-SiTef no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
xid	Campo XID retornado em autenticações 3DS ou certos adquirentes.	< 40 AN
authentication_url	URL de autenticação retornada em fluxos de pagamento com autenticação. Disponível apenas para Cielo e-Commerce.	< 56 AN
balance	Saldo disponível após pagamentos com cartões tipo Gift.	< 12 N
	payment.analysis
code	Código de resposta da operação de análise de fraude.	< 4 N
message	Mensagem de resposta da operação de análise de fraude.	< 200 AN
status	Status da transação de análise de fraude do e-SiTef. Este campo pode assumir os seguintes valores: NOV – Nova. EXP – Expirada. ACC – Aceita REJ – Rejeitada REV – Em revisão INV – Inválida	= 3 AN

Serviço de confirmação de pagamento com múltiplos meios de pagamento

Após criar e efetuar um pagamento com múltiplos meios de pagamento pendente de confirmação, o lojista deve chamar o serviço de confirmação com múltiplos meios de pagamento para confirmá-lo ou desfazê-lo utilizando o mesmo NIT obtido na primeira etapa do fluxo (ou seja, o NIT da primeira transação).

Fluxo

O fluxo de confirmação de pagamento com múltiplos meios de pagamento difere da confirmação normal por duas razões.

A primeira razão é que temos duas transações para uma mesma chamada e cada uma delas é usada para efetuar a confirmação de um dos meios de pagamento informados.

A segunda razão é que a resposta da confirmação de múltiplos pagamentos é composta pelas respostas de cada uma das transações. Sendo assim, haverá situações em que a resposta de uma transação afetará a resposta da outra.

A seguir, iremos abordar os cenários previstos no e-SiTef com mais detalhes.

Caso de sucesso

Caso de falha na confirmação da primeira transação

Quando a primeira confirmação falha, a segunda transação será desfeita. Uma ocorrência é gerada para a equipe de suporte do e-SiTef e o lojista, caso deseje, pode entrar em contato.

Exemplo de resposta

{
    "code": "255",
    "message": "Transaction Denied",
    "confirmations": [
        {
            "code": "259",
            "message": "Denied transaction",
            "payment": {
                "authorizer_code": "409",
                "authorizer_message": "Brand / card type is invalid or not supported [Cód.: 5996]",
                "status": "PPC",
                "acquirer_id": "414"
            }
        },
        {
            "code": "0",
            "message": "OK. Transaction successful.",
            "payment": {
                "authorizer_code": "200",
                "authorizer_message": "Function performed error-free [Cód.: 00]",
                "status": "PPN",
                "acquirer_id": "414"
            }
        }
    ]
}

Caso de falha na confirmação da segunda transação

Quando a segunda confirmação falha, a primeira transação já está confirmada e o cancelamento, caso seja desejado, deve ser feito manualmente, seja usando o cancelamento REST ou o Portal do Lojista. Uma ocorrência é gerada para a equipe de suporte do e-SiTef e o lojista, caso deseje, pode entrar em contato.

Exemplo de resposta

{
    "code": "255",
    "message": "Transaction Denied",
    "confirmations": [
        {
            "code": "0",
            "message": "OK. Transaction successful.",
            "payment": {
                "authorizer_code": "200",
                "authorizer_message": "Function performed error-free [Cód.: 00]",
                "status": "CON",
                "acquirer_id": "414"
            }
        },
        {
            "code": "259",
            "message": "Denied transaction",
            "payment": {
                "authorizer_code": "409",
                "authorizer_message": "Brand / card type is invalid or not supported [Cód.: 5996]",
                "status": "PPC",
                "acquirer_id": "414"
            }
        }
    ]
}

Detalhes da chamada

• Recurso: /v1/payments/multiple/{nit}
• Método HTTP: PUT
• Formato da requisição: query string
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM

Exemplos

Abaixo está um exemplo de chamada do serviço de confirmação de pagamento utilizando a ferramenta cURL.

Requisição:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/multiple/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr?confirm=true"
--header "merchant_id:xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "confirmations": [
        {
            "code": "0",
            "message": "OK. Transaction successful.",
            "payment": {
                "authorizer_code": "130",
                "status": "CON",
                "acquirer_id": "5"
            }
        },
        {
            "code": "0",
            "message": "OK. Transaction successful.",
            "payment": {
                "authorizer_code": "130",
                "status": "CON",
                "acquirer_id": "5"
            }
        }
    ]
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de confirmação de pagamento com múltiplos meios de pagamento:

Parâmetro	Descrição	Formato	Obrigatório
confirm	Este campo deve ser enviado com o valor true caso se deseje confirmar a transação, ou false, caso queira desfazer o pagamento.	< 5 T/F	SIM

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de confirmação de pagamento:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef para a operação de múltiplos meios de pagamento. Qualquer código diferente de 0 significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	confirmations[]
code	Código de resposta do e-SiTef para a operação de confirmação de um dos meios de pagamento. Qualquer código diferente de 0 significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	payment
status	Status da transação de pagamento no e-SiTef. Saiba mais.	= 3 AN
authorizer_code	Código de resposta do autorizador. Em caso de repetição da confirmação ou do desfazimento, este campo não é devolvido.	< 10 AN
authorizer_message	Mensagem de resposta do autorizador. Em caso de repetição da confirmação ou do desfazimento, este campo não é devolvido.	< 500 AN
acquirer_id	Código do adquirente utilizado na transação. Em caso de repetição da confirmação ou do desfazimento, este campo não é devolvido.	< 4 N

Serviço de confirmação de pagamento de origem externa

Introdução

A funcionalidade de confirmação de pagamento de origem externa permite que uma transação de pagamento criada fora do e-SiTef possa ser confirmada dentro do e-SiTef.

Atualmente esta funcionalidade permite somente a confirmação de transações de pagamento realizadas no SiTef.

Esta operação se divide em duas etapas:

1. A criação de uma transação do tipo "Confirmação" que represente a transação real de pagamento criada externamente
2. A confirmação propriamente dita do pagamento dessa transação

Caso de sucesso

O fluxo abaixo ilustra o caminho feliz, onde a transação é iniciada e, em seguida, a confirmação já é enviada.

Criação da confirmação de pagamento de origem externa

Detalhes da Chamada

• Recurso: /v1/transactions
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM

Exemplo

Requisição:

curl --location --request POST 'https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions' 
--header 'merchant_id: xxxxxxxxxxxxxxxxxx' 
--header 'merchant_key: xxxxxxxxxxxxxxxxxx' 
--header 'Content-Type: application/json' 
--data-raw '{
    "merchant_usn": "21042858195",
    "order_id": "1621949459257",
    "amount": "300",
    "transaction_type": "confirmation",
    "is_transaction_origin_external": "true"
}'
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "confirmation": {
        "status": "PPC",
        "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "1621949459257",
        "merchant_usn": "21042858195",
        "amount": "300"
    }
}

Parâmetros da requisição

A tabela abaixo mostra os campos para a criação transação de confirmação de pagamento de origem externa.

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
amount	Valor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto	< 12N	SIM
merchant_usn	Número sequencial único para cada pedido, criado pela loja. O NSU será utilizado em toda a comunicação com a loja, de forma a identificar o pedido. Como se trata de uma possível chave para acesso do lado da loja, apesar de ser opcional para o e-SiTef, é fortemente recomendado que o campo seja formatado e enviado pela aplicação da loja.	< 12 N	NÃO
order_id	Código do pedido para ser exibido ao comprador, definido pelo lojista. É aconselhável que seja diferente a cada pedido para que facilite a rastreabilidade. Se a integração da Loja com as redes adquirentes/roteamentos (Cielo, Redecard, etc) for via SiTef (TEF), o campo orderId que tem o tamanho máximo de 40 caracteres, será reduzido a 12 caracteres, devido a uma restrição do SiTef. Essa redução será realizada mantendo os caracteres da esquerda para direita (ex.: se um código de pedido inserido for 12345678901234567890 no e-SiTef, no SiTef ele será apenas 123456789012).	< 40 AN	NÃO
transaction_type	Constante fixa e obrigatória para o tipo de transação de confirmação de pagamento de origem externa. Valor = confirmation	< 15 N	SIM
is_transaction_origin_external	Constante fixa e obrigatória para o tipo de transação de confirmação de pagamento de origem externa. Valor = true	< 5 T/F	SIM

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 201. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de criação de transações:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0 significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	payment
status	Status da transação de pagamento no e-SiTef. Saiba mais.	= 3 AN
nit	Identificador da transação de pagamento no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N
amount	Valor da compra especificado pela loja (em centavos) na criação da transação.	< 12 N

Efetivação da confirmação de pagamento de origem externa

Detalhes da chamada

• Recurso: /v1/payments/{nit}
• Método HTTP: PUT
• Formato da requisição: JSON e query string
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM

Exemplo

Requisição:

curl --location --request PUT 'https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/bacd62eb62c27f4bf2eae9cef74c93a02e831985eccb6de371628fd272ee5474?confirm=true'
--header 'merchant_id: xxxxxxxxxxxxxx'
--header 'merchant_key: xxxxxxxxxxxxx'
--header 'Content-Type: application/json' 
--data-raw '{
    "authorizer_id": "1",
    "installments": "1",
    "installment_type": "4",
    "confirmation_data": "123456789012",
    "acquirer": {
        "route_id": "5", 
        "authorization_number": "212991",
        "identification_number": "11111111111",
        "order_id": "1621949459257",
        "authorizer_date": "21/05/2021",
        "host_usn": "000212991   ",
        "terminal": "HA000006",
        "company_code": "00000000"
    }
}'
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "130",
        "status": "CON",
        "acquirer_id": "5",
        "host_usn": "000212991   "
    }
}

Parâmetros na requisição - query string

Parâmetro	Descrição	Formato	Obrigatório
confirm	Este campo deve ser enviado com o valor true caso se deseje confirmar o pagamento, ou false, caso queira desfazer o pagamento.	< 5 T/F	SIM

Parâmetros da requisição - JSON

Parâmetro	Descrição	Formato	Obrigatório
amount	Valor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto. Se não informado, assume o valor informado na criação da transação.	< 12 N	NÃO
authorizer_id	Código da autorizadora no e-SiTef. Saiba mais.	< 3 N	SIM
installments	Número de parcelas. Envie ‘1’ para transações à vista.	< 2 N	NÃO(*)
installment_type	Tipo de financiamento do parcelamento: valor 3 = parcelamento com juros da administradora do cartão. valor 4 = parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista). Valor 6 = parcelamento com juros da administradora (IATA). valor 7 = parcelamento realizado pela loja e sem juros (IATA). O parcelamento IATA é utilizado somente por empresas do seguimento de transporte aéreo.	< 2 N	NÃO(*)
confirmation_data	Informação de pagamento devolvida pelo SiTef ao se efetivar um pagamento. Este parâmetro é fundamental para o sucesso da confirmação. Ele é usada pelo SiTef para identificar o pagamento.	< 128 AN	SIM
	acquirer
route_id	Informação do roteamento utilizado para o pagamento efetuado fora do e-SiTef. Este parâmetro é fundamental para o sucesso da confirmação. Esta informação é utilizada para identificar o roteamento no SiTef.	< 5 N	SIM
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN	NÃO(*)
host_usn	NSU do host/autorizadora da transação a ser confirmada.	= 9 N	NÃO(*)
authorization_number	Número de autorização da transação a ser confirmada.	< 6 N	NÃO(*)
authorizer_date	Data de efetivação SiTef do pagamento no formato DD/MM/AAAA.	= 10 D	NÃO(*)
order_id	Código do pedido usado no pagamento iniciado externamente ao e-SiTef.	< 40 AN	NÃO(*)
identification_number	CPF ou CNPJ usado no pagamento iniciada externamente ao e-SiTef.	< 20 AN	NÃO(*)
terminal	Terminal SiTef que se deseja usar. Se NÃO for enviado, o e-SiTef gerará um terminal aleatório.	= 14 N	NÃO(*)
company_code	Código de empresa SiTef que se deseja usar. Se não for enviado, o e-SiTef enviará o código de empresa cadastrado na loja.	= 8 N	NÃO(*)

Nota: Os campos assinalados com NÃO(*) são opcionais e, se informados, não terão como ser consistidos pelo e-SiTef, pois, na operação de confirmação eles não são enviados para o SiTef. Estes campos, se informados, serão gravados na transação para fins de registro apenas.

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de confirmação de pagamento:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0 significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	payment
status	Status da transação de pagamento no e-SiTef. Saiba mais.	= 3 AN
payment_date	Data de efetivação do pagamento no e-SiTef no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
host_usn	NSU da autorizadora.	< 15 AN

Armazenamento de cartão REST

Visão Geral

O e-SiTef permite o armazenamento de cartões de crédito ou voucher para uso posterior em pagamentos, estornos ou pré-autorizações sem a necessidade de requisitar novamente os dados do cartão para o comprador. Porém, é importante notar que o código de segurança não é armazenado.

Como resultado dessa operação, a loja receberá um token, que deve ser utilizado no lugar do cartão do comprador para realizar as transações com o e-SiTef.

Em caso de erros de comunicação, a loja deve realizar a mesma chamada novamente.

Os tokens de cartões armazenados vencidos são removidos após 1 ano. Exemplo: um cartão vencido em fev/2020 será removido em fev/2021.

Detalhes da chamada

• Recurso: /v1/cards
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM

Fluxo

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de armazenamento de cartão utilizando a ferramenta cURL.

Armazenamento de cartão

Requisição:

Cartão

Carteira Digital

curl
    --request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cards"
    --header "Content-Type: application/json"
    --header "merchant_id: xxxxxxxxxxx"
    --header "merchant_key: xxxxxxxxxxx"
    --data-binary
    {
       "card":{
          "expiry_date":"1222",
          "number":"5555555555555555",
       },
       "authorizer_id":"2",
       "merchant_usn":"16013439434",
       "customer_id":"11122211122"
    }
    --verbose

curl
    --request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cards"
    --header "Content-Type: application/json"
    --header "merchant_id: xxxxxxxxxxx"
    --header "merchant_key: xxxxxxxxxxx"
    --data-binary
    {
       "card":{
          "wallet_transaction_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=="
       },
       "authorizer_id":"2",
       "merchant_usn":"16013439434",
       "customer_id":"11122211122"
    }
    --verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "card":{
      "token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==",
      "suffix":"5555"
   },
   "store":{
      "status":"CON",
      "nsua":"18051600000560A",
      "nita":"xxxxxxxxxxxxxxxxxxx",
      "merchant_usn":"16013439434",
      "customer_id":"11122211122",
      "authorizer_id":"2"
   }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de armazenamento de cartão:

Parâmetro	Descrição	Formato	Obrigatório
authorizer_id	Código da autorizadora no e-SiTef. Saiba mais.	< 3 N	SIM
merchant_usn	Número sequencial único para cada pedido, criado pela loja.	< 12 N	SIM
customer_id	Identificação do comprador para armazenamento de cartão. Esta identificação deve ser única para cada usuário da loja. Mas atenção, essa garantia de unicidade é de total responsabilidade da loja, o e-SiTef não realizará nenhuma validação.	< 20 AN	SIM
	card
number	Número do cartão do comprador (PAN). Não deve ser informado junto com o identificador da carteira.	< 19 N	COND.
expiry_date	Data de vencimento do cartão no formato MMAA. Sua obrigatoriedade depende do adquirente escolhido. Na maioria dos casos, esse campo é obrigatório.	= 4 N	COND.
wallet_transaction_id	Identificador gerado pela carteira digital. Atualmente somente suportado para a Google Pay.	< 2048 AN	COND.

Atenção: os campos card.number e card.wallet_transaction_id não devem ser definidos ao mesmo tempo na mesma requisição.

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 201. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de armazenamento de cartão:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	store
status	Status da transação de armazenamento no e-SiTef. Saiba mais.	= 3 AN
nsua	Número sequencial único da transação de armazenamento no e-SiTef.	= 15 AN
nita	Identificação do armazenado no e-SiTef.	= 64 AN
merchant_usn	Número sequencial único enviado pela loja.	< 12 N
customer_id	Identificação do comprador para armazenamento de cartão.	< 20 AN
authorizer_id	Código da autorizadora utilizada no armazenamento.	< 3 N
	card
token	Identificação do cartão armazenado. Este token deve ser utilizado no lugar do cartão do comprador para realização de transações com o e-SiTef.	= 88 AN
suffix	Últimos 4 dígitos do cartão do comprador.	= 4 AN

Cancelamento REST

Fluxo

O e-SiTef disponibiliza serviços para cancelamento (estorno) de um pagamento.

Por questões de segurança, este fluxo exige uma etapa de autenticidade, onde o e-SiTef faz um POST na URL de autenticidade cadastrada da loja com os dados necessários para dar continuidade ao fluxo e realizar o estorno de fato.

Descrição do fluxo:

• 1. O lojista inicia um cancelamento passando o esitef_usn da transação desejada (campo retornado pelo e-SiTef após aprovar o pagamento). Em caso de sucesso, o e-SiTef retornará código e mensagem correspondentes.
  • 1.1. Durante a chamada de criação de estorno, o e-SiTef fará um POST na URL de autenticidade cadastrada da loja com o NIT da transação de cancelamento. A loja deve então responder a esse POST com um código HTTP 200 (OK). Caso esse código não seja devolvido, o e-SiTef interpretará como uma falha nessa operação e invalidará o NIT.
• 2. A loja virtual prossegue o fluxo chamando o serviço de cancelamento, passando o NIT obtido no POST de autenticidade e dados adicionais que podem ser necessários dependendo da adquirente em questão (como o número do cartão, em caso de pagamentos via SiTef). Caso nenhum problema ocorra, o e-SiTef retornará uma mensagem de sucesso e os dados da transação de estorno.

Consulta dos cancelamentos

As informações das transações de cancelamento podem ser consultadas através do mesmo serviço utilizado pela interface de Pagamento REST. Saiba mais.

Quick start

Este guia mostra o processo de cancelamento de um pagamento, utilizando a interface web service REST do e-SiTef.

O que você precisará

• esitef_usn de um pagamento confirmado no e-SiTef. Saiba mais.
• Uma ferramenta capaz de realizar chamadas HTTP, como Postman, REST Client ou cURL
• Uma aplicação capaz de receber chamadas POST HTTPS

Criando a transação de cancelamento

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição: Preencha o campo <nsu_pagamento> na requisição abaixo com o esitef_usn obtido na resposta do pagamento.

JSON

cURL

{
   "esitef_usn":"<nsu_pagamento>"
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations"
--header "Content-Type: application/json" 
--header "merchant_id: xxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "esitef_usn":"<nsu_pagamento>"
}
--verbose

Recebimento do POST de autenticidade:

Java + Spring Framework

@RestController
public class MyAuthenticityController {

    @PostMapping(value = "/myauthenticity", 
        consumes = "application/x-www-form-urlencoded; charset=utf-8")
    public ResponseEntity<String> myAuthenticity(@RequestParam Map<String, String> request) {
        Log.info("nit = " + request.get("nit"));
        // ...
        // armazena o NIT do cancelamento
        // ...
        return new ResponseEntity<>("OK", HttpStatus.OK);
    }

}

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful."
}

Saiba mais sobre esse serviço.

Cancelando o pagamento

Tipo de requisição: PUT

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations/<nit>

Preencha o campo <nit> na URL acima com o NIT obtido no POST de autenticidade.

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

JSON

cURL

{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"601"
   },
   "amount":"1"
}

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations/<nit>"
--header "Content-Type: application/json" 
--header "merchant_id: xxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"601"
   },
   "amount":"1"
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":" <nit>",
      "order_id":"09062259711",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"09/11/2017T18:23",
      "authorization_number":"092423",
      "merchant_usn":"9062259711",
      "esitef_usn":"171109108051261",
      "sitef_usn":"092424",
      "host_usn":"999092424   ",
      "amount":"1",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005",
      "esitef_date":"09/11/2017T18:23",
      "is_host_cancel":"false"
   }
}

Saiba mais sobre esse serviço.

Verificando o estado do cancelamento

Tipo de requisição: GET

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions/<nit>

Preencha o campo <nit> na URL acima com o NIT obtido no POST de autenticidade.

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

cURL

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions/<nit>"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":" <nit>",
      "order_id":"09062259711",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"09/11/2017T18:23",
      "authorization_number":"092423",
      "merchant_usn":"9062259711",
      "esitef_usn":"171109108051261",
      "sitef_usn":"092424",
      "host_usn":"999092424   ",
      "amount":"1",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005",
      "esitef_date":"09/11/2017T18:23",
      "is_host_cancel":"false"
   }
}

Saiba mais sobre esse serviço.

Cancelamento via host

A funcionalidade de cancelamento via host consiste em efetuar a operação de estorno de uma transação mesmo que ela não conste nos registros do e-SiTef ou do SiTef. Por padrão, as transações são armazenadas por um período de seis meses no e-SiTef, sendo assim, cancelar uma transação efetuada em um período maior que seis meses exigirá um cancelamento via host. Porém, este prazo de seis meses pode ser alterado, logo, sugere-se consultar a equipe de atendimento e-SiTef para verificar tal condição.

Nesta modalidade de cancelamento, os dados são apenas repassados para o adquirente e o e-SiTef não possui formas de ter ciência do que realmente ocorreu com a transação (se foi realmente estornada ou não). Logo, o e-SiTef não se responsabiliza pelo resultado dessa operação.

Até o momento, o cancelamento via host pode ser feito apenas com o adquirente Cielo, via SiTef.

Configurações necessárias no e-SiTef

A loja só conseguirá efetuar o cancelamento via host caso possua permissão para esta operação no back office do e-SiTef. Para isso, é necessário comunicar à equipe de cadastro do e-SiTef a respeito dessa demanda específica.

É importante também que o lojista verifique junto ao adquirente sobre a possibilidade de efetuar esta operação, e também sobre os prazos para poder efetuá-la.

Cancelamento origem externa

A funcionalidade de cancelamento origem externa consiste em efetuar a operação de estorno de uma transação mesmo que ela não conste nos registros do e-SiTef.

Atualmente esta funcionalidade permite somente o cancelamento de transações de pagamento e pré autorização realizadas no SiTef.

Nota:

1 - Quando as informações de terminal e company_code são enviadas, o comportamento do cardquery muda ligeiramente. Neste momento, ao executar o cardquery, o e-SiTef irá identificar a rede retornada pelo SiTef. Uma vez identificada, esta será usada ao invés da cadastrada na loja.

2 - Nas operações de origem externa, não temos como validar a rede que foi utilizada na parte externa da operação, que foi feita fora do e-SiTef. Nestes casos, usamos a rede configurada no SiTef. Por causa disso, mudanças de configuração, se feitas durante o meio da operação, podem ocasionar solicitações inválidas ou negadas. Por exemplo, se uma pré autorização foi feita no meio físico na rede 181 e, antes da finalização da captura, a configuração do SiTef for alterada para a rede 125, as operações que forem feitas via e-SiTef assumirão a rede 125.

ATENÇÃO: Os parâmetros terminal e company_code devem ser enviados simultaneamente.
É necessário também solicitar à equipe de atendimento do e-SiTef a permissão Permite envio de Empresa e Terminal SiTef via REST.

Serviço de criação de cancelamento

O consumo desse serviço é obrigatório no fluxo de cancelamento. Como resultado dessa operação, o lojista obterá um NIT que será necessário para o próximo passo do fluxo.

O NIT possui um tempo limite para sua utilização. Este prazo está configurado no e-SiTef, e caso seja excedido, a transação de cancelamento passará do status NOV (nova) para EXP (expirada), o que impede futuras operações com essa transação, tornando necessário consumir novamente o serviço de criação de cancelamento.

POST de autenticidade x assinatura

O e-SiTef possui duas formas de autenticação da loja na interface de cancelamento REST: POST de autenticidade ou assinatura.

No método de POST de autenticidade, o e-SiTef enviará os dados da transação de cancelamento recém-criada para a URL de autenticidade cadastrada da loja.

No método de assinatura, a loja deve ter uma chave pública de criptografia RSA cadastrada no e-SiTef e deverá montar uma assinatura JWT (JSON Web Tokens) a ser enviada no cabeçalho Authorization. Neste caso, as informações da transação de cancelamento serão retornadas diretamente na resposta do serviço. Saiba mais.

Detalhes da chamada

• Recurso: /v1/cancellations
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM
Authorization	Deve ser enviada a assinatura de autenticação da loja no formato Bearer {assinatura}. Exemplo: Bearer JHVGytfdgauygdauiw78264284527852897hagdg.	< 2000 AN	NÃO

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de criação de cancelamento utilizando a ferramenta cURL.

Criação de cancelamento com POST de autenticidade

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "esitef_usn":"123451234512345"
}
--verbose

Em seguida, o e-SiTef irá enviar uma requisição POST HTTPS (x-www-form-urlencoded) para a URL cadastrada, este POST contém as informações necessárias para o prosseguimento do cancelamento:

POST de autenticidade:

curl -X POST \
  https://dominiodaloja.com.br \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Postman-Token: 8306e1f9-dc45-4cb9-926e-8aeef97229b1' \
  -H 'cache-control: no-cache' \
  -d 'nsu=9055020677&nit=1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr&pedido=09055020677&codigoLoja=xxxxxxxxxxxxxxx'

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful."
}

Criação de cancelamento com assinatura

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IkxPFGFURVNURSIsIm1lcmNoYW50X2tleSI6IkYxOURFMDAxNzdDMzAxREYyNEE4NjVGMTFBQTlCMjU2N0Y2MDQ4OTFGMEY0NEREQUVGRDY5RTMzOTlFMEI3RTEiLCJvcmRlcl9pZCI6IjEzMDE0ODU4NjYzIiwibWVyY2hhbnRfdXNuIjoiMTQ0NjY4MTAxNiIsInRpbWVzdGFtcCI6IjE2MDUzMDM1ODA5MzEifQ.JoYz8mQ8PZ8MCr5QXygbivAy2x9fvdUEGu_jSeOYF-BtSGm7ZSYWFVokyowabk1FM2NCklubb5eEB_-g9lCi1ntRQ9iqKhdldm-U8pl0V98u7Mv_hR-pcp6MHfqql0T-mhkOv1WkfYO1igck4N6EfsNu9iO126BwgvJQC456WjAUW5jgjRHboc6htvaak9NBs6yRVLNZY03cR9gKtQXMoHeXiCGeNU55_2W1SOeRJPk-OsyBzvVlZBX5RdfUjB2BOdRI7H2TDBBS-GZaMV3b2eS5_84JTySFnriCTXJ-Y1FzBnH60e4fTfAiYy1P_J-j9hyXjLYgtRu8jQd8ITfiFG3h4ZIysb4CA_lJNg_d4YuCqhBiZcpculcbfXlcrcfPV-CpDytfiLz34FDWH0Q7Vlna1YuSNOKPzDIUx1MOMZO9bpwaE6Q3kClkqri92-42yeLoUKH6PUrlMpE3JrfuBelALE4ce7QzCrNjcvoqR_KVmCm6ozBjPn9qY0s7x7qe6ZLur7hNUoX79JdWGZy1-bx8dSqqpLrU0SXbMBqtvch5FvdUkktbkJpZAr7q6e0nR13_mK3RTV7adOEw03E_ocUk__rEmjGDAHMSWGmiPowu14jD1-VZ2Yf8FeoKzHYcXmIbEReTVHshk9faBICMQzMS3SXaqow4WXqULZiLTwc"
--data-binary
{
   "esitef_usn":"123451234512345"
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "nit":" 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"09062259711",
      "merchant_usn":"9062259711"
   }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de criação de cancelamento:

Parâmetro	Descrição	Formato	Obrigatório
esitef_usn	NSU do pagamento a ser cancelado. Essa informação é retornada pelo e-SiTef após o pagamento ser aprovado. Este campo não deve ser enviado para cancelamento de transação original gerada externamente ao e-Sitef.	= 15 N	COND
order_id	Código de pedido do pagamento a ser cancelado. Este campo só deve ser enviado em caso de cancelamento via host ou origem externa.	< 40 AN	NÃO
merchant_usn	NSU gerado pela loja do pagamento a ser cancelado. Este campo só deve ser enviado em caso de cancelamento via host ou origem externa.	< 12 N	NÃO
is_transaction_origin_external	Indica se a transação foi originada fora do e-SiTef. É obrigatório o envio deste campo com valor 'true' para cancelamento origem externa.	< 5 AN	COND

Parâmetros do POST de autenticidade

Na tabela abaixo está a descrição dos parâmetros enviados pelo e-SiTef no POST de autenticidade:

Parâmetro	Descrição	Formato
nit	Identificador da transação de cancelamento a ser utilizado na próxima etapa do fluxo.	= 64 AN
pedido	Código de pedido do pagamento a ser cancelado.	< 20 AN
nsu	NSU gerado pela loja do pagamento a ser cancelado.	< 12 N
codigoLoja	Código da loja no e-SiTef.	< 15 AN

O e-SiTef também pode enviar novos parâmetros sem aviso prévio, o que significa que a aplicação do lojista deve estar preparada para receber campos extras e simplesmente ignorá-los.

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 201. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de criação de cancelamento:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
cancellation	Estes campos só são retornados ao usar autenticação com assinatura.
nit	Identificador da transação de cancelamento a ser utilizado na próxima etapa do fluxo.	= 64 AN
order_id	Código de pedido do pagamento a ser cancelado.	< 20 AN
merchant_usn	NSU gerado pela loja do pagamento a ser cancelado.	< 12 N

Serviço de cancelamento

Após obter um NIT de cancelamento na etapa anterior, a loja poderá realizar o estorno de fato.

Após um cancelamento bem-sucedido, a transação de pagamento mudará seu status para EST (estornada). Dependendo do adquirente, é possível realizar estornos parciais, ou seja, cancelar um valor menor do que o que foi pago. Nesse caso, a transação de pagamento manterá o status CON.

Detalhes da chamada

• Recurso: /v1/cancellations/{nit}
• Método HTTP: PUT
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de cancelamento utilizando a ferramenta cURL.

Cancelamento de pagamento via SiTef

Requisição:

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"
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":" 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"09062259711",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"09/11/2017T18:23",
      "authorization_number":"092423",
      "merchant_usn":"9062259711",
      "esitef_usn":"171109108051261",
      "sitef_usn":"092424",
      "host_usn":"999092424   ",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005",
      "esitef_date":"09/11/2017T18:23",
      "is_host_cancel":"false"
   }
}

Cancelamento de pagamento via Cielo e-Commerce

Requisição:

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
{}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"0",
      "authorizer_message":"Operation Successful",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"10022938077",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"2",
      "acquirer_id":"201",
      "acquirer_name":"Cielo e-Commerce",
      "merchant_usn":"10022938091",
      "esitef_usn":"171110108163221",
      "amount":"1000",
      "payment_type":"C",
      "authorizer_merchant_id":"zzzzzzzzzzzzzzzzzz",
      "esitef_date":"10/11/2017T14:29",
      "is_host_cancel":"false"
   }
}

Cancelamento via host

Requisição:

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":{
      "expiry_date":"1222",
      "number":"455182001234512345"
   },
   "amount":"2000",
   "acquirer":{
      "host_usn":"123123123",
      "sitef_usn":"123123",
      "authorizer_date":"090917",
      "authorizer_id":"1",
      "tef_product_code":"0001",
      "tef_flow_code":"01",
      "authorization_number":"123456"
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK!",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"1",
      "acquirer_id":"1125",
      "acquirer_name":"Cielo",
      "authorizer_date":"09/11/2017T18:42",
      "authorization_number":"092425",
      "esitef_usn":"171109108051271",
      "sitef_usn":"092425",
      "host_usn":"000092425   ",
      "amount":"2000",
      "payment_type":"C",
      "authorizer_merchant_id":"020001355570001",
      "esitef_date":"09/11/2017T18:42",
      "is_host_cancel":"true"
   }
}

Cancelamento origem externa

Requisição:

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":{
      "expiry_date":"1222",
      "number":"455182001234512345"
   },
   "amount":"2000",
   "acquirer":{
      "host_usn":"123123123",
      "sitef_usn":"123123",
      "authorizer_date":"090917",
      "authorizer_id":"2",
      "authorization_number":"123456"
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK!",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"09/11/2017T18:42",
      "authorization_number":"092425",
      "esitef_usn":"171109108051271",
      "sitef_usn":"092425",
      "host_usn":"000092425   ",
      "amount":"2000",
      "payment_type":"C",
      "authorizer_merchant_id":"020001355570001",
      "esitef_date":"09/11/2017T18:42"
   }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de cancelamento:

Parâmetro	Descrição	Formato	Obrigatório
amount	Valor em centavos a ser cancelado. É importante notar que não são todos os adquirentes que suportam estorno com valor menor do que o do pagamento (cancelamento parcial). Caso este campo não seja enviado, o e-SiTef utilizará o valor total do pagamento.	< 12 N	NÃO
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais	< 30 AN	NÃO
	card
number	Número do cartão do comprador (PAN). Obrigatório no cancelamento de pagamentos via SiTef.	< 19 N	COND.
expiry_date	Data de vencimento do cartão no formato MMAA. Sua obrigatoriedade depende do adquirente escolhido.	= 4 N	COND.
security_code	Código de segurança. Obrigatório dependendo do contrato firmado com as redes adquirentes.	< 5 N	COND.
token	HASH de um cartão armazenado no e-SiTef. Não é permitido enviar um número de cartão aberto (campo number) e um cartão armazenado (campo token) na mesma requisição.	= 88 AN	NÃO
wallet_transaction_id	ID de uma transação de carteiras digitais. Por enquanto, essa funcionalidade está disponível apenas para as autorizadoras Visa Checkout e VEE (via CardSE via SiTef). Não é permitido enviar um número de cartão aberto (campo number), um cartão armazenado (campo token) e um wallet_transaction_id na mesma requisição.	< 25 AN	NÃO
acquirer	Os campos desse elemento só devem ser enviados em casos de cancelamentos via host, cancelamentos de origem externa ou cancelamentos de roteamentos via PayPal
host_usn	NSU do host/autorizadora da transação a ser cancelada. Obrigatório para cancelamentos via host e origem externa.	< 20 N	COND.
sitef_usn	NSU do SiTef da transação a ser cancelada. Obrigatório para cancelamentos via host e origem externa.	= 6 N	COND.
authorizer_date	Data de efetivação SiTef do pagamento no formato DDMMAA. Obrigatório para cancelamentos via host e origem externa.	= 6 D	COND.
authorizer_id	Código da autorizadora no e-SiTef. Deve ser o mesmo valor enviado no pagamento. Obrigatório para cancelamentos via host e origem externa.	< 3 N	COND.
tef_product_code	Código do produto TEF obtido no pagamento. Este campo pode receber os seguintes valores: 0001 - Visa 0080 - Mastercard Estes valores podem ser alterados pela Cielo sem aviso prévio. Obrigatório para cancelamentos via host e origem externa para roteamento via Cielo.	< 4 N	COND.
tef_flow_code	Código do fluxo TEF obtido no pagamento. Atualmente, este campo pode apenas receber o valor 01 (fluxo crédito). Obrigatório para cancelamentos via host e origem externa para roteamento via Cielo.	< 2 N	COND.
authorization_number	Número de autorização da transação a ser cancelada. Obrigatório para cancelamentos via host e origem externa.	< 60 N	COND.
product_code	Códido de produto. É obrigatório e utilizado apenas em roteamento via Marisa.	< 6 N	COND.
refund_type	Tipo de estorno que se deseja realizar sobre o pagamento. É obrigatório e utilizado apenas para roteamento via Paypal. Valores permitidos: Full - É desejado o estorno completo do pagamento. Partial - É desejado o estorno parcial do pagamento	< 7 AN	COND.
currency_code	Código da moeda a ser utilizada no estorno de acordo com a ISO 4217. Para o Real, o código utilizado é o BRL. É obrigatório e utilizado apenas para roteamento via Paypal.	< 3 AN	COND.
invoice_id	Código de pedido do estorno próprio do lojista para futura consulta ou rastreamento. Utilizado apenas para roteamento via Paypal.	< 127 AN	NÃO
note	Mensagem personalizada para lembretes sobre o estorno. Utilizado apenas para roteamento via Paypal.	< 256 AN	NÃO
retry_until	Data e hora limite até a qual será realizada a tentativa do estorno. Formato: AAAA-MM-DDTHH:MM:SS. Utilizado apenas para roteamento via Paypal.	< 20 AN	NÃO
refund_source	Fonte de fundos do lojista que será utilizado para realizar o estorno. Utilizado apenas para roteamento via Paypal. Valores permitidos: any - O lojista não tem preferência. Será utilizado qualquer fonte de fundos disponível. default - Será utilizado a fonte de fundos configurada na conta do lojista. instant - Será utilizado o balanço do vendedor como fonte de fundos. eCheck - Será utilizado a opção “eCheck” como fonte de fundos. Se o balanço do lojista puder cobrir o estorno, será utilizado o balanço.	< 7 AN	NÃO
merchant_store_details	Informações sobre o estabelecimento do lojista. Utilizado apenas para roteamento via Paypal.	< 50 AN	NÃO
refund_advice	Indicador para cliente que já foi recebeu algum estorno da determinada transação. Utilizado apenas para roteamento via Paypal.	< 5 AN	NÃO
refund_item_details	Detalhes do item individual tratado no estorno. Utilizado apenas para roteamento via Paypal.		NÃO
msg_sub_id	Esse ID identificará de maneira única a mensagem e poderá ser utilizado para requisitar os últimos resultados de um requisição anterior sem a necessidade de criar uma nova requisição. Isso pode ser realizado, por exemplo, em chamadas que foram canceladas por timeout ou erros durante o processo. Utilizado apenas para roteamento via Paypal.	< 38 AN	NÃO
terminal_id	Utilizado caso seja um Ponto de Venda. Utilizado apenas para roteamento via Paypal.	< 50 AN	NÃO
store_id	Utilizado caso seja um Ponto de Venda. Utilizado apenas para roteamento via Paypal.	< 50 AN	NÃO
terminal	Terminal SiTef que se deseja usar. Se não for enviado, o e-SiTef gerará um terminal aleatório.	= 14 N	NÃO
company_code	Código de empresa SiTef que se deseja usar. Se não for enviado, o e-SiTef enviará o código de empresa cadastrado na loja.	= 8 N	NÃO
acquirer.submerchant_split[]	Consiste em um array para transações split, exclusivos para roteamentos BIN e Sipag, ambos via SiTef. Permite a divisão de partes do valor total do pagamento entre outras empresas. O máximo de itens permitido neste array é de 5 itens. Cada item é composto pelos campos submechant_code e submerchant_amount.
submerchant_code	código de estabelecimento BIN/Sipag	< 51 AN	NÃO
submerchant_amout	valor de transação referente ao estabelecimento	< 12 N	NÃO

ATENÇÃO: Os parâmetros terminal e company_code são para uso somente no Cancelamento origem externa. Neste caso, os mesmos devem ser enviados simultaneamente.
É necessário também solicitar à equipe de atendimento do e-SiTef a permissão Permite envio de Empresa e Terminal Sitef via REST.

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de cancelamento:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	cancellation
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
status	Status da transação de cancelamento no e-SiTef. Saiba mais.	= 3 AN
nit	Número identificador da transação de cancelamento no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N
amount	Valor do cancelamento especificado pela loja (em centavos).	< 12 N
sitef_usn	Número sequencial único da transação de cancelamento no SiTef.	= 6 N
esitef_usn	Número sequencial único da transação de cancelamento no e-SiTef.	= 15 N
customer_receipt	Cupom (via cliente).	< 4000 AN
merchant_receipt	Cupom (via estabelecimento).	< 4000 AN
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N
acquirer_id	Código do adquirente utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente utilizado na transação.	< 100 AN
authorizer_date	Data de efetivação do cancelamento retornada pelo autorizador no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
authorization_number	Número de autorização.	< 6 AN
host_usn	NSU da autorizadora.	< 20 AN
tid	ID da transação no adquirente. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
esitef_date	Data de efetivação do cancelamento no e-SiTef no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
is_host_cancel	Este campo retornará o valor true em caso de cancelamento via host.	< 5 T/F

Visão Geral

A pré-autorização é uma transação cujo valor será reservado do limite do cartão, porém não será debitado imediatamente, podendo ser capturado posteriormente por um valor igual ou menor que o autorizado. O prazo para realizar a captura, assim como a possibilidade de capturar valores menores, depende de negociação com a rede adquirente/roteamento, cabendo à Loja Virtual consultar a rede adquirente/roteamento.

A pré-autorização é utilizada nos casos em que será necessário realizar a captura da transação após um longo período de tempo. Assim, é possível apenas autorizar uma transação de pagamento e confirmá-la/capturá-la em um dia posterior. A diferença entre um pagamento com confirmação posterior e uma pré autorização com captura é o período de tempo em que a transação poderá ser efetivada.

O período permitido para realizar a confirmação/captura de uma pré-autorização é maior do que um pagamento com confirmação posterior. Para melhor entendimento, podemos citar os seguintes exemplos de aplicação:

Uma empresa de aluguel de carros realiza a autorização de um pagamento para um cliente. A empresa irá capturar/confirmar a transação apenas quando o cliente devolver o carro, o que pode levar muitos dias. Neste cenário, seria recomendada a utilização de uma transação de Pré-Autorização.

Uma loja autoriza um pagamento, mas antes de confirmar/capturar a transação, realiza um consulta no estoque para verificar a disponibilidade de um meio de pagamento, o que poderia levar alguns minutos ou horas, e após isso efetivar o pagamento. Neste cenário, seria recomendada a utilização de uma transação de pagamento comum com confirmação posterior.

Comunicação

Para realizar uma transação Web Service, toda a comunicação será realizada via HTTPS/TLS. É importante que o servidor do lojista suporte criptografia com no mínimo 128 bits e protocolo mínimo TLS 1.2. O servidor da loja deverá realizar chamadas em endereços específicos para transações REST.

Cada serviço deve ser chamado utilizando a URL base concatenada do recurso desejado (veja o capítulo referente ao serviço a ser consumido). O método HTTP (GET, POST ou PUT) indica a ação esperada sobre o recurso escolhido. Abaixo estão as URLs base do e-SiTef:

URL do ambiente de Certificação/testes:

https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/

URL do ambiente de Produção:

https://esitef-ec.softwareexpress.com.br/e-sitef/api/

Atenção: Nunca utilizar o IP ao invés do domínio esitef-ec.softwareexpress.com.br, porque o IP poderá mudar a qualquer momento e sem aviso prévio, portanto, é importante a utilização do domínio para acesso ao e-SiTef.

Importante: Além dos parâmetros de resposta do webservice descrito nesta especificação, o e-SiTef poderá retornar outros parâmetros sem aviso prévio. É importante que o aplicativo esteja preparado para receber parâmetros extras além dos parâmetros já especificados e simplesmente desprezá-los.

Fluxo

O fluxo de pré-autorização será iniciado pela Loja Virtual quando o aplicativo enviar a operação beginTransaction, na resposta da requisição o aplicativo receberá o nit e outros parâmetros.

Descrição do fluxo:

1. Ao iniciar a operação beginTransaction pela loja virtual, é retornado um nit (identificador da transação) e outros parâmetros;
2. A loja virtual prossegue então consumindo o doPreAuthorization, serviço de efetivação da pré-autorização, passando o nit e os demais parâmetros recebidos. Em caso de sucesso, a transação de pré-autorização mudará seu status para CON (transação confirmada).
3. Posteriormente (conforme a regra de negócio) o mesmo nit enviado na pré-autorização, deverá ser enviado na operação capture juntamente com outros parâmetros e deverá tratar os parâmetros recebidos no webservice response.

Quick start

Este guia mostra o processo de efetivação de uma pré-autorização, utilizando a interface web service REST do e-SiTef.

O que você precisará

• Cadastro ativo no ambiente de homologação do e-SiTef (obtido com nossa equipe de suporte)
• Uma ferramenta capaz de realizar chamadas HTTP, como Postman, REST Client ou cURL

Criando a Pré-Autorização

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

JSON

cURL

{
    "order_id":"orderID",
    "merchant_usn":"20190101",
    "amount":"100",
    "transaction_type":"preauthorization"
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "order_id":"orderID",
    "merchant_usn":"20190101",
    "amount":"100",
    "transaction_type":"preauthorization"
}
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "pre_authorization": {
        "status": "NOV",
        "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "orderID",
        "merchant_usn": "20190101",
        "amount": "100"
    }
}

Saiba mais sobre esse serviço.

Efetivando a Pré-Autorização

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/<nit>

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

JSON

cURL

{
    "authorizer_id":"2",
    "installments":"2",
    "installment_type":"4",
    "card":{
        "number":"xxxxxxxxxxxxxxxx",
        "expiry_date":"1222",
        "security_code":"123"
    }
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "authorizer_id":"2",
    "installments":"2",
    "installment_type":"4",
    "card":{
        "number":"xxxxxxxxxxxxxxxx",
        "expiry_date":"1222",
        "security_code":"123"
    }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "pre_authorization":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK.",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "customer_receipt":"=== CUSTOMER RECEIPT ===",
      "merchant_receipt":"=== MERCHANT RECEIPT ===",
      "authorizer_id":"2",
      "authorizer_date":"09/11/2018T19:40",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorization_number":"013245",
      "merchant_usn":"20190101",
      "esitef_usn":"181109017689784",
      "order_id":"orderID",
      "sitef_usn":"212194",
      "host_usn":"999212194",
      "amount":"100",
      "issuer":"2",
      "payment_type":"C",
      "authorizer_merchant_id":"000000000000000"
   }
}

Saiba mais sobre esse serviço.

Capturando a Pré-Autorização

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/capture/<nit>

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

JSON

cURL

{
    "amount":"100",
    "installments":"1",
    "installment_type":"4",
    "card":{
    "number":"xxxxxxxxxxxxxxxx",
    "expiry_date":"1222",
    "security_code":"123"
    },
    "acquirer":{
        "submerchant_split":[
            {
                "submerchant_code":"empresa01",
                "submerchant_amount":"10"
            },
            {
                "submerchant_code":"empresa02",
                "submerchant_amount":"20"
            },
            {
                "submerchant_code":"empresa03",
                "submerchant_amount":"20"
            },
            {
                "submerchant_code":"empresa04",
                "submerchant_amount":"30"
            },
            {
                "submerchant_code":"empresa05",
                "submerchant_amount":"30"
            }
        ]
    }
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/capture/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "amount":"100",
    "installments":"1",
    "installment_type":"4",
    "card":{
    "number":"xxxxxxxxxxxxxxxx",
    "expiry_date":"1222",
    "security_code":"123"
    },
    "acquirer":{
        "submerchant_split":[
            {
                "submerchant_code":"empresa01",
                "submerchant_amount":"10"
            },
            {
                "submerchant_code":"empresa02",
                "submerchant_amount":"20"
            },
            {
                "submerchant_code":"empresa03",
                "submerchant_amount":"20"
            },
            {
                "submerchant_code":"empresa04",
                "submerchant_amount":"30"
            },
            {
                "submerchant_code":"empresa05",
                "submerchant_amount":"30"
            }
        ]
    }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "capture":{
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"orderID",
      "customer_receipt":"=== CUSTOMER RECEIPT ===",
      "merchant_receipt":"=== MERCHANT RECEIPT ===",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK.",
      "authorizer_date":"11/08/2019T14:17",
      "authorizer_merchant_id":"000000000000000",
      "authorization_number":"212195",
      "esitef_usn":"180921015287704",
      "merchant_usn":"20190101",
      "sitef_usn":"212195",
      "host_usn":"999212195",
      "amount":"100",
      "payment_type":"C",
      "issuer":"2"
   }
}

Saiba mais sobre esse serviço.

Consulta de Cartão

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/<nit>/cards

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

JSON

cURL

{
    "card":{
        "number":"5555555555555555"
    },
    "authorizer_id":"1"
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "card":{
        "number":"5555555555555555"
    },
    "authorizer_id":"1"
}
--verbose

Resposta:

{
    "code":"0",
    "message":"OK. Transaction successful.",
    "preauthorization":{
        "status":"NOV"
    },
    "card":{
        "acquirer_name":"Redecard",
        "authorizer_id":"1",
        "authorizer_response_code":"000",
        "is_customer_id_required":"false",
        "is_expiry_date_required":"true",
        "is_installment_funding_enabled":"true",
        "is_security_code_required":"true",
        "is_spot_sale_enabled":"true",
        "is_with_interest_sale_enabled":"true",
        "is_without_interest_sale_enabled":"true",
        "max_installments_with_interest":"12",
        "min_installments_with_interest":"01",
        "prefixes":{
            "TRAT":"2",
            "PERIFERICO":"1",
            "CSEG":"2"
        }
    }
}

Saiba mais sobre esse serviço.

Consulta de Transações

Tipo de requisição: GET

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transaction/<nit>

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

cURL

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "pre_authorization":{
      "acquirer_id":"1181",
      "acquirer_name":"GetNet Lac",
      "amount":"1470",
      "authorization_number":"301367",
      "authorizer_code":"000",
      "authorizer_date":"30/10/2018T11:58",
      "authorizer_id":"1",
      "authorizer_merchant_id":"000000000000000",
      "authorizer_message":"Transacao OK",
      "customer_receipt":"=== CUSTOMER RECEIPT ===",
      "merchant_receipt":"=== MERCHANT RECEIPT ===",
      "esitef_usn":"181030016873984",
      "host_usn":"010301367   ",
      "issuer":"1",
      "merchant_usn":"20180809",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"201808020001",
      "payment_type":"C",
      "sitef_usn":"301367",
      "status":"CON"
   },
   "capture":{
      "acquirer_id":"1181",
      "acquirer_name":"GetNet Lac",
      "amount":"1380",
      "authorization_number":"000000",
      "authorizer_date":"30/10/2018T12:00",
      "authorizer_id":"1",
      "customer_receipt":"=== CUSTOMER RECEIPT ===",
      "merchant_receipt":"=== MERCHANT RECEIPT ===",
      "esitef_usn":"181030016874034",
      "host_usn":"010301368   ",
      "issuer":"1",
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK SDO DISPONIVEL          244,00",
      "merchant_usn":"20180809",
      "nit":"abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr1234567890",
      "order_id":"201808020001",
      "authorizer_merchant_id":"000000000000000",
      "payment_type":"C",
      "sitef_usn":"301368",
      "status":"CON"
   }
}

Saiba mais sobre esse serviço.

Criar Pré-Autorização

O fluxo da transação de Pré-Autorização é iniciado consumindo a operação beginTransaction, que irá gerar um registro no e-SiTef de uma transação com status=NOV, e, retornará ao aplicativo o parâmetro nit, que identificará essa transação.

O nit tem um prazo de utilização configurado no e-SiTef, se esse tempo limite exceder a transação passará do status "NOV" para o status "EXP". Neste caso não será mais permitido a utilização do mesmo nit, sendo necessário consumir novamente a operação beginTransaction para gerar outro nit válido.

Análise de risco

Para as transações com análise de risco (antifraude), são utilizados os mesmos campos da criação de pagamento com antifraude.

Detalhes da Chamada

• Recurso: /v1/transactions
• Operação HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
Content-Type	Valor fixo "application/json"	= 15 A	Sim
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes	≤ 15 A	Sim
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 A	Sim

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de criação de transações utilizando a ferramenta cURL.

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "order_id":"orderID",
    "merchant_usn":"20190101",
    "amount":"100",
    "transaction_type":"preauthorization"
}
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "pre_authorization": {
        "status": "NOV",
        "nit":
        "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "orderID",
        "merchant_usn": "20190101",
        "amount": "100"
    }
}

Parâmetros de Requisição

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
amount	Valor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto	< 12N	Sim
encrypted_card	Este campo deve ser enviado com valor "true" caso o número do cartão a ser enviado na próxima etapa do fluxo use a criptografia do SiTef. A opção de envio do cartão criptografado só será possível com roteamento via SiTef e é necessário a configuração prévia do SiTef em questão. Opções: 1. "true" 2. "false" (valor default)	< 5 AN	Não
merchant_usn	Número sequencial único para cada pedido, criado pela loja. O NSU será utilizado em toda a comunicação com a loja, de forma a identificar o pedido. Como se trata de uma possível chave para acesso do lado da loja, apesar de ser opcional para o e-SiTef, é fortemente recomendado que o campo seja formatado e enviado pela aplicação da loja.	< 12 N	Não
order_id	Código do pedido para ser exibido ao comprador, definido pelo lojista. É aconselhável que seja diferente a cada pedido para que facilite a rastreabilidade. Se a integração da Loja com as redes adquirentes/roteamentos (Cielo, Redecard, etc) for via SiTef (TEF), o campo orderId que tem o tamanho máximo de 40 caracteres, será reduzido a 12 caracteres, devido a uma restrição do SiTef. Essa redução será realizada mantendo os caracteres da esquerda para direita (ex.: se um código de pedido inserido for 12345678901234567890 no e-SiTef, no SiTef ele será apenas 123456789012).	< 40 AN	Não
transaction_type	Valor fixo "preauthorization"	= 15 A	Sim
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais	< 22 AN	NÃO

Legenda do tipo do campo "Tamanho":

A = alfanumérico

N = numérico

N A = não utilizado

Parâmetros de resposta

Nome do Parâmetro	Descrição	Tamanho
code	Código de resposta do e-SiTef. Qualquer código diferente de ‘0’ significa falha. Para maiores informações, consulte Códigos de Resposta.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 A
amount	Valor da transação especificado pela loja (em centavos) na criação da transação.	< 12 N
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N
nit	Identificador da transação de pré-autorização no e-SiTef.	= 64 A
order_id	Código de pedido enviado pela loja na criação da transação	< 40 AN
status	Status da transação de pré-autorização no e-SiTef.	= 3 A

Efetivação de Pré-Autorização

Detalhes da Chamada

O nit obtido no retorno do serviço de criação de pré-autorização deverá ser enviado na operação de efetivação de pré-autorização juntamente com os parâmetros descritos na tabela abaixo (conforme a necessidade de cada aplicação):

• Recurso: /v1/preauthorizations/{nit}
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
Content-Type	Valor fixo application/json	= 15 AN	SIM
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM

Exemplos:

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "authorizer_id":"2",
    "installments":"2",
    "installment_type":"4",
    "card":{
        "number":"xxxxxxxxxxxxxxxx",
        "expiry_date":"1222",
        "security_code":"123"
    }
}
--verbose

Resposta:

{
    "code":"0",
    "message":"OK. Transaction successful.",
    "pre_authorization":{
        "authorizer_code":"000",
        "authorizer_message":"Transacao OK.",
        "status":"CON",
        "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "customer_receipt":"=== CUSTOMER RECEIPT ===",
        "merchant_receipt":"=== MERCHANT RECEIPT ===",                
        "authorizer_id":"2",
        "authorizer_date":"09/11/2018T19:40",
        "acquirer_id":"1005",
        "acquirer_name":"Redecard",
        "authorization_number":"013245",
        "merchant_usn":"20190101",
        "esitef_usn":"181109017689784",
        "order_id":"orderID",
        "sitef_usn":"212194",
        "host_usn":"999212194",
        "amount":"100",
        "issuer":"2",
        "payment_type":"C",
        "authorizer_merchant_id":"000000000000000"
    }
}

Parâmetros de requisição

Parâmetro	Descrição	Formato	Obrigatório
authorizer_id	Código da autorizadora no e-SiTef. Ver documento Autorizadoras.	< 3 N	SIM
customer_id	Documento de identidade do comprador. Use apenas caracteres alfanuméricos (sem pontos, traços ou outros caracteres especiais).	< 20 AN	NÃO
discount	Valor do desconto, em centavos. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente.	< 12 N	NÃO
installments	Juntamente com o campo installment_type, indica parcelamento (*), utilizados APENAS com autorizadoras roteadas por e-Rede, GetNetLac via SiTef, Rede via SiTef, Cetelem via SiTef e iCards via SiTef. Envie 1 para transações à vista.	< 2 N	COND.
installment_type	Juntamente com o campo installments, indica parcelamento (*), utilizados APENAS com autorizadoras roteadas por e-Rede, GetNetLac via SiTef, Rede via SiTef, Cetelem via SiTef e iCards via SiTef. Para as demais roteamentos, o parcelamento é possível somente na captura. Os valores possíveis para installment_type são: 3: Parcelamento com juros da administradora do cartão 4: Parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista)	= 1 N	COND.
mcc	Merchant Category Code - Indica o código de categoria da loja. Necessário ao utilizar subadquirência Stone WS e é possível enviá-lo na subadquirência via SiTef.	< 4 N	Obrigatório apenas para subadquirência Stone WS
merchant_email	e-mail da Loja. Este parâmetro quando enviado sobrescreve o e-mail do cadastro da Loja.	< 40 AN	NÃO
nit	Identificador da transação no e-SiTef (criptografado). Obtido no retorno da chamada ao beginTransaction.	= 64 AN	SIM
promo_code	Código de promoção Visa Checkout utilizado na pré-autorização. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente.	AN	NÃO
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais	< 22 AN	NÃO
subtotal	Valor do subtotal, em centavos. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente.	< 12 N	NÃO
subacquirer_merchant_id	Identificação da loja na subadquirente.	< 22 N	NÃO
card	Deve ser utilizado apenas um entre os campos: number, token ou wallet_transaction_id
number	Número do cartão do comprador (PAN).	< 19 N	COND.
token	Utilizado para casos de pré-autorização recorrente, onde o cartão já deverá estar armazenado na base de dados do e-SiTef.	= 88 AN	COND.
wallet_transaction_id	Código de identificação de transação com wallet VisaCheckout. Necessário apenas para Visa Checkout	< 25 AN	COND.
initial_wallet_transaction_id	Informa se o Wallet ID (wallet_transaction_id) está sendo utilizado pela primeira vez. Se for a primeira vez, enviar true, caso contrário, enviar false. Necessário apenas para Visa Checkout. Valor padrão: true	< 5 AN	COND.
holder	Nome do portador do cartão. Obrigatório apenas para roteamentos e-Rede, GetNet WS e VR (SmartNet).	< 30 AN	COND.
expiry_date	Data de vencimento do cartão no formato MMAA.	= 4 N	COND.
security_code	Código de segurança.	< 5 N	COND.
external_authentication	Este elemento recebe campos de autenticação MPI.
eci	Eletronic Commerce Indicator – indica o nível de segurança da transação com autenticação do dono do cartão	< 3 N	NÃO
xid	Identificador da transação de autenticação do dono do cartão, feita em serviço externo ao e-SiTef	< 40 N	NÃO
cavv	Cardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão.	< 40 N	NÃO
acquirer	Dados específicos necessários dependendo da adquirente/roteamento.
terminal	Terminal SiTef que se deseja usar. Se não for enviado, o e-SiTef gerará um terminal aleatório.	= 14 N	NÃO
company_code	Código de empresa SiTef que se deseja usar. Se não for enviado, o e-SiTef enviará o código de empresa cadastrado na loja.	= 8 N	NÃO

(*) Parcelamento roteada por GetNetLac via SiTef : Neste caso, a loja será responsável pelo controle do parcelamento, logo não entrarão em vigor as regras de parcelamento configuradas para a interface de pagamento HTML do e-SiTef, somente as regras de parcelamento da autorizadora serão verificadas e aplicadas. Para estas redes mencionadas, caso a pré-autorização seja feita à vista, a captura não pode ser parcelada. Ainda, pré- autorizações roteadas por GetNetLac via SiTef, quando parceladas, apenas são aceitos sem juros, isto é, com o parâmetro installment_type = 4. Parcelamentos com juros não são aceitos para este roteamento.

ATENÇÃO: Os parâmetros terminal e company_code deverão ser usados somente para roteamentos via SiTef e devem ser enviados simultaneamente.
É necessário também solicitar à equipe de atendimento do e-SiTef a permissão Permite envio de Empresa e Terminal Sitef via REST.

Parâmetros de resposta

A tabela abaixo contém os parâmetros de resposta do serviço de efetivação de pré-autorização. O aplicativo deverá armazenar os parâmetros que achar necessário. Sugerimos que sejam armazenados os parâmetros: order_id, authorization_number, merchant_usn, esitef_usn, sitef_usn, host_usn, status, code, amount, message (o parâmetro message poderá ser exibido ao cliente).

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0 significa falha. Para maiores informações, consulte o documento de Códigos de Resposta.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
pre_authorization
acquirer_id	Código do adquirente/roteamento utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente/roteamento utilizado na transação.	< 100 AN
amount	Valor da compra especificado pela loja (em centavos) na criação da transação.	< 12 AN
authorization_number	Número de autorização.	< 6 AN
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_date	Data de efetivação da pré-autorização retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
customer_receipt	Cupom (via cliente).	< 4000 AN
eci	Eletronic Commerce Indicator (indicador do nível de segurança da transação da pré-autorização via Cielo e-Commerce).	< 3 AN
esitef_usn	Número sequencial único da transação de pré-autorização no e-SiTef.	= 6 N
host_usn	NSU da autorizadora.	< 15 AN
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
merchant_receipt	Cupom (via estabelecimento).	< 4000 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 AN
nit	Identificador da transação de pré-autorização no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
payment_type	Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios de pagamento	= 1 AN
sitef_usn	Número sequencial único da transação de pré-autorização no SiTef.	= 6 N
status	Status da transação de pré-autorização no e-SiTef.	= 3 AN
tid	ID da transação no adquirente/roteamento. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
xid	Campo XID retornado em autenticações 3DS ou certos adquirentes/roteamentos.	< 40 AN

Serviço de Consulta de Pré-Autorização

Em caso de falha na comunicação ou demora excessiva na resposta (timeout) em qualquer uma das operações subsequentes ao beginTransaction, a loja obrigatoriamente deverá consumir a operação getStatus. Esta operação permite que se verifique o status de uma requisição a qual o lojista não obteve a resposta, recuperando os parâmetros que não pôde receber no fluxo normal.

A loja deverá recuperar o status da transação (com o prazo máximo para a consulta de 15 dias) desde que possua o nit, através do webservice getStatus, passando como parâmetro a chave de autenticação da loja (merchantKey) e o nit.

Desenvolvimento/Certificação: caso não tenha recebido o merchantKey para desenvolvimento/certificação, favor solicitar através do e-mail autorizadores5317@softwareexpress.com.br ou pelo telefone (11) 3170-5317.

Produção: o merchantKey para Produção será enviado pela equipe do e-SiTef de Produção, caso não tenha recebido depois dos devidos procedimentos para a entrada em Produção, favor solicitar ao e-mail esitef.prod6773@softwareexpress.com.br.

Note que em casos excepcionais a chave de autenticação (merchantKey) pode ser alterada por questões de segurança, porém a equipe de produção irá entrar em contato com a loja antes da alteração.

Lembrando que diversos fatores podem ocasionar a demora na resposta, incluindo instabilidade de internet e o host da rede autorizadora do cartão. Recomendamos que o servidor da loja tenha configurado o timeout igual ou superior a 90 segundos.

Nota: Este serviço só irá devolver os dados se a transação tiver sido efetuada via Web Services, não irá funcionar em caso de transações via Interface HTML.

Atenção: A consulta de transação no e-SiTef NÃO efetua uma consulta do status da transação no adquirente / autorizador. Este serviço retorna o status da transação na base de dados do e-SiTef.
Exemplo: Caso uma transação de pré-autorização seja confirmada no e-SiTef, mas seja estornada via telefone diretamente no adquirente / autorizador, este estorno não será necessariamente refletido no serviço de consulta de transação do e-SiTef.

Detalhes da chamada

• Recurso: /v1/transactions/{nit}

• Método HTTP: GET

• Formato da requisição: JSON

• Formato da resposta: JSON

• Parâmetros de cabeçalho:

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
Content-Type	Valor fixo "application/json"	= 15 A	Sim
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	≤ 80 A	Sim
nit	Identificador da transação no e-SiTef. Obtido no retorno da chamada ao beginTransaction.	= 64 A	Sim

Parâmetros de Requisição

Na URL do recurso deve ser enviado o nit

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
nit	Identificador da transação no e-SiTef. Obtido no retorno da chamada ao beginTransaction.	= 64 A	Sim

A chamada da operação de consulta de transações – getStatus – não necessita de corpo de requisição.

Parâmetros de Resposta

Nome do Parâmetro	Descrição	Tamanho
code	Código de resposta do e-SiTef. Qualquer código diferente de "0" significa falha na consulta. Para maiores informações, consulte o documento Anexo A-2 - Codigos de Resposta.	< 4 N
message	Mensagem de resposta do e-SiTef da consulta.	< 500 AN
acquirer_id	Código do adquirente/roteamento utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente/roteamento utilizado na transação.	< 100 AN
amount	Valor da compra especificado pela loja (em centavos) na criação da transação.	< 12 AN
authorization_number	Número de autorização.	< 6 AN
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_date	Data de efetivação da pré-autorização retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm.
Exemplo: 13/07/2017T16:03	= 16 D
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
customer_receipt	Cupom (via cliente).	< 4000 AN
eci	Eletronic Commerce Indicator (indicador do nível de segurança da transação do pré-autorização via Cielo e-Commerce).	< 3 AN
esitef_usn	Número sequencial único da transação de pré-autorização no e-SiTef.	= 6 N
host_usn	NSU da autorizadora.	< 15 AN
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
merchant_receipt	Cupom (via estabelecimento).	< 4000 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 AN
nit	Identificador da transação de pré-autorização no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
payment_type	Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios de pagamentos, W = Boleto NR via Web Service	= 1 A
sitef_usn	Número sequencial único da transação de pré-autorização no SiTef.	= 6 N
status	Status da transação de pré-autorização no e-SiTef.	= 3 AN
tid	ID da transação no adquirente/roteamento. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
xid	Campo XID retornado em autenticações 3DS ou certos adquirentes/roteamentos.	< 40 AN
acquirer_id	Código do adquirente/roteamento utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente/roteamento utilizado na transação.	< 100 AN
amount	Valor da compra especificado pela loja (em centavos) na criação da transação.	< 12 AN
authorization_number	Número de autorização.	< 6 AN
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_date	Data de efetivação do pré-autorização retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
customer_receipt	Cupom (via cliente).	< 4000 AN
eci	Eletronic Commerce Indicator (indicador do nível de segurança da transação do pré-autorização via Cielo e-Commerce).	< 3 AN
esitef_usn	Número sequencial único da transação de pré-autorização no e-SiTef.	= 6 N
host_usn	NSU da autorizadora.	< 15 AN
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
merchant_receipt	Cupom (via estabelecimento).	< 4000 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 AN
nit	Identificador da transação de pré-autorização no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
payment_type	Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios de pagamentos, W = Boleto NR via Web Service	= 1 A
sitef_usn	Número sequencial único da transação de pré-autorização no SiTef.	= 6 N
status	Status da transação de pré-autorização no e-SiTef.	= 3 AN
tid	ID da transação no adquirente/roteamento. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
xid	Campo XID retornado em autenticações 3DS ou certos adquirentes/roteamentos.	< 40 AN

Atenção: Os campos code e message se referem ao código e mensagem referentes à requisição de consulta. Estes não se referem às transações consultadas.

Exemplo

Requisição:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "pre_authorization": {
        "acquirer_id": "1181",
        "acquirer_name": "GetNet Lac",
        "amount": "1470",
        "authorization_number": "301367",
        "authorizer_code": "000",
        "authorizer_date": "30/10/2018T11:58",
        "authorizer_id": "1",
        "authorizer_merchant_id": "000000000000000",
        "authorizer_message": "Transacao OK"
            "SDO DISPONIVEL                  244,00",
        "customer_receipt": 
            ".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S...."
            "\nSI                            Rede 181"
            "\nMU               Codigo transacao: 100"
            "\nLA             Codigo operacao: 113000"
            "\nDO                        Valor: 14,70"
            "\n.....S...I...M...U...L...A...D...O...."
            "\nSI                   NSU SiTef: 301367"
            "\nMU                      30/10/18 11:58"
            "\nLA                    ID PDV: ES000025"
            "\nDO             Estab.: 000000000000000"
            "\n.....S...I...M...U...L...A...D...O...."
            "\nSI                     Host: 010301367"
            "\nMU         Transacao Simulada Aprovada"
            "\n                               (SiTef)"
            "\n",
        "esitef_usn": "181030016873984",
        "host_usn": "010301367   ",
        "issuer": "1",
        "merchant_receipt": 
            ".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S.... " 
            "\nSI                            Rede 181"
            "\nMU               Codigo transacao: 100"
            "\nLA             Codigo operacao: 113000"
            "\nDO                        Valor: 14,70"
            "\n.....S...I...M...U...L...A...D...O...."
            "\nSI                   NSU SiTef: 301367"
            "\nMU                      30/10/18 11:58"
            "\nLA                    ID PDV: ES000025"
            "\nDO             Estab.: 000000000000000"
            "\n.....S...I...M...U...L...A...D...O...."
            "\nSI                     Host: 010301367"
            "\nMU         Transacao Simulada Aprovada"
            "\n                               (SiTef)" 
            "\n",
        "merchant_usn": "20180809",
        "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "oioi",
        "payment_type": "C",
        "sitef_usn": "301367",
        "status": "CON"
    },
    "capture": {
        "acquirer_id": "1181",
        "acquirer_name": "GetNet Lac",
        "amount": "1380",
        "authorization_number": "000000",
        "authorizer_date": "30/10/2018T12:00",
        "authorizer_id": "1",
        "customer_receipt": 
            ".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S.... "
            "\nSI                            Rede 181"
            "\nMU               Codigo transacao: 220"
            "\nLA             Codigo operacao: 113002"
            "\nDO                        Valor: 13,80"
            "\n.....S...I...M...U...L...A...D...O...."
            "\nSI                   NSU SiTef: 301368"
            "\nMU                      30/10/18 12:00"
            "\nLA                    ID PDV: ES000025"
            "\nDO             Estab.: 000000000000000"
            "\n.....S...I...M...U...L...A...D...O...."
            "\nSI                     Host: 010301368"
            "\nMU         Transacao Simulada Aprovada"
            "\n                               (SiTef)"                                         
            "\n",
        "esitef_usn": "181030016874034",
        "host_usn": "010301368   ",
        "issuer": "1",
        "authorizer_code": "000",
        "authorizer_message": "Transacao OK"
            "SDO DISPONIVEL          244,00",
        "merchant_receipt": 
            ".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S...."
            "\nSI                            Rede 181"                                          
            "\nMU               Codigo transacao: 220"                                          
            "\nLA             Codigo operacao: 113002"                                          
            "\nDO                        Valor: 13,80"                                          
            "\n.....S...I...M...U...L...A...D...O...."                                          
            "\nSI                   NSU SiTef: 301368"                                          
            "\nMU                      30/10/18 12:00"                                          
            "\nLA                    ID PDV: ES000025"                                          
            "\nDO             Estab.: 000000000000000"                             
            "\n.....S...I...M...U...L...A...D...O...."                                          
            "\nSI                     Host: 010301368"               
            "\nMU         Transacao Simulada Aprovada"
            "\n                               (SiTef)"                                          
            "\n",
        "merchant_usn": "20180809",
        "nit": "abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr1234567890",
        "order_id": "201808020001",
        "authorizer_merchant_id": "000000000000000"
        "payment_type": "C",
        "sitef_usn": "301368",
        "status": "CON"
    }
}

Consulta de transações em um grupo de lojas

O e-SiTef exige que as credenciais (merchant_id e merchant_key) sejam as mesmas utilizadas na transação a ser consultada. No entanto, caso o lojista precise, o e-SiTef pode permitir consultas com credenciais de outras lojas de um mesmo grupo. Para isso, basta solicitar às nossas equipes de suporte e produção para que façam essa liberação.

Serviço de Consulta de Cartões

A partir de um NIT de pré autorização com status NOV (novo), é possível realizar uma consulta do BIN do cartão (seis primeiros dígitos) no SiTef para obter dados sobre suas capacidades (possibilidade de pagamento parcelado, máximo de parcelas, exigência de código de segurança, etc.), ou ainda, saber qual autorizadora da loja é a mais adequada para a realização do pagamento.

No caso de transações com Visa Checkout, este serviço também retornará dados do cartão e do usuário retornados pelo Visa.

Fluxo

Descrição do fluxo:

1. O lojista cria uma transação no e-SiTef passando informações como código da loja, número de parcelas e código de pedido e obtém como resposta um NIT (Número Identificador de Transação).
2. O lojista envia o NIT obtido na etapa anterior e os dados do cartão a ser consultado. Com isso, o e-SiTef retorna dados sobre as capacidades do cartão enviado.
3. A loja virtual prossegue então consumindo o serviço de efetivação do pagamento, passando o NIT e os dados do cartão do comprador. Em caso de sucesso, a transação de pagamento mudará seu status para CON (confirmada).

Detalhes da chamada

• Recursos: /v1/preauthorizations/{nit}/cards

• Método HTTP: POST

Obs.: apesar de se tratar de uma consulta, o método POST foi escolhido por questões de segurança.

• Formato da requisição: JSON

• Formato da resposta: JSON

• Parâmetros de cabeçalho:

Nome do Parâmetro	Descrição	Tipo	Tamanho	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	AN	≤ 15	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	AN	≤ 80	SIM
Content-Type	Deve ser enviado com o valor "application/json".	AN	= 15	SIM

Exemplo de Consulta de cartão com envio de autorizadora

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-
sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123456
7890abcdefghijklmnopqr /cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "card":{
        "number":"5555555555555555"
    },
    "authorizer_id":"1"
}
--verbose

Resposta:

{
    "code":"0",
    "message":"OK. Transaction successful.",
    "preauthorization":{
        "status":"NOV"
    },
    "card":{
        "acquirer_name":"Redecard",
        "authorizer_id":"1",
        "authorizer_response_code":"000",
        "is_customer_id_required":"false",
        "is_expiry_date_required":"true",
        "is_installment_funding_enabled":"true",
        "is_security_code_required":"true",
        "is_spot_sale_enabled":"true",
        "is_with_interest_sale_enabled":"true",
        "is_without_interest_sale_enabled":"true",
        "max_installments_with_interest":"12",
        "min_installments_with_interest":"01",
        "prefixes":{
            "TRAT":"2",
            "PERIFERICO":"1",
            "CSEG":"2"
        }
    }
}

Exemplo de Consulta de cartão sem envio de autorizadora

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-
sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123456
7890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "card":{
        "number":"6543210987654321"
    }
}
--verbose

Resposta:

{
    "code":"0",
    "message":"OK. Transaction successful.",
    "preauthorization":{
        "status":"NOV"
    },
    "card":{
        "acquirer_name":"Redecard",
        "authorizer_id":"1",
        "authorizer_response_code":"000",
        "is_customer_id_required":"false",
        "is_expiry_date_required":"true",
        "is_installment_funding_enabled":"true",
        "is_security_code_required":"true",
        "is_spot_sale_enabled":"true",
        "is_with_interest_sale_enabled":"true",
        "is_without_interest_sale_enabled":"true",
        "max_installments_with_interest":"12",
        "min_installments_with_interest":"01",
        "prefixes":{
            "TRAT":"2",
            "PERIFERICO":"1",
            "CSEG":"2"
        }
    }
}

Exemplo de Consulta de cartão Visa Checkout

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-
sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123
4567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "card":{
        "wallet_transaction_id":"4444444444444444444"
    },
    "authorizer_id":"406"
}
--verbose

Resposta:

{
    "code":"0",
    "message":"OK. Transaction successful.",
    "preauthorization":{
        "status":"NOV"
    },
    "card":{
        "acquirer_name":"Redecard",
        "authorizer_id":"406",
        "authorizer_response_code":"000",
        "is_customer_id_required":"false",
        "is_expiry_date_required":"true",
        "is_installment_funding_enabled":"true",
        "is_security_code_required":"true",
        "is_spot_sale_enabled":"true",
        "is_with_interest_sale_enabled":"true",
        "is_without_interest_sale_enabled":"true",
        "max_installments_with_interest":"12",
        "min_installments_with_interest":"01",
        "prefixes":{
            "TRAT":"2",
            "PERIFERICO":"1"
        },
        "visa_checkout_data":{
            "payment_request":{
                "currency_code":"BRL",
                "subtotal":"115.5",
                "total":"115.5",
                "order_id":"09387",
                "source_id":"LOJAVISACHECK"
            },
            "user_data":{
                "user_first_name":"Comprador",
                "user_last_name":"Esitef",
                "user_full_name":"Comprador Esitef",
                "user_name":"esitef2@gmail.com",
                "user_email":"esitef2@gmail.com",
                "enc_user_id":"c5DmPXTXC3VwZywsFESEGAqiLM5PXSZG7hgyQgRv0j8=",
                "user_personal_id":"12345678909"
            },
            "creation_time_stamp":1502206049403,
            "payment_instrument":{
                "id":"AWUU0/rQrmKCMx+C740kBefZP2GNsdAMYUTXAzCPk+M=",
                "last_four_digits":"1010",
                "bin_six_digits":"406897",
                "verification_status":"VERIFIED",
                "issuer_bid":"10029901",
                "nick_name":"Cartão PAN",
                "name_on_card":"aaaaaaaaaa vvvvvvvvvv",
                "card_first_name":"aaaaaaaaaa",
                "card_last_name":"vvvvvvvvvv",
                "payment_type":{
                    "card_brand":"VISA",
                    "card_type":"CREDIT"
                },
                "billing_address":{
                    "person_name":"aaaaaaaaaa vvvvvvvvvv",
                    "first_name":"aaaaaaaaaa",
                    "last_name":"vvvvvvvvvv",
                    "line1":"qqqqqqqqqq",
                    "line2":"eeeeee",
                    "line3":"wwwwwwwww",
                    "city":"cccccccc",
                    "state_province_code":"SP",
                    "postal_code":"01238010",
                    "country_code":"BR",
                    "phone":"987654321",
                    "default":"false"
                },
                "card_arts":{
                    "card_art":[
                        {
                            "base_image_file_name":"https://sandbox.secure.checkout.visa.com/VmeCardArts/lg_visa_card.png",
                            "height":105,
                            "width":164
                        }
                    ]
                },
                "expiration_date":{
                    "month":"11",
                    "year":"2022"
                }
            },
            "risk_data":{
                "advice":"UNAVAILABLE",
                "score":0,
                "avs_response_code":"0",
                "cvv_response_code":"0",
                "age_of_account":"704"
            },
            "visa_checkout_guest":"false"
        }
    }
}

Exemplo de Consulta de cartão com dados adicionais para roteamento iCards via SiTef

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-
sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123456
7890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "card":{
        "number":"6543210987654321"
    },
    "authorizer_id":"38"
}
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "card": {
        "acquirer_name": "iCards",
        "authorizer_id": "38",
        "authorizer_response_code": "000",
        "is_customer_id_required": "true",
        "is_expiry_date_required": "true",
        "is_installment_funding_enabled": "true",
        "is_security_code_required": "true",
        "is_spot_sale_enabled": "true",
        "is_with_interest_sale_enabled": "true",
        "is_without_interest_sale_enabled": "true",
        "max_installments_with_interest": "12",
        "min_installments_with_interest": "01",
        "prefixes": {
            "NPSAQ": "0299",
            "CAPTPPRE": "1",
            "XCAPPREAUT": "11"
        },
        "is_customer_postal_code_required": "true",
        "is_card_holder_required": "true"
    },
    "preauthorization": {
        "status": "NOV"
    }
}

Parâmetros de Requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de consulta de cartão:

Nome do Parâmetro	Descrição	Tipo	Tamanho	Obrigatório
authorizer_id	Código da autorizadora no e-SiTef, conforme listado na lista de autorizadoras. Este campo só é obrigatório caso o campo "wallet_transaction_id" seja enviado.	N	≤ 3	NÃO
number	Número do cartão do comprador (PAN).	N	≤ 19	NÃO
token	HASH de um cartão armazenado no e-SiTef. Não é permitido enviar um número de cartão aberto (campo ‘number’) e um cartão armazenado (campo ‘token’) na mesma requisição.	AN	= 88	NÃO
wallet_transaction_id	ID de uma transação de carteiras digitais. Por enquanto, essa funcionalidade está disponível apenas para a autorizadora Visa Checkout (authorizer_id:406). Não é permitido enviar um número de cartão aberto (campo ‘number’), um cartão armazenado (campo ‘token’) e um wallet_transaction_id na mesma requisição.	AN	≤ 25	NÃO

Obs: Apesar de não obrigatório, recomenda-se o envio do authorizer_id para a consulta de cartão, principalmente para roteamentos via SiTef, a fim de comportamentos mais efetivos em relação ao roteamento cadastrado para a autorizadora.

Parâmetros de Resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de consulta de cartão:

Nome do Parâmetro	Descrição	Tipo	Tamanho
code	Código de resposta do e-SiTef. Qualquer código diferente de ‘0’ significa falha. Para maiores informações, consulte o documento "Anexo A-2 – Codigos de Resposta".	N	≤ 4
message	Mensagem de resposta do e-SiTef.	AN	≤ 500
status	Status da transação de pré-autorização no e-SiTef.	AN	= 3
authorizer_code	Código de resposta do autorizador.	AN	≤ 10
authorizer_message	Mensagem de resposta do autorizador.	AN	≤ 500
acquirer_name	Nome do roteamento. Ex.: Cielo	AN	≤ 256
authorizer_id	Código da autorizadora.	N	≤ 3
is_customer_id_required	Indica a obrigatoriedade da coleta do documento do cliente.	T/F	≤ 5
is_expiry_date_required	Indica a obrigatoriedade da coleta da data de validade do cartão do comprador.	T/F	≤ 5
is_installment_funding_enabled	Indica se o parcelamento está habilitado.	T/F	≤ 5
is_security_code_required	Indica a obrigatoriedade da coleta do código de segurança.	T/F	≤ 5
is_spot_sale_enabled	Indica se o pagamento à vista está habilitado.	T/F	≤ 5
is_with_interest_sale_enabled	Indica se o pagamento com juros está habilitado.	T/F	≤ 5
is_without_interest_sale_enabled	Indica se o pagamento sem juros está habilitado.	T/F	≤ 5
max_installments_with_interest	Parcelamento máximo com juros.	N	≤ 2
min_installments_with_interest	Parcelamento mínimo com juros.	N	≤ 2
visa_checkout_data	Objeto com os dados retornados pela Visa Checkout.
financing_plan_list	Objeto que consiste em um array de planos de financiamento apresentados em roteamento Via Certa Financiadora. Um plano de financiamento consiste dos seguintes campos: - cod_plano: código de identificação do plano de financiamento, que deve ser enviado no momento da efetivação do pagamento; - tipo_plano: código do tipo do plano de financiamento; - desc_plano: descrição do plano, que pode ser apresentado ao comprador; - parc_plano: número máximo de parcelas possíveis para o plano.
is_customer_postal_code_required	Indica a obrigatoriedade da coleta do código postal do usuário (CEP no Brasil).	T/F	< 5
key	Nome do prefixo.	AN	≤ 1024
value	Valor do prefixo	AN	≤ 1024

Serviço de Edição de Pré-Autorização

O roteamento GetnetLac permite alterar o valor de uma pré-autorização não capturada. Consulte nosso Suporte para verificar se existem outros roteamentos com esta funcionalidade. Para utilizar essa funcionalidade, basta chamar novamente a operação doPreAuthorization com os dados de uma transação de pré-autorização com status CON (confirmada) com adição do campo amount. Abaixo estão os detalhes dessa chamada.

Parâmetros de Requisição:

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
nit	Identificador da transação no e-SiTef. Obtido no retorno da chamada ao beginTransaction.	= 64 A	Sim
authorizer_id	Código da autorizadora no e-SiTef. Ver lista de autorizadoras.	≤ 3 N	Sim
amount	Valor total da compra (em centavos).	≤ 12 N	Sim
number	Número do cartão do comprador (PAN).	≤ 19 N	Sim
token	Utilizado para casos de pagamento recorrente, onde o cartão já deverá estar armazenado na base de dados do e-SiTef. Obrigatório utilizar um entre os campos (number, token ou initial_wallet_transaction_id)	= 88 A	Condicional
expiry_date	Data de vencimento no formato MMAA.	= 4 N	Sim
security_code	Código de segurança.	≤ 5 N	Sim

Parâmetros de Resposta:

Nome do Parâmetro	Descrição	Tamanho
code	Código de resposta do e-SiTef. Qualquer código diferente de "0" significa falha. Para maiores informações, consulte o documento Anexo A-2 - Codigos de Resposta.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
acquirer_id	Código do adquirente/roteamento utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente/roteamento utilizado na transação.	< 100 AN
amount	Valor da compra especificado pela loja (em centavos).	< 12 AN
authorization_number	Número de autorização.	< 6 AN
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_date	Data de efetivação da pré-autorização retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
customer_receipt	Cupom (via cliente).	< 4000 AN
eci	Eletronic Commerce Indicator (indicador do nível de segurança da transação da pré-autorização via Cielo e-Commerce).	< 3 AN
esitef_usn	Número sequencial único da transação de pré-autorização no e-SiTef.	= 6 N
host_usn	NSU da autorizadora.	< 15 AN
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
merchant_receipt	Cupom (via estabelecimento).	< 4000 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 AN
nit	Identificador da transação de pré-autorização no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
payment_type	Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios e pagamentos, W = Boleto NR via Web Service	= 1 A
sitef_usn	Número sequencial único da transação de pré-autorização no SiTef.	= 6 N
status	Status da transação de pré-autorização no e-SiTef.	= 3 AN
tid	ID da transação no adquirente/roteamento. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
xid	Campo XID retornado em autenticações 3DS ou certos adquirentes/roteamentos.	< 40 AN

Em caso de sucesso, será retornado o responseCode ‘0’. O status da transação não será alterado em hipótese alguma (sucesso ou falha). Porém, os campos sitef_usn, host_usn, authorization_number, sitef_date, customer_receipt e merchant_receipt sofrerão mudanças caso a alteração seja confirmada.

Serviço de Edição de Pré-Autorização de Origem Externa

O roteamento GetnetLac permite alterar o valor de uma pré-autorização não capturada, mesmo que a mesma não conste nos registros do e-SiTef. Consulte nosso Suporte para verificar se existem outros roteamentos com esta funcionalidade. Para utilizar essa funcionalidade, basta chamar novamente a operação doPreAuthorization com os dados de uma transação de pré-autorização com status CON (confirmada) com adição do campo amount. Abaixo estão os detalhes dessa chamada.

Atualmente esta funcionalidade permite somente a edição de transações de pré-autorização realizadas no SiTef.

Esta operação possui um passo a mais no fluxo, em relação a uma edição de pré-autorização normal. É preciso que seja criada uma edição de pré-autorização utilizando a operação beginTransaction, que irá gerar um registro no e-SiTef de uma transação com status=NOV, e, retornará ao aplicativo o parâmetro nit, que identificará essa transação.

Criação da edição de pré-autorização com origem externa

Detalhes da Chamada

• Recurso: /v1/transactions
• Operação HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
Content-Type	Valor fixo "application/json"	= 15 A	Sim
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes	≤ 15 A	Sim
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 A	Sim

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de criação de transações utilizando a ferramenta cURL.

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "order_id":"orderID",
    "merchant_usn":"20190101",
    "amount":"100",
    "transaction_type":"preauthorization",
    "is_transaction_origin_external": "true"
}
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "pre_authorization": {
        "status": "NOV",
        "nit":
        "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "orderID",
        "merchant_usn": "20190101",
        "amount": "100"
    }
}

Parâmetros de Requisição

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
amount	Valor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto	< 12N	Sim
encrypted_card	Este campo deve ser enviado com valor "true" caso o número do cartão a ser enviado na próxima etapa do fluxo use a criptografia do SiTef. A opção de envio do cartão criptografado só será possível com roteamento via SiTef e é necessário a configuração prévia do SiTef em questão. Opções: 1. "true" 2. "false" (valor default)	< 5 AN	Não
merchant_usn	Número sequencial único para cada pedido, criado pela loja. O NSU será utilizado em toda a comunicação com a loja, de forma a identificar o pedido. Como se trata de uma possível chave para acesso do lado da loja, apesar de ser opcional para o e-SiTef, é fortemente recomendado que o campo seja formatado e enviado pela aplicação da loja.	< 12 N	Não
order_id	Código do pedido para ser exibido ao comprador, definido pelo lojista. É aconselhável que seja diferente a cada pedido para que facilite a rastreabilidade. Se a integração da Loja com as redes adquirentes/roteamentos (Cielo, Redecard, etc) for via SiTef (TEF), o campo orderId que tem o tamanho máximo de 40 caracteres, será reduzido a 12 caracteres, devido a uma restrição do SiTef. Essa redução será realizada mantendo os caracteres da esquerda para direita (ex.: se um código de pedido inserido for 12345678901234567890 no e-SiTef, no SiTef ele será apenas 123456789012).	< 40 AN	Não
transaction_type	Valor fixo "preauthorization"	= 15 A	Sim
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais	< 22 AN	NÃO
is_transaction_origin_external	Indica se a transação foi originada fora do e-SiTef. Valor fixo "true"	= 5 AN	Sim

Legenda do tipo do campo "Tamanho":

A = alfanumérico

N = numérico

N A = não utilizado

Parâmetros de resposta

Nome do Parâmetro	Descrição	Tamanho
code	Código de resposta do e-SiTef. Qualquer código diferente de ‘0’ significa falha. Para maiores informações, consulte Códigos de Resposta.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 A
amount	Valor da transação especificado pela loja (em centavos) na criação da transação.	< 12 N
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N
nit	Identificador da transação de pré-autorização no e-SiTef.	= 64 A
order_id	Código de pedido enviado pela loja na criação da transação	< 40 AN
status	Status da transação de pré-autorização no e-SiTef.	= 3 A

Efetivação da edição de pré-auto com origem externa

A efetivação segue o mesmo fluxo de uma edição de pré-autorização originada no e-SiTef, mas é preciso enviar alguns parâmetros a mais na requisição.

Parâmetros de Requisição

Parâmetro	Descrição	Formato	Obrigatório
acquirer	Os campos desse elemento só devem ser enviados em casos de transações de origem externa.
authorizer_id	Código da autorizadora no e-SiTef. Deve ser o mesmo valor enviado no pagamento.	< 3 N	Sim
host_usn	NSU do host/autorizadora da transação a ser cancelada.	= 9 N	Sim
authorization_number	Número de autorização da transação a ser cancelada.	< 6 N	Sim
authorizer_date	Data de efetivação SiTef do pagamento no formato DD/MM/AAAA.	= 10 D	Sim
order_id	Código do pedido usado na pré-autorização iniciada externamente ao e-SiTef.	< 40 AN	Não
identification_number	CPF ou CNPJ usado na pré-autorização iniciada externamente ao e-SiTef.	< 20 AN	Sim
terminal	Terminal SiTef que se deseja usar. Se não for enviado, o e-SiTef gerará um terminal aleatório.	= 14 N	Não
company_code	Código de empresa SiTef que se deseja usar. Se não for enviado, o e-SiTef enviará o código de empresa cadastrado na loja.	= 8 N	Não

Legenda do tipo do campo "Tamanho":

A = alfanumérico

N = numérico

N A = não utilizado

Nota:

1 - Quando as informações de terminal e company_code são enviadas, o comportamento do cardquery muda ligeiramente. Neste momento, ao executar o cardquery, o e-SiTef irá identificar a rede retornada pelo SiTef. Uma vez identificada, esta será usada ao invés da cadastrada na loja.

2 - Nas operações de origem externa, não temos como validar a rede que foi utilizada na parte externa da operação, que foi feita fora do e-SiTef. Nestes casos, usamos a rede configurada no SiTef. Por causa disso, mudanças de configuração, se feitas durante o meio da operação, podem ocasionar solicitações inválidas ou negadas. Por exemplo, se uma pré autorização foi feita no meio físico na rede 181 e, antes da finalização da captura, a configuração do SiTef for alterada para a rede 125, as operações que forem feitas via e-SiTef assumirão a rede 125.

ATENÇÃO: Os parâmetros terminal e company_code devem ser enviados simultaneamente.
É necessário também solicitar à equipe de atendimento do e-SiTef a permissão Permite envio de Empresa e Terminal SiTef via REST.

Exemplo

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "amount": "3000",
    "installments": "1",
    "installment_type": "4",
    "card": {
        "number": "5555555555555555",
        "expiry_date": "1222",
        "security_code": "123"
    },
    "acquirer": {
        "authorizer_id": "1",
        "authorization_number": 212820,
        "identification_number": "11111111555",
        "order_id": 1611256811271,
        "authorizer_date": "21/01/2021",
        "host_usn": 999212820   
    }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "pre_authorization":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK SDO DISPONIVEL 244,00",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"orderID",
      "customer_receipt":"=== CUSTOMER RECEIPT ===",
      "merchant_receipt":"=== MERCHANT RECEIPT ===",
      "authorizer_id":"1",
      "acquirer_id":"1181",
      "acquirer_name":"GetNet Lac",
      "authorizer_date":"30/03/2021T10:03",
      "authorization_number":"300016",
      "merchant_usn":"30120944339",
      "esitef_usn":"210330069186034",
      "sitef_usn":"300016",
      "host_usn":"003300016 ",
      "amount":"3000",
      "payment_type":"C",
      "authorizer_merchant_id":"000000000000000"
   }
}

Serviço de Incremento de Pré-Autorização

Para determinados roteamentos é possível incrementar o valor de uma pré-autorização não capturada. Consulte nosso atendimento para avaliar quais roteamentos possuem esta funcionalidade.

Para utilizar essa funcionalidade, basta chamar novamente a operação doPreAuthorization com os dados de uma transação de pré-autorização com status CON (confirmada) com adição do campo additional_amount. Abaixo estão os detalhes dessa chamada.

Parâmetros de Requisição:

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
nit	Identificador da transação no e-SiTef. Obtido no retorno da chamada ao beginTransaction.	= 64 A	Sim
authorizer_id	Código da autorizadora no e-SiTef. Ver lista de autorizadoras.	≤ 3 N	Sim
additional_amount	Valor que será incrementado na compra (em centavos).	≤ 12 N	Sim
number(*)	Número do cartão do comprador (PAN).	≤ 19 N	Sim
token(*)	Utilizado para casos de pagamento recorrente, onde o cartão já deverá estar armazenado na base de dados do e-SiTef.	= 88 A	Condicional
wallet_transaction_id(*)	Código de identificação de transação com wallet Visa Checkout.	< 25 A	Condicional
expiry_date	Data de vencimento no formato MMAA.	= 4 N	Sim
security_code	Código de segurança.	≤ 5 N	Sim

(*) Obrigatório utilizar apenas um entre os campos: number, token ou wallet_transaction_id

Parâmetros de Resposta:

Nome do Parâmetro	Descrição	Tamanho
code	Código de resposta do e-SiTef. Qualquer código diferente de "0" significa falha. Para maiores informações, consulte o documento Anexo A-2 - Codigos de Resposta.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
acquirer_id	Código do adquirente/roteamento utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente/roteamento utilizado na transação.	< 100 AN
amount	Valor total da compra (em centavos), isto é, valor pré-autorizado inicialmente mais o(s) valor(es) incrementado(s).	< 12 AN
authorization_number	Número de autorização do incremento.	< 6 AN
authorizer_code	Código de resposta do autorizador do incremento.	< 10 AN
authorizer_date	Data de efetivação do incremento de pré-autorização retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
authorizer_id	Código da autorizadora utilizada no incremento.	< 4 N
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
authorizer_message	Mensagem de resposta do autorizador do incremento.	< 500 AN
customer_receipt	Cupom (via cliente) do incremento.	< 4000 AN
eci	Eletronic Commerce Indicator (indicador do nível de segurança da transação da pré-autorização via Cielo e-Commerce).	< 3 AN
esitef_usn	Número sequencial único da transação de pré-autorização no e-SiTef.	= 6 N
host_usn	NSU da autorizadora do incremento.	< 15 AN
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
merchant_receipt	Cupom (via estabelecimento) do incremento.	< 4000 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 AN
nit	Identificador da transação de pré-autorização no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
payment_type	Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios e pagamentos	= 1 A
sitef_usn	Número sequencial único do incremento de pré-autorização no SiTef.	= 6 N
status	Status do incremento de pré-autorização no e-SiTef.	= 3 AN
tid	ID do incremento no adquirente/roteamento. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
xid	Campo XID retornado em autenticações 3DS ou certos adquirentes/roteamentos.	< 40 AN

Em caso de sucesso, será retornado o responseCode '0'. O status da transação na base dados do e-SiTef não será alterado em hipótese alguma (sucesso ou falha).

Os campos sitef_usn, host_usn, authorization_number, sitef_date, customer_receipt e merchant_receipt na resposta são referentes ao incremento, porém os respectivos dados não são alterados na base de dados do e-SiTef. Apenas o valor total é incrementado na transação.

Exemplo:

1. Criação e de efetivação de pré-autorização de R$20,00:

a. criação - requisição

JSON

{
    "order_id":"orderID",
    "merchant_usn":"20190101",
    "amount":"2000",
    "transaction_type":"preauthorization"
}

supondo que a criação foi efetuada com sucesso...

b. efetivação - requisição

JSON

{
    "authorizer_id":"2",
    "installments":"2",
    "installment_type":"4",
    "card":{
        "number":"xxxxxxxxxxxxxxxx",
        "expiry_date":"1222",
        "security_code":"yyy"
    }
}

c. resposta

JSON

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "pre_authorization":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK.",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "customer_receipt":"=== CUSTOMER RECEIPT ===",
      "merchant_receipt":"=== MERCHANT RECEIPT ===",
      "authorizer_id":"2",
      "authorizer_date":"09/11/2018T19:40",
      "acquirer_id":"1296",
      "acquirer_name":"Safra",
      "authorization_number":"013245",
      "merchant_usn":"20190101",
      "esitef_usn":"181109017689784",
      "order_id":"orderID",
      "sitef_usn":"212194",
      "host_usn":"999212194",
      "amount":"2000",
      "issuer":"2",
      "payment_type":"C",
      "authorizer_merchant_id":"000000000000000"
   }
}

2. Incremento de pré-autorização de R$2,00

a. incremento - requisição

JSON

{
    "authorizer_id":"2",
    "installments":"2",
    "installment_type":"4",
    "additional_amount": "200",
    "card":{
        "number":"xxxxxxxxxxxxxxxx",
        "expiry_date":"1222",
        "security_code":"yyy"
    }
}

b. incremento - resposta

JSON

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "pre_authorization":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK.",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "customer_receipt":"=== CUSTOMER RECEIPT INCREMENT ===",
      "merchant_receipt":"=== MERCHANT RECEIPT INCREMENT ===",
      "authorizer_id":"2",
      "authorizer_date":"09/11/2018T19:42",
      "acquirer_id":"1296",
      "acquirer_name":"Safra",
      "authorization_number":"013246",
      "merchant_usn":"20190101",
      "esitef_usn":"181109017689785",
      "order_id":"orderID",
      "sitef_usn":"212195",
      "host_usn":"999212195",
      "amount":"2200",
      "issuer":"2",
      "payment_type":"C",
      "authorizer_merchant_id":"000000000000000"
   }
}

O detalhe desta resposta é que o campo amount contem o valor total pré-autorizado.

3. Consulta de status da transação de pré-autorização resultante

a. consulta de transação - resposta

JSON

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "pre_authorization":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK.",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "customer_receipt":"=== CUSTOMER RECEIPT ===",
      "merchant_receipt":"=== MERCHANT RECEIPT ===",
      "authorizer_id":"2",
      "authorizer_date":"09/11/2018T19:40",
      "acquirer_id":"1296",
      "acquirer_name":"Safra",
      "authorization_number":"013245",
      "merchant_usn":"20190101",
      "esitef_usn":"181109017689784",
      "order_id":"orderID",
      "sitef_usn":"212194",
      "host_usn":"999212194",
      "amount":"2200",
      "issuer":"2",
      "payment_type":"C",
      "authorizer_merchant_id":"000000000000000"
   }
}

Serviço de Captura de Pré-Autorização

A captura da Pré-Autorização tem como objetivo a efetivação da Pré-Autorização, que poderá ser no valor total ou inferior ao valor total da Pré-Autorização. Isso vai depender da regra de negócio da aplicação da Loja Virtual.

O fluxo seria: realizar a operação de efetivação de pré-autorização e se o resultado for aprovado, o serviço de captura deverá ser consumido para completar o fluxo. A captura será realizada no momento definido pelas regras de negócios da aplicação.

Na operação de captura, o parâmetro amount pode ter o valor igual ou menor ao valor do parâmetro amount da pré-autorização.

Para o roteamento GetNetLac via SiTef, o parcelamento pode ser feito também na etapa de pré-autorização e nesse caso, a captura deve receber um número de parcelas igual ou superior ao enviado anteriormente. Caso a pré-autorização seja feita à vista, a captura não pode ser parcelada.

Detalhes da chamada

• Recurso: /v1/preauthorizations/capture/{nit}
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Nome do Parâmetro	Descrição	Formato	Obrigatório
Content-Type	Valor fixo application/json	= 15 AN	SIM
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM

Exemplo

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/capture/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "amount":"100",
   "installments":"1",
   "installment_type":"4",
   "card":{
      "number":"xxxxxxxxxxxxxxxx",
      "expiry_date":"1222",
      "security_code":"123"
   },
   "acquirer":{
      "submerchant_split":[
         {
            "submerchant_code":"empresa01",
            "submerchant_amount":"10"
         },
         {
            "submerchant_code":"empresa02",
            "submerchant_amount":"20"
         },
         {
            "submerchant_code":"empresa03",
            "submerchant_amount":"20"
         },
         {
            "submerchant_code":"empresa04",
            "submerchant_amount":"30"
         },
         {
            "submerchant_code":"empresa05",
            "submerchant_amount":"30"
         }
      ]
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "capture":{
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"orderID",
      "customer_receipt":"=== CUSTOMER RECEIPT ===",
      "merchant_receipt":"=== MERCHANT RECEIPT ===",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK.",
      "authorizer_date":"09/11/2018T19:40",
      "authorizer_merchant_id":"000000000000000",
      "authorization_number":"212195",
      "esitef_usn":"180921015287704",
      "merchant_usn":"20190101",
      "sitef_usn":"212195",
      "host_usn":"999212195",
      "amount":"100",
      "payment_type":"C",
      "issuer":"2"
   }
}

Parâmetros da requisição

Parâmetro	Descrição	Formato	Obrigatório
amount	Valor total da compra (em centavos).	< 12 N	SIM
discount	Valor do desconto, em centavos. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente.	< 12 N	NÃO
installments	Número de parcelas. 1 = à vista. O número máximo de parcelas configurado no portal e-SiTef do lojista não será verificado neste campo, servindo somente para pagamentos HTML.	< 2 N	SIM
installment_type	Juntamente com o campo installments, indica parcelamento. Os valores possíveis para installment_type são: 3: Parcelamento com juros da administradora do cartão 4: Parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista)	= 1 N	SIM
promo_code	Código de promoção Visa Checkout utilizado no pré-autorização. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente.	AN	NÃO
subtotal	Valor do subtotal, em centavos. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente.	< 12 N	NÃO
card	O envio de dados de cartão é obrigatório para transações com roteamento SiTef com exceção do adquirente Cetelem. Deve ser utilizado apenas um entre os campos: number, token ou wallet_transaction_id
number	Número do cartão do comprador (PAN).	< 19 N	COND.
token	Utilizado para casos de pré-autorização recorrente, onde o cartão já deverá estar armazenado na base de dados do e-SiTef.	= 88 AN	COND.
wallet_transaction_id	Código de identificação de transação com wallet VisaCheckout. Necessário apenas para Visa Checkout	< 25 AN	COND.
initial_wallet_transaction_id	Informa se o Wallet ID (wallet_transaction_id) está sendo utilizado pela primeira vez. Se for a primeira vez, enviar true, caso contrário, enviar false. Necessário apenas para Visa Checkout. Valor padrão: true	< 5 AN	COND.
expiry_date	Data de vencimento do cartão no formato MMAA.	= 4 N	COND.
security_code	Código de segurança.	< 5 N	COND.
acquirer. submerchant_split[]	Consiste em um array para pagamentos split, exclusivos para roteamentos BIN e Sipag, ambos via SiTef. Permite a divisão de partes do valor total do pagamento entre outras empresas. O máximo de itens permitido neste array é de 5 itens. Cada item é composto pelos campos submechant_code e submerchant_amount.
submerchant_code	Código de estabelecimento BIN/Sipag	< 15 AN	NÃO
submerchant_amount	valor de transação referente ao estabelecimento	< 12 N	NÃO
mcc	O MCC (Merchant Category Code) é um código que classifica um negócio pelo tipo de bens ou produtos fornecidos.	< 4 N	NÃO
subacquirer_merchant_id	Identificação da loja na subadquirente.	< 22 AN	NÃO

Parâmetros de resposta

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0 significa falha. Para maiores informações, consulte o documento anexo A-2 - Codigos de Resposta.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
capture
acquirer_id	Código do adquirente/roteamento utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente/roteamento utilizado na transação.	< 100 AN
amount	Valor da compra especificado pela loja (em centavos) na criação da transação.	< 12 AN
authorization_number	Número de autorização.	< 6 AN
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_date	Data de efetivação da pré-autorização retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
customer_receipt	Cupom (via cliente).	< 4000 AN
eci	Eletronic Commerce Indicator (indicador do nível de segurança da transação do pré-autorização via Cielo e-Commerce).	< 3 AN
esitef_usn	Número sequencial único da transação de pré-autorização no e-SiTef.	= 6 N
host_usn	NSU da autorizadora.	< 15 AN
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
merchant_receipt	Cupom (via estabelecimento).	< 4000 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 AN
nit	Identificador da transação de pré-autorização no e-SiTef.	= 64 AN
payment_type	Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios de pagamentos, W = Boleto NR via Web Service	= 1 AN
sitef_usn	Número sequencial único da transação de pré-autorização no SiTef.	= 6 N
status	Status da transação de pré-autorização no e-SiTef.	= 3 AN
tid	ID da transação no adquirente/roteamento. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
xid	Campo XID retornado em autenticações 3DS ou certos adquirentes/roteamentos.	< 40 AN

Serviço Captura de Pré autorização com origem externa

A funcionalidade de captura origem externa consiste em efetuar a operação de captura de uma transação mesmo que ela não conste nos registros do e-SiTef.

Atualmente esta funcionalidade permite somente a captura de transações de pré autorização realizadas no SiTef.

Esta operação possui um passo a mais no fluxo, em relação a uma captura normal. É preciso que seja criada uma captura utilizando a operação beginTransaction, que irá gerar um registro no e-SiTef de uma transação com status=NOV, e, retornará ao aplicativo o parâmetro nit, que identificará essa transação.

Criação da captura origem externa

Detalhes da Chamada

• Recurso: /v1/transactions
• Operação HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
Content-Type	Valor fixo "application/json"	= 15 A	Sim
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes	≤ 15 A	Sim
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 A	Sim

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de criação de transações utilizando a ferramenta cURL.

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "order_id":"orderID",
    "merchant_usn":"20190101",
    "amount":"100",
    "transaction_type":"capture",
    "is_transaction_origin_external": "true"
}
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "capture": {
        "status": "NOV",
        "nit":
        "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "orderID",
        "merchant_usn": "20190101",
        "amount": "100"
    }
}

Parâmetros de Requisição

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
amount	Valor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto	< 12N	Sim
encrypted_card	Este campo deve ser enviado com valor "true" caso o número do cartão a ser enviado na próxima etapa do fluxo use a criptografia do SiTef. A opção de envio do cartão criptografado só será possível com roteamento via SiTef e é necessário a configuração prévia do SiTef em questão. Opções: 1. "true" 2. "false" (valor default)	< 5 AN	Não
merchant_usn	Número sequencial único para cada pedido, criado pela loja. O NSU será utilizado em toda a comunicação com a loja, de forma a identificar o pedido. Como se trata de uma possível chave para acesso do lado da loja, apesar de ser opcional para o e-SiTef, é fortemente recomendado que o campo seja formatado e enviado pela aplicação da loja.	< 12 N	Não
order_id	Código do pedido para ser exibido ao comprador, definido pelo lojista. É aconselhável que seja diferente a cada pedido para que facilite a rastreabilidade. Se a integração da Loja com as redes adquirentes/roteamentos (Cielo, Redecard, etc) for via SiTef (TEF), o campo orderId que tem o tamanho máximo de 40 caracteres, será reduzido a 12 caracteres, devido a uma restrição do SiTef. Essa redução será realizada mantendo os caracteres da esquerda para direita (ex.: se um código de pedido inserido for 12345678901234567890 no e-SiTef, no SiTef ele será apenas 123456789012).	< 40 AN	Não
transaction_type	Valor fixo "capture"	= 7 A	Sim
is_transaction_origin_external	Indica se a transação foi originada fora do e-SiTef. Valor fixo "true"	= 5 AN	Sim
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais	< 22 AN	NÃO

Legenda do tipo do campo "Tamanho":

A = alfanumérico

N = numérico

N A = não utilizado

Parâmetros de resposta

Nome do Parâmetro	Descrição	Tamanho
code	Código de resposta do e-SiTef. Qualquer código diferente de ‘0’ significa falha. Para maiores informações, consulte Códigos de Resposta.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 A
amount	Valor da transação especificado pela loja (em centavos) na criação da transação.	< 12 N
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N
nit	Identificador da transação de pré-autorização no e-SiTef.	= 64 A
order_id	Código de pedido enviado pela loja na criação da transação	< 40 AN
status	Status da transação de pré-autorização no e-SiTef.	= 3 A

Efetivação da captura origem externa

A efetivação segue o mesmo fluxo de uma captura de transação originada no e-SiTef, mas é preciso enviar alguns parâmetros a mais na requisição.

Parâmetros de Requisição

Parâmetro	Descrição	Formato	Obrigatório
acquirer	Os campos desse elemento só devem ser enviados em casos de captura origem externa.
authorizer_id	Código da autorizadora no e-SiTef. Deve ser o mesmo valor enviado no pagamento.	< 3 N	Sim
host_usn	NSU do host/autorizadora da transação a ser cancelada.	= 9 N	Sim
authorization_number	Número de autorização da transação a ser cancelada.	< 6 N	Sim
authorizer_date	Data de efetivação SiTef do pagamento no formato DD/MM/AAAA.	= 10 D	Sim
order_id	Código do pedido usado na pré-autorização iniciada externamente ao e-SiTef.	< 40 AN	Não
identification_number	CPF ou CNPJ usado na pré-autorização iniciada externamente ao e-SiTef.	< 20 AN	Sim
terminal	Terminal SiTef que se deseja usar. Se não for enviado, o e-SiTef gerará um terminal aleatório.	= 14 N	Não
company_code	Código de empresa SiTef que se deseja usar. Se não for enviado, o e-SiTef enviará o código de empresa cadastrado na loja.	= 8 N	Não

Legenda do tipo do campo "Tamanho":

A = alfanumérico

N = numérico

N A = não utilizado

Nota:

1 - Quando as informações de terminal e company_code são enviadas, o comportamento do cardquery muda ligeiramente. Neste momento, ao executar o cardquery, o e-SiTef irá identificar a rede retornada pelo SiTef. Uma vez identificada, esta será usada ao invés da cadastrada na loja.

2 - Nas operações de origem externa, não temos como validar a rede que foi utilizada na parte externa da operação, que foi feita fora do e-SiTef. Nestes casos, usamos a rede configurada no SiTef. Por causa disso, mudanças de configuração, se feitas durante o meio da operação, podem ocasionar solicitações inválidas ou negadas. Por exemplo, se uma pré autorização foi feita no meio físico na rede 181 e, antes da finalização da captura, a configuração do SiTef for alterada para a rede 125, as operações que forem feitas via e-SiTef assumirão a rede 125.

ATENÇÃO: Os parâmetros terminal e company_code devem ser enviados simultaneamente.
É necessário também solicitar à equipe de atendimento do e-SiTef a permissão Permite envio de Empresa e Terminal SiTef via REST.

Exemplo

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/capture/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "amount": "300",
    "installments": "1",
    "installment_type": "4",
    "card": {
        "number": "5555555555555555",
        "expiry_date": "1222",
        "security_code": "123"
    },
    "acquirer": {
        "authorizer_id": "2",
        "authorization_number": 212820,
        "identification_number": "11111111555",
        "order_id": 1611256811271,
        "authorizer_date": "21/01/2021",
        "host_usn": 999212820   
    }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "capture":{
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"orderID",
      "customer_receipt":"=== CUSTOMER RECEIPT ===",
      "merchant_receipt":"=== MERCHANT RECEIPT ===",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK.",
      "authorizer_date":"21/01/2021T19:40",
      "authorizer_merchant_id":"000000000000000",
      "authorization_number":"212195",
      "esitef_usn":"180921015287704",
      "merchant_usn":"20190101",
      "sitef_usn":"212195",
      "host_usn":"999212195",
      "amount":"100",
      "payment_type":"C",
      "issuer":"2"
   }
}

Agendamento REST

Visão Geral

O e-SiTef possui duas interfaces para integração com a loja virtual, POST/HTML e Web Services (REST ou SOAP), possibilitando a maneira adequada de interação da loja com o e-SiTef, conforme a linguagem e plataforma de execução da loja virtual.

Na interface REST, a coleta dos dados do cartão e do pagamento será realizada pela Loja Virtual e o e-SiTef apenas se encarregará de efetuar o pagamento com a instituição financeira.

Nessa interface estão disponíveis os pagamentos com cartão de crédito, débito ou voucher. Para pagamentos via banco como transferência bancária, boleto, utilize a interface POST/HTML.

Também disponível nesta interface está a funcionalidade de agendamento de pagamentos recorrentes.

Comunicação

Para realizar uma transação Web Service, toda a comunicação será realizada via HTTPS/SSL. É importante que o servidor do lojista suporte criptografia com no mínimo 128 bits. O servidor da loja deverá realizar chamadas em endereços específicos para transações REST.

Cada serviço deve ser chamado utilizando a URL base concatenada do recurso desejado (veja o capítulo referente ao serviço a ser consumido). O método HTTP (GET, POST ou PUT) indica a ação esperada sobre o recurso escolhido. Abaixo estão as URLs base do e-SiTef:

URL base de Produção:

https://esitef-ec.softwareexpress.com.br/e-sitef/api

URL base de Homologação:

https://esitef-homologacao.softwareexpress.com.br/e-sitef/api

Todas as chamadas realizadas para os serviços serão respondidas de forma síncrona.

Atenção:

Nunca utilize o IP ao invés do domínio esitef-ec.softwareexpress.com.br. O IP pode mudar a qualquer momento e sem aviso prévio, portanto é importante a utilização do domínio para acesso ao e-SiTef.

Importante:

Além dos parâmetros de retorno dos serviços descritos nesta especificação o e-SiTef poderá devolver outros parâmetros sem aviso prévio.

É importante que o aplicativo esteja preparado para receber os parâmetros desconhecidos além dos parâmetros já especificados e simplesmente desprezá-los.

Fluxo

É possível realizar um agendamento de transações recorrentes com ou sem um pagamento imediato. No caso de agendamento com pagamento, o e-SiTef garante a atomicidade da operação, ou seja, o agendamento só será ativado se o pagamento for confirmado.

Agendamento com pagamento imediato

Descrição do fluxo:

1. O lojista cria uma transação no e-SiTef passando os dados de pagamento e agendamento e obtém como resposta um NIT (número identificador de transação). O simples fato de dados de agendamento serem enviados já será interpretado como um pagamento com agendamento.
2. A loja virtual prossegue então consumindo o serviço de efetivação do pagamento, passando o NIT e os dados do cartão do comprador. Em caso de sucesso, a transação de pagamento mudará seu status para CON (confirmada) e a transação de agendamento assumirá o status ATV (ativa).

Também é possível fazer um pagamento com agendamento com confirmação tardia. O fluxo a ser seguido é o mesmo de um pagamento simples com confirmação tardia. Saiba mais.

Agendamento sem pagamento imediato

Descrição do fluxo:

1. O lojista cria uma transação no e-SiTef passando os dados do agendamento e o parâmetro do_payment_now com valor false. Como resposta, o lojista obterá um SID (identificador de agendamento).
2. A loja virtual prossegue então consumindo o serviço de ativação do agendamento, passando o SID e os dados do cartão do comprador. Em caso de sucesso, o agendamento terá seu status alterado para ATV (ativo).

Consulta dos agendamentos

As informações das transações de agendamento podem ser consultadas através do mesmo serviço utilizado pela interface de Pagamento REST. Saiba mais.

Quick start

Este guia mostra o processo de agendamento de pagamentos recorrentes, utilizando a interface web service REST do e-SiTef.

O que você precisará

• Cadastro ativo no ambiente de homologação do e-SiTef (obtido com nossa equipe de suporte)
• Uma ferramenta capaz de realizar chamadas HTTP, como Postman, REST Client ou cURL

Criando a transação

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

JSON

cURL

{
   "merchant_usn":"12055523043",
   "order_id":"12055523043",
   "authorizer_id":"2",
   "schedule":{
      "amount":"1",
      "do_payment_now":"false",
      "initial_date":"03/08/2025",
      "number_of_times":"3",
      "interval":"1",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   },
   "additional_data":{
      "payer":{
         "store_identification":"98253053045"
      }
   }
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"12055523043",
   "order_id":"12055523043",
   "authorizer_id":"2",
   "schedule":{
      "amount":"1",
      "do_payment_now":"false",
      "initial_date":"03/08/2025",
      "number_of_times":"3",
      "interval":"1",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   },
   "additional_data":{
      "payer":{
         "store_identification":"98253053045"
      }
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "schedule":{
      "status":"NOV",
      "sid":"<sid>",
      "amount":"1",
      "order_id":"12055523043",
      "merchant_usn":"12055523043"
   }
}

Saiba mais sobre esse serviço.

Ativando o agendamento

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/<sid>

Preencha o campo <sid> na URL acima com o SID obtido na resposta da fase anterior de criação da transação.

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

JSON

cURL

{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222"
   }
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/<sid>"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "Content-Type: application/json"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222"
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "schedule":{
      "status":"ATV",
      "sid":"<sid>",
      "schedule_usn":"170713000000040",
      "amount":"1",
      "initial_date":"03/08/2025",
      "next_date":"03/08/2025",
      "number_of_times":"3",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   }
}

Saiba mais sobre esse serviço.

Verificando o estado do agendamento

Tipo de requisição: GET

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/<sid>

Preencha o campo <sid> na URL acima com o SID obtido na resposta da fase de criação da transação.

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

cURL

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/<sid>"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "schedule":{
      "status":"ATV",
      "sid":"<sid>",
      "schedule_usn":"170713000000050",
      "authorizerId":"2",
      "amount":"1",
      "initial_date":"03/08/2025",
      "next_date":"03/08/2025",
      "number_of_times":"3",
      "current_times":"0",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   }
}

Saiba mais sobre esse serviço.

Serviço de criação da transação

Para criar uma transação de agendamento, deve-se chamar o mesmo serviço utilizado para criação de pagamentos. O consumo deste método é obrigatório no fluxo de agendamento de recorrência.

Saiba mais sobre esse serviço.

Serviço de ativação de agendamento

Após criar um agendamento sem pagamento e obter um SID, é possível prosseguir para a próxima etapa do fluxo: a chamada ao serviço de ativação de agendamento. Para agendamentos com pagamento, o serviço de efetivação de pagamento deve ser chamado.

Detalhes da chamada

• Recurso: /v1/schedules/{sid}
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM

Exemplos

Abaixo está um exemplo de chamada do serviço de ativação de agendamento utilizando a ferramenta cURL.

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "Content-Type: application/json"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222"
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "schedule":{
      "status":"ATV",
      "sid":"qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
      "schedule_usn":"170713000000040",
      "amount":"900",
      "initial_date":"03/08/2017",
      "next_date":"03/08/2017",
      "number_of_times":"3",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de ativação de agendamento:

Parâmetro	Descrição	Formato	Obrigatório
authorizer_id	Código da autorizadora no e-SiTef. Saiba mais. Caso este campo não tenha sido enviado na etapa de criação da transação, ele passa a ser obrigatório ao consumir o serviço de ativação de agendamento.	< 3 N	COND.
card	Dados do cartão.
number	Número do cartão do comprador (PAN).	< 19 N	SIM
expiry_date	Data de vencimento do cartão no formato MMAA. Sua obrigatoriedade depende do adquirente escolhido. Na maioria dos casos, esse campo é obrigatório.	= 4 N	COND.
holder	Nome do portador do cartão. Obrigatório apenas para pagamentos com e-Rede, GetNet WS e VR (SmartNet).	< 30 AN	COND.
token	HASH de um cartão armazenado no e-SiTef. Não é permitido enviar um número de cartão aberto (campo number) e um cartão armazenado (campo token) na mesma requisição.	= 88 AN	NÃO
wallet_transaction_id	ID de uma transação de carteiras digitais. Por enquanto, essa funcionalidade está disponível apenas para a autorizadora Visa Checkout. Não é permitido enviar um número de cartão aberto (campo number), um cartão armazenado (campo token) e um wallet_transaction_id na mesma requisição.	< 25 AN	NÃO

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 201. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de ativação de agendamento:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	schedule
status	Status do agendamento no e-SiTef. Saiba mais.	= 3 AN
sid	Identificador da transação de agendamento no e-SiTef.	= 64 AN
schedule_usn	Número sequencial único do agendamento no e-SiTef.	= 15 N
authorizer_id	Código da autorizadora a ser utilizada nos pagamentos agendados.	= 4 N
amount	Valor dos pagamentos agendados especificado pela loja (em centavos) na criação da transação.	< 12 N
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N
initial_date	Data de execução do primeiro pagamento agendado no formato DD/MM/AAAA.	= 10 D
next_date	Data de execução do próximo pagamento agendado no formato DD/MM/AAAA.	= 10 D
number_of_times	Número total de pagamentos agendados.	< 3 N
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais	< 30 AN
show_times_invoice	Para agendamentos por tempo finito, caso esse campo tenha valor true acrescenta ao final do campo soft_descriptor o número de execuções/total de execuções (exemplo: Assinatura 3/12).	< 5 T/F

Execução dos pagamentos agendados

Diariamente, o e-SiTef processará os pagamentos agendados do dia em questão e atualizará dados dos agendamentos executados, como o número de execuções corrente. Caso o agendamento já tenha sido executado pelo número de vezes desejado pelo lojista, ele terá seu status alterado para FIN (finalizado) e será desconsiderado em futuros processamentos, pois somente agendamentos com status ATV (ativo) serão executados.

O número corrente de execuções de um agendamento só será incrementado em pagamentos confirmados ou negados. Em caso de transações negadas, o e-SiTef não os reprocessará.

Para cada pagamento realizado, o e-SiTef realizará um POST na URL de status da loja configurada no e-SiTef, informando vários dados do pagamento recorrente.

Aviso de status dos pagamentos recorrentes

No cadastro da loja deve ser informada uma URL de Status, onde o e-SiTef irá enviar um POST HTTPS (x-www-form-urlencoded) contendo o status da transação em adição dos seguintes parâmetros:

curl -X POST \
  https://dominiocadastrado.com.br \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Postman-Token: b639d289-f3c9-4cec-a0e3-a4e3742a792e' \
  -H 'cache-control: no-cache' \
  -d 'rede=xxxx&tipoFinanciamento=4&binCartao=xxxxxx&nsuesitef=191107123456780&tid=authorizerTransactionId12345678901234567&parcelas=2&nsu=merchantNsu&autorizadora=1&nit=nitWith64charsLike1234567890123456789012345678901234567890123457&pedido=orderId1234&
  tipoPagamento=C&finalCartao=2345&status=NEG'

Parâmetro	Descrição	Formato
nit	NIT identificador da transação	= 64 A
pedido	Código do Pedido (na loja)	< 20 A
nsu	Número sequencial enviado pela loja	< 12 N
nsuSitef	Número sequencial único do SiTef	< 10 A
nsuHost	Número sequencial único da Autorizadora	< 20 A
nsuesitef	NSU do e-SiTef	= 15 A
status	Status da transação de pagamento no e-SiTef. Saiba mais.	= 3 A
cupom	Cupom do pagamento (via do cliente) em caso de pagamento efetuado. Não contém quebras de linha, cada linha é separada por @ ao invés de quebra de linha.	< 4000 A
cupomEstabelecimento	Cupom do estabelecimento em caso de pagamento efetuado. Não contém quebras de linha, cada linha é separada por um @.	< 4000 A
autorizadora	Código da Autorizadora (no e-SiTef)	< 10 A
tipoPagamento	Tipo do pagamento: C=Crédito, D=Débito, B=Boleto	= 1 A
dataSitef	Data do pagamento no formato DD/MM/AAAA hh:mm:SS. Atenção: este parâmetro só é enviado para transações confirmadas que foram roteadas pelo SiTef.	= 19 A
dataEfetivacao	Data do pagamento no formato DD/MM/AAAA hh:mm:SS no caso de pagamentos que não forem via SiTef. Atenção: este parâmetro só é enviado para transações confirmadas que não foram roteadas pelo SiTef.	= 19 A
parcelas	Número de parcelas	< 2 N
tipoFinanciamento	Tipo do financiamento escolhido pelo cliente. 3 = parcelado administradora (com juros), 4 = parcelado loja (sem juros).	= 1 N
mensagem	Mensagem da autorizadora	< 1024 A
rede	Nome da rede pela qual o pagamento está sendo efetuado	< 500 A
numeroAutorizacao	Número da autorização (gerado pela autorizadora)	= 6 A
tid	TID da transação, presente somente quando efetuada via meios de pagamento externos.	= 40 A
eci	Eletronic Comerce Indicator (ECI) da transação presente somente em transações com autenticação.	= 3 A
bandeira	Código da bandeira utilizada na transação, conforme tabela de código de bandeiras (Apêndice D).	< 5 N
binCartao	BIN (6 primeiros dígitos) do cartão usado para pagamento.	= 6 N
finalCartao	Últimos 4 dígitos do cartão usado para pagamento.	= 4 N

Importante:

Além dos parâmetros acima o e-SiTef pode devolver outros sem aviso prévio. Por favor, esteja preparado para receber parâmetros extras além dos da tabela acima, que podem ser ignorados.

Não é necessário devolver nada no POST, porém se o POST não for bem-sucedido (HTTP Status-Code 200: OK), o e-SiTef tentará de novo até o número de vezes configurado no sistema, antes de desistir e deixar a transação como pendente de aviso.

Nem todos os parâmetros podem estar presentes em todas as transações, alguns parâmetros podem não ser enviados dependendo da forma de pagamento ou se a transação não for concluída, por exemplo.

Restrições do agendamento

Abaixo estão listadas as funcionalidades não suportadas pelo agendamento:

• Envio de prefixos do SiTef
• Pagamentos com autenticação
• Pagamentos com análise de fraude
• Transações IATA
• Uso de cartão com criptografia do SiTef
• Envio do código de segurança nos pagamentos agendados

Fluxo de edição de agendamento

O e-SiTef disponibiliza serviços para alteração dos dados de um agendamento previamente feito. Com isso, é possível, por exemplo, inativar um agendamento ou mudar o cartão.

Para garantir a integridade dos dados dos agendamentos, o fluxo de edição exige uma etapa de autenticidade, onde o e-SiTef faz um POST na URL de autenticidade cadastrada da loja com os dados necessários para dar continuidade ao fluxo e realizar a edição de fato.

Descrição do fluxo:

• 1. O lojista inicia uma edição de agendamento passando o SID da transação desejada. Em caso de sucesso, o e-SiTef retornará código e mensagem correspondentes.
  • 1.1. Durante a chamada de criação de edição de agendamento, o e-SiTef fará um POST na URL de autenticidade cadastrada da loja com o SEID (identificador da edição de agendamento). A loja deve então responder a esse POST com um código HTTP 200 (OK). Caso esse código não seja devolvido, o e-SiTef interpretará como uma falha nessa operação e invalidará o SEID.
• 2. A loja virtual prossegue o fluxo chamando o serviço de edição de agendamento, passando o SEID obtido no POST de autenticidade e os dados a serem alterados. Caso nenhum problema ocorra, o e-SiTef retornará uma mensagem de sucesso e os dados atualizados do agendamento.

Quick start: edição de agendamento

Este guia mostra o processo de edição de um agendamento, utilizando a interface web service REST do e-SiTef.

O que você precisará

• SID de um agendamento com status ATV ou INA no e-SiTef. Saiba mais.
• Uma ferramenta capaz de realizar chamadas HTTP, como Postman, REST Client ou cURL
• Uma aplicação capaz de receber chamadas POST HTTPS

Criando uma edição de agendamento

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/edits

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição: Preencha o campo <sid> na requisição abaixo com o SID do agendamento a ser alterado.

JSON

cURL

{
   "sid":"<sid>",
   "merchant_data":"14114532781"
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/edits"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "sid":"<sid>",
   "merchant_data":"14114532781"
}
--verbose

Recebimento do POST de autenticidade:

Java + Spring Framework

@RestController
public class MyAuthenticityController {

    @PostMapping(value = "/myauthenticity", 
        consumes = "application/x-www-form-urlencoded; charset=utf-8")
    public ResponseEntity<String> myAuthenticity(@RequestParam Map<String, String> request) {
        Log.info("seid = " + request.get("seid"));
        // ...
        // armazena o SEID da edição de agendamento
        // ...
        return new ResponseEntity<>("OK", HttpStatus.OK);
    }

}

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful."
}

Saiba mais sobre esse serviço.

Alterando o agendamento

Tipo de requisição: PUT

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/edits/<seid>

Preencha o campo <seid> na URL acima com o SEID obtido no POST de autenticidade.

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

JSON

cURL

{
   "status":"INA"
}

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/edits/<seid>"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "status":"INA"
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "schedule":{
      "status":"INA",
      "amount":"1",
      "next_date":"03/08/2025",
      "number_of_times":"3",
      "current_times":"0",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   },
   "schedule_edit":{
      "status":"CON"
   }
}

Saiba mais sobre esse serviço.

Serviço de criação de edição de agendamento

O consumo desse serviço é obrigatório no fluxo de edição de agendamento. Como resultado dessa operação, o lojista obterá um SEID que será necessário para o próximo passo do fluxo.

O SEID possui um tempo limite para sua utilização. Este prazo está configurado no e-SiTef, e caso seja excedido, a transação de edição passará do status NOV (nova) para EXP (expirada), o que impede futuras operações com essa transação, tornando necessário consumir novamente o serviço de criação de edição.

Detalhes da chamada

• Recurso: /v1/schedules/edits
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM

Exemplo

Abaixo está um exemplo de chamada do serviço de criação de edição de agendamento utilizando a ferramenta cURL.

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/edits"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "sid":"qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
   "merchant_data":"14114532781"
}
--verbose

POST de autenticidade:

seid=qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm02
merchant_data=14114532781
sid=qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful."
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de criação de edição de agendamento:

Parâmetro	Descrição	Formato	Obrigatório
sid	Identificador do agendamento a ser editado.	= 64 AN	SIM
merchant_data	Dados gerados pelo lojista que serão retornados no POST de autenticidade. Este campo pode ser utilizado para ajudar a loja a identificar a origem dos POSTs de autenticidade recebidos.	< 20 AN	NÃO

Parâmetros do POST de autenticidade

Na tabela abaixo está a descrição dos parâmetros enviados pelo e-SiTef no POST de autenticidade:

Parâmetro	Descrição	Formato
seid	Identificador da edição de agendamento a ser utilizado na próxima etapa do fluxo.	= 64 AN
sid	Identificador do agendamento a ser alterado.	= 64 AN
merchant_data	Dados enviados pelo lojista para ajudar a identificar a origem do POST de autenticidade.	< 20 AN

O e-SiTef também pode enviar novos parâmetros sem aviso prévio, o que significa que a aplicação do lojista deve estar preparada para receber campos extras e simplesmente ignorá-los.

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 201. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de criação de edição de agendamento:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN

Serviço de edição de agendamento

Após obter um SEID na etapa anterior, a loja poderá realizar edição do agendamento de fato. Todos os parâmetros enviados serão considerados para edição, ou seja, caso não queira alterar um atributo do agendamento, basta enviar o parâmetro vazio.

Detalhes da chamada

• Recurso: /v1/schedules/edits/{seid}
• Método HTTP: PUT
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de edição de agendamento utilizando a ferramenta cURL.

Edição de múltiplos atributos

Requisição:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/edits/qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm02"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "status":"INA",
   "amount":"5555",
   "next_date":"15/07/2017",
   "installments":"2",
   "installment_type":"3",
   "soft_descriptor":"Assinatura",
   "show_times_invoice":"false",
   "card":{
      "expiry_date":"1222",
      "number":"5555555555555555"
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "schedule":{
      "status":"INA",
      "amount":"5555",
      "next_date":"15/07/2017",
      "number_of_times":"3",
      "current_times":"0",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   },
   "schedule_edit":{
      "status":"CON"
   }
}

Inativação de agendamento

Requisição:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/edits/qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm02"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "status":"INA"
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "schedule":{
      "status":"INA",
      "amount":"900",
      "next_date":"03/08/2017",
      "number_of_times":"3",
      "current_times":"0",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   },
   "schedule_edit":{
      "status":"CON"
   }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de edição de agendamento:

Parâmetro	Descrição	Formato	Obrigatório
status	Status do agendamento. Pode receber os seguintes valores: ATV – Ativa o agendamento. Este valor deve ser usado sobre agendamentos com status INA (inativo). Caso o agendamento seja reativado após sua data de execução, ele será reagendado para o mesmo dia do mês seguinte. INA – Inativa o agendamento, ou seja, os pagamentos agendados previamente não serão mais executados.	= 3 AN	NÃO
amount	Valor em centavos dos pagamentos agendados.	< 12 N	NÃO
next_date	Data da próxima execução do agendamento no formato DD/MM/AAAA. Só são permitidas datas futuras com dia entre 1 e 28.	= 10 D	NÃO
installments	Número de parcelas de cada pagamento agendado.	< 2 N	NÃO
installment_type	Tipo de financiamento do parcelamento de cada pagamento agendado: Valor 3 = parcelamento com juros da administradora do cartão. Valor 4 = parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista).	< 2 N	NÃO
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais	< 30 AN	NÃO
show_times_invoice	Para agendamentos por tempo finito, enviar esse campo com valor true caso se deseje acrescentar ao final do campo soft_descriptor o número de execuções/total de execuções (exemplo: Assinatura 3/12).	< 5 T/F	NÃO
	card
number	Número do cartão do comprador (PAN).	< 19 N	NÃO
expiry_date	Data de vencimento do cartão no formato MMAA. O envio deste parâmetro deve, obrigatoriamente, vir acompanhado do número do cartão, ou seja, não é possível enviar apenas a data de validade.	= 4 N	NÃO

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de edição de agendamento:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	schedule
status	Status do agendamento no e-SiTef. Saiba mais.	= 3 AN
amount	Valor dos pagamentos agendados especificado pela loja (em centavos) na criação da transação.	< 12 N
next_date	Data de execução do próximo pagamento agendado no formato DD/MM/AAAA.	= 10 D
number_of_times	Número total de pagamentos agendados.	< 3 N
current_times	Número de pagamentos agendados já executados.	< 3 N
installments	Número de parcelas a ser utilizado nos pagamentos agendados.	< 2 N
installment_type	Tipo de financiamento a ser utilizado nos pagamentos agendados.	< 2 N
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador.	< 30 AN
show_times_invoice	Para agendamentos por tempo finito, caso esse campo tenha valor true acrescenta ao final do campo soft_descriptor o número de execuções/total de execuções (exemplo: Assinatura 3/12).	< 5 T/F
	schedule_edit
status	Status da edição de agendamento no e-SiTef. Pode assumir os seguintes valores: NOV – Novo EXP – Expirado CON – Confirmado INV – Inválido	= 3 AN

Recarga REST

Visão Geral

A coleta dos dados será realizada pela Loja Virtual, que capturará as informações de recarga e os dados do cartão (em caso de recarga com pagamento) ou apenas as informações de recarga (para realizar apenas uma recarga).

Comunicação

Para realizar uma transação Web Service, toda a comunicação será realizada via HTTPS/SSL. É importante que o servidor do lojista suporte criptografia com no mínimo 128 bits. O servidor da loja deverá realizar chamadas em endereços específicos para transações REST.

Cada serviço deve ser chamado utilizando a URL base concatenada do recurso desejado (veja o capítulo referente ao serviço a ser consumido). O método HTTP (GET, POST ou PUT) indica a ação esperada sobre o recurso escolhido. Abaixo estão as URLs base do e-SiTef:

URL base de Produção:

https://esitef-ec.softwareexpress.com.br/e-sitef

URL base de Homologação:

https://esitef-homologacao.softwareexpress.com.br/e-sitef

Todas as chamadas realizadas para os serviços serão respondidas de forma síncrona.

Atenção:

Nunca utilize o IP ao invés do domínio esitef-ec.softwareexpress.com.br. O IP pode mudar a qualquer momento e sem aviso prévio, portanto é importante a utilização do domínio para acesso ao e-SiTef.

Importante:

Além dos parâmetros de retorno dos serviços descritos nesta especificação o e-SiTef poderá devolver outros parâmetros sem aviso prévio.

É importante que o aplicativo esteja preparado para receber os parâmetros desconhecidos além dos parâmetros já especificados e simplesmente desprezá-los.

Fluxo de recarga sem pagamento

O fluxo de recarga sem pagamento pode ser realizado conforme o exemplo da figura acima.

O desenvolvedor deve seguir o que foi especificado no documento de integração do e-SiTef e enviar os parâmetros:

• De acordo com o tamanho e tipo (numérico ou alfanumérico);
• Se o campo é obrigatório, condicional ou opcional.

De forma resumida, segue abaixo o fluxo transacional para Recarga. Com isso, algumas dúvidas devem ser esclarecidas, agilizando o processo de integração com o e-SiTef.

• 1. O fluxo se inicia com a aplicação da loja realizando uma chamada para iniciar recarga;
  • 1.1. De modo síncrono, o e-SiTef fará um POST HTTPS na URL de autenticidade informada pelo lojista e cadastrada no backoffice do e-SiTef. O POST enviado conterá o NIT necessário para prosseguir com a recarga;
  • 1.2. A resposta da loja ao POST HTTPS obrigatoriamente deve ser "200 OK";
  • 1.3. A resposta do e-SiTef à chamada para iniciar recarga será um código indicando sucesso (valor 0) ou fracasso (valor diferente de 0);
• 2. A loja então deve fazer uma chamada para listar concessionárias passando o NIT recebido anteriormente;
  • 2.1. O e-SiTef retorna uma lista contendo os dados das concessionárias1;
• 3. A loja então deve fazer uma chamada para listar dados da filial passando o código da concessionária escolhida, o DDD desejado e o NIT;
  • 3.1. O e-SiTef retorna os dados da filial, incluindo valores possíveis de recarga, períodos de validade, valores de bônus, dentre outros;
• 4. A loja deve então fazer uma chamada para efetuar recarga passando o NIT, o código da concessionária escolhida, o telefone, o DDD e o valor selecionado;
  • 4.1. O e-SiTef inicia a recarga com a operadora escolhida e retorna os dados da recarga pendente de confirmação;
• 5. A loja deve impreterivelmente fazer uma chamada para confirmar recarga passando o NIT e um campo indicando se a recarga pendente deve ser confirmada ou desfeita na operadora;
  • 5.1. O e-SiTef retorna uma resposta indicando o resultado da confirmação ou desfazimento da recarga;

Fluxo de recarga com pagamento

O fluxo de recarga com ou sem pagamento são iguais, com adendo de que o fluxo com pagamento exige que sejam enviados os dados do pagamento na chamada de efetuar recarga.

Quick start

Este guia mostra o processo de efetivação de um recarga, utilizando a interface web service REST do e-SiTef.

O que você precisará

• Cadastro ativo no ambiente de homologação do e-SiTef (obtido com nossa equipe de suporte)
• Uma ferramenta capaz de realizar chamadas HTTP, como Postman, REST Client ou cURL

Criando a transação

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge

Headers:

• Content-Type: application/json

Requisição:

JSON

cURL

{
   "begin_recharge_request":{
      "merchant_key":"XXXXXXXX"
   }
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge"
--header "Content-Type: application/json"
--data-binary
{
   "begin_recharge_request":{
      "merchant_key":"XXXXXXXX"
   }
}
--verbose

Recebimento do POST de autenticidade:

Java + Spring Framework

@RestController
public class MyAuthenticityController {

    @PostMapping(value = "/myauthenticity", 
        consumes = "application/x-www-form-urlencoded; charset=utf-8")
    public ResponseEntity<String> myAuthenticity(@RequestParam Map<String, String> request) {
        Log.info("nit = " + request.get("nit"));
        // ...
        // armazena o NIT da recarga
        // ...
        return new ResponseEntity<>("OK", HttpStatus.OK);
    }

}

Resposta:

{
   "begin_recharge_response":{
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0"
      }
   }
}

Saiba mais sobre esse serviço.

Listando concessionárias

Tipo de requisição: GET

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargedealers

Requisição:

cURL

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargedealers?nit=asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678&generalhash=0000000000000000"
--verbose

Resposta:

{
   "list_dealers_response":{
      "status":"NOV",
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0"
      },
      "authorizer":{
         "message":"",
         "code":"000"
      },
      "hashes":{
         "general":"09A9681D09A9681D"
      },
      "dealers":[
         {
            "name":"Vivo",
            "code":"001"
         },
         {
            "name":"Claro",
            "code":"002"
         },
         {
            "name":"Oi",
            "code":"003"
         },
         {
            "name":"Tim",
            "code":"004"
         }
      ]
   }
}

Saiba mais sobre esse serviço.

Listando dados da filial

Tipo de requisição: GET

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargebranches

Requisição:

cURL

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargebranches?nit=asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678&ddd=00&dealercode=1&generalhash=0000000000000000"
--verbose

Resposta:

{
   "list_branch_data_response":{
      "status":"NOV",
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0"
      },
      "sitef":{
         "code":"000"
      },
      "hashes":{
         "general":"09A9681D09A9681D"
      },
      "questions":[
         {
            "id":"5",
            "display":"Qual o nome do seu pai?",
            "rule":"3",
            "min":"5",
            "max":"30",
            "type":"i"
         }
      ],
      "general":[
         {
            "message":"MENSAGEM DE TESTE"
         }
      ],
      "categories":[
         {
            "code":"01",
            "description":"RECARGA",
            "amount_ranges":[
               {
                  "message":"MSG_FAIXA_1",
                  "amount_key":"7",
                  "bonus_in_percentage":"100",
                  "bonus":"50",
                  "payment_amount":"700",
                  "bonus_category":"1",
                  "expiry_date":"30",
                  "bonus_expiry_date":"15",
                  "min_amount":"500",
                  "max_amount":"10000"
               },
               {
                  "message":"MSG_FAIXA_2",
                  "amount_key":"8",
                  "bonus_in_percentage":"500",
                  "bonus_category":"2",
                  "min_amount":"1000",
                  "max_amount":"50000"
               }
            ],
            "fixed_amounts":[
               {
                  "bonus":"50",
                  "message":"MSG_FIXO_1",
                  "amount":"300",
                  "amount_key":"1",
                  "bonus_category":"2",
                  "bonus_in_percentage":"200",
                  "payment_amount":"10",
                  "expiry_date":"60",
                  "bonus_expiry_date":"15"
               },
               {
                  "message":"MSG_FIXO_2",
                  "amount":"1500",
                  "amount_key":"2",
                  "payment_amount":"30"
               },
               {
                  "message":"MSG_FIXO_3",
                  "amount":"2000",
                  "amount_key":"3"
               },
               {
                  "amount":"2200",
                  "amount_key":"4",
                  "expiry_date":"90"
               },
               {
                  "message":"MSG_FIXO_4",
                  "amount":"5000",
                  "amount_key":"6",
                  "expiry_date":"120"
               }
            ]
         },
         {
            "code":"02",
            "description":"SMS",
            "amount_ranges":[

            ],
            "fixed_amounts":[

            ]
         },
         {
            "code":"03",
            "description":"PRIMEIRA_RECARGA",
            "amount_ranges":[

            ],
            "fixed_amounts":[

            ]
         }
      ],
      "payment_methods":{
         "max":"4",
         "available":[
            "00",
            "01",
            "02:10",
            "03:10",
            "04:10",
            "05:10",
            "06:10"
         ]
      }
   }
}

Saiba mais sobre esse serviço.

Efetivando a recarga

Recarga com pagamento

Tipo de requisição: PUT

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/<nit>

Headers:

• Content-Type: application/json

Requisição:

JSON

cURL

{
   "do_recharge_request":{
      "hashes":{
         "general":"0000000000000000"
      },
      "dealer":{
         "code":"1",
         "type_code":"03",
         "branch":{
            "code":"98006000000"
         }
      },
      "phone":{
         "ddd":"11",
         "number":"123456789"
      },
      "amount":"3000",
      "amount_key":"3",
      "used_payment_methods":[
         "11",
         "12"
      ],
      "answers":[
         {
            "code":"1",
            "description":"resposta"
         },
         {
            "code":"2",
            "description":"resposta2"
         }
      ],
      "terminal_type":"03",
      "cpf":"8298374982374",
      "cnpj":"123121333000123",
      "zip_code":"01310100",
      "payment":{
         "amount":"12",
         "authorizer_id":"1",
         "customer_id":"12341234",
         "merchant_key":"OIAUSWHFN012375901J23047FNN00UYWHN0R871Y2ND87",
         "installment":{
            "number":"2",
            "type":"4"
         },
         "card":{
            "number":"1111111111111111",
            "token":"",
            "security_code":"123",
            "expiry_date":"1222"
         },
         "extra_param":[
            {
               "key":"CRIPTO",
               "value":"1"
            }
         ]
      }
   }
}

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "do_recharge_request":{
      "hashes":{
         "general":"0000000000000000"
      },
      "dealer":{
         "code":"1",
         "type_code":"03",
         "branch":{
            "code":"98006000000"
         }
      },
      "phone":{
         "ddd":"11",
         "number":"123456789"
      },
      "amount":"3000",
      "amount_key":"3",
      "used_payment_methods":[
         "11",
         "12"
      ],
      "answers":[
         {
            "code":"1",
            "description":"resposta"
         },
         {
            "code":"2",
            "description":"resposta2"
         }
      ],
      "terminal_type":"03",
      "cpf":"8298374982374",
      "cnpj":"123121333000123",
      "zip_code":"01310100",
      "payment":{
         "amount":"12",
         "authorizer_id":"1",
         "customer_id":"12341234",
         "merchant_key":"OIAUSWHFN012375901J23047FNN00UYWHN0R871Y2ND87",
         "installment":{
            "number":"2",
            "type":"4"
         },
         "card":{
            "number":"1111111111111111",
            "token":"",
            "security_code":"123",
            "expiry_date":"1222"
         },
         "extra_param":[
            {
               "key":"CRIPTO",
               "value":"1"
            }
         ]
      }
   }
}
--verbose

Resposta:

{
   "do_recharge_response":{
      "status":"PPC",
      "order_id":"12344231",
      "merchant_usn":"5123",
      "esitef":{
         "message":"OK",
         "code":"0",
         "usn":"123456789012345"
      },
      "sitef":{
         "message":"OK",
         "code":"0"
      },
      "host":{
         "message":"OK",
         "code":"0"
      },
      "acquirer":{
         "branch_code":"cod filial",
         "merchant_code":"codigoEstab"
      },
      "authorization":{
         "confirmation_data":"000033333",
         "authorizer_date":"20150514",
         "authorizer_time":"1100",
         "host_usn":"11122",
         "sitef_usn":"333",
         "number":"332234"
      },
      "customer":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do cliente"
      },
      "merchant":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do estabelecimento"
      },
      "payment_methods":{
         "max":4,
         "available":[
            {
               "name":"dinheiro"
            },
            {
               "name":"cheque"
            }
         ]
      },
      "payment":{
         "status":"PPC",
         "amount":"12",
         "type":"C",
         "esitef":{
            "usn":"098765432109876",
            "date":"12/12/2012 12:12"
         },
         "customer":{
            "receipt":"nwiugrnboinb APROVADO via do cliente"
         },
         "merchant":{
            "receipt":"nwiugrnboinb APROVADO via do estabelecimento "
         },
         "authorizer_id":"1",
         "acquirer":"CIELO",
         "authorization":{
            "number":"163457212",
            "sitef_usn":"456456",
            "host_usn":"654654",
            "tid":"7334312a2",
            "eci":"fr3u214wf71",
            "sitef_date":"12122012"
         },
         "analysis":{
            "status":"PEN",
            "code":"0",
            "message":"aprovado"
         },
         "extra_param":[
            {
               "key":"CRIPTO",
               "value":"1"
            }
         ],
         "sitef":{
            "code":"000"
         }
      }
   }
}

Recarga sem pagamento

Requisição:

JSON

cURL

{
   "do_recharge_request":{
      "dealer":{
         "code":"1"
      },
      "phone":{
         "ddd":"11",
         "number":"123456789"
      },
      "amount":"3000"
   }
}

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "do_recharge_request":{
      "dealer":{
         "code":"1"
      },
      "phone":{
         "ddd":"11",
         "number":"123456789"
      },
      "amount":"3000"
   }
}
--verbose

Resposta:

{
   "do_recharge_response":{
      "status":"PPC",
      "order_id":"12344231",
      "merchant_usn":"5123",
      "esitef":{
         "message":"OK",
         "code":"0",
         "usn":"123456789012345"
      },
      "sitef":{
         "message":"OK",
         "code":"0"
      },
      "host":{
         "message":"OK",
         "code":"0"
      },
      "acquirer":{
         "branch_code":"cod filial",
         "merchant_code":"codigoEstab"
      },
      "authorization":{
         "confirmation_data":"000033333",
         "authorizer_date":"20150514",
         "authorizer_time":"1100",
         "host_usn":"11122",
         "sitef_usn":"333",
         "number":"332234"
      },
      "customer":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do cliente"
      },
      "merchant":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do estabelecimento"
      },
      "payment_methods":{
         "max":4,
         "available":[
            {
               "name":"dinheiro"
            },
            {
               "name":"cheque"
            }
         ]
      }
   }
}

Saiba mais sobre esse serviço.

Confirmando a recarga

Tipo de requisição: PUT

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/<nit>

Headers:

• Content-Type: application/json

Requisição:

JSON

cURL

{
   "confirm_recharge_request":{
      "confirm":"true",
      "merchant_key":"AOSDJF210349H3R0374H874H3T7AHG90SF"
   }
}

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "confirm_recharge_request":{
      "confirm":"true",
      "merchant_key":"AOSDJF210349H3R0374H874H3T7AHG90SF"
   }
}
--verbose

Resposta:

{
   "confirm_recharge_response":{
      "esitef":{
         "message":"OK",
         "code":"0"
      },
      "status":"CON",
      "payment":{
         "status":"CON"
      }
   }
}

Saiba mais sobre esse serviço.

Consultando a recarga

Tipo de requisição: PUT

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/<nit>

Preencha o campo na URL acima com o NIT obtido na resposta da fase de criação da transação.

Headers:

• Content-Type: application/json

Requisição:

cURL

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678/?merchantkey=ASDFGHJK12345678ASDFGHJK12345678"
--verbose

Resposta:

{
   "get_status_recharge_response":{
      "status":"CON",
      "esitef":{
         "message":"OK",
         "code":"0"
      },
      "authorizers":[
         {
            "name":"sitef",
            "message":"textoExibicao",
            "code":"codigoRespSitef"
         },
         {
            "name":"nome operadora (186)",
            "message":"OK",
            "code":"196"
         }
      ],
      "acquirer":{
         "branch_code":"cod filial",
         "merchant_code":"codigoEstab"
      },
      "authorization":{
         "confirmation_data":"000033333",
         "authorizer_date":"20150514",
         "authorizer_time":"1100",
         "host_usn":"11122",
         "sitef_usn":"333",
         "number":"332234"
      },
      "customer":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA mimimim cliente whiskas sache"
      },
      "merchant":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA mimimim estabelecimento lorem ipsum"
      },
      "payment_methods":{
         "max":2,
         "available":[
            {
               "name":"dinheiro"
            },
            {
               "name":"cheque"
            }
         ]
      },
      "payment":{
         "status":"PPC",
         "amount":"12",
         "type":"C",
         "esitef":{
            "usn":"098765432109876",
            "date":"12/12/2012 12:12"
         },
         "customer":{
            "receipt":"nwiugrnboinbAPROVADOaoisuerhn"
         },
         "merchant":{
            "receipt":"nwiugrnboinbAPROVADOaoisuerhn"
         },
         "authorizer_id":"1",
         "acquirer":"CIELO",
         "authorization":{
            "number":"163457212",
            "sitef_usn":"456456",
            "host_usn":"654654",
            "tid":"7334312a2",
            "eci":"fr3u214wf71",
            "sitef_date":"12122012"
         },
         "analysis":{
            "status":"PEN",
            "code":"0",
            "message":"hahaha"
         },
         "extra_param":[
            {
               "key":"CRIPTO",
               "value":"1"
            }
         ],
         "sitef":{
            "code":"000"
         }
      }
   }
}

Saiba mais sobre esse serviço.

Serviço de criação de recarga

POST de autenticidade x assinatura

O e-SiTef possui duas formas de autenticação da loja na interface de recarga REST: POST de autenticidade ou assinatura.

No método de POST de autenticidade, o e-SiTef enviará os dados da transação de recarga recém-criada para a URL de autenticidade cadastrada da loja.

No método de assinatura, a loja deve ter uma chave pública de criptografia RSA cadastrada no e-SiTef e deverá montar uma assinatura JWT (JSON Web Tokens) a ser enviada no cabeçalho Authorization. Neste caso, as informações da transação de recarga serão retornadas diretamente na resposta do serviço. Saiba mais.

Detalhes da chamada

• Recurso: /v3/recharge
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM
Authorization	Deve ser enviada a assinatura de autenticação da loja no formato Bearer {assinatura}. Exemplo: Bearer JHVGytfdgauygdauiw78264284527852897hagdg.	< 2000 AN	NÃO

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de criação de recarga utilizando a ferramenta cURL.

Criação de recarga com envio de todos os parâmetros

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge"
--header "Content-Type: application/json"
--data-binary
{
   "begin_recharge_request":{
      "merchant_key":"XXXXXXXX",
      "merchant_usn":"2398",
      "order_id":"023748",
      "general_hash":"0000000000000000",
      "recharge_type":"normal"
   }
}
--verbose

Resposta:

{
   "begin_recharge_response":{
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0"
      }
   }
}

Criação de recarga com envio mínimo de parâmetros

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge"
--header "Content-Type: application/json"
--data-binary
{
   "begin_recharge_request":{
      "merchant_key":"XXXXXXXX"
   }
}
--verbose

Resposta:

{
   "begin_recharge_response":{
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0"
      }
   }
}

Criação de recarga com envio de assinatura

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge"
--header "Content-Type: application/json"
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IkxPFGFURVNURSIsIm1lcmNoYW50X2tleSI6IkYxOURFMDAxNzdDMzAxREYyNEE4NjVGMTFBQTlCMjU2N0Y2MDQ4OTFGMEY0NEREQUVGRDY5RTMzOTlFMEI3RTEiLCJvcmRlcl9pZCI6IjEzMDE0ODU4NjYzIiwibWVyY2hhbnRfdXNuIjoiMTQ0NjY4MTAxNiIsInRpbWVzdGFtcCI6IjE2MDUzMDM1ODA5MzEifQ.JoYz8mQ8PZ8MCr5QXygbivAy2x9fvdUEGu_jSeOYF-BtSGm7ZSYWFVokyowabk1FM2NCklubb5eEB_-g9lCi1ntRQ9iqKhdldm-U8pl0V98u7Mv_hR-pcp6MHfqql0T-mhkOv1WkfYO1igck4N6EfsNu9iO126BwgvJQC456WjAUW5jgjRHboc6htvaak9NBs6yRVLNZY03cR9gKtQXMoHeXiCGeNU55_2W1SOeRJPk-OsyBzvVlZBX5RdfUjB2BOdRI7H2TDBBS-GZaMV3b2eS5_84JTySFnriCTXJ-Y1FzBnH60e4fTfAiYy1P_J-j9hyXjLYgtRu8jQd8ITfiFG3h4ZIysb4CA_lJNg_d4YuCqhBiZcpculcbfXlcrcfPV-CpDytfiLz34FDWH0Q7Vlna1YuSNOKPzDIUx1MOMZO9bpwaE6Q3kClkqri92-42yeLoUKH6PUrlMpE3JrfuBelALE4ce7QzCrNjcvoqR_KVmCm6ozBjPn9qY0s7x7qe6ZLur7hNUoX79JdWGZy1-bx8dSqqpLrU0SXbMBqtvch5FvdUkktbkJpZAr7q6e0nR13_mK3RTV7adOEw03E_ocUk__rEmjGDAHMSWGmiPowu14jD1-VZ2Yf8FeoKzHYcXmIbEReTVHshk9faBICMQzMS3SXaqow4WXqULZiLTwc"
--data-binary
{
   "begin_recharge_request":{
      "merchant_key":"XXXXXXXX",
      "merchant_usn":"1446681016",
      "order_id":"13014858663",
      "general_hash":"0000000000000000"
   }
}
--verbose

Resposta:

{
   "begin_recharge_response":{
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0"
      },
      "nit": "jhadafsafhjhasdfghiyuw43u8785345jksjknsmnnsjkfkiu34u98ynksnn3535",
      "merchant_id": "XXXXXXXX",
      "order_id": "13014858663",
      "merchant_usn": "1446681016",
      "general_hash": "AF32810AAF32810A"
   }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de criação de recarga:

Parâmetro	Descrição	Formato	Obrigatório
merchant_key	Chave da loja cadastrada no e-SiTef	< 80 A	SIM
merchant_usn	Número sequencial único gerado pela loja	< 12 N	NÃO
order_id	Código de identificação do pedido gerado pela loja	< 20 AN	NÃO
general_hash	Código de identificação da versão da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros). Caso a loja não tenha feito uma recarga anteriormente ou não tenha guardado um valor de general_hash previamente recebido do e-SiTef, o valor: 0000000000000000 pode ser passado ao e-SiTef. Este campo permite ao lojista saber se ocorreu alteração nos dados da recarga. Isso porque se ocorreu alguma alteração na tabela, o general_hash retornado será diferente do general_hash que o lojista possui. Neste caso, é aconselhável que o lojista efetue as consultas e atualize os valores das operadoras de recarga em sua aplicação.	= 16 A	NÃO
recharge_type	Tipo da recarga a ser realizada. Valores: normal – Recarga de celulares others – Recarga para outros tipos de produtos, como PIN de jogos, doações, seguros ou até mesmo recarga de celular por outras modalidades. invoice – Pagamento de fatura por assinatura Valor padrão: normal	= 6 A	NÃO

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de criação de recarga:

Parâmetro	Descrição	Formato
nit	Identificação da transação de recarga no e-SiTef	= 64 AN
merchant_id	Código de identificação da loja no e-SiTef	< 15 AN
order_id	Código de identificação do pedido gerado pela loja	< 20 AN
merchant_usn	Número sequencial único gerado pela loja	< 12 N
general_hash	Código de identificação da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros).	= 16 AN
esitef	Elemento que descreve a resposta do e-SiTef.
code	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN

Parâmetros enviados pelo e-SiTef no POST HTTPS

Importante:

O e-SiTef utiliza o tipo de mídia x-www-form-urlencoded, para envio do POST HTTPS. Sendo assim, o servidor tem que aceitar este tipo de mídia na URL que for cadastrada para recebimento do POST HTTPS.

Parâmetro	Descrição	Formato
nit	Identificação da transação de recarga no e-SiTef	= 64 AN
merchantId	Código de identificação da loja no e-SiTef	< 15 AN
orderId	Código de identificação do pedido gerado pela loja	< 20 AN
merchantUSN	Número sequencial único gerado pela loja	< 12 N
generalHash	Código de identificação da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros).	= 16 AN

Serviço de listagem de concessionárias

Detalhes da chamada

• Recurso: /v3/rechargedealers
• Método HTTP: GET
• Formato da requisição: query string
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
Authorization	Assinatura de autenticidade no formato Bearer {assinatura}. Saiba mais. Exemplo: Bearer hh39458f73hf45324765ft349h5f73t4h95f34. Este campo é obrigatório caso a transação tenha sido criada pelo processo de assinatura.	< 2000 AN	COND.

Exemplos

Abaixo estão exemplos de chamada do serviço de listagem de concessionárias utilizando a ferramenta cURL.

Listagem de concessionárias de recarga normal

Requisição:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargedealers?nit=asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678&generalhash=0000000000000000"
--verbose

Resposta:

{
   "list_dealers_response":{
      "status":"NOV",
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0"
      },
      "authorizer":{
         "message":"",
         "code":"000"
      },
      "hashes":{
         "general":"09A9681D09A9681D"
      },
      "dealers":[
         {
            "name":"Vivo",
            "code":"001"
         },
         {
            "name":"Claro",
            "code":"002"
         },
         {
            "name":"Oi",
            "code":"003"
         },
         {
            "name":"Tim",
            "code":"004"
         }
      ]
   }
}

Listagem de concessionárias de recarga de outros produtos (others)

Requisição:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargedealers?nit=asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--verbose

Resposta:

{
   "list_dealers_response":{
      "status":"NOV",
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0"
      },
      "authorizer":{
         "message":"",
         "code":"000"
      },
      "hashes":{
         "general":"09A9681D09A9681D"
      },
      "dealers":[
         {
            "name":"Vex-PIN",
            "code":"905",
            "branches":[
               {
                  "name":"Vex-PIN",
                  "code":"97200000000"
               }
            ],
            "type_name":"PIN TELEFONE",
            "type_code":"02"
         },
         {
            "name":"TIM-Leste-PIN",
            "code":"902",
            "branches":[
               {
                  "name":"TIM-Leste-PIN",
                  "code":"97001000000"
               }
            ],
            "type_name":"PIN TELEFONE",
            "type_code":"02"
         },
         {
            "name":"E-Prepag",
            "code":"901",
            "branches":[
               {
                  "name":"Brancaleone-Migux",
                  "code":"98000000000"
               },
               {
                  "name":"HABBO HOTEL-Habbo Hotel",
                  "code":"98001000000"
               },
               {
                  "name":"ONGAME-Metin2",
                  "code":"98006000000"
               }
            ],
            "type_name":"PIN GAMES",
            "type_code":"03"
         },
         {
            "name":"Prepag",
            "code":"900",
            "branches":[
               {
                  "name":"Level Up!",
                  "code":"99000000000"
               },
               {
                  "name":"OnGame",
                  "code":"99100000000"
               },
               {
                  "name":"Acclaim",
                  "code":"99300000000"
               }
            ],
            "type_name":"PIN GAMES",
            "type_code":"03"
         },
         {
            "name":"Crianca Esperanca",
            "code":"908",
            "branches":[
               {
                  "name":"Crianca Esperanca",
                  "code":"97299000000"
               }
            ],
            "type_name":"DOACAO",
            "type_code":"04"
         },
         {
            "name":"Sorte Mania",
            "code":"909",
            "branches":[
               {
                  "name":"Sorte Mania",
                  "code":"97298000000"
               }
            ],
            "type_name":"SEGURO",
            "type_code":"05"
         }
      ]
   }
}

Listagem de concessionárias de pagamento de fatura por assinatura (invoice)

Requisição:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargedealers?nit=asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--verbose

Resposta:

{
    "list_dealers_response": {
        "status": "NOV",
        "esitef": {
            "message": "OK. Transaction successful.",
            "code": "0"
        },
        "authorizer": {
            "message": "",
            "code": "000"
        },
        "hashes": {
            "general": "85E791AD85E791AD"
        },
        "dealers": [
            {
                "name": "Vivo SP Pos",
                "code": "800",
                "branches": [
                    {
                        "name": "Vivo SP Pos",
                        "code": "80019000000"
                    }
                ]
            }
        ],
        "questions": [
            {
                "id": "LPERG:126",
                "display": "Identificação do cliente ou Número de contrato",
                "rule": "0",
                "min": "1",
                "max": "11",
                "type": "N"
            }
        ]
    }
}

Listagem de concessionárias com envio de assinatura

Requisição:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargedealers?nit=asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678&generalhash=0000000000000000"
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IkxPFGFURVNURSIsIm1lcmNoYW50X2tleSI6IkYxOURFMDAxNzdDMzAxREYyNEE4NjVGMTFBQTlCMjU2N0Y2MDQ4OTFGMEY0NEREQUVGRDY5RTMzOTlFMEI3RTEiLCJvcmRlcl9pZCI6IjEzMDE0ODU4NjYzIiwibWVyY2hhbnRfdXNuIjoiMTQ0NjY4MTAxNiIsInRpbWVzdGFtcCI6IjE2MDUzMDM1ODA5MzEifQ.JoYz8mQ8PZ8MCr5QXygbivAy2x9fvdUEGu_jSeOYF-BtSGm7ZSYWFVokyowabk1FM2NCklubb5eEB_-g9lCi1ntRQ9iqKhdldm-U8pl0V98u7Mv_hR-pcp6MHfqql0T-mhkOv1WkfYO1igck4N6EfsNu9iO126BwgvJQC456WjAUW5jgjRHboc6htvaak9NBs6yRVLNZY03cR9gKtQXMoHeXiCGeNU55_2W1SOeRJPk-OsyBzvVlZBX5RdfUjB2BOdRI7H2TDBBS-GZaMV3b2eS5_84JTySFnriCTXJ-Y1FzBnH60e4fTfAiYy1P_J-j9hyXjLYgtRu8jQd8ITfiFG3h4ZIysb4CA_lJNg_d4YuCqhBiZcpculcbfXlcrcfPV-CpDytfiLz34FDWH0Q7Vlna1YuSNOKPzDIUx1MOMZO9bpwaE6Q3kClkqri92-42yeLoUKH6PUrlMpE3JrfuBelALE4ce7QzCrNjcvoqR_KVmCm6ozBjPn9qY0s7x7qe6ZLur7hNUoX79JdWGZy1-bx8dSqqpLrU0SXbMBqtvch5FvdUkktbkJpZAr7q6e0nR13_mK3RTV7adOEw03E_ocUk__rEmjGDAHMSWGmiPowu14jD1-VZ2Yf8FeoKzHYcXmIbEReTVHshk9faBICMQzMS3SXaqow4WXqULZiLTwc"
--verbose

Resposta:

{
   "list_dealers_response":{
      "status":"NOV",
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0"
      },
      "authorizer":{
         "message":"",
         "code":"000"
      },
      "hashes":{
         "general":"09A9681D09A9681D"
      },
      "dealers":[
         {
            "name":"Vivo",
            "code":"001"
         },
         {
            "name":"Claro",
            "code":"002"
         },
         {
            "name":"Oi",
            "code":"003"
         },
         {
            "name":"Tim",
            "code":"004"
         }
      ]
   }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de listagem de concessionárias:

Parâmetro	Descrição	Formato	Obrigatório
nit	Identificação da transação de recarga no e-SiTef	= 64 A	SIM
generalhash	Código de identificação da versão da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros). Caso a loja não tenha feito uma recarga anteriormente ou não tenha guardado um valor de generalhash previamente recebido do e-SiTef, o valor: 0000000000000000 pode ser passado ao e-SiTef. Este campo permite ao lojista saber se ocorreu alteração nos dados da recarga. Isso porque se ocorreu alguma alteração na tabela, o generalhash retornado será diferente do generalhash que o lojista possui. Neste caso, é aconselhável que o lojista efetue as consultas e atualize os valores das operadoras de recarga em sua aplicação.	= 16 A	NÃO

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de listagem de concessionárias:

Parâmetro	Descrição	Formato
status	Status da transação de recarga no e-SiTef. Saiba mais.	= 3 AN
	esitef
code	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	authorizer
code	Código de resposta retornado pela autorizadora	< 4 AN
message	Mensagem retornada pela autorizadora	< 64 AN
	hashes
general	Código de identificação da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros).	= 16 AN
	dealers[]
code	Código da concessionária/operadora	= 3 N
name	Nome da concessionária/operadora	< 100 AN
	dealers[].branches[]
code	Código da filial	= 11 N
name	Nome da filial	< 100 AN
	questions[] Este campo agrega uma lista de perguntas para confirmação positiva. As perguntas retornadas devem, obrigatoriamente, ser respondidas pelo usuário e ter suas respostas enviadas ao e-SiTef no passo seguinte (listar dados da filial).
id	Código de identificação da pergunta	< 20 AN
display	Texto da pergunta a ser apresentada	< 180 AN
rule	Indica onde os dados devem ser coletados. Saiba mais.	< 2 AN
min	Indica o tamanho mínimo da resposta	< 4 N
max	Indica o tamanho máximo da resposta	< 5 N
type	Indica o tipo de dados da resposta a ser coletada. Saiba mais.	< 3 AN
min_value	Indica o valor mínimo da resposta	< 3 N
max_value	Indica o valor máximo da resposta	< 3 N

Retorno do campo questions.rule

Regra	Descrição
0	Teclado do operador
1	PinPad (Não se aplica)
2	Leitura de trilha magnética no PIN PAD (Não se aplica)
3	Automação (A pergunta não deve ser apresentada ao operador/cliente para a coleta da resposta. Neste caso, a própria automação deve responder à pergunta sem intervenção do operador/cliente).
4	Senha supervisor (não PINPAD)
5	Teclado do operador com dupla digitação. O <Display> deve conter dois textos, sendo que o primeiro se refere à requisição para a entrada do dado e o segundo, se refere à confirmação da entrada do dado, que deve ser a mesma da primeira. Os textos devem estar separados por ; como informado a seguir. <Display> = Texto para 1ª coleta;Texto para 2ª coleta (confirmação)
6	Leitora de código de barras
7	Digitação com confirmação (Neste caso, deve ser apresentado uma tela para a confirmação dos dados coletados).

Retorno do campo questions.type

Tipo	Descrição
A	Alfabético.
AN	Alfanumérico especial (ans).
LN	Letras (não acentuadas) e números.
Nx	Numérico onde x é o número de casa decimais suportados.
Vx	Valor com x casas decimais.
S	Menu tipo Sim/Não.
Sc	Menu tipo Sim/Não condicional. Caso a entrada seja "Não", deve-se abortar a transação.
M	Menu livre. Neste caso, o campo <Display> terá o seguinte formato: o texto do menu deve estar separado por um caractere | das opções. As opções, por sua vez, devem constituir de índice e texto separados por :, enquanto uma opção é separada pela outra por ^. Ou seja: <Display> = <Texto Menu>|<opção 1>^<opção 2>^...^<opção N> Onde, <Texto Menu> = Texto de cabeçalho do menu (Ex: Escolha a bandeira do cartão) <Opção N> = <Índice>:<Texto da opção> (Ex: 1:Visa)
Mc	Menu livre com confirmação. Segue a regra do Menu Livre, onde: <Display> = <Texto Menu>|<Texto para confirmação>|<opção 1>^<opção 2>^...^<opção N>
M0	Menu livre tipo 0 (zero). (Não se aplica) Segue a regra do Menu Livre com confirmação, porém deve ser suprimida os índices de seleção do menu na exibição e selecionar apenas com as setas do POS. Exemplo de exibição de Menu Livre: 1 – Sim 2 – Não Exemplo de exibição de Menu Livre tipo 0: Sim Não

Serviço de listagem de dados da filial

Detalhes da chamada para recarga tipo normal

• Recurso: /v3/rechargebranches
• Método HTTP: GET
• Formato da requisição: query string
• Formato da resposta: JSON

Detalhes da chamada para recarga tipo others

• Recurso: /v3/rechargebranches/{nit}
• Método HTTP: PUT
• Formato da requisição: JSON
• Formato da resposta: JSON

Detalhes da chamada para recarga tipo invoice

• Recurso: /v3/rechargebranches/{nit}
• Método HTTP: PUT
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM
Authorization	Assinatura de autenticidade no formato Bearer {assinatura}. Saiba mais. Exemplo: Bearer hh39458f73hf45324765ft349h5f73t4h95f34. Este campo é obrigatório caso a transação tenha sido criada pelo processo de assinatura.	< 2000 AN	COND.

Exemplos

Abaixo estão exemplos de chamada do serviço de listagem de dados da filial utilizando a ferramenta cURL.

Listagem de dados da filial de recarga tipo normal

Requisição:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargebranches?nit=asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678&ddd=00&dealercode=1&generalhash=0000000000000000"
--verbose

Resposta:

{
   "list_branch_data_response":{
      "status":"NOV",
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0"
      },
      "sitef":{
         "code":"000"
      },
      "hashes":{
         "general":"09A9681D09A9681D"
      },
      "questions":[
         {
            "id":"5",
            "display":"Qual o nome do seu pai?",
            "rule":"3",
            "min":"5",
            "max":"30",
            "type":"i"
         }
      ],
      "general":[
         {
            "message":"MENSAGEM DE TESTE"
         }
      ],
      "categories":[
         {
            "code":"01",
            "description":"RECARGA",
            "amount_ranges":[
               {
                  "message":"MSG_FAIXA_1",
                  "amount_key":"7",
                  "bonus_in_percentage":"100",
                  "bonus":"50",
                  "payment_amount":"700",
                  "bonus_category":"1",
                  "expiry_date":"30",
                  "bonus_expiry_date":"15",
                  "min_amount":"500",
                  "max_amount":"10000"
               },
               {
                  "message":"MSG_FAIXA_2",
                  "amount_key":"8",
                  "bonus_in_percentage":"500",
                  "bonus_category":"2",
                  "min_amount":"1000",
                  "max_amount":"50000"
               }
            ],
            "fixed_amounts":[
               {
                  "bonus":"50",
                  "message":"MSG_FIXO_1",
                  "amount":"300",
                  "amount_key":"1",
                  "bonus_category":"2",
                  "bonus_in_percentage":"200",
                  "payment_amount":"10",
                  "expiry_date":"60",
                  "bonus_expiry_date":"15"
               },
               {
                  "message":"MSG_FIXO_2",
                  "amount":"1500",
                  "amount_key":"2",
                  "payment_amount":"30"
               },
               {
                  "message":"MSG_FIXO_3",
                  "amount":"2000",
                  "amount_key":"3"
               },
               {
                  "amount":"2200",
                  "amount_key":"4",
                  "expiry_date":"90"
               },
               {
                  "message":"MSG_FIXO_4",
                  "amount":"5000",
                  "amount_key":"6",
                  "expiry_date":"120"
               }
            ]
         },
         {
            "code":"02",
            "description":"SMS",
            "amount_ranges":[

            ],
            "fixed_amounts":[

            ]
         },
         {
            "code":"03",
            "description":"PRIMEIRA_RECARGA",
            "amount_ranges":[

            ],
            "fixed_amounts":[

            ]
         }
      ],
      "payment_methods":{
         "max":"4",
         "available":[
            "00",
            "01",
            "02:10",
            "03:10",
            "04:10",
            "05:10",
            "06:10"
         ]
      }
   }
}

Listagem de dados da filial de recarga tipo others

Requisição:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargebranches/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "list_branch_data_request":{
      "general_hash":"0000000000000000",
      "dealer":{
         "code":"901",
         "type_code":"03",
         "branch":{
            "code":"98006000000"
         }
      }
   }
}
--verbose

Resposta:

{
   "list_branch_data_response":{
      "status":"NOV",
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0"
      },
      "sitef":{
         "code":"000"
      },
      "hashes":{
         "general":"09A9681D09A9681D"
      },
      "questions":[

      ],
      "general":[

      ],
      "categories":[
         {
            "amount_ranges":[

            ],
            "fixed_amounts":[
               {
                  "amount":"50"
               },
               {
                  "amount":"300"
               },
               {
                  "amount":"400"
               },
               {
                  "amount":"500"
               },
               {
                  "amount":"600"
               },
               {
                  "amount":"700"
               },
               {
                  "amount":"800"
               },
               {
                  "amount":"900"
               },
               {
                  "amount":"1000"
               }
            ]
         }
      ],
      "payment_methods":{
         "max":"4",
         "available":[
            "00",
            "01",
            "02:10",
            "03:10",
            "04:10",
            "05:10",
            "06:10"
         ]
      }
   }
}

Listagem de dados da filial de recarga tipo invoice

Requisição:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargebranches/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "list_branch_data_request":{
      
      "dealer":{
         "code":"800",
         "branch":{
            "code":"80019000000"
         }
      },
      "answers": [
        {
        "code":"126",
        "description": "12340000000"
        }
      ]
     
   }
}

Resposta:

{
    "list_branch_data_response": {
        "status": "NOV",
        "esitef": {
            "message": "OK. Transaction successful.",
            "code": "0"
        },
        "sitef": {
            "message": "Transacao Aprovada",
            "code": "000"
        },
        "host": {
            "message": "Vivo SP Pos",
            "code": "00"
        },
        "acquirer": {
            "merchant_code": "302800000000000"
        },
        "authorization": {
            "authorizer_date": "0831",
            "authorizer_time": "153738",
            "host_usn": "000310003",
            "sitef_usn": "310003",
            "number": "000000"
        },
        "hashes": {
            "general": ""
        },
        "questions": [],
        "payment_methods": {
            "max": "4",
            "available": [
                "00",
                "01",
                "02:03-07-08-09-10-14",
                "03:03-07-08-09-10-14",
                "04:10",
                "05:10",
                "06:10"
            ]
        },
        "general": [],
        "categories": [
            {
                "amount_ranges": [],
                "fixed_amounts": []
            }
        ],
        "invoices": [
            {
                "expiry_date": "21082007                                                                                                                                                                                                                                                      ",
                "consumption_reference": "082007                                                                                                                                                                                                                                                        ",
                "bar_code": "84600000000633900800011200241676508075070821                                                                                                                                                                                                                  ",
                "amount": "6339                                                                                                                                                                                                                                                          ",
                "message": "Boleto Parcial Credito Manual                                                                                                                                                                                                                                 "
            },
            {
                "expiry_date": "25072007                                                                                                                                                                                                                                                      ",
                "consumption_reference": "072007                                                                                                                                                                                                                                                        ",
                "bar_code": "84660000001866000800011200243533509074070925                                                                                                                                                                                                                  ",
                "amount": "18660                                                                                                                                                                                                                                                         ",
                "message": "Boleto Parcial Credito Manual                                                                                                                                                                                                                                 "
            },
            {
                "expiry_date": "25092007                                                                                                                                                                                                                                                      ",
                "consumption_reference": "092007                                                                                                                                                                                                                                                        ",
                "bar_code": "84650000000442500800011000217664609076070925                                                                                                                                                                                                                  ",
                "amount": "4425                                                                                                                                                                                                                                                          ",
                "message": "Boleto Parcial Credito Manual                                                                                                                                                                                                                                 "
            },
            {
                "expiry_date": "10092007                                                                                                                                                                                                                                                      ",
                "consumption_reference": "082007                                                                                                                                                                                                                                                        ",
                "bar_code": "84610000001385700800011200474416708073070910                                                                                                                                                                                                                  ",
                "amount": "13857                                                                                                                                                                                                                                                         ",
                "message": "Boleto Parcial Credito Manual                                                                                                                                                                                                                                 "
            },
            {
                "expiry_date": "25082007                                                                                                                                                                                                                                                      ",
                "consumption_reference": "082007                                                                                                                                                                                                                                                        ",
                "bar_code": "84650000001165200800011200243533508078070825                                                                                                                                                                                                                  ",
                "amount": "11652                                                                                                                                                                                                                                                         ",
                "message": "Boleto Parcial Credito Manual                                                                                                                                                                                                                                 "
            },
            {
                "expiry_date": "21092007                                                                                                                                                                                                                                                      ",
                "consumption_reference": "092007                                                                                                                                                                                                                                                        ",
                "bar_code": "84690000019276900800011200245374209078070921                                                                                                                                                                                                                  ",
                "amount": "192769                                                                                                                                                                                                                                                        ",
                "message": "Boleto Parcial Credito Manual                                                                                                                                                                                                                                 "
            }
        ],
        "tv_package_subscription_codes": [],
        "invoice_holder_name": "",
        "echo": "12340000000"
    }
}

Parâmetros de requisição para recarga tipo normal

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de listagem de dados da filial para recarga tipo normal:

Parâmetro	Descrição	Formato	Obrigatório
nit	Identificação da transação de recarga no e-SiTef	= 64 AN	SIM
ddd	Código DDD do telefone	= 2 N	SIM
dealercode	Código da concessionária/operadora	< 3 N	SIM
generalhash	Código de identificação da versão da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros). Caso a loja não tenha feito uma recarga anteriormente ou não tenha guardado um valor de generalhash previamente recebido do e-SiTef, o valor: 0000000000000000 pode ser passado ao e-SiTef. Este campo permite ao lojista saber se ocorreu alteração nos dados da recarga. Isso porque se ocorreu alguma alteração na tabela, o generalhash retornado será diferente do generalhash que o lojista possui. Neste caso, é aconselhável que o lojista efetue as consultas e atualize os valores das operadoras de recarga em sua aplicação.	= 16 AN	NÃO

Parâmetros de requisição para recarga tipo others

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de listagem de dados da filial para recarga tipo others:

Parâmetro	Descrição	Formato	Obrigatório
nit	Identificação da transação de recarga no e-SiTef. Atenção: Este campo vai na URL da requisição e não no corpo.	= 64 AN	SIM
ddd	Código DDD do telefone	= 2 N	NÃO
general_hash	Código de identificação da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros).	= 16 AN	NÃO
	dealer Informações da concessionária/operadora. Estas informações são retornadas na chamada de listagem de concessionárias.
code	Código da concessionária/operadora	< 3 N	SIM
type_code	Código do tipo da concessionária/operadora	< 3 N	SIM
	dealer.branch Informações sobre a filial da concessionária
code	Código da filial da concessionária/operadora	< 11 N	SIM
	answers[] Este campo agrega uma lista de respostas. Envio obrigatório caso perguntas tenham sido recebidas na listagem de concessionárias.
code	Código da pergunta a ser respondida (questions.id da resposta da listagem de concessionárias)	< 20 AN	COND.
description	Resposta da pergunta	< 200 AN	COND.

Parâmetros de requisição para recarga tipo invoice

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de listagem de dados da filial para recarga tipo invoice:

Parâmetro	Descrição	Formato	Obrigatório
nit	Identificação da transação de recarga no e-SiTef. Atenção: Este campo vai na URL da requisição e não no corpo.	= 64 AN	SIM
general_hash	Código de identificação da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros).	= 16 AN	NÃO
	dealer Informações da concessionária/operadora. Estas informações são retornadas na chamada de listagem de concessionárias.
code	Código da concessionária/operadora	< 3 N	SIM
	dealer.branch Informações sobre a filial da concessionária
code	Código da filial da concessionária/operadora	< 11 N	SIM
	answers[] Este campo agrega uma lista de respostas. Envio obrigatório caso perguntas tenham sido recebidas na listagem de concessionárias.
code	Código da pergunta a ser respondida (questions.id da resposta da listagem de concessionárias)	< 20 AN	COND.
description	Resposta da pergunta	< 200 AN	COND.

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de listagem de dados da filial:

Parâmetro	Descrição	Formato
status	Status da transação de recarga no e-SiTef. Saiba mais.	= 3 AN
invoice_holder_name	Nome do titular da fatura	< 70 AN
echo	Campo a ser reenviado para recargas do tipo invoice	< 128 AN
resubmit_transaction	Indica que esta transação deve ser reenviada com o código de assinatura de TV selecionada.	< 5 AN
	esitef
code	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	sitef
code	Código de resposta retornado pela autorizadora	< 4 AN
	hashes
general	Código de identificação da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros).	= 16 AN
	questions[] Este campo agrega uma lista de perguntas para confirmação positiva. As perguntas retornadas devem, obrigatoriamente, ser respondidas pelo usuário e ter suas respostas enviadas ao e-SiTef no passo seguinte (listar dados da filial).
id	Código de identificação da pergunta	< 20 AN
display	Texto da pergunta a ser apresentada	< 180 AN
rule	Indica onde os dados devem ser coletados. Saiba mais.	< 2 AN
min	Indica o tamanho mínimo da resposta	< 4 N
max	Indica o tamanho máximo da resposta	< 5 N
type	Indica o tipo de dados da resposta a ser coletada. Saiba mais.	< 3 AN
min_value	Indica o valor mínimo da resposta	< 3 N
max_value	Indica o valor máximo da resposta	< 3 N
	general Este campo agrega uma lista de características gerais dentre as filiais.
message	Mensagem geral.	< 101 AN
	categories Este campo agrega uma lista de categorias.
code	Código da categoria	< 5 AN
description	Texto descritivo da categoria	< 100 AN
	categories.amount_ranges Este campo agrega uma lista de faixas de valores.
message	Mensagem informativa da recarga	< 100 AN
amount_key	Chave do valor da recarga (a ser enviada ao efetuar recarga).	< 5 AN
bonus_in_percentage	Bônus de recarga em percentual do valor de face (com 2 casas decimais: ex.: 1% = 100).	< 5 N
bonus	Bônus de recarga.	< 12 N
payment_amount	Custo da recarga.	< 12 N
bonus_category	Categoria do bônus (deve ser um dos valores de categories.code).	< 5 AN
expiry_date	Período de validade (em dias).	< 4 N
bonus_expiry_date	Período de validade do bônus (em dias).	< 4 N
min_amount	Valor mínimo da faixa, em centavos de real.	< 12 N
max_amount	Valor máximo da faixa, em centavos de real.	< 12 N
	categories.fixed_amounts Este campo agrega uma lista de valores fixos.
message	Mensagem informativa da recarga	< 100 AN
amount_key	Chave do valor da recarga (a ser enviada ao efetuar recarga).	< 5 AN
bonus_in_percentage	Bônus de recarga em percentual do valor de face (com 2 casas decimais: ex.: 1% = 100).	< 5 N
bonus	Bônus de recarga.	< 12 N
payment_amount	Custo da recarga.	< 12 N
bonus_category	Categoria do bônus (deve ser um dos valores de categories.code).	< 5 AN
expiry_date	Período de validade (em dias).	< 4 N
bonus_expiry_date	Período de validade do bônus (em dias).	< 4 N
amount	Valor de face da recarga, em centavos de real.	< 12 N
	payment_methods
max	Número máximo de formas de pagamento	< 2 N
available	Este campo agrega uma lista de formas de pagamento disponíveis e seus detalhes. Saiba mais.	< 200 AN
	host
message	Nome da instituição	< 16 AN
code	Código de resposta da instituição	< 12 AN
	acquirer
merchant_code	Código do estabelecimento	< 15 N
	authorization
number	Número autorização	< 6 AN
sitef_usn	Nsu do Sitef	< 6 N
host_usn	Nsu do host	< 12 N
authorizer_time	Hora da resposta do autorizador HHMMSS	= 6 N
authorizer_date	Data da resposta do autorizador MMDD	= 4 N
	invoices Este objeto contém campos retornados para pagamento sem fatura (recarga tipo invoice).
expiry_date	Data de vencimento da fatura escolhida em formato AAAAMMDD	= 8 N
consumption_reference	Data de referência na fatura escolhida em formato MMAAAA	= 6 N
bar_code	Código de barras da fatura escolhida	= 48 N
amount	Valor da fatura escolhida	< 12 N
message	Mensagem geral	< 64 AN

Retorno do campo payment_methods.available

O campo payment_methods.available pode conter um ou mais dados para leitura. Cada dado lido possui o seguinte formato:

TipoN:IDColetaN1-IDColetaN2-IDColetaN3-...-IDColetaNn

Onde:

TipoN: indica a forma de pagamento permitida.

Tipo	Descrição
00	Dinheiro
01	Cheque
02	TEF Débito
03	TEF Crédito
10	Ticket Eletrônico
11	Ticket Papel
12	Carteira Digital
13	PIX
50	TEF Cartão
99	Outras Formas

Observações:

• Caso não existam campos a serem coletados, será retornado apenas o campo TipoN.
• Futuramente, novas formas de pagamento podem ser acrescentadas a esta tabela. Caso o PDV desconheça uma destas novas formas, deve estar preparado para "pular" apenas esta forma, sem afetar seu processamento.
• A forma de pagamento "TEF Cartão" (tipo 50) é utilizada para agrupar, em um único tipo, todas as formas de pagamento que envolva cartões (tipos 02 e 03).

IDColetaNn: indica o ID do campo que o PDV deve coletar e enviar ao SiTef.

ID	Descrição	Significado e Formato
01	Tipo de Entrada do Cheque	0: leitura de CMC-7 1: digitação da primeira linha do cheque 2: digitação do CMC-7
02	Dados do Cheque	- CMC-7 lido ou digitado, ou - digitação da primeira linha do cheque, com o seguinte formato: Compensação (3), Banco (3), Agência (4), C1 (1), Conta Corrente (10), C2 (1), Número do Cheque (6) e C3 (1), nesta ordem.
03	Rede Destino	Identificação do autorizador da transação de TEF (conforme tabela de Rede Destino da especificação do SiTef).
04	NSU do SiTef da transação de TEF	Identificação da transação de TEF no SiTef.
05	Data do SiTef da transação de TEF (No momento, ainda não utilizado)	Data da transação de TEF no SiTef, no formato DDMMAAAA.
06	Código da Empresa da transação de TEF	Código do SiTef para a Empresa utilizada na transação de TEF.
07	NSU do Host da transação de TEF	Identificação da transação de TEF no Host.
08	Data do Host da transação de TEF	Data da transação de TEF no Host, no formato DDMMAAAA.
09	Código de Origem da transação de TEF	Código de Estabelecimento da transação de TEF.
10	Dados de confirmação da transação de TEF.	Campo 9 retornado na realização da transação de TEF.
11	Código de Autorização da transação de TEF	Código de Autorização do Host para a transação de TEF.
12	Valor do Cheque	Valor Total do Cheque. Um mesmo cheque pode ser usado para pagar mais de uma conta.
13	Rede Destino – Complemento	Complemento do ID 03
14	Bandeira do Cartão	Bandeira do cartão utilizado na transação de TEF.
15	Tipo Pagamento	00 – a vista 01 – Pré-datado 02 – Parcelado pelo estabelecimento 03 - Parcelado pela administradora

Observações:

O campo de ID 13, diferente dos demais, não indica um campo que deve ser coletado. Este campo funciona apenas como um complemento ao campo de ID 03, enviando a lista de redes destino permitido, no seguinte formato:

13(Rede1,Rede2,...,RedeN)

Ou seja, caso apenas o campo de ID 03 esteja presente, deve ser coletada a rede destino, sem nenhuma restrição quanto às redes que podem pagar uma determinada transação (Exemplo: recarga). No entanto, caso estejam presentes os campos de ID 03 e 13, o primeiro indica que deve ser coletada a rede destino, enquanto o segundo indica quais as redes destino são permitidas para efetuar o pagamento da recarga.

Além disso, como a coleta foi indicada pelo ID 03, o PDV deve enviar a rede destino ao SiTef também por meio deste ID (e não pelo ID 13).

Futuramente, novos campos podem ser acrescentados a esta tabela. Caso o PDV desconheça um destes novos campos, deve estar preparado para "pular" apenas este campo, sem afetar seu processamento.

Serviço de efetivação de recarga

Detalhes da chamada

• Recurso: /v3/recharge/{nit}
• Método HTTP: PUT
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM
Authorization	Assinatura de autenticidade no formato Bearer {assinatura}. Saiba mais. Exemplo: Bearer hh39458f73hf45324765ft349h5f73t4h95f34. Este campo é obrigatório caso a transação tenha sido criada pelo processo de assinatura.	< 2000 AN	COND.

Exemplos

Abaixo estão exemplos de chamada do serviço de efetivação de recarga utilizando a ferramenta cURL.

Recarga tipo normal com pagamento

Requisição:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "do_recharge_request":{
      "hashes":{
         "general":"0000000000000000"
      },
      "dealer":{
         "code":"1",
         "type_code":"03",
         "branch":{
            "code":"98006000000"
         }
      },
      "phone":{
         "ddd":"11",
         "number":"123456789"
      },
      "amount":"3000",
      "amount_key":"3",
      "used_payment_methods":[
         "11",
         "12"
      ],
      "answers":[
         {
            "code":"1",
            "description":"resposta"
         },
         {
            "code":"2",
            "description":"resposta2"
         }
      ],
      "terminal_type":"03",
      "cpf":"8298374982374",
      "cnpj":"123121333000123",
      "zip_code":"01310100",
      "payment":{
         "amount":"12",
         "authorizer_id":"1",
         "customer_id":"12341234",
         "merchant_key":"OIAUSWHFN012375901J23047FNN00UYWHN0R871Y2ND87",
         "installment":{
            "number":"2",
            "type":"4"
         },
         "card":{
            "number":"1111111111111111",
            "token":"",
            "security_code":"123",
            "expiry_date":"1222"
         },
         "extra_param":[
            {
               "key":"CRIPTO",
               "value":"1"
            }
         ]
      }
   }
}
--verbose

Resposta:

{
   "do_recharge_response":{
      "status":"PPC",
      "order_id":"12344231",
      "merchant_usn":"5123",
      "esitef":{
         "message":"OK",
         "code":"0",
         "usn":"123456789012345"
      },
      "sitef":{
         "message":"OK",
         "code":"0"
      },
      "host":{
         "message":"OK",
         "code":"0"
      },
      "acquirer":{
         "branch_code":"cod filial",
         "merchant_code":"codigoEstab"
      },
      "authorization":{
         "confirmation_data":"000033333",
         "authorizer_date":"20150514",
         "authorizer_time":"1100",
         "host_usn":"11122",
         "sitef_usn":"333",
         "number":"332234"
      },
      "customer":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do cliente"
      },
      "merchant":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do estabelecimento"
      },
      "payment_methods":{
         "max":4,
         "available":[
            {
               "name":"dinheiro"
            },
            {
               "name":"cheque"
            }
         ]
      },
      "payment":{
         "status":"PPC",
         "amount":"12",
         "type":"C",
         "esitef":{
            "usn":"098765432109876",
            "date":"12/12/2012 12:12"
         },
         "customer":{
            "receipt":"nwiugrnboinb APROVADO via do cliente"
         },
         "merchant":{
            "receipt":"nwiugrnboinb APROVADO via do estabelecimento "
         },
         "authorizer_id":"1",
         "acquirer":"CIELO",
         "authorization":{
            "number":"163457212",
            "sitef_usn":"456456",
            "host_usn":"654654",
            "tid":"7334312a2",
            "eci":"fr3u214wf71",
            "sitef_date":"12122012"
         },
         "analysis":{
            "status":"PEN",
            "code":"0",
            "message":"aprovado"
         },
         "extra_param":[
            {
               "key":"CRIPTO",
               "value":"1"
            }
         ],
         "sitef":{
            "code":"000"
         }
      }
   }
}

Recarga tipo normal sem pagamento

Requisição:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "do_recharge_request":{
      "dealer":{
         "code":"1"
      },
      "phone":{
         "ddd":"11",
         "number":"123456789"
      },
      "amount":"3000"
   }
}
--verbose

Resposta:

{
   "do_recharge_response":{
      "status":"PPC",
      "order_id":"12344231",
      "merchant_usn":"5123",
      "esitef":{
         "message":"OK",
         "code":"0",
         "usn":"123456789012345"
      },
      "sitef":{
         "message":"OK",
         "code":"0"
      },
      "host":{
         "message":"OK",
         "code":"0"
      },
      "acquirer":{
         "branch_code":"cod filial",
         "merchant_code":"codigoEstab"
      },
      "authorization":{
         "confirmation_data":"000033333",
         "authorizer_date":"20150514",
         "authorizer_time":"1100",
         "host_usn":"11122",
         "sitef_usn":"333",
         "number":"332234"
      },
      "customer":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do cliente"
      },
      "merchant":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do estabelecimento"
      },
      "payment_methods":{
         "max":4,
         "available":[
            {
               "name":"dinheiro"
            },
            {
               "name":"cheque"
            }
         ]
      }
   }
}

Recarga tipo others

Requisição:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "do_recharge_request":{
      "dealer":{
         "code":"901",
         "type_code":"03",
         "branch":{
            "code":"98006000000"
         }
      },
      "amount":"3000"
   }
}
--verbose

Resposta:

{
   "do_recharge_response":{
      "status":"PPC",
      "order_id":"12344231",
      "merchant_usn":"5123",
      "esitef":{
         "message":"OK",
         "code":"0",
         "usn":"123456789012345"
      },
      "sitef":{
         "message":"OK",
         "code":"0"
      },
      "host":{
         "message":"OK",
         "code":"0"
      },
      "acquirer":{
         "branch_code":"cod filial",
         "merchant_code":"codigoEstab"
      },
      "authorization":{
         "confirmation_data":"000033333",
         "authorizer_date":"20150514",
         "authorizer_time":"1100",
         "host_usn":"11122",
         "sitef_usn":"333",
         "number":"332234"
      },
      "customer":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do cliente"
      },
      "merchant":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do estabelecimento"
      }
   }
}

Recarga tipo invoice

Requisição:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "do_recharge_request":{
      "hashes":{
         "general":"85E791AD85E791AD"
      },
      "dealer":{
         "code":"800",
         "branch":{
            "code":"80019000000"
         }
      },
      "amount":"6339",
      "terminal_type":"04",
      "cpf":"12312312312",
      "cnpj":"11110110000101",
      "zip_code":"12345678",
      "invoice":{
         "bar_code":"88888888888888888888888888888888888888888888",
         "description":"Boleto Parcial Credito Manual",
         "expiry_date":"21082007",
         "reference_data":"082007",
         "echo":"12340000000"
      }
   }
}
--verbose

Resposta:

{
   "do_recharge_response":{
      "status":"PPC",
      "order_id":"31045431771",
      "merchant_usn":"2047986911",
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0",
         "usn":"200831056294572"
      },
      "sitef":{
         "message":"Transacao Aprovada",
         "code":"000"
      },
      "acquirer":{
         "merchant_code":"302800000000000"
      },
      "authorization":{
         "confirmation_data":"0831310011A6",
         "authorizer_date":"0831",
         "authorizer_time":"165459",
         "host_usn":"000310011",
         "sitef_usn":"310011",
         "number":"000000"
      },
      "customer":{
         "receipt":"----- COMPROVANTE -----"
      },
      "merchant":{
         "receipt":"----- COMPROVANTE -----"
      },
      "payment_methods":{
         "max":"4",
         "available":[
            {
               "name":"00"
            },
            {
               "name":"01"
            },
            {
               "name":"02:03-07-08-09-10-14"
            },
            {
               "name":"03:03-07-08-09-10-14"
            },
            {
               "name":"04:10"
            },
            {
               "name":"05:10"
            },
            {
               "name":"06:10"
            }
         ]
      },
      "hashes":{
         "general":"85E791AD85E791AD",
         "wallet":""
      },
      "send_payment_methods":"true"
   }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de efetivação de recarga:

Parâmetro	Descrição	Formato	Obrigatório
nit	Identificação da transação de recarga no e-SiTef	= 64 AN	SIM
amount	Valor da recarga, em centavos	< 12 N	SIM
amount_key	Código do valor da recarga	< 10 AN	NÃO
terminal_type	01 - PDV 02 - TU 03 - TAS 04 - Internet 05 - POS-Sitef/POS	= 2 N	NÃO
cpf	CPF do cliente	< 20 AN	NÃO
cnpj	CNPJ do cliente	< 20 AN	NÃO
zip_code	CEP do cliente	< 9 AN	NÃO
	hashes
general	Código de identificação da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros).	= 16 AN	NÃO
	dealer
code	Código da concessionária/operadora	< 3 N	SIM
type_code	Código do tipo concessionária/operadora	< 2 N	SIM
	dealer.branch
code	Código da filial da concessionária/operadora. Obrigatório apenas para recarga tipo others.	11 N	COND.
	phone
phone.ddd	Código DDD do telefone. Obrigatório apenas para recarga tipo normal.	= 2 N	COND.
phone.number	Número do telefone. Obrigatório apenas para recarga tipo normal.	< 9 N	COND.
	answers[] Este campo agrega uma lista de respostas. Obrigatório caso perguntas tenham sido recebidas na listagem de dados da filial.
code	Código da pergunta a ser respondida	< 20 AN	COND.
description	Resposta da pergunta	< 200 AN	COND.
	invoice Este objeto contém campos obrigatórios para pagamento sem fatura (recarga tipo invoice).
bar_code	Código de barras da fatura escolhida.	= 48 N	SIM para tipo invoice
description	Descrição da fatura escolhida.	< 64 AN	SIM para tipo invoice
expiry_date	Data de validade da fatura escolhida em formato DDMMAAAA.	= 8 N	SIM para tipo invoice
reference_data	Dados de referência da fatura escolhida.	< 32 AN	SIM para tipo invoice
echo	Valor do campo echo recebido na listagem de dados da filial.	< 11 N	SIM para tipo invoice
	payment Este elemento somente deve ser enviado caso se deseje efetuar um pagamento atrelado à recarga.* Atenção: O pagamento é permitido apenas no tipo de recarga normal. Para o tipo de recarga others a transação será invalidada.
amount	Valor do pagamento, em centavos	< 12 N	SIM*
authorizer_id	Código da autorizadora no e-SiTef. Saiba mais.	< 5 N	SIM*
customer_id	Documento de identidade do comprador. Use apenas caracteres alfanuméricos	< 20 AN	NÃO
merchant_key	Chave da loja cadastrada no e-SiTef. Deve ser a mesma loja utilizada para efetuar a recarga.	< 80 AN	SIM*
	payment.installment
number	Número de parcelas	< 2 N	SIM*
type	Tipo de financiamento do parcelamento: 3 - parcelamento com juros da administradora do cartão, 4 - parcelamento realizado pela loja e sem juros. (Adotar este valor como padrão/default para transações à vista) 6 - parcelamento com juros da administradora (IATA) 7 - parcelamento realizado pela loja e sem juros (IATA)	= 1 N	SIM*
	payment.card
number	Número do cartão.	< 19 N	SIM*
token	Token do cartão armazenado no e-SiTef.	= 88 AN	SIM*
security_code	Código de segurança do cartão. Campo opcional, se enviado, será utilizado o código de empresa SiTef principal, não o de recorrência (que não pede código de segurança). Sua obrigatoriedade depende do contrato firmado com as Adm. de cartão.	< 5 N	COND.
expiry_date	Data de vencimento no formato MMAA	= 4 N	SIM*
	payment.extra_param[] Este campo agrega uma lista de parâmetros extras.
key	Chave do parâmetro extra	N/A	NÃO
value	Valor do parâmetro extra	N/A	NÃO
	used_payment_methods[] Formas de pagamento utilizadas. Este campo agrega uma lista de valores que devem ser enviados conforme descrito no capítulo abaixo.

Envio do campo used_payment_methods

A loja deve utilizar o próprio campo used_payment_methods para indicar ao e-SiTef quais formas de pagamento foram utilizadas para pagar uma determinada transação, como por exemplo uma recarga.

A quantidade de dados a serem gravadas no campo used_payment_methods é limitada pelo campo payment_methods.max. Se, por exemplo, foi recebido o valor 3 no campo payment_methods.max, então a loja só poderá gravar 3 informações no campo used_payment_methods.

Para cada forma de pagamento utilizada deve ser gravado um elemento (dado) no campo used_payment_methods. O dado a ser gravado no campo used_payment_methods possui o seguinte formato:

TipoN:ValorN:IDColetaN1:DadoColetaN1-IDColetaN2:DadoColetaN2-...-IDColetaNn:DadoColetaNn

Onde:

• TipoN: indica a forma de pagamento utilizada (conforme tabela já apresentada acima).
• ValorN: indica o valor utilizado com esta forma de pagamento, com duas casas decimais, sem a vírgula.
• IDColetaNn: indica o ID do campo que foi coletado pela loja (conforme tabela já apresentada acima).
• DadoColetaNn: indica o conteúdo coletado pela loja para este campo.

Observações:

Se para uma determinada forma de pagamento nenhum campo deva ser coletado pela loja, o campo used_payment_methods deve ser valorizado com os seguintes dados: TipoN:ValorN.

A consistência dos valores (soma das várias formas de pagamento utilizadas, totalizando o valor da transação realizada) deve ser feita pela loja, sendo que o e-SiTef só utilizará os valores da maneira como foram enviados.

Exemplo

Vamos supor que na execução de uma transação de recarga, a loja obteve o valor 2 na leitura do campo payment_methods.max e os seguintes valores do campo used_payment_methods:

00
02:03-07-10-13(5,125)
03:10

O valor 2 recebido no campo payment_methods.max, indica à loja que o mesmo só pode fazer o pagamento da recarga com no máximo 2 formas de pagamento diferentes.

Supondo que a loja realizou o pagamento da recarga da seguinte maneira: R$ 30,00 em dinheiro e R$ 20,00 com cartão de débito processados pela rede adquirente Rede (Rede Destino = 5; NSU do Host = 123456789; Dados de confirmação = 0520200001A6). Neste caso, o campo used_payment_methods deverá ser valorizado com os seguintes dados:

00:3000
02:2000:03:5-07:123456789-10:0520200001A6

Envio de dados do cartão para pagamento

Caso se deseje enviar o token de cartão armazenado no e-SiTef, os demais dados de cartão (card.number, card.expiry_date) não serão considerados.

Caso se deseje enviar os dados abertos do cartão, o token não deve ser enviado.

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de efetivação de recarga:

Parâmetro	Descrição	Formato
status	Status da transação de recarga no e-SiTef. Saiba mais.	= 3 AN
order_id	Código do pedido gerado pela loja.	< 20 AN
merchant_usn	NSU da transação gerado pela loja.	< 12 N
tv_package_subscription_codes[]	Códigos de assinaturas de pacotes de TV.	< 32 AN
resubmit_transaction	Se este campo receber o valor true, a loja deve reenviar a requisição de efetivação de recarga com o campo answers preenchido da seguinte maneira: "answers":[{"code":"126","description":"<um dos códigos recebidos no campo tv_package_subscription_codes>"}] Neste caso, o status da transação será retornado como AGU. Este fluxo só é possível na realização de Recarga TV.	T/F
send_payment_methods	Flag que indica que as formas de pagamento devem ser enviadas na próxima transação. Terá o valor true caso positivo.	< 5 AN
	esitef
code	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
usn	NSU da transação de recarga no e-SiTef	= 15 N
	sitef
code	Código de resposta do SiTef	= 3 AN
message	Mensagem de resposta do SiTef	< 500 AN
	host
code	Código de resposta retornado pela autorizadora	< 4 AN
message	Mensagem retornada pela autorizadora	< 64 AN
	acquirer
branch_code	Código da filial da recarga	< 5 N
merchant_code	Código da loja cadastrada no adquirente	< 15 N
	authorization
confirmation_data	Código da confirmação	< 128 AN
authorizer_date	Data da autorização na autorizadora no formato MMDD	= 4 N
authorizer_time	Horário da autorização na autorizadora no formato HHmmSS	= 6 N
host_usn	NSU do Host	< 20 N
sitef_usn	NSU do SiTef	< 10 N
number	Número da autorização na autorizadora	< 6 N
	customer
total_copies	Número de vias do comprovante do cliente	< 2 N
receipt	Comprovante do cliente	< 4000 AN
	merchant
total_copies	Número de vias do comprovante do estabelecimento	< 2 N
receipt	Comprovante do estabelecimento	< 4000 AN
	hashes
general	Código de identificação da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros).	= 16 AN
wallet	Hash das carteiras digitais.	< 32 AN
	payment_methods
max	Número máximo de formas de pagamento	< 2 N
	payment_methods.available[] Este campo agrega uma lista de formas de pagamento disponíveis.
name	Nome da forma de pagamento disponível. Saiba mais.	< 200 AN
	payment Este elemento somente é retornado caso um pagamento atrelado à recarga tenha sido enviado.
status	Status da transação de pagamento no e-SiTef. Saiba mais.	= 3 AN
amount	Valor do pagamento, o mesmo enviado na criação da transação de pagamento.	< 12 AN
type	Tipo do pagamento da autorizadora escolhida: B = boleto C = crédito D = débito P = cartão crédito Private Label T = tranferência bancária G = cartão gift O = outros meios de pagamentos	= 1A
authorizer_id	Id da autorizadora no e-SiTef onde o pagamento foi feito	< 5 N
acquirer	Tipo de pagamento	< 50 AN
	payment.esitef
usn	NSU do e-SiTef	< 15 AN
date	Data do pagamento no formato DD/MM/AAAA hh:mm no e-SiTef.	< 19A
	payment.sitef
code	Código de resposta retornado pelo SiTef	= 3 AN
	payment.customer
receipt	Comprovante do pagamento (via cliente)	< 4000 AN
	payment.merchant
receipt	Comprovante do pagamento (via estabelecimento)	< 4000 AN
	payment.authorization
number	Número de autorização do pagamento	< 6 AN
sitef_usn	NSU do SiTef	< 15 AN
host_usn	NSU da autorizadora	< 15 AN
tid	ID da transação na autorizadora, retornado por alguns tipos de pagamento.	< 40 AN
eci	Eletronic commerce indicator retornado por alguns tipos de pagamento.	< 3 AN
sitef_date	Data do pagamento no formato DD/MM/AAAA hh:mm no SiTef.	< 19 AN
	payment.analysis
status	Status da transação na instituição de análise.	= 3 AN
code	Código de resposta da análise de risco.	< 4 AN
message	Mensagem de resposta da análise de risco.	< 100 AN
	payment.extra_param[]
key	Chave do parâmetro extra	N/A
value	Valor do parâmetro extra	N/A

Importante:

No caso de recargas de outros produtos (others) que envolvam pins (por exemplo, pins de jogos), o pin será retornado uma única vez, como parte do campo payment.customer.receipt. Por se tratar de um campo sensível, o e-SiTef não o armazena, de forma que consultas de status posteriores não devolverão o pin. Caso ocorra algum problema após o retorno do pin pelo e-SiTef, o pin não poderá ser recuperado e será necessário gerar outro.

Serviço de confirmação de recarga

Detalhes da chamada

• Recurso: /v3/recharge/{nit}
• Método HTTP: PUT
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM
Authorization	Assinatura de autenticidade no formato Bearer {assinatura}. Saiba mais. Exemplo: Bearer hh39458f73hf45324765ft349h5f73t4h95f34. Este campo é obrigatório caso a transação tenha sido criada pelo processo de assinatura.	< 2000 AN	COND.

Exemplos

Abaixo está um exemplo de chamada do serviço de confirmação de recarga utilizando a ferramenta cURL.

Requisição:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "confirm_recharge_request":{
      "confirm":"true",
      "merchant_key":"AOSDJF210349H3R0374H874H3T7AHG90SF"
   }
}
--verbose

Resposta:

{
   "confirm_recharge_response":{
      "esitef":{
         "message":"OK",
         "code":"0"
      },
      "status":"CON",
      "payment":{
         "status":"CON"
      }
   }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de confirmação de recarga:

Parâmetro	Descrição	Formato	Obrigatório
confirm	Deve receber o valor true caso se deseje confirmar a recarga e o pagamento atrelado (caso exista). Deve receber o valor false para o desfazimento da recarga e do pagamento atrelado (caso exista).	< 5 AN	SIM
merchant_key	Chave da loja no e-SiTef utilizada na recarga.	< 80 AN	SIM
used_payment_methods[]	Formas de pagamento utilizadas. O envio deste campo deve seguir as mesmas regras descritas no capítulo correspondente da efetivação de recarga. No caso de recarga TIM, é obrigatório enviar esse campo caso não deseje que seja assumido o tipo de pagamento “Outras formas” (código 99).		COND.

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de confirmação de recarga:

Parâmetro	Descrição	Formato
status	Status da transação de recarga no e-SiTef. Saiba mais.	= 3 AN
	esitef
code	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	payment
status	Status da transação de pagamento no e-SiTef, caso exista. Saiba mais.	= 3 AN

Serviço de consulta de recarga

Essa chamada permite que a loja consulte o status de uma transação de recarga e pagamento atrelado (caso exista) no e-SiTef, a qualquer momento dentro do fluxo, após criar uma recarga.

Atenção:

A consulta de status da transação no e-SiTef NÃO efetua uma consulta do status da transação no adquirente / autorizador. Este serviço retorna o status da transação na base de dados do e-SiTef.

Exemplo: Caso uma transação de pagamento seja confirmada no e-SiTef, mas seja estornada via telefone diretamente no adquirente / autorizador, este estorno não será necessariamente refletido no serviço de consulta de status da transação do e-SiTef.

Detalhes da chamada

• Recurso: /v3/recharge/{nit}
• Método HTTP: GET
• Formato da requisição: query string
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
Authorization	Assinatura de autenticidade no formato Bearer {assinatura}. Saiba mais. Exemplo: Bearer hh39458f73hf45324765ft349h5f73t4h95f34. Este campo é obrigatório caso a transação tenha sido criada pelo processo de assinatura.	< 2000 AN	COND.

Exemplos

Abaixo está um exemplo de chamada do serviço de consulta de recarga utilizando a ferramenta cURL.

Requisição:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678/?merchantkey=ASDFGHJK12345678ASDFGHJK12345678"
--verbose

Resposta:

{
   "get_status_recharge_response":{
      "status":"CON",
      "esitef":{
         "message":"OK",
         "code":"0"
      },
      "authorizers":[
         {
            "name":"sitef",
            "message":"textoExibicao",
            "code":"codigoRespSitef"
         },
         {
            "name":"nome operadora (186)",
            "message":"OK",
            "code":"196"
         }
      ],
      "acquirer":{
         "branch_code":"cod filial",
         "merchant_code":"codigoEstab"
      },
      "authorization":{
         "confirmation_data":"000033333",
         "authorizer_date":"20150514",
         "authorizer_time":"1100",
         "host_usn":"11122",
         "sitef_usn":"333",
         "number":"332234"
      },
      "customer":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA mimimim cliente whiskas sache"
      },
      "merchant":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA mimimim estabelecimento lorem ipsum"
      },
      "payment_methods":{
         "max":2,
         "available":[
            {
               "name":"dinheiro"
            },
            {
               "name":"cheque"
            }
         ]
      },
      "payment":{
         "status":"PPC",
         "amount":"12",
         "type":"C",
         "esitef":{
            "usn":"098765432109876",
            "date":"12/12/2012 12:12"
         },
         "customer":{
            "receipt":"nwiugrnboinbAPROVADOaoisuerhn"
         },
         "merchant":{
            "receipt":"nwiugrnboinbAPROVADOaoisuerhn"
         },
         "authorizer_id":"1",
         "acquirer":"CIELO",
         "authorization":{
            "number":"163457212",
            "sitef_usn":"456456",
            "host_usn":"654654",
            "tid":"7334312a2",
            "eci":"fr3u214wf71",
            "sitef_date":"12122012"
         },
         "analysis":{
            "status":"PEN",
            "code":"0",
            "message":"hahaha"
         },
         "extra_param":[
            {
               "key":"CRIPTO",
               "value":"1"
            }
         ],
         "sitef":{
            "code":"000"
         }
      }
   }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de consulta de recarga:

Parâmetro	Descrição	Formato	Obrigatório
nit	Identificação da transação de recarga no e-SiTef	= 64 AN	SIM
merchantkey	Chave da loja no e-SiTef utilizada na recarga.	< 80 AN	SIM

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de consulta de recarga:

Parâmetro	Descrição	Formato
status	Status da transação de recarga no e-SiTef. Saiba mais.	= 3 AN
order_id	Código do pedido gerado pela loja.	< 20 AN
merchant_usn	NSU da transação gerado pela loja.	< 12 N
send_payment_methods	Flag que indica que as formas de pagamento utilizadas podem ser enviadas na próxima transação.Terá o valor true caso positivo.	< 5 N
	esitef
code	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
usn	NSU da transação de recarga no e-SiTef	= 15 N
	authorizers[] Este campo agrega uma lista de elementos.
name	Nome do autorizador	< 16 AN
code	Código de resposta retornado pela autorizadora	< 4 AN
message	Mensagem retornada pela autorizadora	< 64 AN
	acquirer
branch_code	Código da filial da recarga, responsável pela recarga do conjunto DDD + operadora.	< 5 N
merchant_code	Código da loja cadastrada no adquirente	< 15 N
	authorization
confirmation_data	Código da confirmação	< 128 AN
authorizer_date	Data da autorização na autorizadora no formato MMDD	= 4 N
authorizer_time	Horário da autorização na autorizadora no formato HHmmSS	= 6 N
host_usn	NSU do Host	< 20 N
sitef_usn	NSU do SiTef	< 10 N
number	Número da autorização na autorizadora	< 6 N
	customer
total_copies	Número de vias do comprovante do cliente	< 2 N
receipt	Comprovante do cliente	< 4000 AN
	merchant
total_copies	Número de vias do comprovante do estabelecimento	< 2 N
receipt	Comprovante do estabelecimento	< 4000 AN
	payment_methods
max	Número máximo de formas de pagamento	< 2 N
	payment_methods.available[] Este campo agrega uma lista de formas de pagamento disponíveis.
name	Nome da forma de pagamento disponível. Saiba mais.	< 200 AN
	payment Este elemento somente é retornado caso um pagamento atrelado à recarga tenha sido enviado.
status	Status da transação de pagamento no e-SiTef. Saiba mais.	= 3 AN
amount	Valor do pagamento, o mesmo enviado na criação da transação de pagamento.	< 12 AN
type	Tipo do pagamento da autorizadora escolhida: B = boleto C = crédito D = débito P = cartão crédito Private Label T = tranferência bancária G = cartão gift O = outros meios de pagamentos	= 1A
authorizer_id	Id da autorizadora no e-SiTef onde o pagamento foi feito	< 5 N
acquirer	Tipo de pagamento	< 50 AN
	payment.esitef
usn	NSU do e-Sitef	< 15 AN
date	Data do pagamento no formato DD/MM/AAAA hh:mm no e-SiTef.	< 19A
	payment.sitef
code	Código de resposta retornado pelo SiTef	= 3 AN
	payment.customer
receipt	Comprovante do pagamento (via cliente)	< 4000 AN
	payment.merchant
receipt	Comprovante do pagamento (via estabelecimento)	< 4000 AN
	payment.authorization
number	Número de autorização do pagamento	< 6 AN
sitef_usn	NSU do SiTef	< 15 AN
host_usn	NSU da autorizadora	< 15 AN
tid	ID da transação na autorizadora, retornado por alguns tipos de pagamento.	< 40 AN
eci	Eletronic commerce indicator retornado por alguns tipos de pagamento.	< 3 AN
sitef_date	Data do pagamento no formato DD/MM/AAAA hh:mm no SiTef.	< 19 AN
	payment.analysis
status	Status da transação na instituição de análise.	= 3 AN
code	Código de resposta da análise de risco.	< 4 AN
message	Mensagem de resposta da análise de risco.	< 100 AN
	payment.extra_param[]
key	Chave do parâmetro extra	N/A
value	Valor do parâmetro extra	N/A
	hashes Hashes que indicam o status das mudanças nas tabelas de recarga
general	Hash geral das tabelas de recarga. Este hash será alterado se algum dos hashes de uma rede específica for alterado.	= 16 AN
wallet	Hash das tabelas de recarga de uma rede específica. Se as tabelas da rede de recarga sofrer alguma alteração, o hash retornado neste campo também será alterado. O dado retornado neste campo possui o seguinte formato: <Rede>:<Hash>:<Serviço 1>,< Serviço 2>, <Serviço N> Onde: Rede = Código da rede de recarga Hash = Hash referente às tabelas de recarga da Rede. Serviço n = Tipo de serviço disponibilizado pela Rede, os quais podem ser: F1-1 = Recarga Telefone Nacional F1-3 = Recarga Outros Produtos Os separadores são dois-pontos e vírgula. Exemplo de dado retornado neste campo: 106:0D0C4FCB0D0C4FCB:F1-1,F1-3	< 100 AN

Consulta de transações em um grupo de lojas

O e-SiTef exige que as credenciais (merchantkey) sejam as mesmas utilizadas na transação a ser consultada. No entanto, caso o lojista precise, o e-SiTef pode permitir consultas com credenciais de outras lojas de um mesmo grupo. Para isso, basta solicitar às nossas equipes de suporte e produção para que façam essa liberação.

Autenticação com assinatura

Para garantir maior comodidade e segurança aos seus clientes, o e-SiTef oferece, além da autenticação através da chamada POST à URL cadastrada (saiba mais), a opção de assinatura de mensagens, em que conteúdo e remetente passam a ter garantias de integridade e autenticidade, respectivamente. Dessa forma, a loja recebe as informações da transação recém-criada diretamente na resposta de sua chamada REST e não mais através do POST de autenticidade.

O que você precisará

• Cadastro ativo no ambiente de homologação do e-SiTef (obtido com nossa equipe de suporte);
• A criação de uma chave pública e o gerenciamento da sua respectiva chave privada;
• Cadastro da chave pública no e-SiTef (feito através da nossa equipe de suporte).

Criando as chaves pública e privada

Exemplos de como criar as chaves privada e pública:

• No Linux (utilizando o terminal):

# criando a sua chave privada:
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key

# criando uma chave pública a partir da chave privada criada:
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

• No Windows:

Utilizar ssh-keygen no prompt de comando

# criando a sua chave privada:
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key

Utilizar uma versão do openssl para windows, executar como administrador e executar o seguinte comando:

# criando uma chave pública a partir da chave privada criada:
rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

Atenção:

Esse arquivo de chave pública jwtRS256.key.pub é o único arquivo que você deverá enviar pra nossa equipe de suporte. Sempre mantenha seguros a sua chave privada e a sua senha, caso tenha cadastrado uma.

Algoritmo de assinatura

O algoritmo suportado pela aplicação é o RS256 em conjunto com o padrão JWT (RFC 7519).

Ao utilizar este padrão, uma assinatura é composta por três partes: cabeçalho, dados (payload) e a verificação de assinatura. A cada uma dessas partes, é aplicada uma codificação Base64.

Primeira parte (cabeçalho)

O cabeçalho deve conter o seguinte conteúdo fixo:

{
  "alg": "RS256",
  "typ": "JWT"
}

Cabeçalho Base64:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Segunda parte (payload)

A parte de dados (payload) varia de acordo com a operação a ser assinada. Exemplo:

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "order_id": "182367r12831t29b",
  "merchant_usn" : "92837429837",
  "timestamp": "1605034925174"
}

Payload Base64:

eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0

Composição do payload

Dependendo do serviço chamado, os campos do payload serão diferentes. Abaixo estão descritos os campos necessários para cada serviço.

Serviços de criação e listagem de lojas

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef.	= 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef.	< 80 AN	SIM
timestamp	Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.	< 13 N	SIM

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "timestamp": "1605034925174"
}

Serviços de edição e consulta de loja

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	= 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
timestamp	Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.	< 13 N	SIM
registered_merchant_id	Código da loja criada ou a ser criada no e-SiTef. Os códigos de produção e certificação serão diferentes.	= 15 AN	SIM

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "registered_merchant_id": "YYYYYYY",
  "timestamp": "1605034925174"
}

Serviços de criação de transação

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	= 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
order_id	Código do pedido definido pelo lojista.	< 40 AN	SIM
merchant_usn	Número sequencial único para cada pedido, criado pela loja.	< 12 N	SIM
timestamp	Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.	< 13 N	SIM

Exemplo:

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "order_id": "182367r12831t29b",
  "merchant_usn" : "92837429837",
  "timestamp": "1605034925174"
}

Demais serviços

Parâmetro	Descrição	Formato	Obrigatório
nit	Identificador da transação no e-SiTef.	= 64 AN	SIM
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	= 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
timestamp	Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.	< 13 N	SIM

Exemplo:

{
  "nit":"asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678",
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "timestamp": "1605034925174"
}

Terceira parte (verificação)

A terceira e última parte é o resultado da criptografia RSA das duas partes anteriores codificadas separadamente em Base64 e concatenadas por um ponto (".").

Duas partes anteriores codificadas seperadamente em Base64 e concatenadas por um ponto ("."), onde o primeiro segmento do texto - anterior ao ponto - corresponde ao cabeçalho e o segundo corresponde ao payload:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0

Por fim, uma criptografia RSA, usando a chave privada loja, deve ser feita neste conteúdo. Exemplo:

LLQ2kaC3dG0tsu78JyEIbvd8c1G05lo-1qLDBb0lBXsS2lrJ98-rcusEhuodhHDBE701a_RZwCfOH9ebPZXYdEtuLldqp_Q47y_AYOBYuz3eexuVC0sH3MvmljjHEiMYEIKtFyhsSFrBuQBFvBOT4tJCA779j_cP-JnW4MeDazDehsydEa6phsmkGg_0YfN2xdRzaaTrQqldYibUeI7_YEwLTYrZg0Ys7r45quT7veAzNFLEL4I3iJmMJUcBaCfIQl6NKvX7meoSBeFBaj_MRw8WwXnNTjCFXjU6w_iUiYPg0VVAAKGaEYKP7sHUcw1hn-BawMDMorLcvT9YwP4OxQ

Assinatura final

A assinatura final é a concatenação das 3 partes separadas por ("."):

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0.LLQ2kaC3dG0tsu78JyEIbvd8c1G05lo-1qLDBb0lBXsS2lrJ98-rcusEhuodhHDBE701a_RZwCfOH9ebPZXYdEtuLldqp_Q47y_AYOBYuz3eexuVC0sH3MvmljjHEiMYEIKtFyhsSFrBuQBFvBOT4tJCA779j_cP-JnW4MeDazDehsydEa6phsmkGg_0YfN2xdRzaaTrQqldYibUeI7_YEwLTYrZg0Ys7r45quT7veAzNFLEL4I3iJmMJUcBaCfIQl6NKvX7meoSBeFBaj_MRw8WwXnNTjCFXjU6w_iUiYPg0VVAAKGaEYKP7sHUcw1hn-BawMDMorLcvT9YwP4OxQ

Essas três partes da assinatura, representada pelo exemplo anterior, devem ser enviadas no header Authorization com valor Bearer <assinatura>. Com isso, o e-SiTef poderá validar a assinatura utilizando a chave pública da loja.

Utilizando site JWT para testes

É possível utilizar o site do JWT para criar uma assinatura válida para testes. Para isso é necessário selecionar o algoritmo RS256 e passar o respectivo payload e uma chave pública e privada.

Caso a chave pública não esteja válida a mensagem "Invalid Signature" será exibida.

Pagamento HTML

Visão Geral

O e-SiTef possui duas interfaces para integração com a loja virtual, POST/HTML e Web Services (REST ou SOAP), possibilitando a maneira adequada de interação da loja com o e-SiTef, conforme a linguagem e plataforma de execução da loja virtual.

A interface HTML foi definida para ser uma maneira simples e rápida de integração com os meios de pagamentos e serviços existentes no e-SiTef, no entanto sem perder a flexibilidade. A interface padrão possui apenas dois parâmetros obrigatórios, realizando a coleta dos demais no próprio portal ou através de configurações realizadas pelo administrador da loja na retaguarda do e-SiTef, no entanto se a aplicação da loja virtual quiser passar definições ou restrições para um determinado tipo de serviço, rede ou mesmo número de parcelas, isto poderá ser feito através do conjunto de parâmetros passados no início da transação, antes do redirecionamento do cliente.

Fluxo

O fluxo de pagamento é executado pela loja após o comprador finalizar a compra.

A loja deverá iniciar a transação com o e-SiTef enviando os dados da compra através do serviço de criação de transação.

O fluxo de pagamento sem redirecionamento consiste nos seguintes passos:

1. Após o comprador finalizar a compra, a loja cria uma nova transação no e-SiTef, através de um POST na URL para iniciar uma transação, informando todos os parâmetros necessários. Saiba mais.
2. Como resposta ao POST, a loja receberá uma URL do e-SiTef a qual o comprador deve ser redirecionado. Esta URL será diferente a cada transação de pagamento.
3. O comprador seguirá com o fluxo de pagamento conforme a autorizadora informada, e finaliza o pagamento.
4. Ao final do fluxo de pagamento, o e-SiTef irá redirecionar de volta o comprador para a loja, conforme configuração de URL's de retorno já informados no cadastro da loja, ou para as back_url's (saiba mais) enviadas na criação da transação de pagamento.

Para cada alteração de status da transação de pagamento no e-SiTef, a loja receberá um POST de aviso de status, informando a situação da mesma. Saiba mais.

Todas as chamadas realizadas serão respondidas de forma síncrona exceto o aviso de status que será realizado pelo e-SiTef de forma assíncrona.

O e-SiTef permite que a loja configure o meio de pagamento responsável por autorizar as transações de uma determinada bandeira. Por exemplo, uma loja pode preferir que as transações com cartões VISA sejam roteadas pela CIELO enquanto que transações com cartões Mastercard sejam roteadas pela REDE.

Esta flexibilidade para configuração do roteamento dá à loja a possibilidade de tratar promoções de acordo com a bandeira do cartão.

Pensando em como evitar que um usuário selecione a bandeira VISA, mas acabe informando o número de um cartão Mastercard, o e-SiTef disponibiliza um mecanismo de verificação e troca da autorizadora que responderá pela autorização da transação.

Saiba mais.

Pagamento sem redirecionar o comprador

A figura abaixo ilustra o fluxo de Pagamento HTML 2.0 sem redirecionar o comprador para um ambiente externo ao e-SiTef. Como exemplo temos pagamentos via SiTef, e-Rede, dentre outros.

Pagamento redirecionando o comprador para a Autorizadora

A figura abaixo ilustra o fluxo de Pagamento HTML 2.0 usando uma autorizadora que exige redirecionamento do comprador para o sistema deles (exemplo: PayPal, Banco do Brasil, MercadoPago, dentre outros).

Quick start

Este guia mostra o processo de efetivação de um pagamento, utilizando a interface HTML do e-SiTef.

O que você precisará

• Cadastro ativo no ambiente de homologação do e-SiTef (obtido com nossa equipe de suporte)
• Uma ferramenta capaz de realizar chamadas HTTP, como Postman, REST Client ou cURL
• Uma aplicação capaz de receber chamadas POST HTTPS

Criando a transação de pagamento

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/init/json.se

Headers:

• Content-Type: application/x-www-form-urlencoded

Parâmetros do POST:

• Key/chave: request;
• Value/valor: objeto JSON;
• [tipo_de_retorno]: json ou xml;

Objeto JSON request mínimo:

JSON

cURL

{
    "merchant_id": "xxxxxxxxxx",
    "amount": "1800"
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/init/json.se"
--header "Content-Type: application/x-www-form-urlencoded" 
-d 'request=%7B%22merchant_id%22%3A%22xxxxxxxxxx%22%2C%22amount%22%3A%221800%22%7D'
--verbose

Resposta:

{
  "responseCode" : 0,
  "description" : "OK. Transaction successful.",
  "url" : "https://esitef-homologacao.softwareexpress.com.br/e-sitef/do.se?input['nit']=12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk",
  "nsuesitef" : "123451234512345",
  "nit" : "12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk"
}

Saiba mais sobre esse serviço.

Redirecionando o usuário

A loja deve então redirecionar o usuário para a URL retornada pelo e-SiTef na etapa de criação da transação.

Recebendo um aviso de status

Assim que o status da transação mudar, o e-SiTef notificará a loja com um POST em sua URL de status cadastrada.

Java + Spring Framework

@RestController
public class MyStatusController {

    @PostMapping(value = "/mystatus", 
        consumes = "application/x-www-form-urlencoded; charset=utf-8")
    public ResponseEntity<String> myStatus(@RequestParam Map<String, String> request) {
        Log.info("status = " + request.get("status"));
        // ...
        return new ResponseEntity<>("OK", HttpStatus.OK);
    }

}

Abaixo segue um exemplo de requisição a ser feita pelo e-SiTef no domínio cadastrado pela loja:

cURL

curl -X POST \
  https://dominiocadastrado.com.br \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Postman-Token: fc3c1702-9771-4c6f-8411-d1204f572b7b' \
  -H 'cache-control: no-cache' \
  -d 'rede=xxxx&tipoFinanciamento=4&binCartao=xxxxxx&nsuesitef=191107123456780&tid=authorizerTransactionId12345678901234567&parcelas=2&nsu=merchantNsu&autorizadora=1&nit=nitWith64charsLike1234567890123456789012345678901234567890123457&pedido=orderId1234&tipoPagamento=C&finalCartao=2345&status=NEG'

Saiba mais sobre esse serviço.

Iniciando uma transação de pagamento

Processo de criação da transação

O processo de criação de transação deverá seguir os seguintes passos:

• A transação é criada conforme os parâmetros enviados na chave request e representados por um objeto JSON via POST na requisição;
• A loja recebe uma mensagem de sucesso ou erro, formatada como XML ou JSON, conforme o parâmetro "tipo de retorno" na URL enviada ao se iniciar uma transação.

URL para iniciar uma transação via POST HTTPS:

Ambiente de Homologação:
https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/init/[tipo_de_retorno].se
Ambiente de Produção
https://esitef-ec.softwareexpress.com.br/e-sitef/init/[tipo_de_retorno].se

Atenção: Nunca deve ser usado o IP ao invés do domínio esitef-ec.softwareexpress.com.br (ou esitef-homologacao.softwareexpress.com.br para ambiente de homologação). O IP pode mudar a qualquer instante e sem aviso prévio, logo é importante sempre utilizar o domínio para acessar o e-SiTef.

Parâmetros do POST:

• Key/chave: request;
• Value/valor: objeto JSON;
• [tipo_de_retorno]: json ou xml;

Exemplo de requisição JSON (JavaScriptObjectNotation):

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/init/json.se

Objeto JSON request mínimo:

{
    "merchant_id": "codigoDaLoja",
    "amount": "1800"
}

Objeto JSON "request" com alguns parametros adicionais:

{
    "merchant_id": "codigoDaLoja",
    "order_id": "123456",
    "redirect": "A",
    "installments": "3",
    "installment_type": "4",
    "authorizer_id": "1",
    "amount": "1800",
    "transaction_type":"payment",
    "back_url": {
        "url_success": "",
        "url_failure": "",
        "url_cancel": ""
    },
    "additional_data": {
        "currency": "BRL",
        "method": "",
        "postpone_confirmation": "false",
        "payer": {
            "identification_number": "22222222222",
             "store_identification": "22222222222"
        }
    }
}

Ferramentas para testes

Para testes iniciais nesta interface, caso necessário, podem ser usadas algumas ferramentas a fim de um melhor entendimento da comunicação via REST:

• Aplicação para Windows/Linux/Mac:
  • POSTMAN
• Extensão para Firefox:
  • RESTClient

Abaixo seguem exemplos de tela destas ferramentas:

Parâmetros de requisição

O objeto JSON additional_data possui campos que se alteram conforme a autorizadora utilizada para o pagamento, pelo campo authorizer_id. Para mais detalhes do campo additional_data, por favor consulte a documentação específica para cada autorizadora suportada pela Interface de Pagamento HTML 2.0.

Para iniciar uma transação na nova interface de pagamento HTML, inicialmente podem ser preenchidos os seguintes parâmetros no formato JSON.

{
  "amount": "120000",
  "authenticate": "false",
  "authorizer_id": "1",
  "installments": "1",
  "installment_type": "4",
  "merchant_id": "LOJATESTE",
  "merchant_usn": "999888",
  "order_id": "order123",
  "recharge_included": "false",
  "redirect": "M",
  "soft_descriptor": "softDescriptor",
  "store_card": "false",
  "style": "N",
  "transaction_type": "payment",
  "payment_link":"false",
  "additional_data": { },
  "back_url": { },
  "iata": { },
  "recharge": { }
}

Parâmetro	Descrição	Formato	Obrigatório
amount	Valor total a ser pago pelo comprador. Formato: Deve ser enviado em centavos. Ex.: 1000 (10 reais).	< 12 N	SIM
authenticate	Parâmetro que deve ser enviado caso seja necessária a autenticação dos dados de pagamento do cliente. Valores permitidos: 0, 1, 2, 3 e 4. Valor default – 0	< 1 A	NÃO
authorizer_id	Código da Autorizadora (no e-SiTef)	< 10 A	NÃO
installments	Número de parcelas do pagamento. As seguintes autorizadoras não permitem a definição prévia do número de parcelas, logo nesses casos este parâmetro não deve ser enviado: PayPal Mercado Pago PagSeguro Enviar o valor 1 para pagamentos à vista.	< 2 N	NÃO
installment_type	Tipo do financiamento escolhido pelo cliente. Valores permitidos: 3 – parcelado administradora (com juros) 4 – parcelado loja (sem juros) Valor default = 4	= 1 N	NÃO
merchant_id	Código da loja no e-SiTef	< 15 A	SIM
merchant_usn	Código de identificação da transação pelo lojista.	< 12 A	NÃO
order_id	Código do pedido (na loja)	< 40 N	NÃO
recharge_included	Informa se uma recarga será feita. Valores permitidos: true – caso se deseje fazer uma recarga false – caso não se deseje fazer uma recarga Valor default – false	= 5 A	NÃO
redirect	Tipo de redirecionamento que será realizado ao finalizar o fluxo de transação no e-SiTef. Valores permitidos: A – (Automático) redirecionamento automático: não mostra a tela final do pagamento (incluindo o comprovante) e redireciona o cliente automaticamente para uma das URL's do parâmetro back_url. O parâmetro nit também é enviado na requisição via HTTP GET. M – (Manual) redirecionamento manual: Mostra a tela final do pagamento incluindo o comprovante e apresenta um link para o cliente clicar caso deseje ser redirecionado para a loja. O parâmetro nit também é enviado na requisição via HTTP POST. Valor default – M (Manual)	= 1 A	NÃO
soft_descriptor	Nome do estabelecimento que será apresentado na fatura do cartão. Saiba mais	< 30 A	NÃO
store_card	Indicador de armazenamento de cartão utilizado no pagamento. Valores permitidos: true – indica que o cartão utilizado será armazenado. false – indica que o cartão utilizado não será armazenado. Valor default – false (não será realizado o armazenamento) Caso a loja envie este campo igual a true, o campo additional_data.payer.store_identification passa a ser obrigatório.	< 5 A	NÃO
style	Campo informativo para o estilo de redirecionamento para o e-SiTef. Valores permitidos: N – Redirecionamento no mesmo frame. P – Um pop-up será aberto. Valor default – N A loja deve informar o valor correspondente à forma de redirecionamento escolhida na integração, para que o e-SiTef faça um tratamento adequado das janelas ao final da transação de pagamento.	= 1 A	NÃO
transaction_type	Tipo de transação que será realizada. Valores permitidos: payment – Caso seja realizado um Pagamento preauthorization – Caso seja realizada uma Pré Autorização Valor default – payment	< 32 A	NÃO
payment_link	Este campo deve receber o valor true para ativar a funcionalidade de pagamento com link.	< 5 A	NÃO
additional_data	Objeto do tipo ADDITIONALDATA		NÃO
back_url	Objeto do tipo BACKURL		NÃO
iata	Objeto do tipo IATA. Contém informações sobre parcelamento IATA.		NÃO
recharge	Objeto do tipo RECHARGE. Contêm dados relacionados a uma transação de recarga.		NÃO

BACKURL (back_url)

{
    "url_cancel": "/cancel",
    "url_failure": "/failure",
    "url_success": "/success"
}

Parâmetro	Descrição	Formato	Obrigatório
url_success	URL de redirecionamento do cliente em caso de sucesso. Deve possuir apenas o caminho relativo ao domínio.	< 200 A	NÃO
url_failure	URL de redirecionamento do cliente em caso de fracasso. Deve possuir apenas o caminho relativo ao domínio.	< 200 A	NÃO
url_cancel	URL de redirecionamento do cliente em caso de cancelamento. Deve possuir apenas o caminho relativo ao domínio.	< 200 A	NÃO

IATA (iata)

{
    "departure_tax": "1000",
    "first_installment": "20000"
}

Parâmetro	Descrição	Formato	Obrigatório
departure_tax	Valor de taxa de embarque	< 200 A	NÃO
first_installment	Valor de entrada	< 200 A	NÃO

ADDITIONALDATA (additional_data)

{
    "currency": "BRL",
    "method": "",
    "postpone_confirmation": "false",
    "financing_plan": "",
    "payer": { }
}

Parâmetro	Descrição	Formato	Obrigatório
currency	Moeda utilizada padrão para todos itens da compra. Código da moeda segundo a ISO 4217. Alguns valores permitidos: BRL – Real VEF – Venezuelan bolívar fuerte USD – Dólar Americano GBP – Libra Esterlina Entre outros. Caso esse parâmetro não seja enviado, o e-SiTef utilizará a configuração da loja, e se a loja não estiver configurada, será utilizado como padrão o valor BRL.	= 3 A	NÃO
method	Usado para realizar uma transação diferenciada. Valores permitidos: split – Caso se deseje fazer uma transação SPLIT.	< 1024 AN	NÃO
postpone_confirmation	Campo que permite que loja mantenha a transação como Pendente de Confirmação, e posteriormente, confirmá-la ou desfazê-la.	< 5 A	NÃO
financing_plan	Código de plano de financiamento. Necessário apenas para pagamentos com parcelamento com juros efetuados com roteamento Via Certa Financiadora via SiTef. Deve ser enviado se e somente se forem definidos, nesta etapa, a autorizadora (campo authorizer_id) com roteamento Via Certa Financiadora, as parcelas e o parcelamento com juros.	< 4 AN	NÃO
max_installments	Máximo de parcelas sem juros que será apresentado para o comprador no momento do checkout. Caso informado, sobrescreverá o valor configurado na loja do e-SiTef. Caso a adquirente também retorne um valor máximo de parcelas, o valor a ser utilizado será sempre o menor.	< 3 N	NÃO
submerchant_split	Objeto do tipo SUBMERCHANT_SPLIT Consiste em um array para pagamentos split, exclusivos para roteamentos BIN e Sipag, ambos via SiTef. Permite a divisão de partes do valor total do pagamento entre outras empresas. Funcionalidade exclusiva para pagamentos (transaction_type:payment). O máximo de itens permitido neste array é de 5 itens. Este não deve ser usado juntamente com o campo method:split citado acima, e são funcionalidades diferentes.		NÃO
payer	Objeto do tipo PAYER		NÃO
mcc	O MCC (Merchant Category Code) é um código que classifica um negócio pelo tipo de bens ou produtos fornecidos. É usado na subadquirência para roteamentos via SiTef.	4 N	NÃO
subacquirer_merchant_id	Identificação da loja na subadquirente. É usado na subadquirência para roteamentos via SiTef.	22 N	NÃO
transaction_initiated_by	Indica se a transação foi iniciada pelo Lojista ou pelo Comprador. Valores permitidos: customer – Transação iniciada pelo Comprador. merchant – Transação iniciada pelo Lojista.	< 8 AN	NÃO
multiple_payment_methods	Indica se o lojista deseja permitir que o comprador visualize a opção de pagar usando dois meios de pagamento. Não enviar este campo com valor true quando prefixar autorizadora.	< 5 T/F	NÃO

SUBMERCHANT_SPLIT[] (submerchant_split)

[
   {
      "submerchant_code":"empresa01",
      "submerchant_amount":"120"
   },
   {
      "submerchant_code":"empresa02",
      "submerchant_amount":"420"
   },
   {
      "submerchant_code":"empresa03",
      "submerchant_amount":"300"
   },
   {
      "submerchant_code":"empresa04",
      "submerchant_amount":"400"
   },
   {
      "submerchant_code":"empresa05",
      "submerchant_amount":"250"
   }
]

Parâmetro	Descrição	Formato	Obrigatório
submerchant_code	código de estabelecimento BIN/Sipag	< 15 AN	NÃO
submerchant_amount	valor de transação referente ao estabelecimento.	< 12 N	NÃO

PAYER (payer)

{
    "store_identification": "card_1",
    "identification_number": "123123123"
}

Parâmetro	Descrição	Formato	Obrigatório
store_identification	Identificação do comprador para armazenamento de cartão. Esta identificação deve ser única para cada usuário da loja. Mas atenção, essa garantia de unicidade é de total responsabilidade da loja, o e-SiTef não realizará nenhuma validação.	< 20	NÃO
identification_number	Número de identificação do comprador.	< 1024	NÃO

Nota 1: A especificação dos parâmetros do objeto additional_data pode variar conforme autorizadora. Consulte a documentação específica para este detalhamento.

Nota 2: No caso de parcelamento pré-fixado pelos campos installments e installment_type, sem a definição do campo authorizer_id, as seguintes regras serão aplicadas em relação à apresentação de opções de autorizadoras para o comprador:

• As opções de wallets (Visa Checkout, Masterpass, GooglePay), PayPal, PagSeguro e MercadoPago serão omitidas, pois as opções de parcelamento podem ser escolhidas pelo comprador no ambiente do próprio meio de pagamento.
• No caso de pagamentos parcelados (installments > 1), serão apresentadas apenas as opções de crédito e, dentro destas, somente serão mostradas as que as configurações de parcelamento feitas no cadastro da loja no e-SiTef correspondam ao valor fixado.

Sugestão: Ajuste estas configurações no e-SiTef conforme o acordado com as adquirentes / meios de pagamento. Para mais detalhes, entre em contato com a equipe de atendimento e-SiTef ou acesse o Portal do Lojista.

Atenção: No caso de pagamentos roteados por iCards via SiTef, os campos authorizer_id, installments e installment_type devem ser pré-fixados na criação da transação, não sendo possível para o usuário comprador efetuar esta escolha (autorizadora, parcelas e tipo de parcelamento) durante a navegação.

Parâmetros de resposta

O retorno da operação de criação de transação se dá na forma solicitada no [tipo de retorno].

Abaixo segue um exemplo de retorno JSON:

{
  "responseCode": 0,
  "description": "OK. Transaction successful.",
  "url": "https:// esitef-homologacao.softwareexpress.com.br/e-sitef/do.se?input['nit']= 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
  "nsuesitef": "123456789012345",
  "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
}

Os campos retornados são descritos na tabela abaixo:

Parâmetro	Descrição	Formato
responseCode	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 5 N
description	Descrição da resposta	< 1024 A
url	URL de redirecionamento para iniciar o pagamento.	< 256 A
nit	Identificador da transação no e-SiTef	= 64 A
nsuesitef	NSU (Número Sequencial Único) da transação no e-SiTef	= 15 A

Aviso de Status

A cada mudança de status da transação, o e-SiTef avisará à loja sobre tais mudanças conforme a figura abaixo:

No cadastro da loja deve ser informada uma URL de Status, onde o e-SiTef irá enviar um POST contendo o status da transação com os seguintes parâmetros:

Parâmetro	Descrição	Formato
nit	NIT da transação	= 64 A
pedido	Código do Pedido (na loja)	< 20 A
nsu	Número sequencial enviado pela loja	< 12 N
nsuSitef	Número sequencial único do SiTef	< 10 A
nsuHost	Número sequencial único da Autorizadora	< 20 A
nsuesitef	NSU do e-SiTef	= 15 A
status	Status do pedido. Saiba mais.	= 3 A
cupom	Cupom do pagamento (via do cliente) em caso de pagamento efetuado. Não contém quebras de linha, cada linha é separada por @ ao invés de quebra de linha.	< 4000 A
cupomEstabelecimento	Cupom do estabelecimento em caso de pagamento efetuado. Não contém quebras de linha, cada linha é separada por um @.	< 4000 A
autorizadora	Código da Autorizadora (no e-SiTef). Saiba mais.	< 10 A
tipoPagamento	Tipo do pagamento: C=Crédito, D=Débito, B=Boleto	= 1 A
dataSitef	Data do pagamento no formato DD/MM/AAAA hh:mm:SS. Atenção: este parâmetro só é enviado para transações confirmadas que foram roteadas pelo SiTef.	= 19 A
dataEfetivacao	Data do pagamento no formato DD/MM/AAAA hh:mm:SS no caso de pagamentos que não forem via SiTef. Atenção: este parâmetro só é enviado para transações confirmadas que não foram roteadas pelo SiTef.	= 19 A
parcelas	Número de parcelas	< 2 N
tipoFinanciamento	Tipo do financiamento escolhido pelo cliente. 3 = parcelado administradora (com juros), 4 = parcelado loja (sem juros).	= 1 N
mensagem	Mensagem da autorizadora	< 1024 A
codigoRespostaAutorizadora	Código de Resposta da autorizadora	< 1024 A
rede	Nome da rede pela qual o pagamento está sendo efetuado	< 500 A
numeroAutorizacao	Número da autorização (gerado pela autorizadora)	= 6 A
tid	TID da transação, presente somente quando efetuada via, Cielo eCommerce, e-Rede e e.Rede REST	= 40 A
eci	Eletronic Comerce Indicator (ECI) da transação presente somente quando efetuada via Verified By Visa ou Secure Code Mastercard.	= 3 A
bandeira	Código da bandeira utilizada na transação. OBS.: Este campo normalmente é enviado em transações via SiTef.	< 5 N
analise.status	Status da transação de análise de risco. (NOV = nova, EXP = expirada, ACC = aceita, REJ = negada, REV = em análise)	=3 A
analise.codigo	Código numérico de retorno.	< 3N
analise.mensagem	Mensagem de retorno da instituição de análise	<30 A
NITTransacaoSecundaria	NIT’s das transações secundárias (separadas por &#124; pipe), para transações split.	< 1040 A
binCartao	BIN (6 primeiros dígitos) do cartão usado para pagamento.	= 6 N
finalCartao	Últimos 4 dígitos do cartão usado para pagamento.	= 4 N

Em adição aos campos descritos acima, caso uma transação de recarga for vinculada os seguintes campos serão retornados:

Parâmetro	Descrição	Formato
recarga.nit	Identificador NIT da transação.	= 64 A
recarga.nsusitef	Número sequencial único do SiTef.	< 10 A
recarga.nsuhost	Número sequencial único da Autorizadora.	< 20 A
recarga.nsuesitef	NSU do e-SiTef.	= 15 A
recarga.status	Status do pedido	= 3 A
recarga.cupom	Cupom de recarga (via do cliente) em caso de recarga efetuada. Não contém quebras de linha, cada linha é separada por “@” ao invés de quebra de linha.	< 4000 A
recarga.cupomestabelecimento	Cupom do estabelecimento em caso de recarga efetuada. Não contém quebras de linha, cada linha é separada por um “@”.	< 4000 A
recarga.codigoconcessionaria	Código da Concessionária (no GwCel).	< 10 A
recarga.rede	Código da Adquirente.	< 4 N
recarga.dataefetivacao	Data do pagamento no formato DD/MM/AAAA hh:mm:SS no caso de pagamentos que não forem via SiTef. ATENÇÃO: este parâmetro só é enviado para transações confirmadas que não foram roteadas pelo SiTef.	= 19 A
recarga.dataefetivacaositef	Data do pagamento no formato DD/MM/AAAA hh:mm:SS. ATENÇÃO: este parâmetro só é enviado para transações confirmadas que foram roteadas pelo SiTef.	= 19 A
recarga.dadosconfirmacao	Dados de confirmaçãoda recarga (sequência alfanumérica).	= 12 A
recarga.telefone	Número de telefone da recarga.	< 20 N
recarga.ddd	Código de área do telefone descrito na recarga.	< 4 N
recarga.valor	Valor da recarga.	< 12 N
recarga.codigorespostahost	Código de resposta enviado pela concessionária.	< 4 N
recarga.codigorespostasitef	Código de resposta enviado pelo SiTef.	< 4 N
recarga.mensagemrespostahost	Mensagem de resposta enviada pela concessionária.	< 64 A
recarga.mensagemrespostasitef	Mensagem de resposta enviada pelo SiTef.	< 64 A

Importante:

Além dos parâmetros acima o e-SiTef pode devolver outros sem aviso prévio. Por favor, esteja preparado para receber parâmetros extras além dos da tabela acima, que podem ser ignorados. Porém, em alguns casos parâmetros adicionais retornados por determinadas autorizadoras serão enviados juntamente.

Não é necessário devolver nada no POST, porém se o POST não for bem-sucedido (HTTP Status-Code 200: OK), o e-SiTef tentará de novo até o número de vezes configurado no sistema, antes de desistir e deixar a transação como pendente de aviso, conforme as figuras abaixo.

O POST/HTTPS do e-SiTef pode não ser imediato, mas sim, será assíncrono, com o tempo podendo variar conforme carga do servidor e da Internet. Caso haja algum problema no envio, o e-SiTef tentará reenviar a mensagem após um determinado período de tempo, sendo 3 (três) tentativas.

Nem todos os parâmetros podem estar presentes em todas as transações, alguns parâmetros podem não ser enviados dependendo da forma de pagamento ou se a transação não for concluída, por exemplo.

Tentativas de aviso de mudança de status:

Tentativas sem sucesso de aviso de mudança de status:

Serviço de consulta de transação HTML

A aplicação da loja deverá efetuar a consulta de status, quando ocorrer problemas no recebimento do status da transação.

Fluxo

Para realizar a consulta, a loja deverá fazer um POST no seguinte endereço:

https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/consultarTransacao.se?nit=XXXXX

Onde XXXXX é o NIT recebido pelo site do e-SiTef no pedido de consulta. A resposta será "OK" caso o NIT da transação esteja correto e a comunicação é encerrada.

A seguir o e-SiTef irá enviar um POST/HTTPS na URL de aviso de status cadastrada no servidor e-SiTef, enviando como parâmetro o código do status da transação. A loja deve estar preparada para lidar com estes status, e com a chamada HTTPS (SSL/TLS) na URL de aviso de status cadastrada.

O POST/HTTPS do e-SiTef pode não ser imediato, mas sim, será assíncrono, com o tempo podendo variar conforme carga do servidor e da Internet. Caso haja algum problema no envio, o e-SiTef tentará reenviar amensagem após um determinado período de tempo.

Oportuno lembrar que a loja deve aceitar o POST via HTTPS via SSL/TLS com certificado válido, e mesmo sendo válido pode ser necessária a importação do mesmo no e-SiTef.

Outro ponto importante é que o e-SiTef espera sempre a resposta 200 ("OK") na URL de aviso de status, não aceitando em hipótese alguma um redirecionamento (302) para outra URL e muito menos outro site.

Atenção:

A consulta de status da transação no e-SiTef NÃO efetua uma consulta do status da transação no adquirente / autorizador. Este serviço retorna o status da transação na base de dados do e- SiTef.

Exemplo: Caso uma transação de pagamento seja confirmada no e-SiTef, mas seja estornada via telefone diretamente no adquirente / autorizador, este estorno não será necessariamente refletido no serviço de consulta de status da transação do e-SiTef.

Quando utilizar a Consulta de Status?

Se por algum motivo o aplicativo do lojista atingir o timeout de espera e não receber o aviso de status do e-SiTef, devido a algum problema de infraestrutura ou até mesmo problema no servidor que impediu o recebimento da resposta, nesse caso o aplicativo do lojista deverá realizar a Consulta de Status. Nessa consulta o aplicativo do lojista recebe todos os parâmetros da transação, que ele teria recebido caso o aviso de status tivesse sido recebido normalmente. Dessa forma, evita-se que um mesmo pagamento seja enviado duas vezes ou que ocorra o abandono de um pagamento que já foi enviado e depois vir a debitar o valor na fatura do cartão.

É extremamente importante que o aplicativo do lojista tenha conhecimento do status da transação no e-SiTef antes de realizar qualquer tratamento da transação, assim impede-se que o cliente realize uma nova tentativa de pagamento de um mesmo pedido, sem saber o resultado do pagamento enviado anteriormente.

Exemplo:

Caso a URL de aviso de Status da loja cadastrada seja:

https://www.lojateste.com.br/status.php

A loja receberá um POST em:

https://www.lojateste.com.br/status.php

Com os parâmetros:

  pedido = 1234
  nsu = 123
  status = CON

Atenção:

Não abuse da chamada de aviso de status, chamando-o constantemente, sob pena de o e-SiTef passar a ignorar as chamadas.

Pagamento com armazenamento de cartão

O e-SiTef oferece à loja a opção de armazenar, de forma segura, o número do cartão do comprador para uso futuro em transações de compras ou até para efetuar estorno de um pagamento.

O fluxo seguido para o pagamento com armazenamento do cartão é exatamente o mesmo seguido pelo pagamento descrito anteriormente.

No caso de um pagamento com armazenamento o cartão do comprador é criptografado e depois armazenado em uma base de dados usada pelo e-SiTef. Esse armazenamento se dá seguindo as rígidas normas do PCI (Payment Card Industry).

Algumas observações:

• 1. É importante saber que apenas o número do cartão e a data de validade são armazenados, pois é terminantemente proibido guardar de qualquer maneira o código de segurança (CVV, CVC2, CAV2 ou CID) do cartão;
• 2. Este recurso é permitido para cartões de crédito e;
• 3. Para os seguintes cartões voucher:
  • a. Alelo Cultura
  • b. Alelo Refeição
  • c. Alelo Alimentação
  • d. Sodexo Cultura
  • e. Sodexo Refeição
  • f. Sodexo Alimentação
  • g. Coopercard Cultura
• 4. Outro dado a ser observado é que o cartão só é armazenado no e-SiTef caso a transação de pagamento seja confirmada.

Para efetuar o armazenamento do cartão, a loja deve enviar alguns parâmetros extras ao efetuar uma transação de pagamento no e-SiTef. Segue um exemplo de JSON com armazenamento de cartão:

{
   "merchant_id":"codigoDaLoja",
   "amount":"100",
   "order_id":"12345",
   "store_card":"true",
   "additional_data":{
      "payer":{
         "store_identification":"PAYER_ID"
      }
   }
}

Neste caso, além do nit da transação de pagamento, é criado uma transação com nita, isto é, um nit de armazenamento, que é apresentado no retorno da operação de criação de transação de pagamento. Segue abaixo um exemplo de retorno JSON:

{
   "responseCode":0,
   "description":"OK. Transaction successful.",
   "url":"https://esitef-homologacao.softwareexpress.com.br/e-sitef/do.se?input['nit']=1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
   "nsuesitef":"123456789012345",
   "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
   "nita":"12345678901234a",
   "nsua":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqs"
}

Na tabela abaixo são apresentados os campos adicionais retornados:

Parâmetro	Descrição	Formato
nita	Identificador da transação de armazenamento no e-SiTef.	= 65 A
nsua	Número sequencial único da transação de armazenamento no e-SiTef.	= 15 N

Aviso de Armazenamento

No processamento do pagamento com armazenamento do cartão, o e-SiTef envia dois POSTS HTTPS para o servidor da loja.

O e-SiTef enviará um POST na URL de Aviso de Status com os parâmetros de resposta da transação de pagamento e outro POST na URL de Aviso de Armazenamento com os parâmetros de resposta da transação de armazenamento do cartão, juntamente com o identificador do cartão armazenando.

Os campos enviados no aviso de armazenamento são descritos na seguinte tabela:

Parâmetro	Descrição	Formato
nita	Código NITA, que identificará a transação de armazenamento do cartão no e-SiTef em caso de sucesso.	= 65 A
nsua	NSU do e-SiTef para esta transação de armazenamento, que servirá para acompanhamento nos relatórios do back-office.	= 15 N
nsu	Número sequencial único para cada pedido, criado pela loja. O nsu será usado em toda comunicação com a loja, de forma a identificar o pedido. Como trata de uma possível chave para acesso do lado da loja, é exigido que o campo seja formatado e enviado pela aplicação da loja.	< 12 N
status	Status da transação de armazenamento. Saiba mais.	= 3 A
hash	Código identificador do cartão armazenado no e-SiTef.	= 88 C
bin	6 primeiros dígitos do cartão armazenado.	= 6 N
final	Últimos quatro dígitos do cartão armazenado.	= 4 N
autorizadora	Código da Autorizadora (no e-SiTef) utilizado pelo cliente ao efetuar o pagamento. Saiba mais.	< 10 N

Importante:

Além dos parâmetros acima o e-SiTef pode devolver outros sem aviso prévio. Por favor, esteja preparado para receber parâmetros extras (que podem ser ignorados) além dos contidos na tabela acima.

Não é necessário devolver nenhum conteúdo como resposta ao POST, porém se não for bem sucedido (HTTP Status-Code 200: OK), o e-SiTef tentará de novo até o número de vezes configurado no sistema, antes de desistir e deixar a transação de armazenamento como pendente de aviso.

Pagamento recorrente

O pagamento recorrente decorre da necessidade da loja manter débitos programados no cartão de determinado cliente, podendo ser com valor fixo ou variável, com quantidade de ocorrências programadas ou de maneira perene até que o cliente determine o encerramento dos débitos.

Recorrência é a capacidade do e-SiTef em processar novos pagamentos sem que o cliente necessite entrar com os dados novamente, usando os dados do cartão já previamente armazenados. A necessidade surge em casos de renovação de assinatura, mensalidades, etc.

Importante:

Para as Transações Recorrentes serão armazenados somente: Número e Data de validade do cartão, já o código de segurança (CVV, CVC2, CAV2 ou CID) não poderá ser armazenado e nem enviado no pagamento recorrente. O armazenamento do código de segurança, seja criptografado ou não, é terminantemente proibido pelas normas do PCI SSC (Payment Card Industry Security Standards Council). Caberá ao lojista efetuar negociação com as redes adquirentes (Acquirers) para realização dos pagamentos sem a obrigatoriedade do código de segurança; caso contrário, este parâmetro será solicitado durante o fluxo transacional.

Porém, mesmo que as Redes adquirentes permitam transações sem este código (CVV2), não há garantias que o Emissor (Instituição Bancária) aceite uma transação desta forma (sem o código de segurança).

Para realizar o pagamento recorrente, utilize a nossa interface de pagamento REST.

Consulta dos dados do armazenamento

A consulta dos dados do armazenamento de cartão seguirá o seguinte fluxo:

1. A loja envia uma consulta do armazenamento fornecendo o nita
2. O e-SiTef irá enviar os dados do armazenamento na URL de aviso de armazenamento cadastrada pela loja no e-SiTef.

A loja poderá consultar os dados do armazenamento, conforme a figura abaixo:

Para realizar a consulta, a loja deverá fazer um POST no seguinte endereço:

Ambiente de Homologação
https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/armazenamento/consultarArmazenamento.se?nita=XXXX
Ambiente de Produção
https://esitef-ec.softwareexpress.com.br/e-sitef/armazenamento/consultarArmazenamento.se?nita=XXXX

Atenção:

Nunca utilize o IP ao invés do domínio esitef-ec.softwareexpress.com.br! O IP pode mudar a qualquer instante e sem aviso prévio, por isso é importante a utilização do domínio para acessar o e-SiTef.

Onde XXXX é o NITA criptografado com 65 caracteres alfa numéricos recebido pelo site do e-SiTef no pedido de consulta.

A resposta será OK caso o NITA do armazenamento esteja correto e a comunicação é encerrada.

A seguir o e-SiTef irá enviar um POST HTTPS na URL para aviso de armazenamento cadastrada na loja.

A loja deve estar preparada para lidar com estes parâmetros e com eventuais novos parâmetros que podem passar a serem enviados sem prévio aviso (tais novos parâmetros após recebidos, podem ser ignorados pela loja) e preparada também para a chamada HTTPS (SSL) na URL para envio de HASH cadastrada.

O POST HTTPS do e-SiTef pode não ser imediato, será assíncrono com o tempo podendo variar conforme carga do servidor e da Internet. Caso haja algum problema no envio, o e-SiTef tentará reenviar a mensagem após um determinado período de tempo.

Os parâmetros devolvidos são os mesmos descritos na seção de Aviso de Armazenamento.

Customização de Páginas

Visão Geral

Atenção: como as customizações envolvem tanto arquivos CSS quanto arquivos JavaScript, dependendo do nível da customização recomenda-se que, além de um designer/especialista em UX (user experience), esteja envolvido também um desenvolvedor front-end ou similar com conhecimentos de JavaScript. Ambos trabalharão em conjunto para gerar os artefatos necessários à customização.

Importante: quaisquer conteúdos utilizados nas customizações (sejam imagens, scripts JavaScript, folhas de estilo CSS, arquivos, etc) são de responsabilidade única e exclusiva do cliente efetuando a customização. A Software Express não se responsabiliza por eventuais irregularidades existentes nesses conteúdos, cabendo ao cliente efetuando a customização garantir que tais conteúdos estejam sendo utilizados de acordo com suas respectivas licenças, quando as houver.

Atualmente é possível customizar as páginas de duas formas, utilizando um arquivo CSS de folha de estilo ou um arquivo JS de código JavaScript. É possível utilizar ambas as formas em conjunto.

A personalização via folha de estilo é feita pelo arquivo customV2.css (nome genérico dado à folha de estilo), seguindo alguns padrões que sobrescrevem o style.css (folha estilo padrão da Software Express) atual.

Embora style.css seja o principal arquivo CSS da interface de pagamento HTML, há outros arquivos CSS que podem ser referenciados. Esses arquivos são citados na próxima seção.

A personalização via JavaScript é feita pelos arquivos main.js e end.js (nomes genéricos), que serão inseridos nas páginas.

A folha de estilo customV2.css e os códigos fontes main.js e end.js são únicos para cada cliente e a "instalação" é aplicada pela Software Express.

Quando a loja virtual (assumindo como exemplo o ambiente de Homologação do e-SiTef) redireciona o cliente para a página https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/do.se?input['nit']=XX, o e-SiTef carrega os arquivos .css e .js conforme o cadastro da loja em um diretório, por exemplo:

https://esitef-homologacao.softwareexpress.com.br/custom/xxx/

Onde xxx é o diretório configurado no e-SiTef admin (utiliza-se o código da loja no e-SiTef), que possui a seguinte estrutura:

/custom/xxx/css/customV2.css
/custom/xxx/images
/custom/xxx/js/main.js
/custom/xxx/js/end.js

Portanto, o caminho das imagens para a loja é https://esitef-homologacao.softwareexpress.com.br/custom/xxx/images, e as imagens devem apontar para algo como background-image:url('/custom/xxx/images/botao.gif') no arquivo customV2.css.

O arquivo customV2.css pode sobrescrever as propriedades contidas em style.css, mas não substituirá o arquivo style.css. Portanto a página irá apontar também para um novo arquivo /custom/xxx/css/customV2.css, conforme trecho de HTML abaixo:

<link rel="stylesheet" href="/css/v2/style.css">
<link rel="stylesheet" href="/css/v2/payment.css">
<link rel="stylesheet" href="/css/v2/error.css">
<link rel="stylesheet" href="/custom/xxx/css/customV2.css" />

O arquivo main.js é inserido nas páginas logo antes da tag de fechamento </body>, da forma:

<script type="text/javascript" src="/custom/xxx/js/main.js"> </script>

Assim, ele será executado após o carregamento dos elementos da página e terá referência a todos eles.

O arquivo end.js é inserido apenas na última página, sendo útil para executar algum código no redirecionamento de retorno para a loja. A inserção é feita da forma:

<script type="text/javascript" src="/custom/xxx/js/end.js"> </script>

Vale lembrar que nem tudo no estilo é customizável, somente as cores e imagens de fundo e botões.

Eventuais imagens também podem ser enviadas, mas sujeitas a nossa aprovação quanto a tamanho (bytes) e formato.

Não é permitido remover o logotipo do e-SiTef tanto superior (cabeçalho) quanto inferior (rodapé, se existir). A loja poderá colocar o seu logo em outra posição da página, desde que não remova ou sobrescreva os logotipos do e-SiTef.

O cliente pode tomar como exemplo o css em:

https://esitef-homologacao.softwareexpress.com.br/custom/exemplo/css/customV2.css

Atenção: Nunca utilize o IP ao invés dos domínios esitef-homologacao.softwareexpress.com.br (Homologação) e esitef-ec.softwareexpress.com.br (Produção). O IP pode mudar a qualquer instante e sem aviso prévio, por isso, é importante a utilização do domínio para acesso ao e-SiTef.

Procedimentos para envio de arquivos de customização

Os arquivos de customização, sendo eles customV2.css e as imagens, e/ou os arquivos main.js e end.js, deverão ser entregues à Software Express formatados da seguinte maneira: xxx.zip, onde: xxx é o código da loja no e-SiTef, respeitando a seguinte estrutura:

xxx/
    |- css/customV2.css
    |- images/ 
    |- js/main.js
    |- js/end.js

Os arquivos CSS de referência para a interface HTML 2.0 estão disponíveis no ambiente de homologação em:

• https://esitef-homologacao.softwareexpress.com.br/css/v2/authentication.css
• https://esitef-homologacao.softwareexpress.com.br/css/v2/bootstrap.min.css
• https://esitef-homologacao.softwareexpress.com.br/css/v2/error.css
• https://esitef-homologacao.softwareexpress.com.br/css/v2/fonts.css
• https://esitef-homologacao.softwareexpress.com.br/css/v2/payment-credit.css
• https://esitef-homologacao.softwareexpress.com.br/css/v2/payment.css
• https://esitef-homologacao.softwareexpress.com.br/css/v2/recharge.css
• https://esitef-homologacao.softwareexpress.com.br/css/v2/style.css
• https://esitef-homologacao.softwareexpress.com.br/css/v2/success.css

Envie somente os arquivos referentes à personalização que será utilizada! Se apenas a personalização de estilo for desejada, envie apenas os arquivos customV2.css e as imagens.

Os arquivos de imagens deverão estar preferencialmente no formato JPG e PNG. O layout final estará sempre sujeito a aprovação da Software Express.

Caso a empresa tenha mais de um merchantId

Para as empresas que tenham mais de um merchantId (identificação da loja no e-SiTef) e desejam utilizar a mesma customização, entre em contato com o nosso suporte.

Customização de logotipo

É possível também inserir um logotipo personalizado da loja na tela de início pagamento. Caso o logotipo seja inserido, ele aparecerá na parte superior da página, à esquerda do logotipo do e-SiTef. A seguir, uma ilustração de exemplo:

Caso o logotipo não seja inserido, apenas o logotipo do e-SiTef aparecerá na parte superior direita e o restante da parte superior será de uma mesma cor. A seguir, uma ilustração de exemplo:

Para que o logotipo customizado seja exibido, o cliente deve criar uma figura com resolução de 320 x 160 pixels quadrados, no formato PNG, com fundo transparente. A imagem deve ser passada às equipes de Produção ou Suporte do e-SiTef.

A seguir, a opção de exibição de logo personalizado deve ser habilitada no cadastro da loja pela equipe de Produção ou de Suporte do e-SiTef.

Exemplo de customização

De forma a praticar os conceitos apresentados, um exemplo de customização será apresentado a seguir.

A figura abaixo mostra a página de pagamento padrão, sem nenhuma customização:

Quatro elementos da página serão customizados:

1. Cor de fundo da barra de passos do pagamento, no topo da página (CSS): de verde escuro para azul.
2. Cor de fundo do quadro "RESUMO DA COMPRA" (CSS): de verde para azul.
3. Fonte das caixas de texto "Número do Cartão", "Data de Validade [?]", "Código de segurança [?]" e "Como deseja pagar?" (CSS): de Source Sans Pro para Courier New.
4. Ícone "$" ao lado esquerdo do texto "Escolha a forma de pagamento" (JavaScript): substituição do ícone por outro.

O primeiro passo da customização é montar a estrutura de diretórios mencionada anteriormente. Assumindo que a loja deste exemplo possui o código ecommerce, devemos ter a seguinte estrutura:

ecommerce
   css
       customV2.css
   images
       cifrao.png
   js
       main.js

Inicialmente, os arquivos customV2.css e main.js deverão estar vazios. O arquivo cifrao.png pode ser visto na figura abaixo:

O arquivo customV2.css conterá as customizações dos itens 1, 2 e 3. Os arquivos cifrao.png e main.js serão utilizados na customização do item 4.

Para customizar o item 1, adicione o seguinte conteúdo ao arquivo customV2.css:

.steps {
    background: #0000ff;
}

Nele, alteramos a cor de fundo de elementos com o estilo steps (caso do item 1) para a cor azul (código 0000ff).

Para customizar o item 2, adicione o seguinte conteúdo ao arquivo customV2.css:

.summary {
    background-color: #0000ff;
}

Nele, alteramos a cor de fundo de elementos com o estilo summary (caso do item 2) para a cor azul (código 0000ff).

Para customizar o item 3, adicione o seguinte conteúdo ao arquivo customV2.css:

.form-control {
    font-family: "Courier New";
}

Nele, alteramos a fonte de elementos com o estilo form-control (caso do item 3) para Courier New.

Todas essas customizações obedecem às convenções da linguagem CSS (Cascading Style Sheets). O arquivo customV2.css completo pode ser visto a seguir:

.steps {
    background: #0000ff;
}

.summary {
    background-color: #0000ff;
}

.form-control {
    font-family: "Courier New";
}

A customização do item 4, ao contrário dos outros três itens, não pode ser efetuada por meio de CSS, sendo necessário o uso da linguagem JavaScript.

Para customizar o item 4, adicione o seguinte conteúdo ao arquivo main.js:

$("div.pagament-content > div.payment-title img.img-responsive").attr("src", "/custom/ecommerce/images/cifrao.png");

Nele, alteramos a imagem de elementos que atendem o critério acima (caso do item 4) para a imagem contida no arquivo cifrao.png.

É importante mencionar que o código JavaScript acima está utilizando o framework jQuery (https://jquery.com), mas qualquer código-fonte JavaScript válido pode ser usado.

Com a customização completada, a estrutura de diretórios deve ser comprimida num arquivo chamado ecommerce.zip e enviado à Software Express, conforme as instruções mencionadas anteriormente. Após a Software Express validar a customização, se nenhum problema for encontrado ela estará disponível para visualização.

A figura abaixo mostra a página de pagamento após a customização:

Pagamento com Link

O pagamento com link é uma modalidade que permite ao lojista efetuar uma requisição ao e-SiTef para obtenção de um link / URL, o qual poderá ser enviado diretamente ao comprador na plataforma desejada (exemplo: e-mail, redes sociais, etc.).

Para utilizar esta funcionalidade, basta enviar o parâmetro payment_link com valor true na etapa de criação da transação. A URL retornada terá um tempo de expiração maior, por padrão, de 48 horas. Quando o comprador for encaminhado ao link, ele seguirá o fluxo de pagamento HTML convencional.

A loja também pode ter um tempo de expiração customizado, com um valor entre 5 minutos e 48 horas. Para isso, basta solicitar essa configuração para as nossas equipes de suporte e produção.

Os pagamentos com link gerado por este método podem utilizar a integração com a antifraude CyberSource e Konduto. Veja Serviço de análise de risco na Interface HTML para ter mais detalhes, além da documentação mais específica de cada instituição de análise de risco.

Pagamento Split

O pagamento Split é uma funcionalidade voltada para estabelecimentos que vendem um produto / serviço de terceiros. Possibilitando, através de uma única requisição, a separação do valor principal e do produto / serviço, de tal forma que o montante é diretamente destinado aos estabelecimentos envolvidos.

O valor total de uma venda qualquer é dividido em N partes e enviado (via POST/HTML) para N empresas distintas (N merchantId's distintos) definidas pela aplicação web e devidamente cadastradas no e-SiTef.

Exemplo: Tomando como exemplo uma venda de R$ 100,00 podemos efetuar uma única requisição para enviar a quantia de R$ 60,00 para a fabricante do produto principal, R$20 para a fabricante de um acessório e R$ 20,00 para a prestadora do serviço.

Interfaces e-SiTef suportadas para integração com pagamento SPLIT

A interface utilizada é POST HTML com JSON.

É possível utilizar as seguintes interfaces para a integração com o pagamento Split:

• Interface de Pagamento HTML 2.0 (documento "Pagamento HTML")
• Interface WS de Cancelamento versão 2 (documento "Cancelamento REST").

Observação: Caso a loja esteja iniciando a primeira integração com o e-SiTef, recomenda-se a integração via Pagamento HTML, por oferecer uma melhor experiência ao usuário e uma interface mais moderna para a integração com o sistema da loja.

Funcionalidades e-SiTef NÃO permitidas para integração com pagamento SPLIT

O e-SiTef não permite integração (na mesma transação) entre um pagamento SPLIT e as seguintes funcionalidades do e-SiTef:

• Transação de análise de risco manual (onde o pagamento HTML fica pendente de confirmação posterior pela loja enquanto esta faz a análise de risco separada do e-SiTef);
• Transação de Recarga de crédito de celulares pré-pagos associada ao pagamento;
• Armazenamento de cartão durante o pagamento.

Configurações necessárias no e-SiTef

O lojista que deseja efetuar pagamentos Split deve solicitar à equipe de cadastro para que a permissão para este tipo de pagamento seja ativada.

Parâmetros utilizados para efetuar um pagamento Split

Na realização de pagamentos Split, os parâmetros POST abaixo possuem os seguintes conceitos:

Nome do parâmetro	Descrição	Tamanho	Obrigatório
amount*	Deve ser enviado o valor total do pagamento, ou seja, o valor da transação principal somado com as demais.	<= 1024 N	SIM
installments**	Será utilizado para todas as transações secundárias. A transação principal será sempre à vista.	<= 1024 N	SIM

(*) O e-SiTef realizará a validação dos valores com o total enviado (amount). Caso ocorra alguma diferença, a transação será invalidada.

(**) Em caso de pagamento parcelado, a transação principal sempre será a vista e as transações secundárias serão parceladas, com o mesmo número de parcelas entre elas.

As transações secundárias são todas as transações vinculadas à transação principal. Para requisição, é possível ter um máximo de 16 (dezesseis) transações secundárias. Quanto maior o número de transações enviadas, maior será a demora na resposta devido ao aumento no processamento de várias transações.

Caso ocorra algum problema durante o fluxo completo do Pagamento Split, o e-SiTef irá desfazer todas as transações já aprovadas daquele fluxo de pagamento. Ex.: A aplicação realizou um fluxo de pagamento contendo 3 merchantId’s, a transação do 1° merchantId foi aprovada, porém a transação do 2° merchantId foi negada. Como no fluxo de pagamento ocorreu um erro na segunda transação (status=NEG), o e-SiTef irá desfazer a primeira (status=PPN) e negará o fluxo por completo, retornando NEG também para a terceira transação, mesmo que nenhuma tentativa de pagamento tenha sido realizada. Em casos em que o e-SiTef nega umas das transações, além do comportamento descrito acima (negar todas as transações), é apresentado no relatório de transações (Portal do Lojista) a mensagem “Negada Split” no campo “Mensagem”.

Os parâmetros JSON abaixo possuem os seguintes conceitos:

ADDITIONAL_DATA (additional_data)

Nome do parâmetro	Descrição	Tamanho	Obrigatório
method	Usado para realizar uma transação diferenciada. Caso se deseje fazer uma transação SPLIT, este campo deve receber o texto "SPLIT".	<= 1024 A	SIM
extra_amount	Será utilizado para receber o valor da transação principal	<= 1024 N	SIM

INNER_TRANSACTIONS (inner_transactions)

Nome do parâmetro	Descrição	Tamanho	Obrigatório
merchant_id	Código da loja no e-SiTef a ser utilizado em cada transação secundária.	<= 1024 A	SIM
amount	Deve ser enviado o valor total do pagamento de cada transação secundária, sempre respeitando o limite do valor total do pagamento.	<= 1024 N	SIM
order_id	Código do pedido na loja a ser utilizado em cada transação secundária.	<= 1024 A	NÃO
merchant_usn	Número sequencial da loja a ser utilizado em cada transação secundária.	<= 1024 A	NÃO

IMPORTANTE 1: As autorizadoras configuradas de uma loja secundária devem ser as mesmas configuradas na loja enviada na transação principal. Entretanto, não há impedimentos para que os roteamentos sejam diferentes entre as lojas. Exemplo: loja 1 configurado com Visa e rede adquirente Cielo, loja 2 configurada com Visa e rede adquirente Rede é um cenário válido.

IMPORTANTE 2: Caso qualquer uma das transações seja negada, seja qual for o motivo (falha de comunicação, saldo insuficiente, etc.), o comportamento padrão será de desfazer / negar todas as transações envolvidas. A funcionalidade foi desenvolvida com a premissa de confirmar todas ou negar todas as transações.

Aviso de status

O aviso de status enviado pelo e-SiTef para a URL de aviso de status da loja possui um campo adicional no caso de transações Split.

Nome do parâmetro	Descrição	Tamanho
NITTransacaoSecundaria	Campo composto de merchantIds e NIT’s das transações secundárias, no formato (merchantId1:nit1|merchantId2:nit2)	<= 1296 A

O campo NITTransacaoSecundaria é enviado no aviso de status da transação principal, indicando os NIT’s das transações secundárias e permitindo, assim, a consulta de status de todas elas.

Exemplo de campo NITTransacaoSecundaria para 2 transações secundárias:

NITTransacaoSecundaria=LOJATESTE:95f386518449f6be6b4d25449989b5cee7736eb93ce96901ea2338a76fd01ad8|LOJATESTE2:95f386518449f6bea6fed3e03f7326fbe7736eb93ce96901dc1d6fba16d8f011

Exemplos de chamada

Exemplo de chamada com os parâmetros da transação do e-SiTef + dados do pagamento Split em formato JSON para Pagamento HTML:

JSON

{
  "merchant_id": "CODIGO_LOJA1",
  "amount": "15000",
  "order_id": "654321",
  "additional_data": {
    "method": "split",
    "extra_amount": "1000",
    "inner_transactions": [
      {
        "merchant_id": "CODIGO_LOJA2",
        "merchant_usn": "12341234",
        "order_id": "654321",
        "amount": "10000"
      },
      {
        "merchant_id": "CODIGO_LOJA3",
        "merchant_usn": "3456789",
        "order_id": "654321",
        "amount": "4000"
      }
    ]
  }
}

Pagamento com múltiplos meios de pagamento

O pagamento com múltiplos meios de pagamento é uma modalidade que permite ao comprador efetuar um pagamento usando mais de um meio de pagamento.

Para utilizar esta funcionalidade, basta enviar o parâmetro multiple_payment_methods dentro do additional_data com valor true na etapa de criação da transação. Também é necessário que o lojista habilite a permissão de múltiplos pagamentos no cadastro da loja.

Essa modalidade não permite pagamentos split nem autorizadora pré-fixada.

Falaremos mais sobre as diferenças em relação ao pagamento simples a seguir.

Fluxo e telas

Quando o lojista indica que quer permitir o pagamento com múltiplos meios de pagamento, a tela de checkout apresenta as opções "Pagar com um cartão" e "Pagar com 2 cartões" logo acima das opções de autorizadoras conforme exemplificado na figura abaixo.

Note também que os passos do checkout são alteradas quando a opção de 2 cartões é selecionada, e são mostradas apenas autorizadoras do tipo crédito.

A inserção dos dados do primeiro cartão segue um fluxo semelhante ao do pagamento simples, com a diferença de que, ao invés de aparecer o botão de confirmação após o preenchimento dos dados do cartão e do pagamento, é mostrado o botão "Próxima forma de pagamento".

Caso o comprador preencha o primeiro meio de pagamento com o valor total da compra, será apresentada uma mensagem de confirmação para prosseguir como um pagamento simples.

Caso contrário, o comprador segue para o preenchimento do segundo meio de pagamento.

Note que, na tela inicial do segundo pagamento, são apresentados os dados do primeiro pagamento, mas estes só poderão ser modificados se o comprador clicar em "Corrigir dados anteriores" depois de escolher uma autorizadora.

O fluxo segue da mesma forma: o usuário seleciona uma autorizadora, preenche os dados do cartão e confirma o pagamento.

Quando a compra for confirmada, serão apresentados um recibo para cada cartão.

Caso haja falha no pagamento com algum dos meios de pagamento, será lançada uma ocorrência no e-SiTef e a loja será notificada. Tendo a posse dos dados enviados na notificação, a loja pode consultar e cancelar o pagamento problemático no Portal do Lojista ou entrar em contato com a equipe de Suporte do e-SiTef.

Aviso de status

O aviso de status enviado pelo e-SiTef para a URL de aviso de status da loja possui um campo adicional no caso de transações de múltiplos cartões nas quais ocorreram falhas.

Nome do parâmetro	Descrição	Tamanho
NITTransacaoAssociada	Campo composto do NIT do outro meio de pagamento selecionado.	= 64 AN

O campo NITTransacaoAssociada é enviado no aviso de status da transação principal, indicando o NIT da transação com o outro cartão.

Exemplo de campo NITTransacaoAssociada:

NITTransacaoAssociada=95f386518449f6be6b4d25449989b5cee7736eb93ce96901ea2338a76fd01ad8

Integração 3DS 2.0

O pagamento HTML do e-SiTef está integrado com o 3DS Server, que é responsável pela realização de autenticações 3DS 2.0. Esta funcionalidade autentica o portador do cartão, conduzindo o processo com o mínimo de fricção possível ao comprador.

Autorizadoras disponíveis

Esta integração é suportada pelas seguintes autorizadoras:

ID	Nome
1	Visa Crédito
2	Mastercard Crédito
41	Elo Crédito
221	Visa Débito
286	Mastercard Débito
288	Elo Débito

Credenciais necessárias

As seguintes informações devem ser fornecidas às nossas equipes de suporte e produção:

Nome	Descrição
Acquirer Merchant ID	Para cada roteamento utilizado, é necessário obter com o adquirente o seu Acquirer Merchant ID. Este valor pode ser o mesmo utilizado como código de estabelecimento para o processo de autorização, e deve seguir a formatação especificada na ISO 8583.
Acquirer BIN	Identificador de cada meio de pagamento atribuído pelo adquirente.

Com isso, o cadastro será feito de modo que a loja fique preparada para transacionar com 3DS.

Parâmetros específicos da integração

O serviço de criação de transação HTML possui os seguintes campos específicos da integração 3DS 2.0:

Parâmetro	Descrição	Formato	Obrigatório
authenticate	Enviar o valor 1 para habilitar o uso de 3DS 2.0.	SIM	= 1 N
additional_data	Dados gerais da transação.
exponent	Número de casas decimais da moeda conforme definido na ISO 4217.	= 1 N	SIM
extra_info	Informações adicionais sobre a conta fornecidas opcionalmente pelo 3DS Requestor.	< 64 AN	NÃO
additional_data .authentication	Dados gerais de autenticação.
transaction_type	Identifica o tipo de transação sendo autenticada. 01 = Compra de bens/serviços 03 = Check Acceptance 10 = Financiamento de Conta 11 = Transação Quasi-Cash 28 = Ativação e carga de pré-pago	= 2 N	SIM
indicator	Indica o tipo da requisição de autenticação. 01 = Transação de pagamento 02 = Transação recorrente 03 = Transação parcelada 04 = Adição de cartão 05 = Manter cartão 06 = Verificação do portador como parte de EMV token ID&V	= 2 N	SIM
challenge_indicator	Indica se um desafio é requerido para essa transação. 01 = Sem preferência 02 = Desafio não pedido 03 = Desafio pedido (preferência do 3DS Requestor) 04 = Desafio pedido (mandato) 05 = Desafio não pedido (análise de fraude já realizada) 06 = Desafio não pedido (apenas compartilhamento de dados) 07 = Desafio não pedido (forte autenticação de consumidor já é feita) 08 = Desafio não pedido (usar isenção de lista branca caso o desafio não seja requerido) 09 = Desafio pedido (uso de lista branca caso desafio seja requerido)	= 2 N	NÃO
address_match	Indica se o endereço de entrega e de cobrança do portador são iguais. Y = Endereços são iguais N = Endereços não são iguais	= 1 AN	NÃO
additional_data .authentication .info	Informações sobre como o 3DS Requestor autenticou o portador do cartão antes ou durante a transação.
method	Mecanismo usado pelo portador do cartão para se autenticar no 3DS Requestor. 01 = Nenhuma autenticação do 3DS Requestor ocorreu (ou seja, portador fez "login" como visitante) 02 = Login para a conta do portador no sistema do 3DS Requestor usando as credenciais do próprio 3DS Requestor 03 = Login para a conta do portador no sistema do 3DS Requestor usando ID federado 04 = Login para a conta do portador no sistema do 3DS Requestor usando credenciais do emissor 05 = Login para a conta do portador no sistema do 3DS Requestor usando autenticação terceirizada 06 = Login para a conta do portador no sistema do 3DS Requestor usando FIDO Authenticator 07 = Login para a conta do portador no sistema do 3DS Requestor usando FIDO Authenticator (garantia de dados FIDO assinada) 08 = Seguro de Dados SRC	= 2 N	NÃO
timestamp	Data e hora UTC da autenticação do portador em formato AAAAMMDDHHMM.	= 12 N	NÃO
additional_data .authentication .prior_info	Informações sobre como o 3DS Requestor autenticou o portador do cartão como parte de uma transação 3DS prévia.
method	Mecanismo usado anteriormente pelo portador para se autenticar no 3DS Requestor. 01 = Autenticação frictionless ocorrida pelo ACS 02 = Desafio do portador ocorrida pelo ACS 03 = AVS verificada 04 = Outras formas do emissor	= 2 N	NÃO
timestamp	Data e hora UTC da autenticação prévia do portador em formato AAAAMMDDHHMM.	= 12 N	NÃO
reference	Este elemento fornece informações adicionais para que o ACS determine a melhor forma de tratar uma requisição.	< 36 AN	NÃO
additional_data .authentication .account	Informações sobre a conta do comprador no 3DS Requestor.
age_indicator	Período de tempo que o portador teve conta no 3DS Requestor. 01 = Sem conta (visitante) 02 = Criado durante esta transação 03 = Menos de 30 dias 04 = 30−60 dias 05 = Mais de 60 dias	= 2 N	NÃO
change_date	Data da última alteração da conta do comprador em formato AAAAMMDD.	= 8 N	NÃO
change_indicator	Período de tempo desde a última alteração na conta do portador. 01 = Alterada durante esta transação 02 = Menos de 30 dias 03 = 30−60 dias 04 = Mais de 60 dias	= 2 N	NÃO
date	Data em que o portador abriu a conta no 3DS Requestor no formato AAAAMMDD.	= 8 N	NÃO
password_change	Data em que o comprador alterou sua senha no formato AAAAMMDD.	= 8 N	NÃO
password_change_indicator	Indica o período de tempo desde a última alteração de senha do portador. 01 = Sem alteração 02 = Alterada durante esta transação 03 = Menos de 30 dias 04 = 30−60 dias 05 = Mais de 60 dias	= 2 N	NÃO
number_purchases	Número de compras com esta conta durante os últimos 6 meses.	< 4 N	NÃO
provision_attempts_day	Número de tentativas de adição de cartão nas últimas 24 horas.	< 3 N	NÃO
txn_activity_day	Número de transações (confirmadas e abandonadas) para este portador com o 3DS Requestor nas últimas 24 horas.	< 3 N	NÃO
txn_activity_year	Número de transações (confirmadas e abandonadas) para este portador com o 3DS Requestor no último ano.	< 3 N	NÃO
payment_account_age	Data em que a conta de pagamento foi registrada na conta do portador com o 3DS Requestor no formato AAAAMMDD.	= 8 N	NÃO
payment_account_indicator	Indica o período de tempo que a conta de pagamento foi registrada no 3DS Requestor. 01 = Sem conta (visitante) 02 = Durante esta transação 03 = Menos de 30 dias 04 = 30−60 dias 05 = Mais de 60 dias	= 2 N	NÃO
ship_address_usage	Data do primeiro uso do endereço de entrega no formato AAAAMMDD.	= 8 N	NÃO
ship_address_usage_indicator	Indica quando foi primeiramente utilizado o endereço de entrega. 01 = Nesta transação 02 = Menos de 30 dias 03 = 30−60 dias 04 = Mais de 60 dias	= 2 N	NÃO
ship_name_indicator	Indica se nome do portador do cartão é idêntico ao nome de entrega utilizada para esta transação. 01 = Nome da conta idêntico ao nome de entrega 02 = Nome de conta diferente de nome de entrega	= 2 N	NÃO
suspicious_activity	Indica se o 3DS Requestor teve experiências suspeitas (incluindo fraude prévia) com a conta do comprador. 01 = Nenhuma atividade suspeita foi observada 02 = Atividade suspeita foi observada	= 2 N	NÃO
additional_data .authentication .merchant_risk	Avaliação da loja sobre o nível de risco de fraude para a autenticação específica para o portador e a autenticação sendo conduzida.
delivery_email_address	Para entrega eletrônica, o endereço de e-mail para qual a mercadoria foi entregue.	< 254 AN	NÃO
delivery_timeframe	Indica o período de tempo de entrega da mercadoria. 01 = Entrega eletrônica 02 = Entrega no mesmo dia 03 = Entrega no dia seguinte 04 = Entrega em dois ou mais dias	= 2 N	NÃO
gift_card_amount	Para compra com cartão presente ou pré-pago, o valor total da compra em números inteiros (por exemplo, 123.45 é 123).	< 15 N	NÃO
gift_card_count	Para compra com cartão presente ou pré-pago, contagem de cartões pré-pagos/presentes comprados.	< 2 N	NÃO
gift_card_currency	Para compra com cartão presente ou pré-pago, código de moeda ISO 4217 de três dígitos do cartão presente.	= 3 N	NÃO
pre_order_date	Para uma pré-venda, a data esperada de disponibilidade da mercadoria no formato AAAAMMDD.	= 8 N	NÃO
pre_order_purchase_indicator	Indica se o portador está fazendo um pedido para uma mercadoria com disponibilidade futura. 01 = Mercadoria disponível 02 = Disponibilidade futura	= 2 N	NÃO
reorder_items_indicator	Indica se o portador está pedindo uma mercadoria comprada anteriormente. 01 = Pedida pela primeira vez 02 = Pedida novamente	= 2 N	NÃO
shipping_indicator	Indica a forma de entrega escolhida para a transação. 01 = Entregar no endereço de cobrança 02 = Entregar em outro endereço verificado no arquivo com a loja 03 = Entregar no endereço que é diferente do endereço de cobrança 04 = Entregar na própria loja 05 = Bens digitais 06 = Bilhetes de viagem ou evento, não entregues fisicamente 07 = Outros	= 2 N	NÃO
additional_data .authentication .message	Particularidades sobre a mensageria 3DS.
category	Identifica a categoria da mensagem para um caso de uso específico. 01 - Autenticação de pagamento 02 - Autenticação de não-pagamento 80 - Mastercard Data Only Valor padrão: 01.	= 2 N	NÃO
additional_data .authentication .recurring	Dados de recorrência.
expiry	Data em que não serão feitas mais autorizações no formato AAAAMMDD. Obrigatório quando authentication.indicator = 02 ou 03.	= 8 N	COND.
frequency	Indica o número mínimo de dias entre autorizações. Obrigatório quando authentication.indicator = 02 ou 03.	< 4 N	COND.
additional_data .purchase_information_data	Dados da compra.
date	Data e hora UTC da compra no formato AAAAMMDDHHMMSS.	= 12 N	SIM
additional_data .payer	Informações do portador do cartão.
email	Endereço de email do portador.	< 256 AN	SIM
name	Nome do portador.	< 45 AN	SIM
additional_data .payer .phones[]	Informações do telefone do portador do cartão.
ddi	DDI do telefone.	< 3 N	SIM
ddd	DDD do telefone.	< 3 N	SIM
number	Número do telefone.	< 12 N	SIM
type	Tipo do telefone: 1: residencial (fixo) 2: comercial 6: celular	< 12 N	SIM
additional_data .billing_data .address	Endereço de cobrança.
city	Cidade.	< 50 AN	SIM
country	Código numérico ISO 3166-1 de três dígitos do país.	= 3 N	SIM
street_name	Nome da rua.	< 50 AN	SIM
street_number	Número da rua.	< 50 AN	SIM
complement	Complemento do endereço.	< 50 AN	SIM
zip_code	CEP.	< 16 AN	SIM
state	Sigla do estado.	< 3 AN	SIM
additional_data .shipment .address	Endereço de entrega.
city	Cidade.	< 50 AN	SIM
country	Código numérico ISO 3166-1 de três dígitos do país.	= 3 N	SIM
street_name	Nome da rua.	< 50 AN	SIM
street_number	Número da rua.	< 50 AN	SIM
complement	Complemento do endereço.	< 50 AN	SIM
zip_code	CEP.	< 16 AN	SIM
state	Sigla do estado.	< 3 AN	SIM

Exemplo de JSON:

{
   "merchant_id":"XXXXX",
   "authorizer_id":"2",
   "amount":"10004",
   "authenticate":"1",
   "additional_data":{
      "payer":{
         "name":"name"
      },
      "purchase_information_data":{
         "date":"20201023113749"
      },
      "exponent":"2",
      "authentication":{
         "transaction_type":"01",
         "indicator":"01"
      }
   }
}

Mastercard 3DS Identity Check Insights (Dataonly)

O Identity Check Insights é um modo de 3DS exclusivo da Mastercard que possui as seguintes características:

• Sempre frictionless (não é pedido ao usuário para inserir informações extras).
• O lojista será responsável por arcar com as fraudes (sem liability shift).
• Maior taxa de aprovação.
• É permitido somente para cartões com a bandeira Mastercard.

Mais detalhes na documentação oficial da Mastercard.

No e-SiTef é possível realizar uma transação de pagamento utilizando Identity Check Insights de duas maneiras:

• Via parâmetro ao iniciar uma transação de pagamento
• Via configuração de loja

Via parâmetro ao iniciar transação

O lojista pode indicar que deseja utilizar Identity Check Insights informando o valor 80 no parâmetro additional_data.authentication.message.category.

Exemplo:

{
   "merchant_id":"LOJAYYZ",
   "authorizer_id":"2",
   "amount":"10004",
   "authenticate":"1",
   "additional_data":{
      "payer":{
         "name":"name"
      },
      "purchase_information_data":{
         "date":"20201023113749"
      },
      "exponent":"2",
      "authentication":{
         "transaction_type":"01",
         "indicator":"01",
         "message":{
            "category":"80"
         }
      }
   }
}

Via configuração de loja

O lojista pode solicitar ao atendimento e-SiTef que habilite a opção Utiliza Mastercard 3DS Identity Check Insights.

Com esta configuração habilitada, todas as transações de pagamento utilizando cartões com bandeira Mastercard e Maestro, utilizarão como padrão o Mastercard 3DS Identity Check Insights.

Exemplo:

{
   "merchant_id":"DATAONLYON",
   "authorizer_id":"2",
   "amount":"10004",
   "authenticate":"1",
   "additional_data":{
      "payer":{
         "name":"name"
      },
      "purchase_information_data":{
         "date":"20201023113749"
      },
      "exponent":"2",
      "authentication":{
         "transaction_type":"01",
         "indicator":"01"
      }
   }
}

É possível sobrescrever este comportamento informando o valor 01 no parâmetro additional_data.authentication.message.category, ignorando assim a configuração da loja.

Exemplo:

{
   "merchant_id":"DATAONLYON",
   "authorizer_id":"2",
   "amount":"10004",
   "authenticate":"1",
   "additional_data":{
      "payer":{
         "name":"name"
      },
      "purchase_information_data":{
         "date":"20201023113749"
      },
      "exponent":"2",
      "authentication":{
         "transaction_type":"01",
         "indicator":"01",
         "message":{
            "category":"01"
         }
      }
   }
}

Pré-autorização HTML

Visão Geral

O fluxo para pré-autorização é exatamente o mesmo do pagamento. Para permitir que o comprador efetue a compra via pré-autorização, basta indicar o campo transaction_type com o valor "preauthorization". Saiba mais..

Atenção:

Quando comparada ao pagamento, a pré-autorização na interface HTML possui uma restrição. O envio da autorizadora, o número e o tipo de parcelas se tornam obrigatórios na criação da transação e devem ser pré-fixados pela loja, não permitindo a escolha/alteração pelo usuário comprador.

Estes campos são, respectivamente: authorizer_id, installments e installment_type, descritos nos parâmetros de requisição do serviço de criação de transação.

Exemplo de requisição de pré-autorização

{
    "merchant_id": "codigoDaLoja",
    "amount": "1800",
    "transaction_type":"preauthorization",
    "authorizer_id": "1",
    "installments": "3",
    "installment_type": "4"
}

Captura de pré-autorização

Uma vez que a pré-autorização foi confirmada com sucesso, o lojista pode capturá-la posteriormente via Web Services, efetivando assim a cobrança. Saiba mais.

Recarga HTML

Visão Geral

O e-SiTef possui duas interfaces para integração com a loja virtual, POST/HTML e Web Services (REST ou SOAP), possibilitando a maneira adequada de interação da loja com o e-SiTef, conforme a linguagem e plataforma de execução da loja virtual.

A interface HTML foi definida para ser uma maneira simples e rápida de integração com os meios de pagamentos e serviços existentes no e-SiTef, no entanto sem perder a flexibilidade. A interface padrão possui apenas dois parâmetros obrigatórios, realizando a coleta dos demais no próprio portal ou através de configurações realizadas pelo administrador da loja na retaguarda do e-SiTef, no entanto se a aplicação da loja virtual quiser passar definições ou restrições para um determinado tipo de serviço, rede ou mesmo número de parcelas, isto poderá ser feito através do conjunto de parâmetros passados no início da transação, antes do redirecionamento do cliente.

Fluxo

O fluxo padrão é iniciado pela loja após o comprador finalizar a compra:

A loja deverá iniciar a transação com o e-SiTef enviando os dados da compra através do serviço de criação de transação.

O fluxo de recarga consiste nos seguintes passos:

1. Após o comprador finalizar a compra, a loja cria uma nova transação no e-SiTef, através de um POST na URL para iniciar uma transação, informando todos os parâmetros necessários. Saiba mais.
2. Como resposta ao POST, a loja receberá uma URL do e-SiTef a qual o comprador deve ser redirecionado. Esta URL será diferente a cada transação de recarga.
3. O comprador selecionará os dados de recarga como concessionária/operadora, ddd, número de telefone e valor da recarga, e visualizará dados associados a este valor, como validade, bônus, etc.
4. Após isto, o comprador seguirá com o fluxo de pagamento, selecionando a autorizadora de pagamento, dentre as disponíveis para a loja.
5. Na etapa final do pagamento, as transações de pagamento e de recarga serão efetivadas, respectivamente na autorizadora e na concessionária/operadora, nesta ordem.
6. Ao final do fluxo, o e-SiTef irá redirecionar de volta o comprador para a loja, conforme configuração de URL’s de retorno já cadastrados na loja, ou para as back_url’s (vide Tabela 1) enviadas na criação das transações.

Para cada alteração de status da transação de pagamento no e-SiTef, a loja receberá um POST de aviso de status, informando a situação da mesma. Saiba mais.

Todas as chamadas realizadas serão respondidas de forma síncrona exceto o aviso de status que será realizado pelo e-SiTef de forma assíncrona.

Iniciando uma transação de recarga

Para iniciar um recarga HTML, veja a documentação de quickstart.

Efetuando uma transação de recarga

Ao acessar a url retornada pelo serviço de criação de transação, a tela de seleção de valores de recarga será retornada, conforme a figura abaixo:

Quick start

Este guia mostra o processo de efetivação de um recarga, utilizando a interface HTML do e-SiTef.

O que você precisará

• Cadastro ativo no ambiente de homologação do e-SiTef (obtido com nossa equipe de suporte)
• Uma ferramenta capaz de realizar chamadas HTTP, como Postman, REST Client ou cURL
• Uma aplicação capaz de receber chamadas POST HTTPS

Criando a transação de recarga

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/init/json.se

Headers:

• Content-Type: application/x-www-form-urlencoded

Parâmetros do POST:

• Key/chave: request;
• Value/valor: objeto JSON;
• [tipo_de_retorno]: json ou xml;

Objeto JSON request mínimo:

JSON

cURL

{
    "recharge_included":"true",
    "merchant_id":"xxxxxxxxxx"
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/init/json.se"
--header "Content-Type: application/x-www-form-urlencoded"
-d 'request=%7B%22merchant_id%22%3A%22xxxxxxxxxx%22%2C%22recharge_included%22%3A%22true%22%7D'
--verbose

Resposta:

{
  "responseCode" : 0,
  "description" : "OK. Transaction successful.",
  "url" : "https://esitef-homologacao.softwareexpress.com.br/e-sitef/do.se?input['nit']=12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk",
  "nsuesitef" : "123451234512345",
  "nit" : "12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk"
}

Saiba mais sobre esse serviço.

Redirecionando o usuário

A loja deve então redirecionar o usuário para a URL retornada pelo e-SiTef na etapa de criação da transação.

Recebendo um aviso de status

Assim que o status da transação mudar, o e-SiTef notificará a loja com um POST em sua URL de status cadastrada.

Java + Spring Framework

@RestController
public class MyStatusController {

    @PostMapping(value = "/mystatus",
        consumes = "application/x-www-form-urlencoded; charset=utf-8")
    public ResponseEntity<String> myStatus(@RequestParam Map<String, String> request) {
        Log.info("status = " + request.get("status"));
        // ...
        return new ResponseEntity<>("OK", HttpStatus.OK);
    }

}

Saiba mais sobre esse serviço.

Iniciando uma transação de recarga

Processo de criação da transação

O processo de criação de transação deverá seguir os seguintes passos:

• A transação é criada conforme os parâmetros enviados na chave request e representados por um objeto JSON via POST na requisição;
• A loja recebe uma mensagem de sucesso ou erro, formatada como XML ou JSON, conforme o parâmetro "tipo de retorno" na URL enviada ao se iniciar uma transação.

URL para iniciar uma transação via POST HTTPS:

Ambiente de Homologação:
https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/init/[tipo_de_retorno].se
Ambiente de Produção
https://esitef-ec.softwareexpress.com.br/e-sitef/init/[tipo_de_retorno].se

Atenção: Nunca deve ser usado o IP ao invés do domínio esitef-ec.softwareexpress.com.br (ou esitef-homologacao.softwareexpress.com.br para ambiente de homologação). O IP pode mudar a qualquer instante e sem aviso prévio, logo é importante sempre utilizar o domínio para acessar o e-SiTef.

Parâmetros do POST:

• Key/chave: request;
• Value/valor: objeto JSON;
• [tipo_de_retorno]: json ou xml;

Exemplo de requisição JSON (JavaScriptObjectNotation):

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/init/json.se

Objeto JSON request mínimo:

{
    "merchant_id": "codigoDaLoja",
    "amount": "1800"
}

Objeto JSON "request" com alguns parametros adicionais:

{
    "merchant_id": "codigoDaLoja",
    "order_id": "123456",
    "installments": "4",
    "recharge_included":"true",
    "recharge":{
        "dealer_code":"2",
        "phone":{
            "number":"87654321",
            "ddd":"11"
        }
    }
}

Ferramentas para testes

Para testes iniciais nesta interface, caso necessário, podem ser usadas algumas ferramentas a fim de um melhor entendimento da comunicação via REST:

• Aplicação para Windows/Linux/Mac:
  • POSTMAN
• Extensão para Firefox:
  • RESTClient

Abaixo seguem exemplos de tela destas ferramentas:

Parâmetros de requisição

O objeto JSON additional_data possui campos que se alteram conforme a autorizadora utilizada para o pagamento, pelo campo authorizer_id. Para mais detalhes do campo additional_data, por favor consulte a documentação específica para cada autorizadora suportada pela Interface de Pagamento HTML 2.0.

Para iniciar uma transação na nova interface de pagamento HTML, inicialmente podem ser preenchidos os seguintes parâmetros no formato JSON.

{
    "merchant_id": "codigoDaLoja",
    "recharge_included":"true",
    "recharge":{ }
}

Parâmetro	Descrição	Formato	Obrigatório
amount	Valor total a ser pago pelo comprador. Formato: Deve ser enviado em centavos. Ex.: 1000 (10 reais).	< 12 N	SIM
recharge_included	Informa se uma recarga será feita. Valores permitidos: true – caso uma recarga for realizada. false – caso uma recarga não for realizada. Valor default - false	< 5 A	SIM
recharge	Objeto do tipo RECHARGE. Contêm dados relacionados a uma transação de recarga.		NÃO

RECHARGE (recharge)

{
    "dealer_code": "1",
    "phone": { },
}

Parâmetro	Descrição	Formato	Obrigatório
dealer_code	Código da concessionária/operadora	< 3 N	NÃO
phone	Objeto do tipo PHONE. Contêm dados relacionados ao telefone da recarga.		NÃO

PHONE (phone)

{
    "number": "123456789",
    "ddd": "11",
}

Parâmetro	Descrição	Formato	Obrigatório
number	número do telefone.	< 20 N	NÃO
ddd	ddd (código de área) do telefone.	< 4 N	NÃO

Parâmetros de resposta

O retorno da operação de criação de transação se dá na forma solicitada no [tipo de retorno].

Abaixo segue um exemplo de retorno JSON:

{
  "responseCode": 0,
  "description": "OK. Transaction successful.",
  "url": "https:// esitef-homologacao.softwareexpress.com.br/e-sitef/do.se?input['nit']= 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
  "nsuesitef": "123456789012345",
  "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
}

Os campos retornados são descritos na tabela abaixo:

Parâmetro	Descrição	Formato
responseCode	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 5 N
description	Descrição da resposta	< 1024 A
url	URL de redirecionamento para iniciar o pagamento.	< 256 A
nit	Identificador da transação no e-SiTef	= 64 A
nsuesitef	NSU (Número Sequencial Único) da transação no e-SiTef	= 15 A

Visão geral

O e-SiTef possui uma interface REST para a realização de operações genéricas. Entenda que as "operações genéricas" são operações exclusivas de determinados autorizadoras e que não se adequam ao operações padronizadas anteriores.

Nesta interface REST considere que cada código de operação depende de dados adicionais para que funcione conforme o esperado. Algumas destas operações necessitam de um token de autenticidade, a qual deve ser gerada para cada chamada da operação genérica. Para maiores detalhes de cada operação genérica, veja as documentações do roteamento configurado para sua loja.

Comunicação

Para realizar uma requisição de web service REST de operações genéricas, utilize as seguintes URLs base do e-SiTef:

URL base de Produção:

https://esitef-ec.softwareexpress.com.br/e-sitef/api

URL base de Homologação:

https://esitef-homologacao.softwareexpress.com.br/e-sitef/api

O que você precisará

• Uma aplicação capaz de receber chamadas POST HTTPS
• Cadastro ativo no ambiente do e-SiTef com a URL para o POST de autenticidade (solicite o cadastro à nossa equipe de suporte)

Fluxo

As operações genéricas possuem dois fluxos que dependem da obrigatoriedade do token de autenticidade para a execução da operação.

Descrição do fluxo:

1. Lojista solicita a geração de um token de autenticidade para as operações genéricas.
2. O e-SiTef gera um token de autenticidade internamente
3. O token de autenticidade gerado é enviado para a loja através de um POST na URL de autenticidade. A loja deve guardar este token.
4. A loja usa o token de autenticidade gerado para realizar uma operação genérica.
5. O e-SiTef valida e inativa o token de autenticidade antes de realizar a operação solicitada.
6. O e-SiTef realiza a operação genérica e obtem os resultados da operação.
7. O e-SiTef retorna o resultado da operação solicitada.

Obs: Existem operações genéricas que não necessitam do token de autenticidade, consulte o item correspondente à operação utilizada no roteamento de interesse para verificar esta necessidade.
No caso do token de autenticidade não ser necessário, os passos 1, 2 e 3 do fluxo acima não são necessários.

Serviço de geração de token

O consumo do serviço de geração de token é obrigatório em alguns fluxos de operações genéricas. Como resultado dessa operação, o lojista obterá um token pela URL de autenticidade que serão necessários para os próximos passos do fluxo.

Detalhes da chamada

• Recurso: /v1/token
• Método HTTP: GET
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Tipo	Tamanho	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	AN	< 15	Sim
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	AN	< 80	Sim

Em seguida, o e-SiTef irá enviar uma requisição POST HTTPS (x-www-form-urlencoded) para a URL cadastrada, este POST contém as informações necessárias para obter o token para ser utilizado nas operações genéricas.

Simulação de POST de autenticidade:

curl -X POST \
  https://urlDeAutenticidadeDaLoja.com.br \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'cache-control: no-cache' \
  -d 'token=1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr

Atenção: É essencial que o site hospedado na URL de Autenticidade da loja receba o token de autenticidade e responda HTTP 200, pois isto é condição para que o e-SiTef considere o sucesso deste POST.

Caso o POST de autenticidade tenha ocorrido com sucesso, o e-SiTef responderá um código "responseCode": "0" para a requisição da loja.

Serviço de operação genérica

O serviço de operação genérica depende da autorizadora / roteamento. Este capítulo irá se focar nas características em comum de cada operação. Para maiores detalhes de cada operação, veja a documentação elaborada para cada roteamento.

Detalhes da chamada

• Recurso: /v1/genericoperation
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Tipo (Tamanho)	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	AN (≤ 15)	Sim
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	AN (≤ 80)	Sim
Content-Type	Utilizar valor "application/json".	AN (= 15)	Sim

Parâmetro de requisição

Parâmetro	Descrição	Tipo (Tamanho)	Obrigatório
operation	Número identificador da operação que se deseja chamar.	N (≤ 3)	Sim
parameters	Conjunto de propriedades que devem ser enviadas para realizar a operação especificada no parâmetro operation.	AN (≤ 20)	Sim

Tabela descritiva dos parameters

Cada operação possui um conjunto de parâmetros. Abaixo segue os parâmetros com características em comum para todas as operações:

Parâmetro	Descrição	Tipo (Tamanho)	Obrigatório
token	Token de autenticidade que foi gerado pelo e-SiTef (Saiba mais)	AN (= 66)	Condicional por operação
authorizer_id	Código da autorizadora no e-SiTef (Saiba mais)	AN (≤ 3)	Sim
terminal_id	Valor numérico que representa um terminal lógico no SiTef. Um número de terminal lógico não pode ser usado ao mesmo tempo por duas requisições diferentes.	AN (= 8)	Sim
merchant_usn	NSU da operação gerado pela loja	N (≤ 12)	Sim
operator_code	Código do operador	N (= 2)	Não
supervisor_code	Código do supervisor	N (= 5)	Não
subfunction	Subfunção da operação. O valor deste campo deve estar condizente com a operação	N (= 2)	Sim

Resposta

A resposta depende de cada operação e será especificado na documentação de cada autorizadora/roteamento.

Pagamento JavaScript

Visão Geral

A interface de Pagamento JavaScript permite que a coleta dos dados do cartão do comprador seja realizada pelo e-SiTef na página do lojista, isentando a loja da manipulação destes dados sensíveis e deixando esta tarefa sob a responsabilidade do ambiente com certificação PCI DSS do e-SiTef.

Esta interface é recomendada a lojistas que desejam ter sua própria página de checkout, possuindo ao mesmo tempo um alto padrão de segurança.

Esta solução é integrada com a interface de pagamento REST. Saiba mais sobre Pagamento REST.

Fluxo

Descrição do fluxo:

• 1. O cliente envia os dados de sua compra e prossegue para a tela de pagamento.
  • 1.1. A Loja Virtual cria uma transação de pagamento no e-SiTef, enviando adicionalmente o parâmetro payment_js com valor true. Saiba mais.
  • 1.2. O e-SiTef retorna para a loja um NIT e um Pay Token.
  • 1.3. Loja exibe para o comprador a sua página de pagamento contendo o script do e-SiTef e os campos de dados de cartão com as classes especificadas em Campos com dados de cartão.
• 2. Cliente preenche os dados do seu cartão e clica em "pagar". Este clique deve chamar o script de pagamento do e-SiTef, passando como parâmetro o NIT, o Pay Token, o código da loja e as funções de callback (procedimentos do lojista que serão chamados após o pagamento do e-SiTef).
  • 2.1. O e-SiTef retorna o resultado do pagamento, incluindo código, mensagem e status da transação.
• 3. Callback do lojista é chamado, que envia a resposta do e-SiTef para o servidor da loja.
  • 3.1. A Loja Virtual realiza uma consulta da transação no e-SiTef. Saiba mais.
  • 3.2. O e-SiTef retorna o status da transação, assim como informações de autorização.
  • 3.3. A Loja Virtual analisa as informações recebidas e redireciona o comprador para uma tela de sucesso ou fracasso.

Quick start

Criando a transação

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

JSON

cURL

{
    "merchant_usn":"12042142155",
    "order_id":"12042142155",
    "installments":"1",
    "installment_type":"4",
    "authorizer_id":"2",
    "amount":"1000",
    "payment_js":"true"
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxx"
--data-binary
{
    "merchant_usn":"12042142155",
    "order_id":"12042142155",
    "installments":"1",
    "installment_type":"4",
    "authorizer_id":"2",
    "amount":"1000",
    "payment_js":"true"
}
--verbose

Resposta:

{
    "code":"0",
    "message":"OK. Transaction successful.",
    "payment":{
        "status":"NOV",
        "nit":"1234567890123456789012345678901234567890123456789012345678901234",
        "order_id":"12042142155",
        "merchant_usn":"12042142155",
        "amount":"1000",
        "pay_token":"123456789012345678901234567890123456789012345678901234567890123456"
    }
}

Saiba mais sobre esse serviço.

Página de pagamento da loja virtual

A página de pagamento do lojista deve conter o script do e-SiTef. Abaixo estão as URLs para download:

URL para ambiente de Produção:

https://esitef-ec.softwareexpress.com.br/js/esitefpayment-1.0.min.js

URL para ambiente de Homologação:

https://esitef-homologacao.softwareexpress.com.br/js/esitefpayment-1.0.min.js

Exemplo:

Abaixo está um exemplo de uma página integrada com o pagamento JavaScript do e-SiTef:

HTML

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8" />
    <script type="text/javascript" src="https://esitef-
homologacao.softwareexpress.com.br/js/esitefpayment-1.0.min.js"></script>
    <script>
        function myPay() {
            var request = {
                onSuccess: function(response) {
                    console.log(response.code);
                    console.log(response.message);
                    console.log(response.payment.authorizer_code);
                    console.log(response.payment.authorizer_message);
                    console.log(response.payment.status);
                    console.log(response.payment.nit);
                    console.log(response.payment.order_id);
                    console.log(response.payment.customer_receipt);
                    console.log(response.payment.authorizer_id);
                },
                onFailure: function(response) {
                    console.log(response.code);
                    console.log(response.message);
                    console.log(response.payment.authorizer_code);
                    console.log(response.payment.authorizer_message);
                    console.log(response.payment.status);
                    console.log(response.payment.nit);
                    console.log(response.payment.order_id);
                    console.log(response.payment.authorizer_id);
                },
                onInvalid: function(errors) {
                    for (var i = 0; i < errors.length; i++) {
                        console.log(errors[i].field);
                        console.log(errors[i].cause);
                    }
                },
                nit: '1234567890123456789012345678901234567890123456789012345678901234',
                payToken: '123456789012345678901234567890123456789012345678901234567890123456',
                merchantId: 'xxxxxxxx',
                locale: 'pt',
                isCardSecurityCodeOptional: false
            };
            esitefDoPayment(request);
        }
    </script>
</head>

<body>
    <form method="POST">
        <input type="text" class="esitef-cardnumber" />
        <input type="text" class="esitef-cardexpirymonth" />
        <input type="text" class="esitef-cardexpiryyear" />
        <input type="text" class="esitef-cardsecuritycode" />
        <input type="button" onclick="myPay()" />
    </form>
</body>

</html>

Serviço de criação da transação

O consumo desse serviço é obrigatório no fluxo de pagamento JavaScript. Adicionalmente aos parâmetros de requisição de pagamento REST, também deve ser enviado o seguinte parâmetro:

Parâmetro	Descrição	Formato	Obrigatório
payment_js	Deve ser enviado com o valor true para habilitar o fluxo de pagamento JavaScript.	< 5 A	SIM

Como resposta, o seguinte parâmetro será adicionalmente retornado:

Parâmetro	Descrição	Formato
	payment
pay_token	Token associado ao pagamento JavaScript.	= 66 AN

Para mais detalhes sobre essa chamada, consulte Pagamento REST.

Exemplo

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxx"
--data-binary
{
    "merchant_usn":"12042142155",
    "order_id":"12042142155",
    "installments":"1",
    "installment_type":"4",
    "authorizer_id":"2",
    "amount":"1000",
    "payment_js":"true"
}
--verbose

Resposta:

{
    "code":"0",
    "message":"OK. Transaction successful.",
    "payment":{
        "status":"NOV",
        "nit":"1234567890123456789012345678901234567890123456789012345678901234",
        "order_id":"12042142155",
        "merchant_usn":"12042142155",
        "amount":"1000",
        "pay_token":"123456789012345678901234567890123456789012345678901234567890123456"
    }
}

Pagamento com Armazenamento

Caso se deseje armazenar o cartão utilizado, basta enviar os seguintes campos:

Parâmetro	Descrição	Formato	Obrigatório
store_card	Deve ser enviado com o valor true para habilitar o fluxo de pagamento com armazenamento JavaScript.	< 5 A	NÃO
additional_data .payer .store_identification	Identificação do comprador para armazenamento de cartão. Este campo é obrigatório se for passado o campo store_card como true	< 20 N	COND

Como resposta, o seguinte parâmetro será adicionalmente retornado:

Parâmetro	Descrição	Formato
	store
nita	Número identificador de transação de armazenamento.	= 65 AN

Após a efetivação do pagamento, as informações do cartão armazenado serão enviadas para loja através de um Aviso de Armazenamento.

Exemplo

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxx"
--data-binary

{
    "merchant_usn": "571335733160",
    "order_id": "1571335733160",
    "installments": "1",
    "installment_type": "4",
    "amount": "1000",
    "authorizer_id": "2",
    "payment_js": "true",
    "store_card": "true",
    "additional_data":{
       "payer":{
           "store_identification":"1222"
       }
    }
 }
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "status": "NOV",
        "nit": "fa8d9a5b840cca22c467db6aaa22d61561cfcf299f5fba5b033ba43fb7bd35b2",
        "order_id": "1571335733160",
        "merchant_usn": "571335733160",
        "amount": "1000",
        "pay_token": "ef3d19cb2c0db0d8c54945da8130b9f47aeb14f3b2f884ef151ecf18d2683d3601"
    },
    "store": {
        "nita": "Z529ebaf6342d0ab680c51c4ec8409bdc0dd43a00bf9956c2f60f7e76f3476419"
    }
}

Página de pagamento da loja virtual

A página de pagamento do lojista deve conter o script do e-SiTef. Abaixo estão as URLs para download:

URL para ambiente de Produção:
https://esitef-ec.softwareexpress.com.br/js/esitefpayment-1.0.min.js

URL para ambiente de Homologação:
https://esitef-homologacao.softwareexpress.com.br/js/esitefpayment-1.0.min.js

Campos com dados de cartão

Os campos de cartão devem conter as classes especificadas abaixo:

Parâmetro	Descrição	Formato	Obrigatório
esitef-cardnumber	Número do cartão do comprador (PAN).	< 19 N	SIM
esitef-cardexpirydate	Data de vencimento do cartão no formato MMAA.	= 4 N	SIM
esitef-cardexpirymonth & esitef-cardexpiryyear	Mês e ano de vencimento do cartão, nos formatos MM e AA, respectivamente. Esses campos podem ser enviados no lugar de esitef-cardexpirydate. Caso sejam todos enviados ao mesmo tempo, a data separada (esitef-cardexpirymonth e esitef-cardexpiryyear) terá prioridade.	= 2 N	SIM
esitef-cardsecuritycode	Código de segurança do cartão.	< 5 N	SIM
esitef-cardholder	Nome do portador do cartão. Obrigatório apenas para pagamentos com e-Rede, GetNet WS e VR AN (SmartNet).	< 30 AN	COND.

Chamando o script do e-SiTef

Quando o comprador preencher os dados do cartão e clicar em "pagar", a página do lojista deve chamar a function Javascript esitefDoPayment passando como argumento uma requisição com os seguintes campos:

Parâmetro	Descrição	Formato	Obrigatório
nit	Identificador de transação no e-SiTef. Campo nit recebido na etapa de criação da transação.	= 64 AN	SIM
payToken	Campo pay_token recebido na etapa de criação da transação. Este token só pode ser utilizado uma vez.	= 66 AN	SIM
merchantId	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 N	SIM
locale	Linguagem das mensagens retornadas em erros de validação (callback "onInvalid"). Pode receber os seguintes valores: pt - Português en - Inglês es - Espanhol Caso o locale não seja enviado, será utilizado pt.	= 2 A	NÃO
isCardSecurityCode Optional	Define se o código de segurança do cartão será validado como campo obrigatório ou opcional. Enviar true caso seja um campo opcional. Caso esse campo não seja enviado, será considerado o valor false (código de segurança obrigatório).	T/F	NÃO
onSuccess	Function de callback que será chamada após um pagamento bem-sucedido no e-SiTef. Esta function recebe como argumento a resposta do pagamento descrita em - Resposta dos callbacks de sucesso e fracasso.	F	SIM
onFailure	Function de callback que será chamada após um pagamento mal sucedido no e-SiTef. Esta function recebe como argumento a resposta do pagamento descrita em - Resposta dos callbacks de sucesso e fracasso.	F	SIM
onInvalid	Function de callback que será chamada após um erro de validação JavaScript. Esta function recebe como argumento a lista de erros descrita em - Resposta do callback de erro de validação.	F	SIM

Resposta dos callbacks de sucesso e fracasso

As functions de callback onSuccess e onFailure recebem como argumento um objeto contendo informações referentes ao pagamento. Abaixo estão as descrições desses campos:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0 (zero) significa falha. Para maiores informações, consulte os Códigos de Resposta.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	payment
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
status	Status da transação de pagamento no e-SiTef.	= 3 AN
nit	Número identificador da transação de pagamento no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
customer_receipt	Cupom (via cliente).	< 4000 AN
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N

Resposta do callback de erro de validação

A function de callback onInvalid recebe como argumento uma lista de objetos de erro de validação, contendo os campos abaixo:

Parâmetro	Descrição	Formato
field	Nome do campo com erro.	< 30 AN
cause	Mensagem de erro.	<100 AN

Exemplo

Abaixo está um exemplo de uma página integrada com o pagamento JavaScript do e-SiTef:

HTML

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8" />
    <script type="text/javascript" src="https://esitef-
homologacao.softwareexpress.com.br/js/esitefpayment-1.0.min.js"></script>
    <script>
        function myPay() {
            var request = {
                onSuccess: function(response) {
                    console.log(response.code);
                    console.log(response.message);
                    console.log(response.payment.authorizer_code);
                    console.log(response.payment.authorizer_message);
                    console.log(response.payment.status);
                    console.log(response.payment.nit);
                    console.log(response.payment.order_id);
                    console.log(response.payment.customer_receipt);
                    console.log(response.payment.authorizer_id);
                },
                onFailure: function(response) {
                    console.log(response.code);
                    console.log(response.message);
                    console.log(response.payment.authorizer_code);
                    console.log(response.payment.authorizer_message);
                    console.log(response.payment.status);
                    console.log(response.payment.nit);
                    console.log(response.payment.order_id);
                    console.log(response.payment.authorizer_id);
                },
                onInvalid: function(errors) {
                    for (var i = 0; i < errors.length; i++) {
                        console.log(errors[i].field);
                        console.log(errors[i].cause);
                    }
                },
                nit: ‘1234567890123456789012345678901234567890123456789012345678901234’,
                payToken: ‘123456789012345678901234567890123456789012345678901234567890123456’,
                merchantId: 'xxxxxxxx',
                locale: 'pt',
                isCardSecurityCodeOptional: false
            };
            esitefDoPayment(request);
        }
    </script>
</head>

<body>
    <form method="POST">
        <input type="text" class="esitef-cardnumber" />
        <input type="text" class="esitef-cardexpirymonth" />
        <input type="text" class="esitef-cardexpiryyear" />
        <input type="text" class="esitef-cardsecuritycode" />
        <input type="button" onclick="myPay()" />
    </form>
</body>

</html>

Serviço de consulta de transação

Este serviço deve ser chamado após o recebimento dos callbacks de sucesso ou fracasso para assegurar o status da transação e obter mais informações referentes ao pagamento. Esta operação também deve ser utilizada para sondar a situação da transação, enquanto uma resposta por parte da página de pagamento não é recebida.

Para mais detalhes sobre essa chamada consulte Serviço de consulta de transação do Pagamento REST.

Armazenamento JavaScript

A interface de Armazenamento JavaScript permite que a coleta dos dados do cartão do comprador seja realizada pelo e-SiTef na página do lojista, isentando a loja da manipulação destes dados sensíveis e deixando esta tarefa sob a responsabilidade do ambiente com certificação PCI DSS do e-SiTef.

Esta interface é recomendada a lojistas que desejam ter sua própria página de checkout, possuindo ao mesmo tempo um alto padrão de segurança.

Fluxo

Descrição do fluxo:

• 1. O cliente envia os dados de sua compra e prossegue para a tela de armazenamento.
  • 1.1. A Loja Virtual cria uma transação de armazenamento no e-SiTef, enviando os parâmetros customer_id e merchant_usn.
  • 1.2. O e-SiTef retorna para a loja um NITA e um Store Token.
  • 1.3. Loja exibe para o comprador a sua página contendo o script do e-SiTef e os campos de dados de cartão com as classes especificadas em Campos com dados de cartão.
• 2. Cliente preenche os dados do seu cartão e realiza o submit dos dados do cartão. Chama o script de armazenamento do e-SiTef, passando como parâmetro o NITA, o Store Token, o código da loja, id da autorizadora e as funções de callback (procedimentos do lojista que serão chamados após o armazenamento do e-SiTef).
  • 2.1. De modo síncrono, o e-SiTef fará um POST HTTPS na URL de armazenamento informada pelo lojista e cadastrada no backoffice do e-SiTef. O POST enviado conterá o Hash do cartão armazenado. Saiba mais.
  • 2.2. A resposta da loja ao POST HTTPS obrigatoriamente deve ser "200 OK".
  • 2.3.O e-SiTef retorna o resultado do armazenamento, incluindo código, mensagem, status da transação, nsu da loja e nita.
  • 2.4. Callback do lojista é chamado.

Quick start

Criando a transação

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/store

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {sua chave da loja}

Requisição:

JSON

cURL

{
   "merchant_usn":"16013439434",
   "customer_id":"11122211122"
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/store"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"16013439434",
   "customer_id":"11122211122"
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "store":{
      "status":"CON",
      "nsua":"18051600000560A",
      "merchant_usn":"16013439434",
      "customer_id":"11122211122",
      "nita":"Z123adsfrh342r72498r34920ur23r328r2038r023rh0h203rh032r082380rf43",
      "store_token": "123456789012345678901234567890123456789012345678901234567890123456"
   }
}

Saiba mais sobre esse serviço.

Página de pagamento da loja virtual

A página do lojista deve conter o script do e-SiTef. Abaixo estão as URLs para download:

URL para ambiente de Produção:

https://esitef-ec.softwareexpress.com.br/js/esitefstore-1.0.min.js

URL para ambiente de Homologação:

https://esitef-homologacao.softwareexpress.com.br/js/esitefstore-1.0.min.js

Exemplo:

Abaixo está um exemplo de uma página integrada com o armazenamento JavaScript do e-SiTef:

HTML

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8" />
    <script type="text/javascript" src="https://esitef-homologacao.softwareexpress.com.br/js/esitefstore-1.0.min.js"></script>
    <script>
        function myStore() {
            var request = {
                onSuccess: function(response) {
                    console.log(response.code);
                    console.log(response.message);
                    console.log(response.store.status);
                    console.log(response.store.nita);
                    console.log(response.store.merchant_usn);
                },
                onFailure: function(response) {
                    console.log(response.code);
                    console.log(response.message);
                    console.log(response.store.status);
                    console.log(response.store.nita);
                    console.log(response.store.merchant_usn);
                },
                onInvalid: function(errors) {
                    for (var i = 0; i < errors.length; i++) {
                        console.log(errors[i].field);
                        console.log(errors[i].cause);
                    }
                },
                nita: 'Zdn2482f8924jh8fh842390hfef2fij20fj40jf024jf9j240hf4hjf0h243f84jf',
                storeToken: '123456789012345678901234567890123456789012345678901234567890123456',
                merchantId: 'xxxxxxxx',
                locale: 'pt',
                authorizerId: '2'
            };
            esitefStore(request);
        }
    </script>
</head>

<body>
    <form method="POST">
        <input type="text" class="esitef-cardnumber" />
        <input type="text" class="esitef-cardexpirymonth" />
        <input type="text" class="esitef-cardexpiryyear" />
        <input type="button" onclick="myStore()" />
    </form>
</body>

</html>

Recebendo um aviso de armazenamento

Assim que o armazenamento for concluído, o e-SiTef notificará a loja com um POST (x-www-form-urlencoded) em sua URL de armazenamento cadastrada, contendo o token do cartão armazenado.

Java + Spring Framework

@RestController
public class MyStoreController {

    @PostMapping(value = "/mystore", 
        consumes = "application/x-www-form-urlencoded; charset=utf-8")
    public ResponseEntity<String> myStore(@RequestParam Map<String, String> request) {
        Log.info("token = " + request.get("hash"));
        // ...
        return new ResponseEntity<>("OK", HttpStatus.OK);
    }

}

Abaixo segue um exemplo de requisição a ser feita pelo e-SiTef no domínio cadastrado pela loja:

cURL

curl -X POST \
  https://urlDaLojaCadastrada.com.br \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Postman-Token: 08e28c6b-77f6-437a-9bbe-de56bd614e0a' \
  -H 'cache-control: no-cache' \
  -d 'nsua=9055020677&nita=1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr&nsu=09055020677&status=CON&hash=67890afghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr&bin=498406&final=2268&autorizadora=1'

Saiba mais sobre esse serviço.

Serviço de criação da transação

Detalhes da chamada

• Recurso: /v1/store
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Headers:
  • Content-Type: application/json
  • merchant_id: {seu código de loja}
  • merchant_key: {sua chave da loja}

O consumo desse serviço é obrigatório no fluxo de armazenamento JavaScript.

Parâmetros de requisição

Os seguintes parâmetros de requisição devem ser enviados:

Parâmetro	Descrição	Formato	Obrigatório
merchant_usn	Número sequencial único para cada pedido, criado pela loja.	< 12 N	SIM
customer_id	Identificação do comprador para armazenamento de cartão. Esta identificação deve ser única para cada usuário da loja. Mas atenção, essa garantia de unicidade é de total responsabilidade da loja, o e-SiTef não realizará nenhuma validação.	< 20 AN	SIM

Parâmetros de resposta

Na tabela abaixo está a descrição dos parâmetros de resposta:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	store
status	Status da transação de armazenamento no e-SiTef. Saiba mais.	= 3 AN
nsua	Número sequencial único da transação de armazenamento no e-SiTef.	= 15 AN
nita	Número identificador criptografado da transação de armazenamento devolvido à loja pelo e-SiTef.	< 65 AN
merchant_usn	Número sequencial único enviado pela loja.	< 12 N
customer_id	Identificação do comprador para armazenamento de cartão.	< 20 AN
store_token	Token associado ao armazenamento JavaScript.	= 66 AN

Exemplo

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/store"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"16013439434",
   "customer_id":"11122211122"
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "store":{
      "status":"CON",
      "nsua":"12345600000560A",
      "merchant_usn":"16013439434",
      "customer_id":"11122211122",
      "nita":"Z123adsfrh342r72498r34920ur23r328r2038r023rh0h203rh032r082380rf43",
      "store_token": "123456789012345678901234567890123456789012345678901234567890123456"
   }
}

Página da loja virtual

A página do lojista deve conter o script do e-SiTef. Abaixo estão as URLs para download:

URL para ambiente de Produção:
https://esitef-ec.softwareexpress.com.br/js/esitefstore-1.0.min.js

URL para ambiente de Homologação:
https://esitef-homologacao.softwareexpress.com.br/js/esitefstore-1.0.min.js

Campos com dados de cartão

Os campos de cartão devem conter as classes especificadas abaixo:

Parâmetro	Descrição	Formato	Obrigatório
esitef-cardnumber	Número do cartão do comprador (PAN).	< 19 N	SIM
esitef-cardexpirydate	Data de vencimento do cartão no formato MMAA.	= 4 N	SIM
esitef-cardexpirymonth & esitef-cardexpiryyear	Mês e ano de vencimento do cartão, nos formatos MM e AA, respectivamente. Esses campos podem ser enviados no lugar de esitef-cardexpirydate. Caso sejam todos enviados ao mesmo tempo, a data separada (esitef-cardexpirymonth e esitef-cardexpiryyear) terá prioridade.	= 2 N	SIM

Chamando o script do e-SiTef

Quando o comprador preencher os dados do cartão e realizar o submit, a página do lojista deve chamar a function Javascript esitefStore passando como argumento uma requisição com os seguintes campos:

Parâmetro	Descrição	Formato	Obrigatório
nita	Número identificador criptografado da transação de armazenamento devolvido à loja pelo e-SiTef.	< 65 A	SIM
storeToken	Campo store_token recebido na etapa de criação da transação. Este token só pode ser utilizado uma vez.	= 66 AN	SIM
merchantId	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 N	SIM
locale	Linguagem das mensagens retornadas em erros de validação (callback "onInvalid"). Pode receber os seguintes valores: pt - Português en - Inglês es - Espanhol Caso o locale não seja enviado, será utilizado pt.	= 2 A	NÃO
authorizer_id	Código da autorizadora no e-SiTef. Saiba mais.	< 3 N	SIM
onSuccess	Function de callback que será chamada após um armazenamento bem-sucedido no e-SiTef. Esta function recebe como argumento a resposta do armazenamento descrita em - Resposta dos callbacks de sucesso e fracasso.	F	SIM
onFailure	Function de callback que será chamada após um armazenamento mal sucedido no e-SiTef. Esta function recebe como argumento a resposta do armazenamento descrita em - Resposta dos callbacks de sucesso e fracasso.	F	SIM
onInvalid	Function de callback que será chamada após um erro de validação JavaScript. Esta function recebe como argumento a lista de erros descrita em - Resposta do callback de erro de validação.	F	SIM

Resposta dos callbacks de sucesso e fracasso

As functions de callback onSuccess e onFailure recebem como argumento um objeto contendo informações referentes ao armazenamento. Abaixo estão as descrições desses campos:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0 (zero) significa falha. Para maiores informações, consulte os Códigos de Resposta.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	store
status	Status da transação de armazenamento no e-SiTef.	= 3 AN
nita	Número identificador da transação de armazenamento no e-SiTef.	= 65 AN
merchant_usn	Número sequencial único enviado pela loja.	< 12 N

Resposta do callback de erro de validação

A function de callback onInvalid recebe como argumento uma lista de objetos de erro de validação, contendo os campos abaixo:

Parâmetro	Descrição	Formato
field	Nome do campo com erro.	< 30 AN
cause	Mensagem de erro.	< 100 AN

Exemplo:

Abaixo está um exemplo de uma página integrada com o armazenamento JavaScript do e-SiTef:

HTML

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8" />
    <script type="text/javascript" src="https://esitef-homologacao.softwareexpress.com.br/js/esitefstore-1.0.min.js"></script>
    <script>
        function myStore() {
            var request = {
                onSuccess: function(response) {
                    console.log(response.code);
                    console.log(response.message);
                    console.log(response.store.status);
                    console.log(response.store.nita);
                    console.log(response.store.merchant_usn);
                },
                onFailure: function(response) {
                    console.log(response.code);
                    console.log(response.message);
                    console.log(response.store.status);
                    console.log(response.store.nita);
                    console.log(response.store.merchant_usn);
                },
                onInvalid: function(errors) {
                    for (var i = 0; i < errors.length; i++) {
                        console.log(errors[i].field);
                        console.log(errors[i].cause);
                    }
                },
                nita: 'Zdn2482f8924jh8fh842390hfef2fij20fj40jf024jf9j240hf4hjf0h243f84jf',
                storeToken: '123456789012345678901234567890123456789012345678901234567890123456',
                merchantId: 'xxxxxxxx',
                locale: 'pt',
                authorizerId: '2'
            };
            esitefStore(request);
        }
    </script>
</head>

<body>
    <form method="POST">
        <input type="text" class="esitef-cardnumber" />
        <input type="text" class="esitef-cardexpirymonth" />
        <input type="text" class="esitef-cardexpiryyear" />
        <input type="button" onclick="myStore()" />
    </form>
</body>

</html>

Introdução

Visão Geral

O Portal do Lojista do e-SiTef é uma ferramenta de gerência das lojas cadastradas para um usuário.

Por meio dele é possível ter controle sobre parâmetros da loja, bem como obter informações através de relatórios. Também é possível ter permissão para cancelar transações, dependendo do perfil configurado para o lojista.

Todas as chamadas realizadas serão respondidas de forma síncrona exceto o aviso de status que será realizado pelo e-SiTef de forma assíncrona.

Acesso ao Portal

Para usar o Portal do Lojista, acesse o link: https://esitef.softwareexpress.com.br/e-sitef-loja/.

Faça o login preenchendo os campos Usuário e Senha nos espaços correspondentes, tais como na figura abaixo:

Caso algum dos campos seja inválido, será mostrada uma mensagem de erro logo acima dos campos, destacada na figura a seguir:

Se os dados estiverem corretos você será encaminhado para a tela de página inicial do portal:

Note que os links no menu principal depende do perfil configurado ao usuário**.

Primeiro Acesso

A realização do primeiro acesso pode ocorrer com dados de usuário e senha fornecidos pela equipe de produção do e-SiTef ou por outro usuário que tenha acesso a criação de novos acessos.

Esses dados podem ser provisórios ou definidos através de um e-mail contendo um link para definição de senha.

Dados de acesso via e-mail

Um link para definição da senha de acesso é encaminhado para o e-mail fornecido no cadastro. Caso não localize o e-mail na sua caixa de entrada, verifique a caixa de spam.

Abaixo o conteúdo do e-mail de definição de senha:

Assunto: Definição de Senha | e-SiTef
Lojista, Seu usuário do e-SiTef foi criado com nome: lojista Por favor, clique no link abaixo para definir sua senha: https://esitef.softwareexpress.com.br/e-sitef-loja/acesso/primeiraSenha.se?token=abcd12345_exemplodetoken== Obrigado pela preferência, Equipe e-SiTef

Ao acessar o link fornecido no e-mail você será direcionado para uma tela de definição de senha, na mesma será solicitado a senha que será utilizada no seu acesso ao portal.

Após a definição da senha, você será encaminhado para outra página confirmando o sucesso do procedimento.

Clique em “Ir para página inicial” e inicie o processo de login com o usuário informado no e-mail e a senha que definiu:

Dados de acesso provisórios

Logo ao efetuar o primeiro acesso com os dados provisórios, o usuário será prontificado a alterar sua senha. Será apresentada uma tela semelhante à da figura a seguir:

Os campos Nova senha e Confirme a nova senha devem ser preenchidos de forma idêntica.

Só serão aceitas senhas de no mínimo oito caracteres e força pelo menos Mediana.

Os níveis são calculados de acordo com o tamanho da senha e tipos de caracteres utilizados nela.

A figura seguinte abaixo mostra os diferentes níveis de senha que podem ser obtidos.

Após mudar a senha, o usuário será direcionado para a página inicial do portal.

Redefinição de senha

Para iniciar o processo de redefinição de senha, clique em “Esqueci minha senha” na tela inicial de login do portal:

Será solicitado que você preencha o seu login:

Após confirmar, será exibida a seguinte tela:

Será encaminhado um e-mail para o endereço de e-mail cadastrado com o seguinte conteúdo:

Assunto: Redefinição de Senha | e-SiTef
Lojista, Recebemos uma solicitação de redefinição da senha do seu usuário no Portal e-SiTef, clique no link abaixo para prosseguir: https://esitef.softwareexpress.com.br/e-sitef-loja/acesso/entradaReset.se?token=abcd12345_exemplodetoken== Se você não efetuou a solicitação, pode ignorar este e-mail. Obrigado pela preferência, Equipe e-SiTef

Ao acessar o link fornecido no e-mail você será direcionado para uma tela de definição de senha. Defina a nova senha que será utilizada no seu acesso ao portal.

Após a definição da senha, você será encaminhado para outra página confirmando o sucesso do procedimento.

Clique em “Ir para página inicial” e inicie o processo de login com o usuário informado no e-mail e a senha que definiu:

Autenticação em duas etapas

Para garantir maior comodidade e segurança aos seus clientes, o e-SiTef oferece a autenticação em dois fatores, em que, além do login na plataforma, é necessário informar um código de verificação de uso único exibido num app previamente configurado. Para fins de simplificação, assumimos o Google Authenticator como o app utilizado na nossa documentação.

O que você precisará

• Cadastro ativo no ambiente de homologação do e-SiTef (obtido com nossa equipe de suporte);
• A funcionalidade de autenticação em duas etapas habilitada pelo supervisor;
• Instalação do app Google Authenticator num dispositivo móvel seguro.

Habilitando a autenticação em duas etapas para outros usuários

Um usuário com perfil Lojista - Administrador possui acesso ao cadastro de usuários e pode também habilitar esta funcionalidade para seus demais usuários.

Para fazer essa habilitação, o administrador/supervisor deve ir ao Cadastro de Usuários e editar o cadastro do mesmo.

Na tela de edição, encontram-se os campos Status de geração de QR Code e Data limite para geração do QR Code, além do link para habilitar a autenticação em 2 etapas para o usuário selecionado.

Basta clicar no link que uma data padrão será preenchida no campo de data limite. Clicando em Salvar efetivará essa habilitação.

Cadastrando a autenticação em duas etapas

Com a funcionalidade de autenticação em duas etapas habilitada pela equipe de suporte e feito o login no Portal Lojista, acesse a opção Autenticação em duas etapas no menu de usuário, conforme imagem abaixo:

Se todos os pré-requisitos estiverem corretos, você deverá receber uma tela parecida com a seguinte:

Com o app devidamente configurado no dispositivo móvel, ao clicar em Visualizar QR Code, uma tela como a seguinte deverá ser exibida:

Dentro do app Google Authenticator, selecione a opção de Ler Código QR e aponte a câmera para o código QR exibido na tela. Um número de 6 dígitos será exibido em seguida no celular, o qual deve ser inserido no campo indicado na tela do Portal Lojista e, por fim, clicar em Prosseguir.

ATENÇÃO: NUNCA informe este código para terceiros. Ele é pessoal e intransferível. Caso tenha algum problema ou dúvida, entre em contato com a nossa equipe de suporte, a qual em nenhuma circunstância solicita sua senha ou este código de autenticação.

Se tudo correu bem, será exibida uma mensagem de sucesso ou a próxima tela da etapa da operação que você estava tentando fazer, e o seu usuário estará habilitado para a autenticação em duas etapas. Sempre que exigido, você deverá acessar o Google Authenticator e digitar no campo indicado na tela do Portal Lojista o número de 6 dígitos exibido no app.

Configurações do usuário

Alterar senha

Para alterar a senha cadastrada, basta clicar no nome do usuário na borda superior da página, indicado na figura abaixo:

O usuário verá a tela apresentada no item Redefinição de senha do Acesso ao Portal. Basta seguir os mesmos procedimentos e a senha será alterada ao final do processo.

Alterar idioma

Para alterar o idioma do portal, basta clicar no ícone da bandeira correspondente ao idioma desejado, no canto superior direito da página, indicado na figura a seguir.

O idioma padrão é português PT-BR.

Configurar Autorizadoras

A opção Configurar Autorizadoras permite alterar os parâmetros referentes às autorizadoras cadastradas para uma determinada loja. Através dela, é possível modificar o status da autorizadora, tipo de roteamento, e propriedades referentes ao parcelamento.

IMPORTANTE: Para realizar configurações em autorizadoras que possuem parâmetros extras pelo Portal do Lojista, será exigido o código de autenticação em duas etapas para concluir a configuração. Caso esse método de autenticação não esteja habilitado, será exibida na tela instruções sobre qual procedimento deve ser tomado para continuar. Para mais informações sobre essa autenticação e como habilitá-la, clique aqui.

Para prosseguir com a configuração de autorizadoras, siga os procedimentos abaixo.

1. Clique em Configurar Autorizadoras, no menu principal:

2. Selecione a loja na qual deseja realizar a configuração:

Observação:

Caso o usuário só possua uma loja cadastrada, a tela abaixo não será mostrada, então pule para o próximo passo.

Para selecionar uma loja, basta clicar em um dos respectivos dados: código da loja, nome fantasia, ou razão social. Todos redirecionam para a página mostrada no próximo passo.

O botão VOLTAR retorna para a página inicial do portal.

3. Selecione a autorizadora que deseja configurar:

Para selecionar uma autorizadora, basta clicar num dos respectivos dados: id da autorizadora, autorizadora, status da autorizadora, ou tipo de roteamento. Todos redirecionam para a página mostrada no próximo passo.

O botão VOLTAR retorna para a tela de lojas cadastradas para configuração de autorizadoras.

ATENÇÃO: Caso a autorizadora selecionada possua parâmetros extras e o método de autenticação em duas não esteja habilitado, será exibida uma tela de instruções para configurar a autenticação em duas etapas.

Para mais informações sobre essa autenticação e como habilitá-la, clique aqui.

4. Preencha os campos de acordo com o desejado:

Clique no botão Salvar para consolidar a configuração realizada. A mensagem de confirmação de sucesso está destacada na figura abaixo.

O botão VOLTAR retorna para a tela de autorizadoras cadastradas para a loja.

Em alguns casos, a autorizadora possui parâmetros de configuração adicionais que precisam ser inseridos para a operação correta com a mesma, como no exemplo abaixo:

ATENÇÃO:

Conforme as necessidades de cada autorizadora, um grupo de parâmetros diferentes serão solicitados.

Nesses casos ao clicar em salvar será exigido o token da Autenticação em Dois Fatores.

Para mais informações, clique aqui.

Em alguns casos, é cadastrado um parâmetro do tipo senha:

Neste caso deve-se inserir uma senha já cadastrada junto à autorizadora/rede roteadora. Para inserir uma senha ou atualizar com uma nova senha, deve-se preenchê-la repetidamente no campo Novo(a) e Confirmar Novo(a). Caso a senha inserida não seja a mesma em ambos os campos, uma mensagem de erro é apresentada, como na figura a seguir:

Caso a senha seja inserida ou alterada com sucesso, uma mensagem de sucesso será apresentada na tela:

Relatório de Transações

O Relatório de Transações permite visualizar todas as transações registradas em suas lojas num determinado período de tempo. Vários filtros são aplicáveis na listagem das transações, e funcionalidades como gráficos também estão disponíveis para o lojista.

Para acessar esse relatório, coloque o cursor do mouse sobre o link Relatórios do menu principal, e um sub-menu aparecerá. Depois, clique em Relatório de Transações conforme figura abaixo:

Assim uma tela semelhante a abaixo será apresentada:

Nesta tela, o lojista tem a opção de definir filtros que deseja aplicar antes de gerar a listagem das transações do período de tempo determinado. A tabela a seguir descreve os filtros possíveis para este relatório:

Tabela 1: Filtros do Relatório de Transações.

Filtro	Descrição
Data Inicial *	Data inicial de referência para listagem das transações
Data Final *	Data final de referência para listagem das transações
NSU Transação	Número único correspondente à transação
NSU Loja	Número sequencial da loja
Hora Inicial	Hora inicial de referência para listagem das transações
Hora Final	Hora final de referência para listagem das transações
Código Pedido	Identificação do pedido realizado à loja
Documento	Identificação do cliente
Tipo	Tipo da transação (Pagamento, Estorno, Recarga, Consulta AVS, Pré-autorização ou Captura de pré-autorização).
Código Loja	Loja cadastrada para o lojista
Autorizadora	Autorizadora cadastrada na loja
Status	Status da transação (Nova, Aguardando usuário, Aguardando pagamento, Pagamento pendente de confirmação, Pagamento desfeito, Confirmada, Expirada, Cancelada, Negada, Inválida, Estornada, Bloqueada, Abandonada, Removida, Erro de comunicação).

Atenção:

Note que os campos de Data, com marcação *, são de preenchimento obrigatório e não deverão ultrapassar uma diferença de 3 (três) meses.

Vale ressaltar que os campos Hora Inicial e Hora Final só são aplicados caso o filtro de Data corresponda a um único dia (ou seja, apresente o mesmo dia tanto na Data Inicial quanto na Data Final). Caso o período de tempo seja maior que um dia, os campos de hora serão ignorados na listagem de transações.

Por fim, depois de definir os filtros desejados, basta clicar em Buscar. Você receberá uma lista com todas as transações que satisfazem os critérios determinados. A tela é semelhante à da figura a seguir:

Nesta lista, estão presentes várias funcionalidades úteis ao lojista. Por exemplo, é possível ordenar as transações por ordem numérica ou alfabética de algum dos parâmetros principais. Para isso, basta clicar em algum dos títulos de parâmetro – NSU TRANSAÇÃO, TIPO, STATUS, LOJA, PEDIDO, VALOR, DATA.

Clicar uma vez ordena as transações em ordem ascendente. Clicar outra vez as ordena em ordem descendente. O padrão da listagem é organizar as transações em ordem da mais recente para a menos recente.

Também é possível ver mais detalhes sobre a transação. Para isso, basta clicar no ícone , ao final da linha correspondente à transação:

Isto abrirá um espaço com mais detalhes sobre a transação:

É possível ocultar estes detalhes clicando no ícone , ao final da linha correspondente à transação (no mesmo lugar onde foi clicado em no ícone ).

Também é possível exibir os detalhes de todas as transações da lista. Para isso, basta clicar no título de parâmetro DETALHES. Clicar uma vez exibe os detalhes de todas as transações da lista. Clicar de novo oculta todos os detalhes.

Gráficos de transações

Outra funcionalidade existente ao lojista é a possibilidade de visualizar gráficos correspondentes à listagem de transações exibida. Podem ser gerados gráficos por status da transação, ou por autorizadora. Para visualizar estes gráficos, basta clicar em GERAR GRÁFICO POR STATUS, ou GERAR GRÁFICO POR AUTORIZADORA, destacados na figura a seguir:

Após clicar em um desses links, seu navegador abrirá uma janela pop-up para exibir este gráfico. A figura abaixo é um exemplo do visual do gráfico gerado:

Exportação em arquivo CSV

Mais uma funcionalidade presente neste relatório é a possibilidade de exportar a lista de transações em um arquivo CSV (lista de dados separados por ponto-e-vírgula), que pode ser trabalhado no Microsoft Excel ou um programa similar.

Para isso, basta clicar em EXPORTAR ARQUIVO CSV, destacado na figura a seguir:

Em seguida seu navegador efetuará o download do arquivo CSV.

A tabela seguinte apresenta os campos que compõe o arquivo:

Tabela 2: Campos exportados em CSV.

Campo	Descrição
NSU	NSU (número sequencial único) no e-SiTef
TIPO	Tipo da transação
STATUS	Status da transação no e-SiTef
CODIGOLOJA	Código da loja (merchant id)
NOMELOJA	Nome fantasia da loja
PEDIDO	Código do pedido
VALOR	Valor da transação (centavos)
DATACRIACAO	Data de criação da transação no e-SiTef
DATAEFETIVACAO	Data de efetivação da transação no e-SiTef
DATAEFETIVACAOOSITEF	Data de efetivação no SiTef ou adquirente direto
IDAUTORIZADORA	Código da autorizadora (authorizer id) no e-SiTef
NOMEAUTORIZADORA	Nome da autorizadora no e-SiTef
TIPOPAGAMENTO	Roteamento da transação
RESPOSTASITEF	Código de Resposta do SiTef ou adquirente direto
MENSAGEMSITEF	Mensagem de Resposta do SiTef ou adquirente direto
NSUSITEF	NSU no SiTef
NSUHOST	NSU no Host
NSULOJA	NSU da Loja
AUTORIZACAO	Código de Autorização
PARCELAS	Parcelas da transação
FINANCIAMENTO	Tipo de financiamento: 3 - parcelado com juros 4 - parcelado sem juros
TID	TID (Transaction ID) - identifica a transação na adquirente em integrações diretas
ECI	ECI (Electronic Commerce Indicator) - indica o nível de segurança da transação eletrônica em relação a autenticação de portador do cartão.
ESTILO	Estilo da Transação: V - POS Virtual
AVISOS	Tentativas de Aviso a Loja sobre status de transações HTML
FALHAS	Tentativas com Falha de Aviso a Loja sobre status de transações HTML
IPCLIENTE	IP do Usuário Final
DOCUMENTO	Documento / customerID
USUARIO	Login do usuário que efetuou a transação no POS Virtual
MOEDA	Moeda registrada na transação, seguindo a ISO 4217. Em muitos casos, tem apenas valor de apresentação em relatórios, dependendo da rede adquirente. Ex: Para o SiTef esta informação não é repassada.

Atenção:

Novos campos podem ser adicionados a estes sem aviso prévio. Caso este arquivo seja processado por algum sistema, este deve estar SEMPRE preparado para a inclusão de novos campos.

Marcação de fraude

Após uma transação com antifraude bem sucedida, a loja pode vir a identificar que, na realidade, se tratou de uma fraude. Nesse caso, caso o usuário tenha a permissão adequada (entre em contato com nossa equipe de suporte), ele pode localizar essa transação no relatório e clicar no botão "Marcar fraude" para avisar a instituição de análise de risco sobre essa ocorrência, conforme a figura abaixo:

Isso irá refinar o processo de análise dessa instituição, tornando-o mais preciso e evitando mais fraudes futuramente.

Atualmente, esta funcionalidade suporta as seguintes instituições de antifraude:

• Konduto
• Fraud Detect

Relatório de Resumo Diário

O Relatório de Resumo Diário consiste na visualização rápida e prática dos gráficos de Status e Autorizadora das transações realizadas até aquele momento no dia.

Para acessar esse relatório, coloque o cursor do mouse sobre o link Relatórios do menu principal, e um submenu aparecerá. Depois, clique em Resumo Diário:

A tela apresentada será semelhante à abaixo:

O botão VOLTAR retorna para a página inicial do portal.

Relatório de Armazenamentos

O Relatório de Armazenamentos permite visualizar todos os armazenamentos de cartão registrados em suas lojas num determinado período de tempo. Vários filtros são aplicáveis na listagem dos armazenamentos, e funcionalidades como gráficos também estão disponíveis para o lojista.

Para acessar esse relatório, coloque o cursor do mouse sobre o link Relatórios do menu principal, e um sub-menu aparecerá. Depois, clique em Relatório de Armazenamentos:

A tela apresentada será semelhante à abaixo:

Nesta tela, o lojista tem a opção de definir filtros que deseja aplicar antes de gerar a listagem dos armazenamentos do período de tempo determinado. Para selecionar filtros adicionais clique no ícone ao lado do botão Buscar:

A tabela a seguir descreve os filtros possíveis para este relatório:

Tabela 1: Filtros do Relatório de Armazenamentos.

Filtro	Descrição
Data Inicial *	Data inicial de referência para listagem das transações
Data Final *	Data final de referência para listagem das transações
NSU Armazenamento	Número único correspondente ao armazenamento de cartão
Pedido	Identificação do pedido realizado à loja
Hora Inicial	Hora inicial de referência para listagem das transações
Hora Final	Hora final de referência para listagem das transações
Documento	Identificação do cliente
Código Loja	Loja cadastrada para o lojista
Autorizadora	Autorizadora de cartão
Status	Status do armazenamento (Novo, Aguardando usuário, Confirmado, Duplicado, Cancelado, Negado, Inválido, Bloqueado, Abandonado, Expirado).

Atenção

Note que os campos de Data, com marcação *, são de preenchimento obrigatório e não deverão ultrapassar uma diferença de 3 (três) meses.

Vale ressaltar que os campos Hora Inicial e Hora Final só são aplicados caso o filtro de Data corresponda a um único dia (ou seja, apresente o mesmo dia tanto na Data Inicial quanto na Data Final). Caso o período de tempo seja maior que um dia, os campos de hora serão ignorados na listagem de armazenamentos.

Por fim, depois de definir os filtros desejados, basta clicar em Buscar. Você receberá uma lista com todos os armazenamentos que satisfazem os critérios determinados. A tela é semelhante a seguinte:

Nesta lista, estão presentes várias funcionalidades úteis ao lojista. Por exemplo, é possível ordenar os armazenamentos por ordem numérica ou alfabética de algum dos parâmetros principais. Para isso, basta clicar em algum dos títulos de parâmetro – NSU ARMAZENAMENTO, STATUS, LOJA, PEDIDO, DATA CRIAÇÃO.

Clicar uma vez ordena os armazenamentos em ordem ascendente. Clicar outra vez os ordena em ordem descendente. O padrão da listagem é organizar os armazenamentos em ordem do mais recente para o menos recente.

Também é possível ver mais detalhes sobre o armazenamento. Para isso, basta clicar no ícone , ao final da linha correspondente ao armazenamento:

A tela apresentada será semelhante à abaixo:

É possível ocultar estes detalhes clicando em no ícone , ao final da linha correspondente ao armazenamento (no mesmo lugar onde foi clicado no ícone ).

Também é possível exibir os detalhes de todos os armazenamentos da lista. Para isso, basta clicar no título de parâmetro DETALHES. Clicar uma vez exibe os detalhes de todos os armazenamentos da lista. Clicar de novo oculta todos os detalhes.

Relatório de Recargas

O Relatório de Recargas permite visualizar todas as recargas registradas em suas lojas num determinado período de tempo. Vários filtros são aplicáveis na listagem das recargas.

Atenção:

Para visualizar o Relatório de Recargas, é preciso que a equipe de operação libere a permissão necessária.

Para acessar esse relatório, coloque o cursor do mouse sobre o link Relatórios do menu principal, e um sub-menu aparecerá. Depois, clique em Relatório de Recargas:

A tela apresentada será semelhante à abaixo:

Nesta tela, o lojista tem a opção de definir filtros que deseja aplicar antes de gerar a listagem das recargas do período de tempo determinado. A tabela a seguir descreve os filtros possíveis para este relatório:

Tabela 1: Filtros do Relatório de Recargas.

Filtro	Descrição
Data Inicial *	Data inicial de referência para listagem das transações
Data Final *	Data final de referência para listagem das transações
Código Loja	Loja cadastrada para o lojista
Operadora	Operadora do celular no qual foi realizada a recarga (Vivo, Claro, Oi, Tim)
Data Inicial	Data inicial de referência para listagem das transações
Data Final	Data final de referência para listagem das transações
Código Loja	Loja cadastrada para o lojista
Operadora	Operadora do celular no qual foi realizada a recarga (Vivo, Claro, Oi, Tim)
Data Inicial	Data inicial de referência para listagem das transações
Data Final	Data final de referência para listagem das transações

Atenção:

Note que os campos de Data, com marcação *, são de preenchimento obrigatório e não deverão ultrapassar uma diferença de 3 (três) meses.

Por fim, depois de definir os filtros desejados, basta clicar em Buscar. Você receberá uma lista com todas as recargas que satisfazem os critérios determinados. A tela é semelhante a seguinte:

Nesta lista, estão presentes várias funcionalidades úteis ao lojista. Por exemplo, é possível ordenar as recargas por ordem numérica ou alfabética de algum dos parâmetros principais. Para isso, basta clicar em algum dos títulos de parâmetro – NSU RECARGA, STATUS TRANSAÇÃO, OPERADORA, LOJA, DATA CRIAÇÃO.

Clicar uma vez ordena as recargas em ordem ascendente. Clicar outra vez os ordena em ordem descendente. O padrão da listagem é organizar as recargas em ordem da mais recente para a menos recente.

Também é possível ver mais detalhes sobre a recarga. Para isso, basta clicar no ícone , ao final da linha correspondente à recarga:

A tela apresentada será semelhante à abaixo:

É possível ocultar estes detalhes clicando no ícone , ao final da linha correspondente ao armazenamento (no mesmo lugar onde foi clicado no ícone ).

Também é possível exibir os detalhes de todas as recargas da lista. Para isso, basta clicar no título de parâmetro DETALHES. Clicar uma vez exibe os detalhes de todos os armazenamentos da lista. Clicar de novo oculta todos os detalhes.

Atenção:

Note que a transação de recarga também traz consigo (dentro dos detalhes) informações sobre a transação de pagamento relacionada. Essa transação de pagamento aparece no Relatório de Transações também.

Uma funcionalidade a mais, presente no Relatório de Recargas, é a visualização de cupons, tanto da recarga quanto do pagamento efetuado.

Para visualizar o comprovante da recarga, basta clicar no status Confirmada, que está em negrito, na linha da recarga:

Só existe o comprovante de recarga em caso de status confirmado. O comprovante entrará em foco na tela, como é possível observar na figura abaixo:

Também é possível visualizar o comprovante do pagamento. Para isso, bastas clicar no status Confirmada da transação de pagamento:

Só existe o comprovante de pagamento em caso de status confirmado. O comprovante entrará em foco na tela, como é possível observar abaixo:

Relatório Analítico

O Relatório Analítico permite exportar transações de link de pagamento por grupo de lojas num determinado período de tempo.

Para acessar esse relatório, coloque o cursor do mouse sobre o link Relatórios do menu principal, e um sub-menu aparecerá. Depois, clique em Analítico conforme figura abaixo:

Com isso, uma tela semelhante a abaixo será apresentada:

Nesta tela, o lojista tem a opção de definir filtros que deseja aplicar antes de exportar o arquivo com as transações do período de tempo determinado. Existe também a opção de envio do arquivo (compactado) para o e-mail do usuário. A tabela a seguir descreve os filtros possíveis para este relatório:

Filtro	Descrição
Data Inicial *	Data inicial de referência para exportação
Data Final *	Data final de referência para exportação
Buscar por grupo de lojas	Essa opção deve ser marcada caso o usuário deseje exportar transações por grupo de lojas. Caso seja desmarcada, a exportação será feita por loja.
Enviar relatório por e-mail	Caso essa opção seja habilitada, o e-SiTef enviará o relatório para o e-mail do usuário.
Grupo de Lojas	Grupo associado ao usuário com uma coleção de lojas.
Código Loja	Loja associada ao usuário. Deixar em branco caso se deseje exportar transações de todas as lojas.

Atenção:

Note que os campos de Data, com marcação *, são de preenchimento obrigatório e não deverão ultrapassar uma diferença de 3 (três) meses.

Na opção de envio de email, o e-SiTef não se responsabiliza pelo não recebimento do arquivo se o e-mail do usuário estiver inválido ou desatualizado ou ainda, se o servidor de e-mail estiver fora do ar.

Por fim, depois de definir os filtros desejados, basta clicar em Exportar. Você receberá um arquivo CSV com todas as transações que satisfazem os critérios determinados.

Cancelamento de Transações

O Cancelamento de Transações é uma ferramenta que permite ao lojista cancelar transações já confirmadas.

Atenção:

Para visualizar o Cancelamento de Transações, é preciso que o usuário logado tenha o perfil que permite esta operação. Em caso de dúvidas, por favor consulte a equipe de suporte.

O prazo para cancelamento das transações através do Portal é de até seis meses, a depender das configurações da autorizadora.

Atenção:

Para o caso de pagamentos Gift é necessária que a opção de cancelamento esteja habilitada no SiTef.

Cancelamento de transações passo a passo

Para cancelar transações, coloque o cursor do mouse sobre o link Cancelamento do menu principal, e um sub-menu aparecerá. Depois, clique em Cancelamento de Transações:

A tela apresentada será semelhante à abaixo:

Nesta tela, é possível filtrar uma transação pelo seu código de pedido, desde que ela tenha sido realizada entre Data inicial e final. Caso o campo Código Pedido seja deixado em branco, todas as transações do dia serão mostradas após o usuário clicar no botão Buscar. A figura abaixo retrata este último caso.

Para cancelar uma das transações, basta clicar em um dos seus respectivos dados: NSU E-SITEF, LOJA, VALOR, DATA PAGAMENTO, NSU ou CÓDIGO PEDIDO. Um exemplo é mostrado na figura seguinte:

Após este passo, você será direcionado para a tela de cancelamento da transação. Ela é semelhante à apresentada no item seguinte.

Cancelamento de transações

Para o cancelamento de transações de pagamento realizadas via SiTef é apresentada a tela mostrada abaixo:

Aqui, é possível conferir os dados da transação a ser cancelada. Clicar no botão VOLTAR retorna para a tela de cancelamento de transações. Caso essa seja a transação desejada, para cancelar basta clicar no botão Cancelar Pagamento destacado na figura abaixo:

Depois disso, o usuário precisa preencher o campo que apareceu com o número do cartão utilizado na transação e clicar em confirmar. Esta etapa está representada na figura abaixo:

O cancelamento será processado. Após o sucesso no cancelamento, será exibida uma tela com os dados da transação original, o comprovante de cancelamento e uma mensagem de sucesso. Essa tela é semelhante à da figura a seguir:

A mensagem de sucesso foi destacada acima. É possível imprimir esses dados clicando no botão IMPRIMIR, que abrirá uma nova página com o comprovante formatado para impressão. Clicar no botão VOLTAR retorna para a tela de cancelamento de transações.

Após um cancelamento bem-sucedido, será criada uma transação de estorno com o mesmo código de pedido da transação original. É possível conferir essa nova transação no Relatório de Transações.

Atenção:

Para cancelamento de transações utilizando a autorizadora PayPal, o procedimento apresenta particularidades como campos adicionais para preenchimento. Por favor, solicite o documento específico: Anexo D - PayPal.

Agendamentos de Recorrência

O e-SiTef permite o agendamento de pagamentos recorrentes (utilizado principalmente para assinatura de serviços, como revistas, academias, etc.), ou seja, a realização automática de pagamentos mensalmente.

No Portal do Lojista é possível cadastrar agendamentos, visualizar um relatório dos agendamentos cadastrados, assim como alterar seus dados.

Relatório de Agendamentos

O Relatório de Agendamentos permite visualizar todos os agendamentos registrados em suas lojas num determinado período de tempo. Vários filtros são aplicáveis na listagem dos agendamentos, além da funcionalidade de edição dos agendamentos também disponível para o lojista.

Para acessar esse relatório, coloque o cursor do mouse sobre o link Relatórios do menu principal, e um sub-menu aparecerá. Depois, clique em Relatório de Agendamentos conforme figura abaixo:

Assim uma tela semelhante à abaixo será apresentada:

Nesta tela, o lojista tem a opção de definir os filtros que deseja aplicar antes de gerar a listagem dos agendamentos do período de tempo determinado. A tabela a seguir descreve os filtros possíveis para este relatório:

Tabela 1: Filtros do Relatório de Agendamentos.

Filtro	Descrição
Data Inicial *	Data inicial de referência para listagem dos agendamentos.
Data Final *	Data final de referência para listagem dos agendamentos.
Tipo da Data	Define a qual data os filtros Data Inicial e Data Final se referem. Eles podem agir sobre a data de criação da transação de agendamento ou sobre a data de sua próxima execução.
NSU Loja	Número sequencial da loja.
Código Pedido	Identificação do pedido realizado pela loja.
NSU Agendamento	Número único correspondente ao agendamento.
Loja	Loja cadastrada para o lojista.
Status	Status do agendamento. Para mais informações, consulte a Tabela 2.

A tabela abaixo descreve os status possíveis dos agendamentos:

Tabela 2: Status de agendamento

Nome	Descrição
Ativo	Os pagamentos recorrentes referentes a esse agendamento serão processados na data de próxima execução especificada.
Erro	Um erro ocorreu ao tentar ativar o agendamento.
Finalizado	Todos os pagamentos recorrentes referentes a esse agendamento foram executados.
Inativo	O agendamento foi inativado pelo lojista, ou seja, os pagamentos recorrentes não serão processados.
Desfeito	O agendamento, que estava pendente, foi desfeito pelo lojista.
Expirado	Um agendamento com status Novo excedeu o prazo para ativação. Este SID não pode mais ser utilizado.
Inválido	Algum parâmetro inválido foi enviado pelo lojista na tentativa de criação do agendamento.
Novo	Transação de agendamento foi criada recentemente, porém nenhuma tentativa de ativação foi feita.
Pendente	O agendamento está pendente de uma confirmação do lojista para que seja, de fato, ativado.

Por fim, depois de definir os filtros desejados, basta clicar em Buscar. Você receberá uma lista com todos os agendamentos que satisfazem os critérios determinados. A tela é semelhante à da figura a seguir:

Nesta lista, estão presentes várias funcionalidades úteis ao lojista. Por exemplo, é possível ordenar os agendamentos por ordem numérica ou alfabética de algum dos parâmetros principais. Para isso, basta clicar em algum dos títulos de parâmetro – NSU AGENDAMENTO, STATUS, LOJA, CÓDIGO PEDIDO, VALOR, DATA CRIAÇÃO.

Clicar uma vez ordena os agendamentos em ordem ascendente. Clicar outra vez os ordena em ordem descendente. O padrão da listagem é organizar os agendamentos em ordem do mais recente para o menos recente.

Também é possível ver mais detalhes sobre o agendamento. Para isso, basta clicar em v, ao final da linha correspondente ao agendamento:

Isto abrirá um espaço com mais detalhes sobre o agendamento:

É possível ocultar estes detalhes clicando em ^, ao final da linha correspondente ao agendamento (no mesmo lugar onde foi clicado em v).

Também é possível exibir os detalhes de todos os agendamentos da lista. Para isso, basta clicar no título de parâmetro DETALHES. Clicar uma vez exibe os detalhes de todos os agendamentos da lista. Clicar de novo oculta todos os detalhes.

A tabela abaixo descreve os campos listados:

Tabela 3: Descrição dos campos listados no Relatório de Agendamentos

Nome	Descrição
NSU Agendamento	Identificador da transação de agendamento.
Status	Status da transação de agendamento. Para mais informações, consulte a Tabela 2.
Loja	Nome da loja que criou o agendamento.
Código Pedido	Código de pedido definido pela loja.
Valor	Valor monetário a ser utilizado nos pagamentos recorrentes.
Data Criação	Data em que a transação de agendamento foi criada.
Data Inicial	Primeira data de execução do agendamento.
Última Execução	Data da última vez que esse agendamento foi executado.
Próxima Execução	Data da próxima vez em que esse agendamento será executado.
Execuções	Este campo contém duas informações: o número de vezes que esse agendamento foi executado (antes da barra) e o total de execuções que o agendamento deve ter para ser considerado como finalizado.
Intervalo (meses)	Frequência de execução do agendamento.
NSU Loja	Número sequencial da loja.
Autorizadora	Autorizadora a ser utilizada nos pagamentos recorrentes.
Parcelas	Número de parcelas a ser utilizado nos pagamentos recorrentes.
Financiamento	Financiamento a ser utilizado nos pagamentos recorrentes (loja ou administradora).
Soft Descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais
Exibe “parcela/plano” (nn/nn)?	Define se o texto do soft descriptor será procedido do campo Execuções.
NSU Últimos Pagamentos	Identificadores dos últimos seis pagamentos recorrentes.

Também é possível exportar os dados listados para um arquivo tipo CSV clicando no link EXPORTAR ARQUIVO CSV:

Edição de agendamentos

O lojista pode alterar alguns dados de agendamentos com status Ativo ou Inativo como o valor, o cartão ou o status. Para isso, no relatório de agendamentos, encontre o agendamento desejado, clique em ver para visualizar seus detalhes e em seguida, clique no link em frente ao texto Editar, conforme a imagem abaixo:

Ao acessar o link descrito acima, o lojista será redirecionado a uma página semelhante à apresentada na imagem abaixo:

Esta tela contém todos os campos passíveis de edição e seus valores atuais. Para realizar alterações, clique no lapis do campo desejado, como na figura abaixo:

Ao realizar o clique, o campo se tornará aberto para edição, como na imagem abaixo:

A tabela abaixo descreve os campos editáveis:

Tabela 4: Campos da edição de agendamentos

Campo	Descrição
Valor	Valor dos pagamentos recorrentes.
Próxima Execução	Data de execução do próximo pagamento recorrente.
Status	Este campo dá a possibilidade de ativar ou inativar o agendamento. Para mais informações, consulte a Tabela 2.
Soft Descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais
Exibir “parcela/plano”	Para agendamentos por tempo finito, acrescenta no final do campo Soft Descriptor o número de execuções/total de execuções (exemplo: Assinatura 3/12).
Número do cartão	Número do cartão do comprador.
Data de validade	Data de validade do cartão do comprador.

Após realizar todas as alterações desejadas, o lojista deve clicar no botão Salvar. Com isso, ele será redirecionado de volta ao relatório de agendamentos, que agora terá uma mensagem de sucesso acima dos filtros, como na figura abaixo:

Cadastro de Agendamentos

O Cadastro de Agendamentos é uma ferramenta que permite que o lojista agende pagamentos recorrentes para sua loja no e-SiTef.

Atenção

Para visualizar o Cadastro de Agendamentos, é preciso que o usuário tenha o perfil que permita esta operação. Em caso de dúvidas, por favor, consulte a equipe de suporte.

Para acessar esta funcionalidade, basta clicar no link Cadastro de Agendamentos, conforme apresentado a seguir:

Caso o usuário do lojista tenha múltiplas lojas associadas, ele será redirecionado a uma tela em que deverá selecionar a loja desejada, como na figura abaixo:

Após selecionar a loja, o lojista será encaminhado para a página de cadastro de agendamentos, conforme apresentado a seguir:

A tabela abaixo descreve os campos do formulário de cadastro de agendamento:

Tabela 5: Campos de cadastro de agendamento

Campo	Descrição
Autorizadora *	Bandeira do cartão do comprador.
Valor *	Valor a ser cobrados pelos pagamentos recorrentes.
Data Inicial *	Data da execução do primeiro pagamento agendado. No mínimo 2 dias a partir da data atual. Os dias 29, 30 e 31 não são aceitos neste campo.
Número de Execuções	Número de pagamentos a serem executados pelo agendamento. Caso esse campo não seja preenchido, o agendamento será executado por tempo indeterminado.
Documento (CPF / RG) *	Documento do comprador.
Código do Pedido	Código do pedido gerado pela loja.
NSU Loja	Número sequencial único gerado pela loja para facilitar a identificação do agendamento.
Soft Descriptor	Texto que será apresentado na fatura do cartão.
Exibir “parcela/plano”	Para agendamentos por tempo finito, acrescenta no final do campo Soft Descriptor o número de execuções/total de execuções (exemplo: Assinatura 3/12).
Número do cartão *	Número do cartão do comprador.
Data de validade *	Data de validade do cartão do comprador.

Campos acompanhados de * são obrigatórios.

Após preencher o formulário e clicar no botão ENVIAR, o lojista será redirecionado para uma página de sucesso, contendo as informações de seu agendamento, como na imagem abaixo:

Execução dos pagamentos agendados

Diariamente, o e-SiTef processará os pagamentos agendados do dia em questão e atualizará dados dos agendamentos executados, como o número de execuções corrente. Caso o agendamento já tenha sido executado pelo número de vezes desejado pelo lojista, ele terá seu status alterado para Finalizado e será desconsiderado em futuros processamentos, pois somente agendamentos com status Ativo serão executados.

O número corrente de execuções de um agendamento só será incrementado em pagamentos confirmados ou negados. Em caso de transações negadas, o e-SiTef não os reprocessará.

Configurar Análise de Risco

A opção de Configurar Análise de Risco é uma ferramenta que permite ao lojista definir os parâmetros de decisão sobre uma transação de análise de risco.

Atenção:

Para visualizar a opção de Configurar Análise de Risco, é preciso que a equipe de operação libere a permissão necessária.

Já existe uma documentação sobre esta ferramenta. Por favor, solicite o documento Integracao com solucoes Antifraude.

Configurar Ordenação de Autorizadoras

O Portal do Lojista também fornece a funcionalidade de Ordenação de Autorizadoras, que é mostrada ao clicar-se em Configurar Autorizadoras, conforme apresentado a seguir:

Uma vez que o usuário clique em Ordenar Autorizadoras são listadas as lojas (figura a seguir) que estão habilitadas com essa funcionalidade, caso nenhuma loja esteja habilitada e o usuário deseje utilizar a funcionalidade, entre em contato com suporte informando as lojas em que a ordenação será ativada:

Após selecionar-se uma loja, a tela de ordenação é apresentada, como na figura abaixo. A ordenação é realizada através de movimentos de clicar e arrastar que podem ser realizados nos Tipos de autorizadoras (lado esquerdo da tela) e nas Autorizadoras (lado direito da tela).

Após escolher e clicar em Salvar. Uma mensagem de aviso de sucesso será exibido.

Administração de Usuários

Caso seu usuário tenha as permissões necessárias (fornecidas pela equipe de operação da Software Express), é possível cadastrar, listar e alterar usuários.

Cadastro de Usuários

Para acessar a tela de cadastro de novos usuários, siga os passos abaixo:

1. Clique em Cadastros:

2. No submenu que aparecer, clique em Usuários:

3. No novo submenu, clique em Novo Usuário:

Com isso, a seguinte página será exibida:

Todos os campos deste formulário são obrigatórios. Abaixo está a descrição de cada um deles:

• Login: nome que será utilizado para acesso ao Portal do Lojista. Esse login é acrescido de um prefixo especifico para o lojista que efetua o cadastro.
• Nome: nome do usuário.
• Email: endereço de e-mail do usuário.
• Senha: senha do usuário a ser utilizada para acesso ao Portal do Lojista. Ao digitar a senha, a página exibirá logo abaixo a sua força, ou seja, o quão segura é a senha.
• Confirme a senha: digite a senha do usuário novamente. Este procedimento é importante para evitar erros no cadastro da senha.

Atenção:

O prefixo de login é cadastrado pela Software Express. Caso deseje alterá-lo, é necessário entrar em contato com a equipe de ativação. A modificação do prefixo não alterará os usuários já existentes no Portal do Lojista.

A figura abaixo ilustra o preenchimento dos campos listados até agora, assim como a indicação de força de senha:

O campo Tipo de Acesso conta com duas opções:

• Portal do Lojista: acesso a diversos relatórios, cadastro de agendamentos, configuração de autorizadoras, entre outras funcionalidades.
• POS Virtual: realização de pagamentos, recargas e cancelamentos, acesso a relatórios de transações e configurações básicas dessas operações.

Independente da opção marcada, a página exibirá várias opções que representam as permissões de acesso de cada usuário.

Abaixo está descrito quais funcionalidades podem ser acessadas ao marcar as opções disponíveis para o tipo de acesso Portal do Lojista:

• Administrador: administração de usuários (cadastro, listagem e edição).
• Cadastro de Agendamentos: cadastro de agendamentos de recorrência.
• Cancelamento de Transações: cancelamento/estorno de transações.
• Configurador - Análise de Risco: configuração de transações com análise de risco.
• Gerência de Lojas: configuração e ordenação de autorizadoras das lojas.
• Relatório de Agendamentos: relatório de transações de agendamento de recorrência.
• Relatório de Recargas: relatório de transações de recarga.
• Relatório de Transações: relatório de transações e gráficos de resumo diário.

Os perfis Relatório de Transações e Gerência de Lojas não podem ser atribuídos simultaneamente a um mesmo usuário.

Abaixo está descrito quais funcionalidades podem ser acessadas ao marcar as opções disponíveis para o tipo de acesso POS Virtual:

• Administrador do POS Virtual: configuração de transações feitas no Portal do Lojista.
• Cancelamento de Transações via POS Virtual: cancelamento/estorno de transações.
• Gerente do POS Virtual: visualização do relatório de resumo diário.
• POS Virtual: realização de transações de pagamento e visualização do relatório de transações.
• Recarga POS Virtual: realização de transações de recarga.

Além dos campos apresentados até agora, também é necessário selecionar uma loja para ser associada ao usuário em questão.

Após preencher todos os campos e clicar em ENVIAR, você será encaminhado para a página de edição do usuário que acabou de cadastrar. No canto superior esquerdo da tela, uma mensagem de sucesso será apresentada.

Listagem de Usuários

Para acessar a tela de listagem de usuários, siga os passos abaixo:

1. Clique em Cadastros:

2. No submenu que aparecer, clique em Usuários:

Com isso, a seguinte página será exibida:

Ao clicar em Buscar, a listagem dos usuários propriamente dita será realizada:

Para cada página da listagem são exibidos no máximo 20 usuários. Para navegar entre as páginas, basta clicar nas setas abaixo da tabela.

É possível ordenar os resultados obtidos clicando no cabeçalho do campo desejado.

Os resultados podem ser filtrados por Login, nome e e-mail. Para isso, basta preencher os campos desejados e clicar em Buscar.

Ao clicar no login de um usuário, o e-SiTef apresentará a página para edição deste usuário.

Edição de Usuários

Conforme visto nos capítulos anteriores, é possível acessar a tela de edição de usuário em duas situações:

• Logo após cadastrar o usuário
• Na tela de listagem de usuários, clicando no login do usuário

O único diferencial da edição para o cadastro é a possibilidade de adicionar ou remover lojas, disponível acessando o link Editar Lojas.

Com isso, a seguinte página será exibida:

Para adicionar uma loja, basta selecioná-la no campo Lojas Disponíveis e clicar em ADICIONAR. Com isso, uma janela de confirmação será apresentada:

Ao confirmar a adição, a operação será realizada, e a página exibirá a listagem de lojas novamente, porém agora contendo a nova loja.

Não é permitida a adição de lojas repetidas.

É possível remover uma loja clicando no link Remover em sua listagem.

Com isso, uma janela de confirmação será apresentada:

Após confirmar a remoção, a operação será realizada de fato, e a listagem de lojas será exibida novamente, porém sem a loja removida.

Só é permitido remover lojas do usuário caso ele tenha pelo menos duas lojas.

Geração de link de pagamento

A Geração de link de pagamento permite que o lojista gere links de pagamento ou links de pagamento com agendamento que podem ser compartilhados com o comprador a fim de se realizar transações de pagamento ou pagamento com agendamento mesmo quando o lojista não possui um website próprio.

Para acessar esta funcionalidade, coloque o cursor do mouse sobre o link Pagamento do menu principal, e um sub-menu aparecerá. Depois, clique em Gerar link, conforme mostrado na figura a seguir:

Página de seleção de lojas

Caso o lojista possua mais de uma loja cadastrada, a primeira tela solicitará que o lojista selecione uma delas:

Atenção:

Se o lojista possui apenas uma loja cadastrada, a tela acima não será apresentada.

Lojas sem permissão de geração de link de pagamento não serão listadas.

Em seguida, deve-se clicar na loja e será apresentado um formulário de preenchimento dos dados do pagamento.

Formulário para geração do link

O formulário para a geração de links tem a aparência abaixo.

Os campos de preenchimento obrigatório são marcados por *.

Atenção:

O campo Parcelamento depende das configurações de autorizadoras para a loja. Devido a isso, ele não aparece enquanto o campo Autorizadora não for preenchido, conforme exemplificado nas figuras abaixo.

Parcelamento quando nenhuma autorizadora foi selecionada

Parcelamento quando alguma autorizadora foi selecionada

Opcionalmente, o lojista pode solicitar fazer um pagamento com agendamento, ou pagamentos recorrentes. Neste caso, deve marcar o checkbox Habilitar agendamento.

Note que serão apresentados mais campos para preenchimento e, da mesma forma que os campos do pagamento, os campos obrigatórios de agendamento serão marcados por *.

Abaixo, seguem as tabelas com a descrição de todos os campos que podem ser preenchidos no formulário.

Campos para a geração de link de pagamento

Campo	Descrição	Formato
Loja	Nome Fantasia da loja selecionada pelo lojista.	-
Código da Loja	Código de cadastro no e-SiTef da loja selecionada pelo lojista.	-
Valor *	Valor do pagamento	< 12 N
Código do pedido	Código do pedido para ser exibido ao comprador, definido pelo lojista. É aconselhável que seja diferente para cada pedido a fim de facilitar a rastreabilidade. Se a integração da Loja com as redes adquirentes (Cielo, Redecard, etc) for com e-SiTef e SiTef, o campo orderId - que tem o tamanho máximo de 20 caracteres, será reduzido a 12 caracteres, devido a uma restrição do SiTef. Essa redução será realizada mantendo os caracteres da esquerda para direita (ex.: se um código de pedido inserido for 12345678901234567890 no e-SiTef, no SiTef ele será apenas 123456789012).	< 20 AN
NSU loja	Número sequencial único enviado pela loja na criação da transação.	< 12 N
Autorizadora	Autorizadora no e-SiTef configurada no cadastro da loja Saiba mais.	-
Parcelamento	Combinação de número de parcelas e tipo de financiamento (com ou sem juros). As opções são apresentadas de acordo com a configuração de parcelas para a autorizadora selecionada.	-
Habilitar agendamento	Marque esta checkbox para gerar um link de pagamento com agendamento. Quando esta opção está marcada, o formulário de agendamento é mostrado	-

Atenção:

Os campos marcados com * são obrigatórios.

Campos extras para a geração de link de pagamento com agendamento

Campo	Descrição	Formato
Valor *	Valor dos pagamentos agendados.	< 12 N
Data Inicial *	Data de execução do primeiro pagamento agendado. Essa data deve ter pelo menos dois dias à frente do dia atual e dias 29, 30 e 31 nunca são permitidos.	DD/MM/AAAA (Exemplo: 20/04/2021)
Documento (CPF / RG) *	Identificação do comprador para armazenamento de cartão. Esta identificação deve ser única para cada usuário da loja. Mas atenção, essa garantia de unicidade é de total responsabilidade da loja, o e-SiTef não realizará nenhuma validação.	< 20 N
Número de Execuções	Número de pagamentos agendados a serem executados. Caso esse campo não seja enviado, agendamento ficará ativo infinitamente.	< 3 N
Soft Descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais	< 30 AN
Exibir "parcela/plano" (nn/nn)	Para agendamentos por tempo finito, enviar esse campo com valor true caso se deseje acrescentar ao final do campo soft_descriptor o número de execuções/total de execuções (exemplo: Assinatura 3/12).	-

Atenção:

Os campos marcados com * são obrigatórios quando o campo Habilitar agendamento estiver marcado.

Página de Dados da geração do link

A página de Dados da geração do link apresenta o link gerado e todas informações relacionadas a ele.

Para copiar o link, basta clicar no botão Copiar link.

Atenção:

O link gerado é de uso único e tem validade de 48 horas.

A loja também pode ter um tempo de expiração customizado, respeitando o limite de 48 horas. Para isso, basta solicitar essa configuração para as nossas equipes de suporte e produção.

Além dos dados relacionados ao preenchimento pelo lojista, esta página também mostra o NSU Agendamento, que é o campo que identifica o agendamento e que pode ser usado para fins de consulta no Relatório de Agendamentos Saiba mais.

Análise de risco

Os pagamentos com link gerado pelo portal do lojista podem utilizar a anállise de risco CyberSource e Konduto. Para que seja possível agregar a análise de risco ao pagamento por link gerado pelo portal do lojista, solicite ao nosso suporte para que possamos configurar adequadamente a sua loja.

Envio de dados de carrinho

Caso a loja esteja habilitada para envio de dados de carrinho (entre em contato com nossas equipes de Suporte e Produção se desejar essa funcionalidade), o formulário de geração de link exibirá o botão "Adicionar Produto":

Ao clicar nele, os campos para preenchimento dos dados do produto serão disponibilizados:

Essas informações serão repassadas para a instituição de análise de risco. Atualmente, não exibimos dados de carrinho em nossa tela de pagamento.

POS Virtual

Para atender uma necessidade do lojista que pretende realizar pagamentos por meio de uma interface objetiva, foi elaborado o Pagamento via POS Virtual. De modo similar a um POS (Point Of Sale) esta interface não possui integração com um aplicativo de e-commerce, logo não totaliza ou consolida suas vendas com outros sistemas da loja. Se trata de um meio para realização de uma venda, mesmo não possuído um aplicativo especifico desenvolvido.

É uma solução diferenciada que utiliza a plataforma e-SiTef com foco em pequenos call-centers.

Outro objetivo seria a contingência para a realização de transações de pagamento quando o site integrado ao e-SiTef vier a falhar ou estiver indisponível.

Todas as chamadas realizadas serão respondidas de forma síncrona exceto o aviso de status que será realizado pelo e-SiTef de forma assíncrona.

Roteamentos suportados

O POS Virtual apenas pode ser utilizados com roteamentos via SiTef. Isso quer dizer que roteamentos como Cielo e-Commerce, e-Rede, Getnet WS e outros de comunicação com plataforma de e-commerces não podem ser utilizados nesta interface.

Para configurar os roteamentos e autorizadoras, consulte página de Configuração de Autorizadoras.

Configurando o POS Virtual

Para configurar o POS Virtual de uma loja, consulte a página sobre Configuração do POS Virtual.

Realizando pagamentos via POS Virtual

Para realizar um pagamento via POS Virtual, consulte a página sobre Pagamento via POS Virtual.

Configuração do POS Virtual

Antes de iniciar operações no POS Virtual, o lojista deve, através do Portal do Lojista do e-SiTef configurar as Autorizadoras e seus roteamentos para serem utilizados no POS Virtual.

A tela de configuração de POS Virtual permite que o lojista modifique os parâmetros a serem exibidos e validados no pagamento via POS Virtual.

Para acessar esta funcionalidade, clique no menu POS VIRTUAL e em seguida no submenu Configurar POS Virtual conforme mostrado na figura a seguir:

Atenção:

O usuário deve ter o perfil Administrador do POS Virtual para acessar a funcionalidade. Para mais informações, veja como administrar usuários.

Página de seleção de lojas

Caso o lojista possua mais de uma loja cadastrada, a primeira tela solicitará a seleção de uma delas:

Atenção:

Se o lojista possui apenas uma loja cadastrada, a tela acima não será apresentada.

Tela de configuração do POS Virtual

Abaixo, a tela de configuração de POS Virtual:

Abaixo, segue a tabela com a descrição das configurações disponíveis:

Configurações disponíveis

Campo	Descrição	Formato
Valor máximo de compra	Valor máximo de compra que será permitido em um pagamento via POS Virtual.	< 12 N
Exibir NSU Loja	Se selecionado, exibe na primeira etapa do pagamento via POS Virtual o campo de coleta de NSU Loja.	-
Exibir documento	Se selecionado, exibe na primeira etapa do pagamento via POS Virtual o campo de coleta de documento do comprador.	-
Bloquear Parcelamento	Se selecionado, não irá permitir que o usuário selecione as parcelas e automaticamente efetuará o pagamento à vista.	-
Documento Obrigatório	Se selecionado, torna o preenchimento obrigatório do documento na primeira etapa do Pagamento via POS Virtual. Será apenas editável se a opção Exibir documento estiver habilitada.	-
Código de Pedido Obrigatório	Se selecionado, torna o preenchimento obrigatório do Código de Pedido na primeira etapa do Pagamento via POS Virtual.	-

Para realizar um pagamento via POS Virtual, consulte a página sobre Pagamento via POS Virtual.

Pagamento via POS Virtual

Para acessar funcionalidade de pagamento via POS Virtual, clique no menu POS VIRTUAL e em seguida no submenu Efetuar pagamento conforme mostrado na figura a seguir:

Atenção:

O usuário deve ter o perfil POS Virtual para acessar a funcionalidade. Para mais informações, veja como administrar usuários.

Página de seleção de lojas

Caso o lojista possua mais de uma loja cadastrada, a primeira tela solicitará a seleção de uma delas:

Atenção:

Se o lojista possui apenas uma loja cadastrada, a tela acima não será apresentada.

Fluxo de pagamento via POS Virtual

Tela Inicial

Abaixo, a página inicial de pagamento via POS Virtual:

Descrição dos campos:

Campo	Descrição	Formato
Valor da Compra	Valor do pagamento. O valor máximo será limitado de acordo com a configuração.	< 10 N
Código do Pedido	Código de pedido da compra. Será obrigatório ou não de acordo com a configuração realizada.	-
NSU Loja	NSU (Número Sequencial Único) da loja. Será coletado ou não de acordo com a configuração realizada.	-
Documento	Documento do pagador. Será coletado/obrigatório ou não de acordo com a configuração realizada.	< 20 N
Número do Cartão	Número do cartão do pagador. Obrigatório.	> 13 N e < 19 N
Validade	Validade do cartão. Obrigatório.	MM/AA

Com todos os campos preenchidos corretamente, clique no botão Prosseguir. A consulta do cartão será realizada.

Consulta do cartão

Nesse momento será realizada uma consulta bin para identificar a autorizadora referente ao número do cartão enviado. Caso exista mais de uma autorizadora identificada, será apresentada a opção de Seleção de Autorizadora, como mostrado na figura seguinte:

Caso apenas uma autorizadora seja identificada pela consulta do número do cartão, a tela anterior não é apresentada, passando para a tela de Inserção de Dados Extras.

Após selecionar a autorizadora desejada (se necessário), clique no botão Prosseguir.

Inserção de Dados Extras

Conforme a necessidade, serão solicitados alguns dos seguintes dados: Código de Segurança, Documento e Data de Emissão do cartão. No exemplo abaixo, apenas o o código de segurança foi requisitado:

É possível que nenhuma informação extra seja solicitada. Neste caso, será solicitada diretamente a escolha de parcelas do pagamento.

Escolha de parcelamento

O usuário deve escolher a forma de parcelamento e clicar em Prosseguir. Após a escolha, será exibida uma mensagem para confirmação dos dados informados.

Abaixo, a tela de esolha de parcelas:

Atenção:

Esse passo não será exibido caso o POS Virtual da loja esteja configurado para bloquear parcelamentos.

Mensagem de confirmação

Após preencher todos os dados dos passos anteriores, uma mensagem para conferência de dados será exibida. Caso esteja tudo correto, clique no botão Efetuar Pagamento.

Tela de cupom

Caso o pagamento seja efetuado com sucesso, a seguinte tela será apresentada:

Na tela final você poderá:

• Efetuar um novo pagamento com a mesma loja.
• Efetuar um novo pagamento com outra loja.
• Imprimir o cupom.

Relatório de Transações POS Virtual

Para visualizar o relatório de transações efetuadas, visite a página sobre Relatório de Transações POS.

Cancelamento de Transações POS Virtual

Para mais informações sobre cancelamento de transações via POS Virtual, visite a página sobre Cancelamento de Transações.

Relatório de Transações POS

Para acessar funcionalidade de relatórios de transações POS, clique no menu RELATÓRIOS e em seguida no submenu Transações POS conforme mostrado na figura a seguir:

Atenção:

O usuário deve ter o perfil POS Virtual ou Gerente de POS Virtual para acessar a funcionalidade.

Tela de relatório de Transações POS

Abaixo, a tela inicial do relatório de Transações POS:

Preencha os filtros de busca desejados e, clique no botão Buscar. Caso sejam necessários outros filtros, clique no ícone ao lado do botão Buscar:

Resultado da busca

Após clicar em Buscar, os resultados serão apresetados como na figura abaixo:

Para exibir mais detalhes sobre uma transação, clique no ícone ao lado direito da transação:

Visualização do cupom

É possível visualizar o cupom de uma transação confirmada clicando no link da transação. Um popup com o cupom será exibido como na figura abaixo:

Gráficos de transações por Status

Esta funcionalidade permite a apresentação de gráficos com a distribuição de transações conforme seu status.

Atenção:

O usuário deve ter o perfil Gerente de POS Virtual para acessar a funcionalidade.

Para acessar a funcionalidade, clique o link Gerar gráfico por Status que será exibido após uma busca:

Gráficos de transações por Autorizadora

Esta funcionalidade permite a apresentação de gráficos com a distribuição de transações conforme a Autorizadora (Bandeira + Roteamento) escolhida.

Atenção:

O usuário deve ter o perfil Gerente de POS Virtual para acessar a funcionalidade.

Para acessar a funcionalidade, clique o link Gerar gráfico por Autorizadora que será exibido após uma busca:

Exportação de arquivo .CSV

Esta funcionalidade permite que o usuário faça o download do relatório em formato csv (comma separated value).

Atenção:

O usuário deve ter o perfil Gerente de POS Virtual para acessar a funcionalidade.

O arquivo irá contér as seguintes informações sobre a transação:

Campo	Descrição
NSU	NSU (número sequencial único) no e-SiTef.
TIPO	Tipo da transação.
STATUS	Status da transação no e-SiTef.
CODIGOLOJA	Código da loja (merchant id).
NOMELOJA	Nome fantasia da loja.
PEDIDO	Código do pedido.
VALOR	Valor da transação (centavos).
DATACRIACAO	Data de criação da transação no e-SiTef.
DATAEFETIVACAO	Data de efetivação da transação no e-SiTef.
DATAEFETIVACAOOSITEF	Data de efetivação no SiTef ou adquirente direto.
IDAUTORIZADORA	Código da autorizadora (authorizer id) no e-SiTef.
NOMEAUTORIZADORA	Nome da autorizadora no e-SiTef.
TIPOPAGAMENTO	Roteamento da transação.
RESPOSTASITEF	Código de Resposta do SiTef ou adquirente direto.
MENSAGEMSITEF	Mensagem de Resposta do SiTef ou adquirente direto.
NSUSITEF	NSU no SiTef.
NSUHOST	NSU no Host.
NSULOJA	NSU da Loja.
AUTORIZACAO	Código de Autorização.
PARCELAS	Parcelas da transação.
FINANCIAMENTO	Tipo de financiamento. 3 – parcelado com juros 4 – parcelado sem juros
TID	TID (Transaction ID) – identifica a transação na adquirente em integrações diretas.
ECI	ECI (Electronic Commerce Indicator) – indica o nível de segurança da transação eletrônica em relação a autenticação de portador do cartão.
ESTILO	Estilo da Transação. V – POS Virtual
AVISOS	Tentativas de Aviso a Loja sobre status de transações HTML.
FALHAS	Tentativas com Falha de Aviso a Loja sobre status de transações HTML.
IPCLIENTE	IP do Usuário Final.
DOCUMENTO	Documento / customerID.
USUARIO	Login do usuário que efetuou a transação no POS Virtual.
MOEDA	Moeda registrada na transação, seguindo a ISO 4217. Em muitos casos, tem apenas valor de apresentação em relatórios, dependendo da rede adquirente. Ex: Para o SiTef esta informação não é repassada.

Atenção:

Novos campos podem ser adicionados a estes sem aviso prévio. Caso este arquivo seja processado por algum sistema, este deve estar sempre preparado para a inclusão de novos campos.

Recarga POS Virtual

A Recarga de celular via POS Virtual (Portal do Lojista) permite que operadores associados a uma loja efetuem recarga de créditos em celulares para clientes finais. Esta funcionalidade requer que, além do log in inicial no Portal do Lojista do e-SiTef, seja feita uma segunda etapa de autenticação do usuário, antes que a transação de recarga seja confirmada. Isto é feito para garantir a autenticidade da recarga, uma vez que esta não pode ser estornada.

Para mais informações sobre como habilitar essa autenticação e conseguir efetuar Recarga de Celular via POS Virtual, clique aqui.

Atenção:

O usuário deve ter o perfil Recarga POS Virtual para acessar a funcionalidade. Para mais informações, veja como administrar usuários.

Realizando recargas via POS Virtual

Para realizar uma recarga via POS Virtual, consulte a página sobre Recargas via POS Virtual.

Relatório de recargas via POS Virtual

Para visualizar as recargas realizadas via POS Virtual, consulte a página sobre Relatório de recarga via POS Virtual.

Recarga via POS Virtual

Para acessar a funcionalidade de recarga via POS Virtual, clique no menu RECARGA POS e em seguida no submenu Efetuar Recarga de Celular conforme mostrado na figura a seguir:

Atenção:

O usuário deve ter o perfil Recarga POS Virtual para acessar a funcionalidade. Para mais informações, veja como administrar usuários.

Página de seleção de lojas

Caso o lojista possua mais de uma loja cadastrada, a primeira tela solicitará a seleção de uma delas:

Atenção:

Se o lojista possui apenas uma loja cadastrada, a tela acima não será apresentada.

Fluxo de recarga via POS Virtual

Autenticação em duas etapas

Para realizar recargas pelo Portal do Lojista, uma segunda etapa de autenticação é necessária para garantir a segurança durante as transações.

IMPORTANTE: Essa autenticação é imprescindível para realizar operações de recarga via POS Virtual. Para mais informações sobre essa autenticação e como habilitá-la, clique aqui.

Recarga via POS Virtual

Dados da recarga

Na tela inicial de recarga via POS, digite as informações do telefone celular do cliente:

Campo	Descrição	Formato
Código do Pedido	Código do pedido da recarga. Opcional.	< 12 N
Operadora	Operadora do número de celular a ser recarregado.	-
Número do Celular	Número do celular a ser recarregado.	< 11 N
Confirme o Celular	Confirmação do número de celular a ser recarregado.	< 11 N

Após preencher todos os dados corretamente, clique em Confirmar Número. Uma consulta do número será efetuada e os valores de recarga serão apresentados.

Os detalhes da recarga serão apresentados na parte inferior da tela.

Valores fixos

Em caso de valores fixos, selecione o valor desejado e clique em Seguir para Autenticação:

Valores variáveis

Em caso de valores variáveis selecione um intervalo de valores, digite o valor desejado ao lado (o valor deve estar dentro dos limites da opção selecionada) e clique em Seguir para Autenticação:

Dados de Autenticação

Ao confirmar os dados da recarga, será necessario utilizar o Google Authenticator para validar a recarga.

Abra o aplicativo e digite o token de 6 dígitos na tela abaixo:

Após inserir o token, clique em Confirmar Recarga.

Atenção:

Caso o token seja digitado 3 vezes de forma incorreta, a recarga será invalidada e o processo deve ser reiniciado.

Tela de cupom

Caso a recarga seja efetuado com sucesso, a seguinte tela será apresentada:

Na tela final você poderá:

• Efetuar uma nova recarga com a mesma loja.
• Efetuar uma nova recarga com outra loja.
• Imprimir o cupom.

Relatório de Recargas via POS Virtual

Para visualizar o relatório de recargas efetuadas, visite a página sobre Relatório de Recarga via POS.

Cancelamento de Transações POS Virtual

Não existe a possibilidade de cancelamento de recargas de celular. Em caso de dúvidas, entre em contato com o suporte.

Retentativa

Ao realizar uma transação de pagamento, determinadas respostas de "transação negada" das adquirentes sinalizam que é possível realizar uma nova tentativa sem comprometer o score da loja, havendo assim uma nova chance para converter a transação em bem-sucedida.

A retentativa de transação no e-SiTef é um procedimento automático que identifica as respostas das adquirentes que são adequadas para retentativas e atuam de acordo com um fluxo que foi configurado para sua loja. Se ao final do fluxo de retentativa não for possível converter em uma transação bem-sucedida, a transação se manterá com a última resposta da adquirente.

A retentativa será executada independentemente do dia ou momento do dia. Logo, é possível o cenário em que a transação original foi negada em uma determinada data, mas a transação de retentativa bem-sucedida foi executada em uma data posterior.

Importante 1:

A funcionalidade de retentativas de transações só é possível em operações com cartões de crédito com os seguintes roteamentos:

• Todos via SiTef
• Cielo e-Commerce
• e-Rede
• e.Rede REST
• Getnet WS
• GlobalPayment WS

Importante 2:

Pagamentos Split via interface HTML não fazem retentativa.

Atenção:

Ao configurar retentativas automáticas, recomenda-se não executar uma retentativa manual de transação negada (i.e. uma nova chamada em uma transação de NIT já negado), pois isto pode causar comportamentos inesperados.

Fluxos da Retentativa

Os fluxos de retentativas online e offline diferem principalmente sobre quando a execução das retentativas são realizadas para as adquirentes.

Fluxo de Retentativa Online

No fluxo de retentativa online, a retentativa é realizada durante o fluxo transacional de pagamento e é possível executar no máximo duas retentativas.

Este fluxo de retentativa é possível configurar que as retentativas utilizem mais de uma adquirente. Se a retentativa for executada em mais de uma adquirente, é necessário que sua loja tenha contrato com as adquirentes desejadas, e que isto seja cadastrado no e-SiTef de forma correspondente.

Existem diferenças entre a interface REST e HTML, que serão detalhadas a seguir.

Interface REST

Descrição do fluxo:

1. A cada resposta de tentativa é verificado a necessidade e a possibilidade de realizar uma retentativa.
2. Ao final do processo, a Loja Virtual recebe a resposta final e a repassa para o Comprador.

Interface HTML

Descrição do fluxo:

1. O processo inicia quando o Comprador solicita a finalização da compra para a Loja Virtual.
2. A Loja Virtual inicia uma transação no e-SiTef. O e-SiTef responde com uma URL para que a Loja Virtual redirecione o Comprador para o e-SiTef.
3. O Comprador começa a interagir diretamente com o e-SiTef e deve informar todos os dados de cobrança.
4. O e-SiTef executa as tentativas de pagamento. A cada resposta, o e-SiTef verifica a necessidade de realizar uma outra retentativa.
5. Ao final do fluxo, o e-SiTef envia um aviso de status da transação para a Loja Virtual e o Comprador recebe a resposta final do pagamento efetuado.

Fluxo de Retentativa Offline

No fluxo de retentativa offline, a retentativa é agendada para ser executada em um outro momento e a transação fica marcada com status RET enquanto o processo não termina.

As retentativas offline são agendadas de acordo com a configuração definida para o roteamento:

• Número máximo de retentativas;
• Intervalo entre as retentativas (em dias).

Por padrão serão executadas 3 (três) retentativas com um dia de intervalo entre elas.

Para habilitar esta funcionalidade e mudar a configuração padrão, deve-se entrar em contato com a equipe de produção do e-SiTef.

Se a execução da retentativa offline ocorrer com sucesso, a transação passará de status RET para CON.

Diferentemente do fluxo de retentativa online, o fluxo de retentativa offline não pode realizar a retentativa com mais de uma adquirente.

Neste fluxo de retentativa, a loja deve estabelecer acordos com a adquirente para viabilizar pagamentos sem a necessidade do código de segurança.

Além disso, também existem diferenças entre a interface REST e HTML, que serão detalhadas a seguir.

Interface REST

Descrição do fluxo:

1. Na primeira tentativa, o e-SiTef verifica a possibilidade de realizar a retentativa offline. Em caso afirmativo, o e-SiTef responde com o status de transação RET para Loja Virtual e agenda a retentativa de acordo com a configuração definida para o tipo de pagamento.
2. A retentativa é agendada de acordo com a configuração definida para o tipo de pagamento, no dia em que ela foi criada. Ou seja, se a retentativa offline foi criada num dia e depois a configuração de intervalo e/ou quantidade foi alterada, será mantida a configuração antiga.
3. Diariamente o e-sitef verifica se existe agendamento de retentativa e em caso positivo o executa.
4. A cada resposta de retentativa, o e-SiTef verifica a necessidade ou a possibilidade de agendar uma nova retentativa. Se for detectado o fim das retentativas, a transação de estado RET é alterada para um estado de acordo com a última resposta de retentativa.
5. Ao final de cada retentativa, o e-SiTef envia um aviso de status para a Loja Virtual.

Interface HTML

Descrição do fluxo:

1. O processo inicia quando o Comprador solicita a finalização da sua compra na Loja Virtual.
2. A Loja Virtual inicia uma transação com o e-SiTef e redireciona o Comprador para o e-SiTef.
3. O Comprador começa a interagir diretamente com o e-SiTef e deve informar todos os dados de cobrança.
4. Na primeira tentativa, o e-SiTef agenda uma retentativa, após verificar que é possível realizar uma retentativa offline. Além disto, o e-SiTef envia o aviso de status para Loja Virtual, indicando que a transação está com status RET e responde ao Comprador que o "pagamento foi recebido e está sendo processado".
5. A retentativa é agendada de acordo com a configuração definida para o tipo de pagamento, no dia em que ela foi criada. Ou seja, se a retentativa offline foi criada num dia e depois a configuração de intervalo e/ou quantidade foi alterada, será mantida a configuração antiga.
6. Diariamente o e-SiTef verifica se existe agendamento de retentativa e em caso positivo o executa.
7. A cada resposta da retentativa, o e-SiTef verifica a necessidade ou a possibilidade de agendar uma nova retentativa. Se for detectado o fim das retentativas, a transação sai do estado RET.
8. Ao final de cada retentativa, o e-SiTef envia um aviso de status para a Loja Virtual.

Importante:

O cliente pode optar por combinar o uso das Retentativas Online e Offline. Neste cenário o fluxo da rententivas offline será iniciado caso as retentativas online forem negadas.

Retentativa e Agendamento de Recorrência

A retentativa também funciona para os agendamento de recorrência. Saiba mais sobre agendamento de recorrência.

Atenção: no agendamento de recorrência é mencionado o termo "reprocessamento". Não confunda este termo com as retentativas. Os dois são processos distintos no e-SiTef e não possuem relação/interferência entre si.

Seguem alguns detalhes da relação entre retentativa e agendamento de recorrência.

Execução dos pagamentos agendados

Os pagamentos agendados são executados como um pagamento normal. Logo, caso sua loja esteja com a retentativa habilitada e o contexto transacional se encaixe nos cenários da retentativa, o pagamento agendado irá acionar os fluxos de retentativa.

Portal do Lojista - relatório de agendamento de recorrência

No portal de Lojista é possível consultar os agendamentos de recorrência. Saiba mais sobre o relatório de agendamentos no portal do lojista.

Enquanto a retentativa está no meio de um dos fluxos, o agendamento de recorrência ficará com estado de "Erro". Caso a retentativa consiga confirmar a transação, o agendamento de recorrência passará a ficar ativo. Logo, é possível que o agendamento de recorrência fique temporariamente em estado de "Erro" até que a retentativa termine o fluxo.

Retentativa e códigos de retornos permitidos

Códigos de retorno reversiveis, que podem ter retentativas são:

Autorizadora	Código retorno
Cielo	DS
Cielo	EK
Cielo	R1
Cielo	S0
Cielo	TM
Cielo	V7
Cielo	AA
Cielo	005
Cielo	006
Cielo	019
Cielo	025
Cielo	028
Cielo	05
Cielo	057
Cielo	060
Cielo	061
Cielo	065
Cielo	076
Cielo	089
Cielo	091
Cielo	092
Cielo	096
Cielo	098
Cielo	099
Cielo	110
Cielo	19
Cielo	213
Cielo	25
Cielo	28
Cielo	57
Cielo	60
Cielo	61
Cielo	65
Cielo	89
Cielo	91
Cielo	92
Cielo	96
Cielo	98
Cielo	AE
Cielo	AV
Cielo	BO
Cielo	DF
Cielo e-Commerce	05
Cielo e-Commerce	R1
Cielo e-Commerce	19
Cielo e-Commerce	25
Cielo e-Commerce	28
Cielo e-Commerce	57
Cielo e-Commerce	60
Cielo e-Commerce	61
Cielo e-Commerce	65
Cielo e-Commerce	89
Cielo e-Commerce	90
Cielo e-Commerce	91
Cielo e-Commerce	92
Cielo e-Commerce	96
Cielo e-Commerce	98
Cielo e-Commerce	99
Cielo e-Commerce	999
Cielo e-Commerce	AA
Cielo e-Commerce	AE
Cielo e-Commerce	AF
Cielo e-Commerce	AG
Cielo e-Commerce	AV
Cielo e-Commerce	BD
Cielo e-Commerce	BO
Cielo e-Commerce	DF
Cielo e-Commerce	DS
Cielo e-Commerce	EK
Cielo e-Commerce	15
eRede	15
e.Rede REST	103
e.Rede REST	104
e.Rede REST	106
e.Rede REST	107
e.Rede REST	121
e.Rede REST	150
e.Rede REST	56
e.Rede REST	64
e.Rede REST	74
GetNet Lac	80
GetNet Lac	V7
GetNet Lac	96
GetNet Lac	91
GetNet Lac	83
GetNet Lac	S0
GetNet Lac	TM
GetNetWS	85
GetNetWS	86
GetNetWS	87
GetNetWS	88
GetNetWS	94
GetNetWS	19
GetNetWS	O1
GetNetWS	Q0
GetNetWS	Q1
GetNetWS	Q2
GetNetWS	68
GetNetWS	O0
Global Payments via WS	96
Global Payments via WS	68
Global Payments via WS	91
Redecard	19
Redecard	V7
Redecard	TM
Redecard	91
Redecard	96
Redecard	S0
Safra	099
Safra	S0
Safra	TM
Safra	V7
Stone	TM
Stone	S0
Stone	96
Stone	06
Stone	V7

Importante: os códigos não presentes acima são irreversíveis, ou seja, não podem ser retentados.

Bradescard

A loja tem a possibilidade de configurar o roteamento de transações feitas no e-SiTef por vários meios de pagamento, um desses meios é o Bradescard.

Interfaces e-SiTef suportadas para integração

Utilizaremos as seguintes interfaces para a integração com o roteamento Bradescard:

• Pagamento REST
• Pagamento HTML
• Cancelamento REST
• Cancelamento via Portal do Lojista
• Operação genérica para realizar consultas Bradescard

Serviço de Consultas Bradescard

Nas consultas Bradescard é possível realizar a consulta de extrato resumido e a consulta de saldos de um determinado cartão.

Detalhes da chamada

O serviço de consulta Bradescard é um serviço disponibilizado pela interface de operação genérica (Saiba mais). No caso da operação de consulta Bradescard, é obrigatório o token de autenticidade para cada consulta realizada, logo é necessário obter o token (Saiba mais) e depois realizar a chamada de operação genérica (Saiba mais).

A consulta Bradescard é identificada com o código de operação 172 (utilize este valor no campo operation na requisição).

Parâmetros das consultas Bradescard

Abaixo, seguem os parâmetros que são utilizados pela operação de consultas Bradescard.

Parâmetro	Descrição	Formato	Obrigatório
date	Data fiscal.	N	Não
time	Hora fiscal.	N	Não
subfunction	Subfunção da transação de consulta. Estão previstas as seguintes consultas: 01 – Consulta de saldos 02 – Consulta de extrato resumido	2 N	Não
card_entry_mode	Modo de entrada. Os valores possíveis para este campo são: 1 – Cartão magnético 2 – Número do cartão digitado	1 N	Sim
card_number	Este campo deve ser preenchido com o número do cartão.	N	CONDICIONAL Sim, se card_entry_mode for igual a "2"
track1	Este campo deve ser preenchido com a trilha 1 do cartão.	< 99 AN	CONDICIONAL Sim, se card_entry_mode for igual a "1"
track2	Este campo deve ser preenchido com a trilha 2 do cartão.	< 99 N	CONDICIONAL Sim, se card_entry_mode for igual a "1"
card_expiry_date	Data de vencimento do cartão.	4 N (MMAA)	CONDICIONAL Sim, se card_entry_mode for igual a "2"
card_security_code	Código de segurança.	< 10 N	CONDICIONAL Sim, se for solicitado na consulta de cartão (Saiba mais).
card_issue_date	Data da emissão do cartão.	6 N (MMAAAA)	CONDICIONAL Sim, se for solicitado na consulta de cartão (Saiba mais).

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de consultas Bradescard:

Parâmetro	Descrição
response_code	Código de resposta do e-SiTef.
response_message	Mensagem de resposta do e-SiTef.
authorizer_response_code	Código de resposta da autorizadora.
authorizer_response_message	Mensagem de resposta da autorizadora.
parameters.date	Data.
parameters.time	Hora.
parameters.acquirer_id	Id da rede adquirente no SiTef.
parameters.host_usn	NSU host.
parameters.sitef_usn	NSU SiTef.
parameters.institution_response_code	Código de resposta da autorizadora/adquirente.
parameters.institution_name	Nome da instituição.
parameters.authorization_number	Número da autorização.
parameters.affiliation_code	Código do estabelecimento na autorizadora/adquirente.
parameters.confirmation_data	Dados da confirmação.
parameters.customer_receipt	Comprovante do comprador.
parameters.merchant_receipt	Comprovante da loja.
parameters.sale_response_data	Dados de resposta da venda.

Cetelem

Para realizar o pagamento através da adquirente Aura-Cetelem no e-SiTef, além dos parâmetros básicos do Serviço de Criação de Pagamento REST e do Serviço de Efetivação de Pagamento REST, são necessários alguns dados que serão enviados através do parâmetro prefixes descrito na sessão de Prefixos abaixo.

IMPORTANTE: Antes de começar, verifique se a autorizadora desejada está utilizando como tipo de pagamento a rede = 93 (Aura – Cetelem).

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento Cetelem:

• Pagamento REST
• Pré-Autorização REST
• Cancelamento REST
• Cancelamento via Portal

Pagamento REST

Criação de Pagamento

A seguir, são listados os parâmetros com dados específicos para a transação via Cetelem que o aplicativo da loja virtual deve enviar no Serviço de criação de transação REST:

Parâmetro	Descrição	Formato	Obrigatório
authorizer_id	Código da Autorizadora no e-SiTef – Usar o código Aura-Cetelem que é o 93	≤ 10 A	Sim
installment_type	Tipo do financiamento de parcelamento. Valores permitidos: 3 - rotativo normal 4 - rotativo normal ou parcelado ou 17 - crediário	= 2 N	Sim para crediário

Efetivação de Pagamento

A seguir, são listados os parâmetros com dados específicos para a transação via Cetelem que o aplicativo da loja virtual deve enviar no Serviço de efetivação de transação REST:

Parâmetro	Descrição	Formato	Obrigatório
acquirer
prefixes	Elemento para envio de prefixos do SiTef. Caso o prefixo enviado não seja suportado pelo cartão enviado, o e-SiTef invalidará a transação, impedindo que se dê uma falsa impressão do uso de uma determinada funcionalidade. Os prefixos suportados pela Aura-Cetelem estão listados na seção Prefixos. Exemplo: { "key" : "value" } -> { "CICLOS" : "01" }	≤ 2000 A	Sim

Prefixos

Prefixo	Descrição	Tamanho	Obrigatório
CMAT	Código do Material vendido	= 4 N	Sim para crediário
CPLANO	Código do Plano	= 5 AN	Sim para crediário

Pré-Autorização REST

Criação de Pré-Autorização

Abaixo está a descrição dos parâmetros específicos de Cetelem para o serviço de criação de pré-autorização REST:

Parâmetro	Descrição	Formato	Obrigatório
additional_data
pre_auth_lifecycle	Representa o número de dias em que se considera válida a pré-autorização.	< 2 N	NÃO
entry_amount	Valor de entrada em centavos.	< 12 N	NÃO
additional_data .extra_param .prefixes[]	Elemento para envio de prefixos do SiTef. Caso o prefixo enviado não seja suportado pelo cartão enviado, o e-SiTef invalidará a transação, impedindo que se dê uma falsa impressão do uso de uma determinada funcionalidade. Os prefixos suportados pela Aura-Cetelem estão listados na seção Prefixos.
key	Nome do prefixo.	< 1024 AN	NÃO
value	Valor do prefixo.	< 1024 AN	NÃO

Exemplo:

{
   "merchant_usn":"14111112826",
   "order_id":"14111112826",
   "authorizer_id":"6",
   "amount":"2300",
   "transaction_type":"preauthorization",
   "additional_data":{
      "pre_auth_lifecycle":"7",
      "entry_amount":"1",
      "extra_param":{
         "prefixes":[
            {
               "key":"CPLANO",
               "value":"13219"
            },
            {
               "key":"CMAT",
               "value":"11"
            }
         ]
      }
   }
}

Efetivação de Pré-Autorização

As informações de parcelamento (campos installments e installment_type) devem ser enviadas nesta etapa. Na captura, os mesmos valores devem ser utilizados.

Abaixo está a descrição específica de alguns parâmetros do Cetelem para o serviço de efetivação de pré-autorização REST:

Parâmetro	Descrição	Formato	Obrigatório
installment_type	Tipo do financiamento de parcelamento. Valores permitidos: 3 - super limite crediário 4 - rotativo normal ou parcelado	= 2 N	SIM
installments	Número de parcelas da transação. Obs: utilize installment_type = 4 e installments = 1 para pagamentos à vista.	= 2 N	SIM

Captura de Pré-Autorização

Abaixo está a descrição específica de alguns parâmetros do Cetelem para o serviço de captura de pré-autorização REST:

Parâmetro	Descrição	Formato	Obrigatório
installment_type	Tipo do financiamento de parcelamento. Valores permitidos: 3 - super limite crediário 4 - rotativo normal ou parcelado	= 2 N	SIM
installments	Número de parcelas da transação. Obs: utilize installment_type = 4 e installments = 1 para pagamentos à vista.	= 2 N	SIM

IMPORTANTE: Para o roteamento Cetelem, a captura de Pré-Autorização não necessita de dados de cartão.

Exemplo

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/capture/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "amount":"100",
   "installments":"1",
   "installment_type":"4",
   "acquirer":{
      "entry_amount": "1555"
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "capture":{
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"orderID",
      "customer_receipt":"=== CUSTOMER RECEIPT ===",
      "merchant_receipt":"=== MERCHANT RECEIPT ===",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK.",
      "authorizer_date":"09/11/2018T19:40",
      "authorizer_merchant_id":"000000000000000",
      "authorization_number":"212195",
      "esitef_usn":"180921015287704",
      "merchant_usn":"20190101",
      "sitef_usn":"212195",
      "host_usn":"999212195",
      "amount":"100",
      "payment_type":"C",
      "issuer":"2"
   }
}

Abaixo está a descrição dos parâmetros específicos de Cetelem para o serviço de captura de pré-autorização REST:

Parâmetro	Descrição	Formato	Obrigatório
acquirer
entry_amount	Valor de entrada em centavos.	< 12 N	NÃO

GetnetLac

Neste item serão apresentadas caracteristicas especificas para o roteamento GetnetLac via SiTef.

Pré-Autorização

• Sobre a pré-autorização roteada pela GetnetLac, a informação de parcelamento (installments e installment_type) deve ser sempre passada na etapa de pré-autorização, e não na captura. Caso a pré-autorização seja a vista, a captura não pode ser parcelada.
• Para este roteamento, o parcelamento de pré-autorizações sempre será sem juros, isto é, installment_type= 4. Isto vale para as Interfaces HTML e REST.

Split de Pagamento

No Split de Pagamento, as informações de divisão de valores entre os sub-vendedores são enviados por uma transação única no e-SiTef, e a distribuição de fundos fica a cargo da adquirente.

O roteamento GetnetLac permite que seja feito o Split de Pagamento através da inclusão de parâmetros no objeto additional_data na criação da transação de pagamento, tanto para interfaces de Pagamento HTML e REST.

Parâmetros de requisição

Parâmetro	Descrição	Formato	Obrigatório
additional_data.split_request	Elemento com os dados do split
seller_id	Identificador do vendedor na plataforma MarketPlace Getnet.	< 36 A	SIM
sale_id	Identificador da venda ou pedido.	< 36 A	SIM
additional_data.split_request.subsellers[]	Lista com dados dos sub-vendedores.
id	Id do Sub-vendendor na plataforma MarketPlace Getnet.	< 36 A	SIM
sales_amount	Parte do Valor correspondente ao Sub-vendedor - em centavos.	< 12 N	SIM
additional_data.split_request.subsellers.products[]	Lista com dados dos itens.
product_id	Identificador do Item.	< 15 A	SIM
amount	Valor do Item em centavos.	< 12 N	SIM
description	Descrição do Item.	< 80 A	SIM
tax_percent	Taxa do item em porcentagem. Formato NNNDDDDDD onde: NNN Parte inteira - completar com zeros a esquerda até atingir 3 dígitos; DDDDDD Parte fracionária. Completar com zeros a direita até atingir 6 dígitos.	< 9 A	NÃO
tax_amount	Taxa do item em valor em centavos.	< 12 N	NÃO

Pagamento HTML

Exemplo de JSON - criação de transação

Obs: Os valores dos exemplos são fictícios.

{
  "merchant_id":"Codigo_Loja",
  "merchant_usn":"12345678",
  "order_id":"order_12345",
  "amount":"5000",
  "additional_data":{
    "split_request":{
      "seller_id":"6eb2412c-165a-41cd-b1d9-76c575d70a28",
      "sale_id":"6d2e4380-d8a3-4ccb-9138-c289182818a3",
      "subsellers":[
        {
          "id":"853984759834734",
          "sales_amount":"3700",
          "products":[
            {
              "product_id":"X0001",
              "amount":"1500",
              "description":"DESCRICAO PRODUTO 1",
              "tax_percent":"005934500",
              "tax_amount":"150"
            },
            {
              "product_id":"X0001",
              "amount":"1500",
              "description":"DESCRICAO PRODUTO 2",
              "tax_percent":"005934500",
              "tax_amount":"150"
            }
          ]
        },
        {
          "id":"256714932547251",
          "sales_amount":"1300",
          "products":[
            {
              "product_id":"X0003",
              "amount":"1300",
              "description":"DESCRICAO PRODUTO 3",
              "tax_percent":"005934500",
              "tax_amount":"150"
            }
          ]
        }
      ]
    }
  }
}

Após a finalização do Pagamento HTML, os seguintes parâmetros serão adicionados ao Aviso de Status (saiba mais):

Parâmetro	Descrição	Formato
splitPaymentId	Identificador do pagamento split.	< 36 A
splitTransactionId	Identificador da transação split.	< 19 N

Pagamento REST

Exemplo de JSON

Obs: Os valores dos exemplos são fictícios.

Requisição de criação de transação

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
  "merchant_usn":"12345678",
  "order_id":"order_12345",
  "installments":"1",
  "installment_type":"4",
  "authorizer_id":"1",
  "amount":"5000",
  "additional_data":{
    "split_request":{
      "seller_id":"6eb2412c-165a-41cd-b1d9-76c575d70a28",
      "sale_id":"6d2e4380-d8a3-4ccb-9138-c289182818a3",
      "subsellers":[
        {
          "id":"853984759834734",
          "sales_amount":"3700",
          "products":[
            {
              "product_id":"X0001",
              "amount":"1500",
              "description":"DESCRICAO PRODUTO 1",
              "tax_percent":"005934500",
              "tax_amount":"150"
            },
            {
              "product_id":"X0001",
              "amount":"1500",
              "description":"DESCRICAO PRODUTO 2",
              "tax_percent":"005934500",
              "tax_amount":"150"
            }
          ]
        },
        {
          "id":"256714932547251",
          "sales_amount":"1300",
          "products":[
            {
              "product_id":"X0003",
              "amount":"1300",
              "description":"DESCRICAO PRODUTO 3",
              "tax_percent":"005934500",
              "tax_amount":"150"
            }
          ]
        }
      ]
    }
  }
}
--verbose

Resposta da efetivação de pagamento

{
  "code":"0",
  "message":"OK. Transaction successful.",
  "payment":{
    "authorizer_code":"000",
    "authorizer_message":"Transacao OK                                                    SDO DISPONIVEL                                                   244,00",
    "status":"CON",
    "nit":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "order_id":"order_12345",
    "customer_receipt":"*****",
    "merchant_receipt":"*****",
    "authorizer_id":"1",
    "acquirer_id":"181",
    "acquirer_name":"GetNet Lac",
    "authorizer_date":"12/08/2020T14:24",
    "authorization_number":"122641",
    "merchant_usn":"12345678",
    "esitef_usn":"200812055315840",
    "sitef_usn":"122641",
    "host_usn":"008122641   ",
    "amount":"5000",
    "payment_type":"C",
    "issuer":"1",
    "authorizer_merchant_id":"000000000000000",
    "terminal_id":"ES000054",
    "payment_date":"12/08/2020T14:24",
    "split":{
      "payment_id":"06f256c8-1bbf-42bf-93b4-ce2041bfb87e",
      "transaction_id":"0023972834623476365"
    }
  }
}

Retornos específicos do Pagamento Split no Pagamento REST

Parâmetro	Descrição	Formato
payment.split	Elemento com os dados de retorno de pagamento split
payment_id	Identificador do pagamento split.	< 36 A
transaction_id	Identificador da transação split.	< 19 N

Orbitall

Introdução

A adquirente Orbitall é responsável por processar cartões da própria rede varejista.

Para realizar o pagamento através da adquirente Orbitall no e-SiTef, além dos parâmetros básicos do Serviço de Criação de Pagamento REST e do Serviço de Efetivação de Pagamento REST, são necessários alguns dados que serão enviados através do parâmetro prefixes descrito na seção de Prefixos abaixo.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento Orbitall:

• Pagamento REST
• Cancelamento REST
• Cancelamento via Portal

Pagamento REST

Criação de Pagamento REST

A seguir, são listados os parâmetros com dados específicos para a transação via Orbitall que o aplicativo da loja virtual deve enviar no Serviço de criação de transação REST:

Parâmetro	Descrição	Formato	Obrigatório
authorizer_id	Código da Autorizadora no e-SiTef – Usar o código Orbitall que é o 160	≤ 10 A	Sim
installment_type	Tipo do financiamento de parcelamento. Valores permitidos: 3 - parcelado com juros 4 - parcelado sem juros ou 37 - Crédito CDC.	= 2 N	Não

Efetivação de Pagamento REST

A seguir, são listados os parâmetros com dados específicos para a transação via Orbitall que o aplicativo da loja virtual deve enviar no Serviço de efetivação de transação REST:

Parâmetro	Descrição	Formato	Obrigatório
acquirer.prefixes	Elemento para envio de prefixos do SiTef. Caso o prefixo enviado não seja suportado pelo cartão enviado, o e-SiTef invalidará a transação, impedindo que se dê uma falsa impressão do uso de uma determinada funcionalidade. Os prefixos suportados pela Orbitall estão listados na seção Prefixos. Exemplo: { "key" : "value" } -> { "CICLOS" : "01" }	≤ 2000 A	Sim

Prefixos

Prefixo	Descrição	Tamanho	Obrigatório
CICLOS:	Deve ser enviado 0 (zero) quando o vencimento for na data do cartão ou de 1 a 99 indicando o número de ciclos a pular. Para usar ciclos é necessária uma configuração previa no SiTef.	≤ 2 N	Sim
CPLANO:	Código do plano acordado entre autorizadora e o estabelecimento. Obrigatório quando o tipo de financiamento for Crédito CDC.	= 5 AN	Não
TPCDC:	Tipo de compra crédito CDC: 1 – CDC Produto 2 – CDC Serviço.	= 1 N	Não
VLRADD:	Valor adicional cobrado para compra tranquila, o parâmetro deve seguir o formato “cc=vv...vvv”, onde: cc = 01 indicando compra tranquila. vv...vvv indica o valor adicional para a compra tranquila (*) . Pode ser no máximo de tamanho 12 e é o valor SEM a vírgula.	≤ 15 AN	Não

(*) é um seguro oferecido na compra CDC (ex: seguro se ficar desempregado). O valor passado na transação é referente ao valor total (compra + valor seguro). O cancelamento tambem é efetuado com o valor total. Para mais detalhes, consultar a rede adquirente.

Código de Autorizadora

O código para a autorizadora Orbitall no e-SiTef é 160. Para saber os códigos das demais autorizadoras no e-SiTef, consulte aqui.

Vero

Para transacionar com o adquirente Vero no e-SiTef, além dos parâmetros básicos de cada serviço, são necessários alguns dados adicionais.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento Vero:

• Pagamento REST
• Pagamento HTML
• Pré-Autorização REST
• Pré-Autorização HTML
• Cancelamento REST
• Cancelamento via Portal

Pagamento REST

Efetivação de Pagamento

A seguir, são listados os parâmetros com dados específicos para a transação via Vero que o aplicativo da loja virtual pode enviar no serviço de efetivação de pagamento REST:

Parâmetro	Descrição	Formato	Obrigatório
	card
holder_present	Indica se o portador do cartão está presente ou não. Enviar true caso positivo, ou false caso contrário. Valor padrão: true	< 5 AN	NÃO
	external_authentication
eci	Eletronic Commerce Indicator – indica o nível de segurança da transação com autenticação do dono do cartão	< 3 N	NÃO
xid	Identificador da transação de autenticação do dono do cartão em transações 3DS 1.0.	< 40 AN	NÃO
cavv	Cardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão.	< 40 AN	NÃO
ucaf_sli	Contêm o UCAF (Universal Cardholder Authentication Field), que corresponde ao último dígito do SLI (Security Level Indicator) do Mastercard Secure Code (para bandeira MasterCard).	= 1 N	NÃO
version	Versão do 3DS (1 ou 2).	= 1 N	NÃO
reference_id	Identificador do Directory Server para transações 3DS 2.0.	< 36 AN	NÃO
tavv	Criptograma de transação tokenizada DSRP-UCAF.	< 40 AN	NÃO
	acquirer
ecommerce_device_type	Tipo do dispositivo.	< 2 AN	NÃO
token_req_id	Identificador do requisitante do Token (Token Requestor ID).	< 11 N	NÃO
pan_token_relation_level	Nível de relação Token e PAN.	< 2 AN	NÃO
ecommerce_input_type	1: Leitura PAN (e-commerce) 2: Leitura PAN (Server) 3: Leitura PAN (MasterCard DSRP Full EMV). Valor padrão: 1	= 1 N	SIM

É obrigatório o envio de dados de autenticação para pagamentos com débito.

Pré-Autorização REST

Criação de Pré-Autorização

Os parâmetros específicos para o serviço de criação de pré-autorização REST são os mesmos do serviço de pagamento, com a adição do seguinte campo:

Parâmetro	Descrição	Formato	Obrigatório
	additional_data
pre_auth_lifecycle	Representa o número de dias em que se considera válida a pré-autorização.	< 2 N	SIM

Captura de Pré-Autorização

Os parâmetros específicos para o serviço de captura de pré-autorização REST são os mesmos do serviço de pagamento citado acima.

Bin

Neste item serão apresentadas caracteristicas especificas para o roteamento Bin via SiTef.

Pagamento REST

Efetivação de Pagamento

A seguir, são listados os parâmetros com dados específicos para a transação via Bin que o aplicativo da loja virtual pode enviar no serviço de efetivação de pagamento REST:

Parâmetro	Descrição	Formato	Obrigatório
	external_authentication
ucaf_sli	Contêm o UCAF (Universal Cardholder Authentication Field), que corresponde ao último dígito do SLI (Security Level Indicator) do Mastercard Secure Code (para bandeira MasterCard).	= 1 N	NÃO
version	Versão do 3DS (1 ou 2).	= 1 N	NÃO
reference_id	Identificador do Directory Server para transações 3DS 2.0.	< 36 AN	NÃO
tavv	Criptograma de transação tokenizada DSRP-UCAF.	< 40 AN	NÃO

Sipag

Neste item serão apresentadas caracteristicas especificas para o roteamento Sipag via SiTef.

Pagamento REST

Efetivação de Pagamento

A seguir, são listados os parâmetros com dados específicos para a transação via Sipag que o aplicativo da loja virtual pode enviar no serviço de efetivação de pagamento REST:

Parâmetro	Descrição	Formato	Obrigatório
	external_authentication
ucaf_sli	Contêm o UCAF (Universal Cardholder Authentication Field), que corresponde ao último dígito do SLI (Security Level Indicator) do Mastercard Secure Code (para bandeira MasterCard).	= 1 N	NÃO
version	Versão do 3DS (1 ou 2).	= 1 N	NÃO
reference_id	Identificador do Directory Server para transações 3DS 2.0.	< 36 AN	NÃO
tavv	Criptograma de transação tokenizada DSRP-UCAF.	< 40 AN	NÃO

Banco do Brasil

Esta documentação descreve a integração com a plataforma de pagamento Banco do Brasil. Além de explicar, também, sobre as configurações que devem ser, necessariamente, efetuadas no ambiente do e-SiTef.

Interfaces e-SiTef suportadas para integração

A loja pode utilizar os seguintes serviços do e-SiTef para a integração com a plataforma Banco do Brasil (os respectivos documentos devem ser consultados para mais detalhes):

• Interface de Pagamento HTML
• Reemissão de Boletos

Configurações necessárias no e-SiTef

Antes de efetuar transações Banco do Brasil com o e-SiTef, devem ser seguidos os passos de configuração apresentados a seguir.

Dados Cadastrais do Banco do Brasil

A loja deve possuir uma conta ativa com o Banco do Brasil para realizar uma transação.

A tabela a seguir mostra as credenciais Banco do Brasil que devem ser obtidas pela loja e dados adicionais a serem inseridos no boleto, e que posteriormente serão cadastradas no e-SiTef:

Nome do parâmetro	Descrição	Formato	Obrigatório
idConvComercio	Identificador de Convênio de Comércio Eletrônico no Banco do Brasil	6 N	SIM
idConvCobranca	Identificador de Convênio de Cobrança no Banco do Brasil	< 7 N	SIM
diasVencimento	Quantidade de dias que deverá ser somado à data da geração do boleto que resultará na data de vencimento do boleto.	N	SIM
mensagem_boleto	Mensagem que será exibida na área de observações do boleto gerado.	< 480 N	NÃO

É necessário também que sejam configurados no portal do Banco do Brasil, na conta do cliente, alguns dados referentes ao e-SiTef:

Valores durante a etapa de Homologação:

URL de Retorno: https://esitef-homologacao.softwareexpress.com.br

URL de Informação: https://esitef-homologacao.softwareexpress.com.br

Assim que a homologação for finalizada e a loja for ativada em produção, os valores cadastrados devem ser modificados:

Valores para ambiente de Produção:

URL de Retorno: https://esitef-ec.softwareexpress.com.br

URL de Informação: https://esitef-ec.softwareexpress.com.br

Inserir dados cadastrais no e-SiTef

Tendo em mãos os dados cadastrais do Banco do Brasil citados acima, o lojista deve solicitar à equipe de atendimento do e-SiTef:

• A ativação do Banco do Brasil como uma autorizadora ativa no cadastro do e-SiTef.
• Caso não possua, um usuário e senha de acesso ao Portal do Lojista no e-SiTef.

Assim que a autorizadora Banco do Brasil estiver associada à loja, o lojista deve acessar o Portal do Lojista e informar os dados cadastrais do Banco do Brasil no item Configuração de Autorizadoras, com os parâmetros idConvComercio, idConvCobranca, diasVencimento, mensagem_boleto citados anteriormente.

Para mais detalhes de como cadastrar estes dados no portal do lojista, por favor, consulte o item sobre o Portal do Lojista - Configuração de Autorizadoras.

Código de Autorizadora para Banco do Brasil no e-SiTef

Para realizar pagamentos com a autorizadora pré-definida, envie um dos seguintes id's de autorizadora referentes ao Banco do Brasil:

• 404 - Boleto
• 415 - Débito PF
• 416 - Débito PF e PJ
• 417 - Crediário

Parâmetros para Pagamento HTML via Banco do Brasil

Sobre o fluxo inicial para iniciar uma transação HTML no e-SiTef com o Banco do Brasil, consulte o item sobre o Pagamento HTML.

Observação: Dados referentes a parcelamento não são repassados ao Banco do Brasil.

Atenção: Transações realizadas com a autorizadora Banco do Brasil, quando o cliente tiver optado pela geração de um boleto, terão seu status final como Processado (PRO), NÃO significando que ele já tenha sido pago, e sim apenas que houve a emissão. Este comportamento decorre da falta de ferramentas para tal verificação por parte do Banco do Brasil.

Parâmetros para transação via Banco do Brasil

O lojista pode enviar os parâmetros do Banco do Brasil para gerar boletos via e-SiTef.

Objeto additional_data

No objeto JSON additional_data, os seguintes parâmetros podem ser enviados:

Parâmetro	Descrição	Formato	Obrigatório
discount_amount	Valor do desconto em centavos. Usado apenas para boletos.	< 12 N	NÃO
discount_limit_date	Data de vencimento do desconto no formato DDMMAAAA. Usado apenas para boletos.	8 N	NÃO
duplicata_type	Informa o tipo de título que originará o boleto: DM - Duplicata Mercantil - utilizado quando forem vendidas mercadorias/produtos; DS - Duplicata de serviços - quando a loja virtual vender a prestação de serviços.	2 A	SIM¹

• ¹ Obrigatório para boleto.

Objeto additiona_data.payer

No Objeto additional_data.payer, os seguintes parâmetros podem ser enviados:

Parâmetro	Descrição	Formato	Obrigatório
name	Nome do comprador.	AN²	SIM
surname	Sobrenome do comprador.	AN²	SIM
address_street_name	Endereço do comprador.	AN³	SIM
address_street_number	Número do endereço do comprador.	AN³	SIM
address_street_complement	Complemento do endereço do comprador.	AN³	SIM
address_zip_code	CEP do comprador	8 N	SIM
city	Cidade do comprador	< 18 A	SIM
state	Estado (UF) do comprador	< 2 A	SIM
identification_number	Número do documento (CPF ou CNPJ) do comprador, sem formatação.	< 14 N	SIM¹
identification_type	Indica que o campo identification_number enviado representa: 1 - pessoa física 2 - pessoa jurídica	1 N	SIM¹

• ¹ Obrigatório para boleto.

• ² O tamanho dos campos name e surname somados não pode ser maior do que 59 caracteres. Conta-se um caractere de espaçamento entre os campos, para totalizar 60 caracteres.

• ³ O tamanho dos campos address_street_name, address_street_number e address_street_complement somados não pode ser maior do que 58 caracteres. Conta-se um caractere de espaçamento entre cada um dos campos, para totalizar 60 caracteres.

Observação: Tamanhos dos campos de acordo com a documentação fornecida pelo Banco do Brasil.

Fluxo de pagamento Banco do Brasil

Após enviar os dados de criação da transação e escolher o meio de pagamento Banco do Brasil, o seguinte fluxo de telas será iniciado:

A figura abaixo apresenta a tela anterior ao redirecionamento do comprador.

A figura seguinte apresenta a tela no Banco do Brasil, onde é realizado o pagamento:

Reemissão de Boletos

O e-SiTef disponibiliza a reemissão de boletos Banco do Brasil. Para isto, basta o redirecionamento do comprador para a seguinte url:

• https://esitef-homologacao.softwareexpress.com.br/e-sitef/reissue.se?nit=XXXXXXXXXXXXX
  (homologação)

• https://esitef-ec.softwareexpress.com.br/e-sitef/reissue.se?nit=XXXXXXXXXXXXX
  (produção)

Sendo que o envio do parâmetro nit é obrigatório e deve ser referente a uma transação de pagamento com o status Processada (PRO) com a autorizadora Banco do Brasil.

Caso a transação de pagamento não esteja no estado esperado, é apresentada a seguinte tela:

O simples acesso a esta URL já permite a visualização direta do boleto reemitido com os mesmos dados da primeira emissão, como na figura abaixo:

Exemplo de requisição no Pagamento HTML

URL de endpoint no ambiente de Homologação:

https://esitef-homologacao.softwareexpress.com.br/e-sitef/init.se

Exemplo do parâmetro “request” com os parâmetros da transação do e-SiTef + dados do Banco do Brasil (additional_data) em formato JSON:

{
   "merchant_id":"CODIGO_LOJA",
   "order_id":"1123456",
   "redirect":"M",
   "authorizer_id":"404",
   "amount":"2000",
   "installments":"1",
   "back_url":{
      "url_success":"url relativa de sucesso cadastrada no e-SiTef",
      "url_failure":" url relativa de fracasso cadastrada no e-SiTef",
      "url_cancel":" url relativa de cancelameto cadastrada no e-SiTef"
   },
   "additional_data":{
      "payer":{
         "name":"João",
         "surname":"Silva",
         "address_street_name":"Rua do Exemplo",
         "address_street_number":"123",
         "address_street_complement":"ap. 11",
         "city":"Sao Paulo",
         "address_zip_code":"01230120",
         "state":"SP"
      }
   }
}

Banrisul Vero

A loja tem a possibilidade de configurar o roteamento de transações feitas no e-SiTef por vários meios de pagamento, um desses meios é o Banri Compras, plataforma de pagamentos do banco Banrisul para e-commerce, desenvolvida pela rede Banrisul Vero.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento Banrisul Vero:

• Pagamento HTML

Credenciais necessárias

Para começar a transacionar com a Banrisul Vero, a loja deve obter o código de Rede, código de Estabelecimento e Senha de acesso para integração no ambiente da Banrisul Vero. Para isso, a loja deve solicitar sua credencial de acesso através do e-mail: srac@banrisul.com.br

Após recebimento, o lojista deve encaminhar o código de Estabelecimento e o código de Rede para a equipe produção da Software Express. Esses dados podem ser cadastrados também no Portal do Lojista do e-SiTef no item de menu "Configurar Autorizadoras".

A senha de acesso ao portal Banri Compras deve ser obrigatoriamente cadastrada pelo lojista no Portal do Lojista do e-SiTef. Este dado é importante para que o e-SiTef informe o status atualizado das transações efetuadas no Banri Compras na conta do lojista.

Saiba mais sobre o Portal do Lojista do e-SiTef.

Campo	Descrição
codigoEstabelecimento	Identificação do estabelecimento no Banrisul Vero.
codigoRede	Identificação da rede no Banrisul Vero.
senha	Senha de acesso ao Portal Banri Compras.

Parâmetros de requisição

A Banrisul Vero permite que sejam realizadas três modalidades de pagamento: à vista, parcelado ou pré-datado.

Todas as modalidades de pagamento acima são realizadas somente via transferência bancária.

Caso a opção escolhida for parcelada ou pré-datada, alguns parâmetros adicionais (additional_data.extra_param.params) devem ser enviados na requisição HTML como nos exemplos abaixo.

Saiba mais sobre a interface HTML.

À vista

Nenhum dado adicional é necessário nos casos de pagamentos à vista. O código de autorizadora (authorizer_id) é 411.

Exemplo de requisição

{  
   "merchant_id":"BANRICOMPRAS",
   "order_id":"09024709605",
   "authorizer_id":"411",
   "amount":"1000"
}

Parcelado

Campo	Descrição	Formato
bank_installments	Número de parcelas totais. Para a Banrisul Vero, este campo será utilizado no lugar do campo installments.	2 N
installment	Campo que informa quais parcelas serão pagas. Devem ser informadas no formato NN. Exemplo: 0102 (serão pagas as parcelas um e dois).	2 N a cada parcela
deadline_option	Campo que informa se o prazo de pagamento das parcelas será informado em dias ou por uma data específica. Valores permitidos: D – Definido por uma data. P – Definido por um prazo em dias.	1 A
deadline_date	Caso seja escolhida a opção D para o campo deadline_option, deve ser informado neste campo a data sugerida para o pagamento das parcelas. A data para cada parcela deve ser informada no formato AAAMMDD. Exemplo: 20181023 (23/10/2018). Ao informar a data de mais de uma parcela, concatenar as datas na ordem das parcelas. Exemplo: 2018102320181124 (para a primeira parcela a data é 23/10/2018 e para a segunda parcela 24/11/2018).	8 N a cada parcela
deadline_period	Caso seja escolhida a opção P para o campo deadline_option, deve ser informado neste campo o prazo sugerido para o pagamento das parcelas. O prazo para cada parcela deve ser informado no formato NNN. Exemplo: 030 (30 dias de prazo para o pagamento da parcela). Ao informar o prazo de mais de uma parcela, concatenar os prazos na ordem das parcelas. Exemplo: 030060 (para a primeira parcela o prazo é de 30 dias e para a segunda parcela 60 dias).	3 N a cada parcela
installments_amount	Informa o valor de cada parcela a ser paga. O valor das parcelas deve ser informado no formado 15 N. Exemplo: 000000000005000 (50 reais). Ao informar o valor de mais de uma parcela, concatenar os valores na ordem das parcelas. Exemplo: 000000000005000000000000006000 (para a primeira parcela o valor é de 50 reais e para a segunda parcela 60 reais).	15 N a cada parcela

Exemplo de requisição

{  
   "merchant_id":"BANRICOMPRAS",
   "order_id":"09035003921",
   "authorizer_id":"412",
   "amount":"1000",
   "additional_data":{  
      "extra_param":{  
         "params":[  
            {  
               "key":"bank_installments",
               "value":"02"
            },
            {  
               "key":"deadline_option",
               "value":"P"
            },
            {  
               "key":"installment",
               "value":"0102"
            },
            {  
               "key":"deadline_date",
               "value":""
            },
            {  
               "key":"deadline_period",
               "value":"000030"
            },
            {  
               "key":"installments_amount",
               "value":"000000000000500000000000000500"
            }
         ]
      }
   }
}

Pré-datado

Campo	Descrição	Formato
bank_installments	Obrigatoriamente 01.	2 N
installment	Obrigatoriamente 01.	2 N
deadline_option	Campo que informa se o prazo de pagamento das parcelas será informado em dias ou por uma data específica. Valores permitidos: D – Definido por uma data. P – Definido por um prazo em dias.	1 A
deadline_date	Caso seja escolhida a opção D para o campo deadline_option, deve ser informado neste campo a data sugerida para o pagamento da parcela. A data para cada parcela deve ser informada no formato AAAMMDD. Exemplo: 20181023 (23/10/2018). ATENÇÃO: Caso seja escolhida a opção P para o campo deadline_option, fixar o valor 00000000 neste campo.	8 N
deadline_period	Caso seja escolhida a opção P para o campo deadline_option, deve ser informado neste campo o prazo sugerido para o pagamento das parcelas. O prazo para cada parcela deve ser informado no formato NNN. Exemplo: 030 (30 dias de prazo para o pagamento da parcela).	3 N
installments_amount	Informa o valor de cada parcela a ser paga. O valor das parcelas deve ser informado no formado 15 N. Exemplo: 000000000005000 (50 reais).	15 N

Exemplo de requisição

{  
   "merchant_id":"BANRICOMPRAS",
   "order_id":"09024709605",
   "authorizer_id":"413",
   "amount":"5000",
   "additional_data":{  
      "extra_param":{  
         "params":[  
            {  
               "key":"bank_installments",
               "value":"01"
            },
            {  
               "key":"deadline_option",
               "value":"P"
            },
            {  
               "key":"installment",
               "value":"01"
            },
            {  
               "key":"deadline_date",
               "value":"00000000"
            },
            {  
               "key":"deadline_period",
               "value":"030"
            },
            {  
               "key":"installments_amount",
               "value":"000000000005000"
            }
         ]
      }
   }
}

Fluxo de Pagamento HTML

Ao realizar uma transação Banrisul Vero, o seguinte fluxo de telas será iniciado:

Saiba mais sobre a interface HTML.

Ao clicar no botão "ACESSAR BANCO" o comprador será redirecionado para o ambiente da Banri Compras:

Ao finalizar o processo de pagamento no ambiente da Banri Compras, o pagador será redirecionado para a página de fracasso ou sucesso que estão configuradas no portal da Banrisul. O próximo capítulo apresenta mais detalhes sobre a configuração de URL's.

Configuração de URL's de redirecionamento

Para realizar o cadastro de URL's de redirecionamento, deve-se acessar o Portal da Banrisul:

http://ww4.banrisul.com.br/banricompras/LINK/logon/Index.asp?info=true

Ao entrar com as credenciais de acesso, a seguinte tela será exibida:

Clique em páginas de aviso de operação para usuário e configure as URL's para as quais o pagador será redirecionado ao final do pagamento no ambiente Banri Compras:

Configurações de tempo no e-SiTef

O e-SiTef tem configurado por padrão alguns tempos relacionados a pagamentos Banrisul Vero:

Descrição	Valor padrão
Tempo para timeout de chamadas do e-SiTef ao Sistema Banrisul Vero	60 segundos
Máximo de dias que o e-SiTef efetua consulta de transações pendentes no Sistema Banrisul Vero	15 dias
Intervalo de tempo em segundos entre consultas de transações pendentes no Sistema Banrisul Vero	60 segundos
Quantidade máxima de consultas de transações pendentes no Sistema Banrisul Vero	10 consultas

Atenção: os valores descritos acima são apenas para referência inicial. Consulte a equipe de atendimento do e-SiTef para ter os valores exatos configurados no ambiente.

Cielo e-Commerce

A loja tem a possibilidade de configurar o roteamento de transações feitas com cartão de crédito no e-SiTef por vários meios de pagamento, um desses meios é o Cielo e-Commerce.

Nesta página será usada a nomenclatura "CieloEC" para referenciar o roteamento no e-SiTef.

Assim, a loja pode configurar o e-SiTef para que as transações feitas com cartões VISA, por exemplo, sejam roteadas pela CieloEC enquanto que as feitas com MASTERCARD sejam roteadas pela CIELO.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento CieloEC:

• Interface Pré Autorização REST
• Interface Pagamento REST
• Interface Cancelamento REST
• Interface Pagamento HTML
• Interface Pré-Autorização HTML

Observação: Esta integração também aceita o envio de dados de autenticação 3DS (eci, xid e cavv). Saiba mais.

Autorizadoras permitidas

As seguintes autorizadoras são suportadas pelo roteamento CieloEC:

• CRÉDITO

  • VISA (1)
  • MASTERCARD (2)
  • AMERICAN EXPRESS (3)
  • ELO (41)
  • AURA (6)
  • JCB (43)
  • DINERS (33)
  • DISCOVER (44)

• DÉBITO

  • VISA ELECTRON (221)
  • MASTERCARD DÉBITO (286)

• TRANSFERÊNCIA

  • BRADESCO (8)
  • BANCO DO BRASIL (408)

• ZERO DÓLLAR

  • VISA (1)
  • VISA ELECTRON (221)
  • MASTERCARD (2)
  • MASTERCARD DÉBITO (286)
  • ELO (41)

Credenciais necessárias

A loja deve obter com a CieloEC as credenciais listadas abaixo, e repassá-las à Software Express ou fazer o cadastro como explicado mais a frente neste mesmo documento.

Campo	Descrição	Formato
merchantID	Identificador da loja na CieloEC.	< 36 AN
merchantKey	Chave pública para a autenticação dupla na CieloEC.	< 40 AN

Importante para Pagamento HTML: No caso de uma autorizadora da loja não ter cadastrado essas credenciais, essa autorizadora não será exibida na tela de seleção de cartão de crédito durante a operação de pagamento.

Cadastro das informações pelo portal do lojista

O próprio lojista pode cadastrar as informações obtidas com a CieloEC no Portal do Lojista do e-SiTef. Para essa finalidade, o lojista deve selecionar a autorizadora e entrar na tela de edição como no exemplo exibido abaixo:

Cadastro do SoftDescriptor no e-SiTef

O cadastro do softDescriptor é opcional, possui tamanho 13, não aceita caracteres especiais e está disponível apenas para Visa e Mastercard.

Fluxos

Nesta seção serão apresentadas as particularidades do fluxo transacional CieloEC.

Pagamento REST

Essa interface suporta o envio da de campos de autenticação externa

Crédito

É possível enviar os seguintes campos na etapa de efetivação do pagamento:

Parâmetro	Descrição	Formato	Obrigatório
card
holder	Nome do portador impresso no cartão	< 25 AN	NÃO
external_authentication
eci	Eletronic Commerce Indicator – indica o nível de segurança da transação com autenticação do dono do cartão	< 3 N	NÃO
xid	Identificador da transação de autenticação do dono do cartão, feita em serviço externo ao e-SiTef	< 40 N	NÃO
cavv	Cardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão.	< 40 N	NÃO
version	Versão do 3DS utilizado no processo de autenticação.	1 AN	SIM para versão 2 do 3DS
reference_id	RequestID retornado no processo de autenticação.	36 AN	SIM para versão 2 do 3DS

Crédito com autenticação

É possível enviar o seguinte campo na etapa de criação da transação:

Parâmetro	Descrição	Formato	Obrigatório
authorizer_authentication	Define se o lojista deseja um pagamento com autenticação. Enviar true caso positivo.	< 5 AN	SIM para crédito com autenticação

Caso o pagamento seja bem sucedido, o serviço retornará a transação com status PEN (pendente) e terá o seguinte campo:

Parâmetro	Descrição	Formato
authentication_url	URL para qual o lojista deve redirecionar o comprador para a realização da autenticação.	< 56 AN

Após uma autenticação bem sucedida, o pagamento estará sempre confirmado (status CON), ou seja, não é possível um crédito com autenticação sem auto confirmação.

Na imagem abaixo é possível verificar o funcionamento do fluxo de uma transação com autenticação:

Débito

Com exceção das transações efetuadas por meio do Corona Voucher, todas as operações de débito sempre exigem autenticação e, com isso, independem do envio do campo authorizer_authentication. O fluxo a ser seguido é o mesmo de um crédito com autenticação.

Toda operação de débito é auto-confirmada, logo não permitimos realizar débito com confirmação tardia.

Crédito com análise de fraude

Para realizar um crédito com análise de fraude, é necessário enviar o campo additional_data contendo informações adicionais para anti-fraude. Seu valor segue o formato JSON conforme o exemplo abaixo:

{
   "amount":"1000",
   "authorizer_id":"1",
   "installments":"1",
   "installment_type":"4",
   "additional_data":{
      "payer":{
         "name":"Comprador",
         "surname":"credito AF",
         "email":"compradorteste@live.com",
         "city":"Rio de Janeiro",
         "state":"RJ",
         "address_street_name":"Rua Jupiter",
         "address_street_number":"174",
         "address_zip_code":"21241140",
         "born_date":"1991-01-02T08:30:00",
         "address_street_complement":"AP 201",
         "address_country":"BRA"
      },
      "shipment":{
         "method":"LOW_COST",
         "name":"Sr Comprador Teste",
         "phones":[
            {
               "number":"21114740",
               "ddd":"16",
               "ddi":"55"
            }
         ],
         "receiver_address":{
            "complement":"AP 201",
            "city":"Rio de Janeiro",
            "state":"RJ",
            "country":"BRA",
            "zip_code":"21241140",
            "street_number":"174",
            "street_name":"Rua Jupiter"
         }
      },
      "connections":[
         {
            "from":"RAO",
            "to":"SAO",
            "flight_date":"2020-01-02T20:15:00"
         }
      ],
      "gift":"false",
      "browser":{
         "email":"compradorteste@live.com",
         "agent":"Chrome",
         "cookies_accepted":"false",
         "host_name":"Teste",
         "ip_address":"200.190.150.350"
      },
      "items":[
         {
            "title":"ItemTeste",
            "quantity":"1",
            "id":"1487337308522",
            "risk":"HIGH",
            "hedge":{
               "time":"NORMAL",
               "host":"OFF",
               "nonSensical":"OFF",
               "obscenities":"OFF",
               "phone":"OFF",
               "velocity":"HIGH"
            },
            "passenger":{
               "name":"Comprador accept",
               "email":"compradorteste@live.com",
               "rating":"ADULT",
               "phone":{
                  "number":"999994444",
                  "ddd":"11",
                  "ddi":"55"
               },
               "legal_document":"1234567890",
               "customer_class":"Gold"
            },
            "unit_price":"1000",
            "category_id":"other",
            "gift_category":"OFF"
         }
      ],
      "extra_param":{
         "acquirer_params":[
            {
               "key":"95",
               "value":"Eu defini isso"
            }
         ]
      },
      "anti_fraud":"enabled_before_auth",
      "anti_fraud_institution":"AUTHORIZER",
      "anti_fraud_criteria":"ALWAYS",
      "finger_print_id":"074c1ee676ed4998ab66491013c565e2",
      "returns_accepted":"true",
      "journey_type":"OUTWARD"
   }
}

Na tabela a seguir estão descritos os campos do JSON:

Parâmetro	Descrição	Formato	Obrigatório
anti_fraud_institution	Instituição que efetuará a análise de fraude para a loja. Deve ser enviado com o valor AUTHORIZER.	< 10 AN	SIM para análise de fraude
anti_fraud	Habilita o serviço de análise de fraude. Valores permitidos: enabled_before_auth – a análise de fraude será realizada ANTES da autorização do pagamento. Caso a análise seja rejeitada, o pagamento não será iniciado. enabled_after_auth – a análise de fraude será realizada APÓS a autorização do pagamento. Caso a análise seja rejeitada, o pagamento que já foi autorizado será cancelado.	< 19 AN	SIM para análise de fraude
anti_fraud_criteria	Critério de execução da análise de fraude. Valores permitidos: ON_SUCCESS – só realiza a análise se tiver sucesso na transação. ALWAYS – sempre realiza a análise.	< 10 AN	NÃO
finger_print_id	Identificador utilizado para cruzar informações obtidas pelo Browser do internauta com os dados enviados para análise. Saiba mais	< 50 AN	NÃO
gift	Indica se o pedido é para presente ou não.	< 5 T/F	NÃO
returns_accepted	Define se devoluções são aceitas para o pedido.	< 5 T/F	NÃO
journey_type	Tipo de viagem. Valores permitidos: ROUND_TRIP – ida e volta. OUTWARD - ida RETURN- volta.	< 10 AN	NÃO
payer	Dados adicionais do comprador
name	Nome do comprador. Obs.: a concatenação de nome com o sobrenome não pode ultrapassar 255 caracteres.	< 200 AN	NÃO
surname	Sobrenome do comprador. Obs.: a concatenação de nome com o sobrenome não pode ultrapassar 255 caracteres.	< 200 AN	NÃO
email	E-mail do comprador.	< 255 AN	NÃO
born_date	Data de nascimento do comprador, no formato YYYY-MM-DDTHH:MM:SS Ex.: 1991-01-02T08:30:00	19 AN	NÃO
adress_street_name	Endereço do comprador.	< 255 AN	NÃO
adress_street_number	Número do endereço do comprador.	< 15 AN	NÃO
adress_street_complement	Complemento do endereço do comprador.	< 50 AN	NÃO
adress_zip_code	CEP do endereço do comprador. Ex.: 21241140.	< 9 AN	NÃO
city	Cidade do endereço do comprador.	< 9 AN	NÃO
state	Estado do endereço do comprador. Ex. SP	2 AN	NÃO
addres_country	País do endereço do comprador. Ex. BRA	< 35 AN	NÃO
shipment .receiver_address	Dados adicionais do endereço de entrega
street_name	Endereço de entrega.	< 255 AN	NÃO
street_number	Número do endereço de entrega.	< 15 AN	NÃO
complement	Complemento do endereço de entrega.	< 50 AN	NÃO
zip_code	CEP do endereço de entrega. Ex.: 21241-140.	< 9 AN	NÃO
city	Cidade do endereço de entrega.	< 50 AN	NÃO
state	Estado do endereço de entrega.	< 2 AN	NÃO
country	País do endereço de entrega seguindo a ISO 3166-1. Ex.: BRA	3 AN	NÃO
browser	Dados adicionais do navegador
cookies_accepted	Identifica se o browser do cliente aceita cookies. Enviar ‘true’ caso positivo.	< 5 AN	NÃO
email	E-mail registrado no browser do comprador.	< 100 AN	NÃO
host_name	Nome do host onde o comprador estava antes de entrar no site da loja.	< 60 AN	NÃO
ip_address	Endereço IP do comprador. É altamente recomendável o envio deste campo.	< 15 AN	NÃO
agent	Nome do browser utilizado pelo comprador. Ex.: Chrome.	< 40 AN	NÃO
items[]	Dados adicionais do produto
gift_category	Campo que avaliará os endereços de cobrança e entrega para diferentes cidades, estados ou países. Pode assumir os seguintes valores: OFF - Ignora a análise de risco para endereços divergentes. YES - Em caso de divergência entre endereços de cobrança e entrega, marca com risco pequeno. NO - Em caso de divergência entre endereços de cobrança e entrega, marca com risco alto.	< 3 AN	NÃO
risk	Nível do risco do produto. Pode assumir os seguintes valores: LOW - O produto tem um histórico de poucos chargebacks. NORMAL - O produto tem um histórico de chargebacks considerado normal. HIGH - O produto tem um histórico de chargebacks acima da média.	< 6 AN	NÃO
title	Nome do produto.	< 255 AN	NÃO
quantity	Quantidade do produto a ser adquirido.	< 15 N	NÃO
id	Código comerciante identificador do produto.	< 255 AN	NÃO
unit_price	Preço unitário do produto em centavos.	< 15 N	NÃO
category_id	Tipo do produto. Pode assumir os seguintes valores: art, baby, coupon, donation, computing, camera, video_game, television, car_electronic, electronic, automotive, entertainment, fashion, game, home, musical, phone, service, learning, ticket, travel, virtual_good, physical, other, adult_content, gift_certificate, handling, shipping, shipping_and_handling ou subscription	< 21 AN	NÃO
items[] .hedge	Dados adicionais da compra do produto
time	Nível de importância da hora do dia do pedido do cliente. Pode assumir os seguintes valores: LOW - Baixa importância no horário do dia em que foi feita a compra, para a análise de risco. NORMAL - Média importância no horário do dia em que foi feita a compra, para a análise de risco. HIGH - Alta importância no horário do dia em que foi feita a compra, para a análise de risco. OFF - O horário da compra não afeta a análise de risco.	< 6 AN	NÃO
host	Nível de importância do e-mail e endereços IP dos clientes em risco de pontuação. Pode assumir os seguintes valores: LOW - Baixa importância do e-mail e endereço IP na análise de risco. NORMAL - Média importância do e-mail e endereço IP na análise de risco. HIGH - Alta importância do e-mail e endereço IP na análise de risco. OFF - E-mail e endereço IP não afetam a análise de risco.	< 6 AN	NÃO
non_sensical	Nível dos testes realizados sobre os dados do comprador com pedidos recebidos sem sentido. Pode assumir os seguintes valores: LOW - Baixa importância da verificação feita sobre o pedido do comprador, na análise de risco. NORMAL - Média importância da verificação feita sobre o pedido do comprador, na análise de risco. HIGH - Alta importância da verificação feita sobre o pedido do comprador, na análise de risco. OFF - Verificação do pedido do comprador não afeta a análise de risco.	< 6 AN	NÃO
obscenities	Nível de obscenidade dos pedidos recebidos. Pode assumir os seguintes valores: LOW - Baixa importância da verificação sobre obscenidades do pedido do comprador, na análise de risco. NORMAL - Média importância da verificação sobre obscenidades do pedido do comprador, na análise de risco. HIGH- Alta importância da verificação sobre obscenidades do pedido do comprador, na análise de risco. OFF - Verificação de obscenidade no pedido do comprador não afeta a análise de risco.	< 6 AN	NÃO
phone	Nível dos testes realizados com os números de telefones. Pode assumir os seguintes valores: LOW - Baixa importância nos testes realizados com números de telefone. NORMAL - Média importância nos testes realizados com números de telefone. HIGH - Alta importância nos testes realizados com números de telefone. OFF - Testes de números de telefone não afetam a análise de risco.	< 6 AN	NÃO
velocity	Nível de importância de frequência de compra do cliente. Pode assumir os seguintes valores: LOW - Baixa importância no número de compras realizadas pelo cliente nos últimos 15 minutos. NORMAL - Média importância no número de compras realizadas pelo cliente nos últimos 15 minutos. HIGH - Alta importância no número de compras realizadas pelo cliente nos últimos 15 minutos. OFF - A frequência de compras realizadas pelo cliente não afeta a análise de fraude.	< 6 AN	NÃO
items[] .passenger	Dados adicionais do passageiro
email	E-mail do passageiro.	< 255 AN	NÃO
legal_document	Id do passageiro a quem o bilhete foi emitido.	< 32 AN	NÃO
name	Nome do passageiro.	< 120 AN	NÃO
rating	Classificação do passageiro. Pode assumir os seguintes valores: ADULT - Passageiro adulto. CHILD - Passageiro criança. INFANT - Passageiro infantil. YOUTH - Passageiro adolescente. STUDENT - Passageiro estudante. SENIOR_CITIZEN - Passageiro idoso. MILITARY - Passageiro militar.	< 14 AN	NÃO
customer_class	Classificação da empresa aérea. Pode-se usar valores como Gold ou Platina.	< 32 AN	NÃO
items[] .passenger .phone	Dados adicionais do telefone do passageiro
ddi	Código do país do telefone do passageiro. Para pedidos fora dos EUA, é recomendável o envio deste campo.	< 3 N	NÃO
ddd	Código da área do telefone do passageiro.	< 3 N	NÃO
number	Número de telefone do passageiro.	< 9 N	NÃO
extra_param .acquirer_params[]	Parâmetros adicionais da adquirente
key	Id das informações adicionais a serem enviadas.	< 1024 N	NÃO
value	Valor das informações adicionais a serem enviadas.	< 1024 AN	NÃO
shipment	Dados sobre o serviço de entrega
name	Nome do destinatário da entrega.	< 255 AN	NÃO
method	Tipo de serviço de entrega do produto. Pode assumir os seguintes valores: SAME_DAY – Serviço de entrega no mesmo dia. ONE_DAY – Serviço de entrega noturna ou no dia seguinte. TWO_DAY – Serviço de entrega em dois dias. THREE_DAY – Serviço de entrega em três dias. LOW_COST – Serviço de entrega de baixo custo. PICKUP – Produto retirado na loja. OTHER – Outro método de entrega. NONE – Sem serviço de entrega, pois é um serviço ou assinatura.	< 9 AN	NÃO
shipment .phones	Dados sobre o telefone do destinatário
ddi	Código do país do telefone do destinatário da entrega. Para pedidos fora dos E.U.A., é recomendável o envio deste campo.	< 3 AN	NÃO
ddd	Código da área do telefone do destinatário da entrega.	< 3 AN	NÃO
number	Número de telefone do destinatário da entrega.	< 9 AN	NÃO
connections[]	Dados sobre conexões do voo
flight_date	Data, hora e minuto de partida do voo no formato YYYY-MM-DDTHH:MM:SS Ex.: 1991-01-02T08:30:00	< 19 AN	NÃO
from	Código do aeroporto do ponto de origem da viagem. Ex.: CGH.	< 3 AN	NÃO
to	Código do aeroporto do ponto de destino da viagem. Ex.: GYN.	< 3 AN	NÃO

O retorno do pagamento contará com os seguintes campos adicionais:

Parâmetro	Descrição	Formato
payment .analysis	Dados sobre análise de fraude
code	Código de resposta da operação de análise de fraude.	< 4 N
message	Mensagem de resposta da operação de análise de fraude.	< 200 AN
status	Status da transação de análise de fraude do e-SiTef. Este campo pode assumir os seguintes valores: NOV – Nova. EXP – Expirada. ACC – Aceita REJ – Rejeitada REV – Em revisão INV – Inválida	= 3 AN

Zero Dóllar

A chamada do Zero Dóllar consiste numa chamada de pagamento com o campo amount com valor igual a zero e pode ser efetuada para Visa, Mastercard e Elo, Crédito e Débito, utilizando a interface REST.

Pagamento HTML

Os tópicos abaixo se referem à etapa de criação da transação, em que o lojista envia um documento JSON para o e-SiTef. Para mais informações sobre como efetuar um pagamento pela interface HTML, consulte a página de pagamento via HTML.

Crédito

Nenhuma particularidade em relação a outros meios de pagamento.

Crédito com autenticação

Para realizar um crédito com autenticação, o parâmetro abaixo deve ser enviado:

Parâmetro	Descrição	Formato	Obrigatório
authorizer_authentication	Define se o lojista deseja um pagamento com autenticação. Enviar true caso positivo ou false caso contrário. Este campo deve ser enviado com o valor true caso se deseje confirmar a transação, ou false, caso queira desfazer o pagamento.	< 5 AN	SIM para crédito com autenticação

Exemplo:

{
    "merchant_id":"LOJATESTE",
    "order_id":"20150925001",
    "amount":"1000",
    "transaction_type":"payment",
    "authorizer_authentication":"true"
}

Débito

Operações de débito sempre exigem autenticação e, com isso, independem do envio do campo authorizer_authentication.

Toda operação de débito é auto-confirmada, logo não permitimos realizar débito com confirmação tardia.

Crédito com análise de fraude

O lojista deverá enviar no elemento additional_data os campos referentes à análise de fraude. Exemplo:

{
   "merchant_id":"LOJACIELOEC",
   "merchant_usn":"9876",
   "order_id":"11",
   "redirect":"M",
   "authorizer_id":"",
   "amount":"1000",
   "installments":"",
   "installment_type":"",
   "style":"N",
   "soft_descriptor":"",
   "transaction_type":"payment",
   "back_url":{
      "url_success":"lojateste/loja/loja-index.jsp?pagina=sucesso",
      "url_failure":"lojateste/loja/loja-index.jsp?pagina=fracasso",
      "url_cancel":"lojateste/loja/loja-index.jsp?pagina=fracasso"
   },
   "additional_data":{
      "payer":{
         "name":"Comprador",
         "surname":"credito AF",
         "email":"compradorteste@live.com",
         "city":"Rio de Janeiro",
         "state":"RJ",
         "address_street_name":"Rua Jupiter",
         "address_street_number":"174",
         "address_zip_code":"21241140",
         "born_date":"1991-01-02T08:30:00",
         "address_street_complement":"AP 201",
         "address_country":"BRA"
      },
      "shipment":{
         "method":"LOW_COST",
         "name":"Sr Comprador Teste",
         "phones":[
            {
               "number":"21114740",
               "ddd":"16",
               "ddi":"55"
            }
         ],
         "receiver_address":{
            "complement":"AP 201",
            "city":"Rio de Janeiro",
            "state":"RJ",
            "country":"BRA",
            "zip_code":"21241140",
            "street_number":"174",
            "street_name":"Rua Jupiter"
         }
      },
      "connections":[
         {
            "from":"RAO",
            "to":"SAO",
            "flight_date":"2020-01-02T20:15:00"
                     }
      ],
      "gift":"false",
      "browser":{
         "email":"compradorteste@live.com",
         "agent":"Chrome",
         "cookies_accepted":"false",
         "host_name":"Teste",
         "ip_address":"200.190.150.350"
      },
      "items":[
         {
            "title":"ItemTeste",
            "quantity":"1",
            "id":"1488392648367",
            "risk":"HIGH",
            "hedge":{
               "time":"NORMAL",
               "host":"OFF",
               "17efine17ical":"OFF",
               "obscenities":"OFF",
               "phone":"OFF",
               "velocity":"HIGH"
            },
            "passenger":{
               "name":"Comprador accept",
               "email":"compradorteste@live.com",
               "rating":"ADULT",
               "phone":{
                  "number":"999994444",
                  "ddd":"11",
                  "ddi":"55"
               },
               "legal_document":"1234567890",
               "customer_class":"Gold"
            },
            "unit_price":"1000",
            "category_id":"other",
            "gift_category":"OFF"
         }
      ],
      "extra_param":{
         "acquirer_params":[
            {
               "key":"95",
               "value":"Eu 17efine isso"
            }
         ]
      },
      "anti_fraud":"enabled_before_auth",
      "anti_fraud_institution":"AUTHORIZER",
      "anti_fraud_criteria":"ALWAYS",
      "finger_print_id":"074c1ee676ed4998ab66491013c565e2",
      "returns_accepted":"true",
      "journey_type":"OUTWARD"
   }
}

Transferência Eletrônica

Nenhuma particularidade em relação a outros meios de pagamento.

Pré-Autorização REST

Crédito

É possível enviar o campo abaixo na etapa de efetivação da pré-autorização:

Parâmetro	Descrição	Formato	Obrigatório
card
holder	Nome do portador impresso no cartão	< 25 AN	NÃO
external_authentication
eci	Eletronic Commerce Indicator – indica o nível de segurança da transação com autenticação do dono do cartão	< 3 N	NÃO
xid	Identificador da transação de autenticação do dono do cartão, feita em serviço externo ao e-SiTef	< 40 N	NÃO
cavv	Cardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão.	< 40 N	NÃO
version	Versão do 3DS utilizado no processo de autenticação.	1 AN	SIM para versão 2 do 3DS
reference_id	RequestID retornado no processo de autenticação.	36 AN	SIM para versão 2 do 3DS

Crédito com análise de fraude

Para realizar um crédito com análise de fraude, é necessário enviar o campo additional_data contendo informações adicionais de anti-fraude. O formato de seu valor é o mesmo descrito aqui.

No retorno da pré-autorização, serão devolvidos adicionalmente os seguintes campos:

Parâmetro	Descrição	Formato
pre_authorization .analysis	Dados sobre análise de fraude
code	Código de resposta da operação de análise de fraude.	< 4 N
message	Mensagem de resposta da operação de análise de fraude.	< 200 AN
status	Status da transação de análise de fraude do e-SiTef. Este campo pode assumir os seguintes valores: NOV – Nova. EXP – Expirada. ACC – Aceita REJ – Rejeitada REV – Em revisão INV – Inválida	= 3 AN

Parcelamento

Dados de parcelamento devem ser enviados na etapa de efetivação da pré-autorização e caso não sejam enviados, o e-SiTef assume que a transação é à vista. Em seguida, na captura, os mesmos dados de parcelamento devem ser enviados.

Pré-Autorização HTML

Os tópicos abaixo se referem à etapa de criação da transação, em que o lojista envia um documento JSON para o e-SiTef. Para mais informações sobre como efetuar uma pré-autorização pela interface HTML, consulte a página de pré-autorização.

Crédito com/sem análise de fraude

Os parâmetros a serem enviados seguem o mesmo formato de um pagamento HTML.

Parcelamento

Na etapa de captura, os mesmos dados de parcelamento utilizados na pré-autorização devem ser enviados.

Cancelamento REST

Saiba mais sobre essa interface.

Cartões de testes

A Cielo disponibiliza o seguinte número de cartão para testes:

Bandeira	Número do Cartão	Vencimento	CVV
VISA	4024007197692931	12/2022	123

Restrições

O roteamento CieloEC não suporta pagamentos do tipo IATA (International Air Transport Association).

Campos de MCC Dinâmico

Inicialização da transação de pagamento ou de pré-autorização REST

Parâmetros de requisição

Adicionalmente aos campos mencionados no Serviço de criação de transação REST, os campos abaixo são usados no cenário específico de MCC dinâmico da integração com o Cielo ECommerce:

Parâmetro	Descrição	Formato	Obrigatório
soft_descriptor	Frase personalizada que será impressa na fatura do portador. Para informação referente ao MCC dinâmico, equivale ao nome do sublojista.	< 18 AN	SIM
additional_data	Elemento para envio de dados adicionais.
mcc	MCC do sublojista.	= 4 N	SIM
subacquirer_merchant_id	Código do sublojista. Campo legado!!! Dar preferência ao additional_data.subacquirer_merchant.id	< 15 N	NÃO
additional_data.subacquirer_merchant	Elemento para envio de dados referentes ao lojista de uma subadquirente.
id	Código do sublojista.	< 15 N	SIM
phone_number	Número de Telefone do sublojista.	< 14 AN	NÃO
address	Endereço do sublojista.	< 48 AN	NÃO
city	Cidade do sublojista.	< 13 AN	NÃO
state	Estado do sublojista, em formato de sigla de dois dígitos (ex.: SP).	= 2 A	SIM
country	País do sublojista. Seguir o padrão ISO 3166-1 alpha-2 (ex.: BR).	= 2 A	SIM
zip_code	Código postal do sublojista.	< 9 AN	SIM
identification_number	CNPJ do sublojista.	< 18 N	SIM
payment_facilitator_id	Código do facilitador.	< 11 N	SIM

Exemplo

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
  "merchant_usn": "19035815234",
  "order_id": "1616438400044",
  "installments": "1",
  "installment_type": "4",
  "authorizer_id": "2",
  "amount": "1300",
  "soft_descriptor": "L012121",
  "additional_data": {
    "mcc": "1111",
    "subacquirer_merchant": {
      "id": "12345",
      "address": "Avenida Paulista, 2000",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "zip_code": "01107001",
      "identification_number": "53455823000178",
      "payment_facilitator_id": "654321",
      "phone_number": "+55 11 99999-9999"
    }
  }
}

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "status": "NOV",
        "nit": "6215a32a557f5dc4627b540f517e40abd6a8411cf89a2e073913aa25d7c95590",
        "order_id": "1616438400044",
        "merchant_usn": "19035815234",
        "amount": "1300"
    }
}

Parâmetros na efetivação do pagamento ou da pré-autorização REST

Adicionalmente aos campos mencionados nos Serviço de efetivação de pagamento REST e Serviço de efetivação de Pré-Autorização REST, os campos abaixo são usados no cenário específico de MCC dinâmico da integração com a Cielo EC:

Parâmetro	Descrição	Formato	Obrigatório
soft_descriptor	Frase personalizada que será impressa na fatura do portador. Para informação referente ao MCC dinâmico, equivale ao nome do sublojista. Obrigatório somente se não foi enviado no soft_descriptor da etapa de inicialização da transação.	< 18 AN	COND.
mcc	MCC do sublojista. Obrigatório somente se não foi enviado no additional_data.mcc da etapa de inicialização da transação.	= 4 N	COND.
subacquirer_merchant_id	Código do sublojista. Obrigatório somente se não foi enviado no additional_data.subacquirer_merchant.id da etapa de inicialização da transação.	< 15 N	COND.

ATENÇÃO!

É na efetivação que enviamos os dados acumulados de MCC dinâmico. Porém, se o campo mcc não for enviado em nenhum momento nem estiver cadastrado, os outros campos de MCC dinâmico não serão repassados. Este campo é necessário para identificar que o lojista deseja enviar dados de subadquirência.

Exemplo

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "card": {
        "number": "4024007197692931",
        "expiry_date": "1222",
        "security_code": "123"
    }
}

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "6",
        "authorizer_message": "Operation Successful",
        "status": "CON",
        "nit": "6215a32a557f5dc4627b540f517e40abd6a8411cf89a2e073913aa25d7c95590",
        "order_id": "1616438400044",
        "customer_receipt":"=== CUSTOMER RECEIPT ===",
        "merchant_receipt":"=== MERCHANT RECEIPT ===",
        "authorizer_id": "2",
        "acquirer_id": "201",
        "acquirer_name": "Cielo e-Commerce",
        "authorizer_date": "22/03/2021T15:40",
        "authorization_number": "316176",
        "merchant_usn": "19035815234",
        "esitef_usn": "210322068747730",
        "host_usn": "362400",
        "tid": "9fcd1663-0662-4761-9b9b-b269217cfc32",
        "amount": "1300",
        "payment_type": "C",
        "authorizer_merchant_id": "6d29e58f-b29f-4e7e-8bf2-4d53b71acc1e",
        "payment_date": "22/03/2021T15:40"
    }
}

Tabela de correspondência de campos

Segue abaixo a tabela de correspondência entre os campos de MCC dinâmico definidos pela interface do Cielo ECommerce e os campos do e-SiTef.

Campo Cielo EC	Campo e-SiTef	Observações
Softdescriptor(1)	soft_descriptor	O campo soft_descriptor do e-SiTef pode ser enviado na etapa de criação da transação ou cadastrado pela equipe de atendimento do e-SiTef.
EstablishmentCode(3)	additional_data / subacquirer_merchant / payment_facilitator_id ou paymentFacilitatorId	O campo PaymentFacilitatorID do Cielo ECommerce pode ser enviado na etapa de criação da transação ou ser configurado quando um roteamento de uma autorizadora é feito via e.Rede REST. Neste último caso, o seu valor pode ser alterado pelo Portal do Lojista ("Autorizadoras" > "Configurar Autorizadoras") ou por solicitacão à equipe de atendimento do e-SiTef.
Mcc(2)	additional_data / mcc ou mcc	O campo mcc do e-SiTef pode ser enviado na etapa de criação da transação, na efetivação do pagamento ou da pré-autorização REST ou cadastrado pela equipe de atendimento do e-SiTef.
EstablishmentCode(2)	additional_data / subacquirer_merchant_id ou additional_data / subacquirer_merchant / id ou subacquirer_merchant_id ou subacquirerMerchantId	O campo SubMerchant / SubMerchantID pode ser enviado na etapa de criação da transação, na efetivação do pagamento ou da pré-autorização REST ou ser configurado quando um roteamento de uma autorizadora é feito via Cielo ECommerce. Neste último caso, o seu valor pode ser alterado pelo Portal do Lojista ("Autorizadoras" > "Configurar Autorizadoras") ou por solicitacão à equipe de atendimento do e-SiTef.
Identity(2)	additional_data / subacquirer_merchant / identification_number	Este campo pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
Address(2)	additional_data / subacquirer_merchant / address	Este campo pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
City(2)	additional_data / subacquirer_merchant / city	Este campo pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
State(2)	additional_data / subacquirer_merchant / state	Este campo pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
CountryCode(2)	additional_data / subacquirer_merchant / country	Este campo pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
PostalCode(2)	additional_data / subacquirer_merchant / zip_code	Este campo pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
PhoneNumber(2)	additional_data / subacquirer_merchant / phone_number	Este campo pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.

Legenda das estruturas
(1) Estrutura Payment
(2) Estrutura PaymentFacilitator.SubEstablishment
(3) Estrutura PaymentFacilitator

EPX

A loja tem a possibilidade de configurar o roteamento de transações feitas com cartão de crédito no e-SiTef por vários meios de pagamento, um desses meios é o EPX.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento EPX:

• Pré Autorização REST
• Pagamento REST
• Cancelamento REST
• Pagamento HTML
• Pré-Autorização HTML
• Cancelamento no Portal do Lojista

Credenciais necessárias

A loja deve obter com o EPX as credenciais listadas abaixo, e repassá-las à Software Express ou fazer o cadastro no Portal do Lojista do e-SiTef.

Parâmetro	Descrição
CUST_NBR	Nível de hierarquia do banco patrocinador do lojista nos sistemas internos do EPX.
MERCH_NBR	Nível de hierarquia de liquidação nos sistemas internos do EPX.
DBA_NBR	Nível de hierarquia de "doing business as" (DBA) nos sistemas internos do EPX.
TERMINAL_NBR	Nível de hierarquia do terminal nos sistemas internos do EPX.

Parâmetros de serviço de criação de transação

Requisição

Parâmetro	Descrição	Formato	Obrigatório
amount	Valor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto.	< 12 N	Sim
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N	Não
order_id	Código do pedido para ser exibido ao comprador, definido pelo lojista. É aconselhável que seja diferente a cada pedido para que facilite a rastreabilidade.	< 40 AN	Não
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador.	< 30 A	Não
additional_data	Campos adicionais
tax_amount	É um campo de referência que contém o valor do imposto incluído no valor da transação (em centavos).	< 12 N	Não
tax_exempt	Indica se a transação é isenta de impostos. Enviar um dos seguintes valores: Y - transação é isenta de impostos. N - transação não é isenta de impostos e necessita do envio do campo tax_amount.	< 1 A	Não
tip_amount	Contém o valor da gorjeta incluída no valor da transação (em centavos).	< 12 N	Não
additional_data .extra_param	Parâmetros extras
acquirer_params[]	Representa os campos opcionais que o comerciante pode usar para armazenar informações sobre a transação.	< 80 AN	Não
additional_data .payer	Dados do comprador
born_date	Data de nascimento do comprador, no formato AAAA-MM-DDTHH:MM:SS. Ex.: 1991-01-02T08:30:00	19 N	Não
name	Nome do comprador	< 25 A	Não
surname	Sobrenome do comprador	< 25 A	Não
identification_number	Documento de identificação do comprador (CPF/RG).	< 20 AN	Não
additional_data .payer .address	Endereço do comprador
street_name	Nome da rua do comprador. Este campo será enviado ao EPX concatenado com `street_number.	< 30 AN	Não
street_number	Número do endereço do comprador.	< 30 AN	Não
state	Estado do endereço do comprador. Ex.: SP	< 2 A	Não
zip_code	CEP do endereço do comprador	< 9 AN	Não
additional_data .payer .phones	Telefone do comprador
number	Contém o número de telefone do cliente.	< 10 N	Não
type	Campo utilizado para diferenciar os tipos de telefone: 6 - Celular 2 - Comercial 1 - Residencial	1 N	Não

IMPORTANTE: o EPX NÂO recebe informações relativas a parcelamento e financiamento. Com isso, somente transações à vista são suportadas.

Exemplo de requisição da chamada de criação de transação

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"2061433036",
   "order_id":"02061433035",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"1",
   "amount":"10000",
   "additional_data":{
      "payer":{
         "address":{
            "zip_code":"12345678",
            "street_number":"123",
            "street_name":"John Street",
            "city":"San Francisco",
            "state":"CA"
         },
         "phones":[
            {
               "number":"12345678901",
               "type":"6"
            }
         ]
      }
   }
}
--verbose

Parâmetros de serviço de efetivação do pagamento e pré-autorização

Requisição

Parâmetro	Descrição	Formato	Obrigatório
card	Dados do cartão
number	Número do cartão do comprador	< 19 N	Sim
barcode_data	Contém os dados do código de barras. Este campo deve ser enviado com o campo acquirer.input_type com valor A e suporta os formatos não criptografados PAN ou TLV Visa. Mais detalhes aqui.	< 100 AN	Não
id	Contém o código que representa a forma de identificação do portador do cartão. Pode receber os seguintes valores: 0 - Portador presente 1 - Portador não presente M - Portador presente, cartão ilegível	< 1 AN	Não
security_code	Código de segurança do cartão.	< 4 N	Não
expiry_date	Data de vencimento do cartão no formato MMAA.	4 N	Não
issue_number	Número de emissão do cartão de crédito.	< 3 N	Não
issue_date	Data de emissão do cartão de crédito no formato MMAA.	< 4 A	Não
card.crypto	Dados da criptografia do cartão
type	Identifica a encriptação utilizada: 0 - Usar o campo acquirer.input_type para identificar o formato 1 - Formato MagTek V2 2 Formato 3DES (genérica)	1 N	Não
card.crypto	Dados de EMV do cartão
data	Contém as tags EMV, em transações processadas por meio de chip EMV.	<510 AN	Não
track_1 ou track_2	Contém os dados da tarja magnética do cartão de crédito ou débito. track_1 deve ser usado ao processar uma transação com cartão de crédito, e track_2 deve ser usado se a track_1 estiver indisponível ou ao processar uma transação de débito ou EBT.	<256 AN	Não
acquirer	Dados da adquirente
aci	Identifica características específicas da transação. Pode receber os seguintes valores: R - Transação é recorrente P - Transação é uma parcela	1 AN	Não
input_type	Modo de entrada do cartão. Pode receber os seguintes valores: X - Digitado A - Código de barras H - Trilha 1 D - Trilha 2	1 A	Sim
cash_back_amount	Valor referente ao reembolso (em centavos).	<12 N	Não
reference_number	Número da conta de luz, telefone ou aluguel sendo paga nesta transação.	<25 AN	Não
operator_code	Contém o nome de usuário da pessoa que está enviando a transação.	<25 A	Não
soft_descriptor_2	Campo usado para substituir a seção de cidade/estado do Merchant Descriptor na fatura do portador do cartão.	<40 A	Não
terminal	Dados do terminal
chip_conditions	Campo usado para indicar o motivo da transação de fallback EMV : 0 - Não aplicável a transações de fallback. Para transações de VSDC deve ser 0 1 - A transação foi iniciada a partir de uma tarja magnética com um service code iniciado em 2 ou 6 e a última leitura no terminal VSDC foi uma leitura de chip bem-sucedida ou não foi uma transação de chip. 2 - A transação foi iniciada em um terminal compatível com chip de uma tarja magnética que contém service code 2 ou 6, e a transação anterior iniciada por esse terminal foi uma leitura de chip malsucedida.	1 N	Não
authentication	Dados de autenticação
authentication.pin	Dados do pin de autenticação
value	PIN Criptografado. Obrigatório quando for digitada a senha online do portador do cartão.	< 64 AN	Não
authentication.pin.crypto	Dados da criptografia do pin de autenticação
ksn	KSN da criptografia do PIN. Obrigatório quando for digitada a senha online do portador do cartão.	< 20 AN	Não

Detalhes do campo barcode_data

Posição	Tamanho	Formato	Descrição
1-3	3	N	Tipo: - 000 = PAN - Sem criptografia - 001 = Visa - TLV - Sem criptografia
4-N	Variável	ANS	Dados de código de barra

Exemplo de requisição da chamada de pagamento

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/api/v1/payments/1234567890abcdefghijklmnopqrstuvw
xyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"4111111111111111",
      "expiry_date":"1222"
   },
   "acquirer":{
      "input_type":"X"
   }
}
--verbose

Parâmetros de resposta

Parâmetro	Descrição	Formato
balance	Saldo disponível após pagamentos com vouchers (em centavos).	< 12 N
avs_result	Contém a resposta do Address Verification System para a transação solicitada.	1 A
authorization_number	Número de autorização.	< 6 AN
cvv2_response	Contém a resposta CVV2 para a transação solicitada.	1 A
emv_data	Dados EMV.	< 510 AN
tid	Identificação da transação no EPX.	< 20 AN
authorizer_response_code	Código de resposta do EPX.	< 3 AN
authorizer_response_message	Mensagem de resposta do EPX.	< 80 AN
authorizer_date	Data de efetivação do pagamento retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm. Exemplo: 13/07/2017T16:03	16 AN

Exemplo de resposta da chamada de pagamento

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"00",
      "authorizer_message":"EXACT MATCH",
      "status":"CON",
      "nit":"77866520f106682a128d0e2f8ef4c92517c043fa98e3a77a1ffd37ae884ebc47",
      "order_id":"02061433035",
      "customer_receipt":"===== RECEIPT= ====",
      "merchant_receipt":"===== RECEIPT= ====",
      "authorizer_id":"1",
      "acquirer_id":"0",
      "acquirer_name":"EPX",
      "authorizer_date":"02/01/2019T18:15",
      "authorization_number":"053130",
      "merchant_usn":"2061433036",
      "esitef_usn":"190102021262100",
      "tid":"09KGH48QH799RU2QY3V",
      "amount":"10000",
      "payment_type":"C",
      "authorizer_merchant_id":"700010",
      "avs_result":"Y",
      "payment_date":"02/01/2019T18:15"
   }
}

e.Rede REST

A loja tem a possibilidade de configurar o roteamento de transações feitas com cartões de crédito e débito no e-SiTef por vários meios de pagamento, um desses meios é o e.Rede REST. Esta é a plataforma e-commerce da adquirente Rede.

Será usada a nomenclatura "e.Rede REST" para referenciar o roteamento no e-SiTef.

Atenção: O e-SiTef possui o roteamento e-Rede, porém esta integração é uma versão anterior com funcionalidades limitadas e não terá mais suporte a atualizações. Logo, a opção e.Rede REST é a recomendada atualmente.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento e.Rede REST:

• Pagamento REST
• Pré-Autorização REST
• Captura REST
• Cancelamento REST
• Pagamento HTML
• Pré-Autorização HTML
• Cancelamento no Portal do Lojista

Credenciais necessárias

A loja deve obter com a e.Rede as credenciais listadas abaixo, e repassá-las à Software Express ou fazer o cadastro no Portal do Lojista do e-SiTef conforme será explicado mais a frente neste mesmo documento.

Campo	Descrição	Formato
filiation	Código identificador gerado pela Rede para os estabelecimentos filiados. O PV (ponto de venda) é único para cada estabelecimento.	< 8 AN
token	Código de segurança gerado pela Rede utilizado para garantir a integridade da transação. Faz parte, junto com o PV, das credenciais de autenticação da API	< 32 AN
threeDSecureOnFailure	Indica se deve prosseguir com a autorização em caso de falha na autenticação 3DS	Não prossegue ou Prossegue
subacquirerMerchantId	Código do sub lojista. Utilizável somente quando for usar o MCC Dinâmico	< 32 AN
independentSalesOrganizationId	Código da organização de vendas independente. Utilizável somente quando for usar o MCC Dinâmico	< 11 AN
paymentFacilitatorId	Código do facilitador. Utilizável somente quando for usar o MCC Dinâmico.	< 11 N

Aviso importante para o Pagamento HTML: No caso de uma autorizadora da loja não ter cadastrado essas credenciais, essa autorizadora não será exibida na tela de seleção de cartão de crédito durante a operação de pagamento.

Cadastro das informações pelo Portal do Lojista e-SiTef

O próprio lojista pode cadastrar as informações obtidas com a e.Rede no Portal do Lojista do e-SiTef. Para essa finalidade, o lojista deve selecionar a autorizadora e entrar na tela de edição como no exemplo exibido abaixo:

Saiba mais detalhes sobre o Portal do Lojista.

Fluxos

Nesta seção serão apresentadas as particularidades do fluxo transacional e.Rede REST.

Atualmente, o e.Rede REST não permite parcelamento com juros da administradora do cartão, ou seja, o campo installments_type não pode receber os valores 3 ou 6. O campo installments permite o máximo de 12 parcelas.

Criação de Transação de Pagamento (HTML e REST)

MCC Dinâmico

Campos relevantes na chamada descrita no Serviço de criação de transação HTML e no Serviço de criação de transação REST:

Parâmetro	Descrição	Formato	Obrigatório
soft_descriptor (*)	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais	< 13 AN	NÃO
additional_data	Elemento para envio de dados adicionais.
mcc (*)	O MCC (Merchant Category Code) é um código que classifica um negócio pelo tipo de bens ou produtos fornecidos.	< 4 N	NÃO
postpone_confirmation	Campo que permite que loja mantenha a transação como Pendente de Confirmação, e posteriormente, confirmá-la ou desfazê-la.	< 5 A	NÃO

(*) Aviso sobre SoftDescriptor e MCC: No contexto de marketplace ou facilitador de pagamentos, é permitido o uso de ambos os campos pela requisição ou utilizando dados cadastrados no backoffice do e-SiTef. Os valores enviados via requisição possuem precedência sobre os valores cadastrados. Adicionalmente, para o mesmo contexto, pode ser cadastrado no e-SiTef o id de SubLoja a ser informado no pagamento. Sobre o cadastro destes valores, por favor entre em contato com a equipe de atendimento do e-SiTef.

Autenticação 3DS Rede

Campos relevantes na chamada descrita no Serviço de criação de transação HTML e no Serviço de criação de transação REST:

Parâmetro	Descrição	Formato	Obrigatório
authorizer_authentication	Define se o lojista deseja um pagamento com autenticação na autorizadora. Enviar true caso positivo.	< 5 AN	SIM para crédito com autenticação
back_url	Elemento para envio das urls de redirecionamento utilizadas na autenticação MPI Rede
url_success (*)	URL de redirecionamento do cliente em caso de sucesso. Deve possuir apenas o caminho relativo ao domínio.	< 87 A	NÃO
url_failure (*)	URL de redirecionamento do cliente em caso de fracasso. Deve possuir apenas o caminho relativo ao domínio.	< 87 A	NÃO

É possível realizar um pagamento com autenticação 3DS MPI Rede, desde que esta funcionalidade esteja ativa na conta do lojista na e.Rede. Para utilizar esta funcionalidade no e-SiTef, basta enviar o parâmetro authorizer_authentication com valor true na etapa de criação da transação.

Para pagamentos com cartão de débito, a autenticação é obrigatória, a não ser no caso de Auxílio Emergencial.

(*) Importante: Para pagamentos REST com MPI Rede é obrigatório o envio das informações de backurl referentes aos casos de sucesso e fracasso, para o correto redirecionamento do usuário para a loja ao final do processo de autenticação.

Para cada uma delas o tamanho total da URL (domínio da loja cadastrado no e-SiTef + caminho relativo) deve possuir no máximo 87 caracteres.

Exemplo de requisição de criação de transação para Pagamento REST:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "merchant_usn":"123456789",
    "order_id":"pedido001",
    "amount":"2200",
    "authorizer_id":"2",
    "installments":"2",
    "installment_type":"4",
    "authorizer_authentication":"true",
    "back_url":{
        "url_success":"/urlSucesso.html",
        "url_failure":"/urlFracasso.html"
    }
}
{
--verbose

No caso de falha de autenticação, o lojista pode escolher dar prosseguimento no pagamento ou ter o pagamento interrompido(não prosseguir). Este comportamento deve ser cadastrado no backoffice do e-SiTef, sendo que o seu valor padrão é Não prosseguir caso a autenticação falhe. Para esta configuração, por favor consulte a equipe de atendimento do e-SiTef ou isto pode ser feito via Portal do Lojista.

Pagamento REST

Essa interface suporta o envio de dados de autenticação 3DS externa (eci, xid e cavv) na etapa de efetivação do pagamento. Saiba mais.

Esta integração aceita o uso da carteira digital Visa Checkout.

Pagamento HTML

No caso de pagamento com cartão de débito que não seja elegível para o auxílio emergencial, o e-SiTef forçará a autenticação 3DS com MPI Rede, independente do envio do campo authorizer_authentication na etapa de criação da transação.

Esta integração aceita o uso da carteira digital Masterpass.

Confirmação de Pagamento

É possível confirmar um valor inferior ao valor das autorizações criadas via HTML ou via REST utilizando o campo additional_data.postpone_confirmation igual a true.

Para isso, envie na chamada de confirmação REST o valor de amount desejado:

Parâmetro	Descrição	Formato	Obrigatório
confirm	Este campo deve ser enviado com o valor true caso se deseje confirmar a transação, ou false, caso queira desfazer o pagamento.	< 5 T/F	SIM
amount	Valor em centavos do valor que será confirmado. Caso não seja enviado, o valor completo da transação será confirmado.	< 12 N	NÃO

No e.Rede REST, a confirmação de pagamento gera um novo "NSU da autorizadora" e "data de efetivação do pagamento".

Pré-Autorização REST

Essa interface suporta o envio o envio de dados de autenticação externa 3DS (eci, xid e cavv). Saiba mais.

Também é possível o envio dos campos soft_descriptor e mcc na etapa de criação de transação, da mesma forma que no Pagamento REST (veja acima).

Esta integração aceita o uso da carteira digital Visa Checkout.

No fluxo de Pré-Autorização/Captura, os dados de parcelamento devem ser enviados somente na pré-autorização.

Pré-Autorização HTML

Esta integração aceita o uso da carteira digital Masterpass.

Também é possível o envio dos campos soft_descriptor e mcc na etapa de criação de transação, da mesma forma que no Pagamento HTML (veja acima).

No fluxo de Pré-Autorização/Captura, os dados de parcelamento devem ser enviados somente na pré-autorização.

Recorrência

O e.Rede REST aceita o parâmetros de sinalização de recorrência de transações. Para isso, envie na chamada de efetivação de pagamento REST o campo acquirer.recurrency com o valor true. Caso não seja a primeira transação da recorrência, envie também o TID da primeira transação da recorrência no campo acquirer.recurrency_tid.

Para mais informações consulte a página sobre o Serviço de Efetivação de Pagamento REST.

Parâmetro	Descrição	Formato	Obrigatório
acquirer	Dados específicos necessários dependendo da adquirente/roteamento.
recurrency	Flag que define se o pagamento é ou não recorrente.	< 5 T/F	NÃO
recurrency_tid	Id da transação (TID) na bandeira, referente à primeira transação da recorrência. Identificador que diferencia a primeira recorrência das subsequentes. Só é utilizado quando for uma recorrência. Campo utilizado somente para as bandeiras Visa e Mastercard.	< 16 AN	NÃO

Cancelamento

O Cancelamento de uma transação pode ser feito no Portal do Lojista ou via Web Service REST.

As solicitações de cancelamento podem ser realizadas em até 7 dias para transações de débito e para transações de crédito o padrão é de até 90 dias, mas pode variar conforme o ramo de atuação de cada estabelecimento.

Para cancelamentos solicitados no mesmo dia da transação de autorização ou autorização com captura automática, o processamento será realizado imediatamente, caso contrário, o processamento será realizado em D+1.

Cancelamento parcial disponível somente em D+1 e para transações com captura.

Campos de MCC Dinâmico

Inicialização da transação de pagamento ou de pré-autorização REST

Parâmetros de requisição

Adicionalmente aos campos mencionados no Serviço de criação de transação REST, os campos abaixo são usados no cenário específico de MCC dinâmico da integração com o e.Rede REST:

Parâmetro	Descrição	Formato	Obrigatório
soft_descriptor	Frase personalizada que será impressa na fatura do portador. Para informação referente ao MCC dinâmico, equivale ao nome do sublojista.	< 18 AN	SIM
additional_data	Elemento para envio de dados adicionais.
mcc	MCC do sublojista.	= 4 N	SIM
subacquirer_merchant_id	Código do sublojista. Campo legado!!! Dar preferência ao additional_data.subacquirer_merchant.id	< 15 N	NÃO
additional_data.subacquirer_merchant	Elemento para envio de dados referentes ao lojista de uma subadquirente.
id	Código do sublojista.	< 15 N	SIM
address	Endereço do sublojista.	< 48 AN	NÃO
city	Cidade do sublojista.	< 13 AN	NÃO
state	Estado do sublojista, em formato de sigla de dois dígitos (ex.: SP).	= 2 A	SIM
country	País do sublojista. Seguir o padrão ISO 3166-1 alpha-2 (ex.: BR).	= 2 A	SIM
zip_code	Código postal do sublojista.	< 9 AN	SIM
identification_number	CNPJ do sublojista.	< 18 N	SIM
payment_facilitator_id	Código do facilitador.	< 11 N	SIM
independent_sales_organization_id	Código da organização de vendas independente.	< 11 N	NÃO

Exemplo

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "merchant_usn": "21042858195",
    "order_id": "21042858195",
    "amount": "102",
    "installments": "1",
    "installment_type": "4",
    "mcc": "1111",
    "soft_descriptor": "LOJADOZE",
    "additional_data": {
         "subacquirer_merchant": {
            "id": "1234567890",
            "address": "Rua Acre",
            "city": "CAPIVARI",
            "state": "SP",
            "country": "BR",
            "zip_code": "07064-010",
            "identification_number": "71.789.371/0001-42",
            "payment_facilitator_id": "22349202212",
            "independent_sales_organization_id": "1234567"
        }
    }
}

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "pre_authorization": {
        "status": "NOV",
        "nit": "c2d2887a2961a218e6e6effa8a39f281d386d581c8c8b4dc23a3af03b5c6b8c4",
        "order_id": "21042858195",
        "merchant_usn": "21042858195",
        "amount": "102"
    }
}

Parâmetros na efetivação do pagamento ou da pré-autorização REST

Adicionalmente aos campos mencionados nos Serviço de efetivação de pagamento REST e Serviço de efetivação de Pré-Autorização REST, os campos abaixo são usados no cenário específico de MCC dinâmico da integração com o e.Rede REST:

Parâmetro	Descrição	Formato	Obrigatório
soft_descriptor	Frase personalizada que será impressa na fatura do portador. Para informação referente ao MCC dinâmico, equivale ao nome do sublojista. Obrigatório somente se não foi enviado no soft_descriptor da etapa de inicialização da transação.	< 18 AN	COND.
mcc	MCC do sublojista. Obrigatório somente se não foi enviado no additional_data.mcc da etapa de inicialização da transação.	= 4 N	COND.
subacquirer_merchant_id	Código do sublojista. Obrigatório somente se não foi enviado no additional_data.subacquirer_merchant.id da etapa de inicialização da transação.	< 15 N	COND.

ATENÇÃO!

É na efetivação que enviamos os dados acumulados de MCC dinâmico. Porém, se o campo mcc não for enviado em nenhum momento nem estiver cadastrado, os outros campos de MCC dinâmico não serão repassados. Este campo é necessário para identificar que o lojista deseja enviar dados de subadquirência.

Exemplo

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "authorizer_id":"2",
    "installments":"1",
    "installment_type":"4",
    "soft_descriptor":"outraloja",
    "mcc": "2234",
    "subacquirer_merchant_id": "223456",
    "card":{
        "number":"5448280000000007",
        "expiry_date":"0121",
        "security_code":"123"
    }
}

Resposta:

{
    "code":"0",
    "message":"OK. Transaction successful.",
    "pre_authorization":{
        "authorizer_code":"000",
        "authorizer_message":"Transacao OK.",
        "status":"CON",
        "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "customer_receipt":"=== CUSTOMER RECEIPT ===",
        "merchant_receipt":"=== MERCHANT RECEIPT ===",                
        "authorizer_id":"2",
        "authorizer_date":"09/11/2018T19:40",
        "acquirer_id":"1005",
        "acquirer_name":"Redecard",
        "authorization_number":"013245",
        "merchant_usn":"20190101",
        "esitef_usn":"181109017689784",
        "order_id":"orderID",
        "sitef_usn":"212194",
        "host_usn":"999212194",
        "amount":"100",
        "issuer":"2",
        "payment_type":"C",
        "authorizer_merchant_id":"000000000000000"
    }
}

Tabela de correspondência de campos

Segue abaixo a tabela de correspondência entre os campos de MCC dinâmico definidos pela interface do e.Rede REST e os campos do e-SiTef.

Campo e.Rede REST	Campo e-SiTef	Observações
softDescriptor	soft_descriptor	O campo softDescriptor do e.Rede REST pode ser enviado na etapa de criação da transação, na efetivação do pagamento ou da pré-autorização REST ou cadastrado pela equipe de atendimento do e-SiTef.
PaymentFacilitatorID	additional_data / subacquirer_merchant / payment_facilitator_id ou paymentFacilitatorId	O campo PaymentFacilitatorID do e.Rede REST pode ser enviado na etapa de criação da transação ou ser configurado quando um roteamento de uma autorizadora é feito via e.Rede REST. Neste último caso, o seu valor pode ser alterado pelo Portal do Lojista ("Autorizadoras" > "Configurar Autorizadoras") ou por solicitacão à equipe de atendimento do e-SiTef.
IndependentSalesOrganizationID	additional_data / subacquirer_merchant / independent_sales_organization_id ou independentSalesOrganizationId	O campo IndependentSalesOrganizationID do e.Rede REST pode ser enviado na etapa de criação da transação ou ser configurado quando um roteamento de uma autorizadora é feito via e.Rede REST. Neste último caso, o seu valor pode ser alterado pelo Portal do Lojista ("Autorizadoras" > "Configurar Autorizadoras") ou por solicitacão à equipe de atendimento do e-SiTef.
SubMerchant / MCC	additional_data / mcc ou mcc	O campo SubMerchant / MCC do e.Rede REST pode ser enviado na etapa de criação da transação, na efetivação do pagamento ou da pré-autorização REST ou cadastrado pela equipe de atendimento do e-SiTef.
SubMerchant / SubMerchantID	additional_data / subacquirer_merchant_id ou additional_data / subacquirer_merchant / id ou subacquirer_merchant_id ou subacquirerMerchantId	O campo SubMerchant / SubMerchantID do e.Rede REST pode ser enviado na etapa de criação da transação, na efetivação do pagamento ou da pré-autorização REST ou ser configurado quando um roteamento de uma autorizadora é feito via e.Rede REST. Neste último caso, o seu valor pode ser alterado pelo Portal do Lojista ("Autorizadoras" > "Configurar Autorizadoras") ou por solicitacão à equipe de atendimento do e-SiTef.
SubMerchant / Address	additional_data / subacquirer_merchant / address	O campo SubMerchant / Address do e.Rede REST pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
SubMerchant / City	additional_data / subacquirer_merchant / city	O campo SubMerchant / City do e.Rede REST pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
SubMerchant / State	additional_data / subacquirer_merchant / state	O campo SubMerchant / State do e.Rede REST pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
SubMerchant / Country	additional_data / subacquirer_merchant / country	O campo SubMerchant / Country do e.Rede REST pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
SubMerchant / CEP	additional_data / subacquirer_merchant / zip_code	O campo SubMerchant / CEP do e.Rede REST pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
SubMerchant / Cnpj	additional_data / subacquirer_merchant / identification_number	O campo SubMerchant / Cnpj do e.Rede REST pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.

ATENÇÃO!

Quando um campo puder ser enviado de mais de uma forma, sempre prevalecerá o valor do campo enviado mais recentemente ou mais específico. Ou seja, a prioridade segue a regra: mais recente > mais específico > cadastral.

Exemplo: Se o campo SubMerchant / SubMerchantID for enviado na efetivação, este terá prioridade sobre o enviado na inicialização, o qual tem prioridade sobre o campo cadastral.

Fepas HUB

A loja tem a possibilidade de configurar o roteamento de transações feitas no e-SiTef por vários meios de pagamento, um desses meios é o FEPAS HUB.

O objetivo desta documentação é descrever os campos disponíveis no e-SiTef para viabilizar a venda no FEPAS HUB.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento Fepas HUB:

• Pagamento REST
• Cancelamento REST
• Logon REST
• Carga de Tabelas REST

ATENÇÃO: A funcionalidade de agendamento não é suportada para este roteamento.

Pagamento REST

Os campos a seguir são complementares aos menciados na documentação de Serviço de efetivação de pagamento.

Efetivação de Pagamento REST

Requisição de Pagamento

Parâmetro	Descrição	Formato	Obrigatório
resubmission_id	ID usado para ressubmeter um pagamento negado anteriormente em determinados casos conforme permitido pelo emissor.	= 16 N	Cond.
acquirer_id	Código do roteamento a ser utilizado na transação. Pode assumir os valores dos códigos descritos na tabela Códigos de Roteamento. Caso este campo não seja enviado, a configuração da autorizadora da loja será utilizada para definir o roteamento.	< 4 N	NÃO
authentication	Atributo do tipo authentication
terminal	Atributo do tipo terminal
card	Atributo do tipo card
mtt	Atributo do tipo mtt

Exemplo de Requisição de Pagamento

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "card":{
        "expiry_date":"1222",
        "crypto":{
            "ksn":"xxxxxxxxxxx"
        },
        "track_2":"****************************************",
        "pos_entry_mode":{
            "value":"07",
            "pin_capability":"2"
        },
        "emv":{
            "card_sequence_number":"xxxxxx",
            "data":"820258009F2701809F2608B42433F98916B3319F36020074"
        }
    },
    "terminal":{
        "id":"SE111111",
        "type":"2",
        "input_mode":"5",
        "pin_pad_physical_features":"6",
        "handling_type":"1",
        "reader_capabilities":"7"
    },
    "mtt": {
        "id": "1",
        "first_journey_date": "0925",
    },
    "resubmission_id": "0123456789012345"
}
--verbose

Resposta de Pagamento

Parâmetro	Descrição	Formato
resubmission_id	ID a ser usado para ressubmeter em caso de pagamento negado.	= 16 N
payment	Atributo do tipo payment
card	Atributo do tipo resp_card

Exemplo de Resposta de Pagamento

{
    "code":"0",
    "message":"OK. Transaction successful."
    "payment":{
        "authorizer_code":"000",
        "authorizer_message":"Transacao OK",
        "status":"CON",
        "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id":"13034649671",
        "customer_receipt":"====CUPOM COMPRADOR====",
        "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
        "authorizer_id":"2",
        "acquirer_id":"0005",
        "acquirer_name":"FEPAS HUB",
        "authorizer_date":"07/08/2018T16:52",
        "authorization_number":"132030",
        "merchant_usn":"13034649671",
        "esitef_usn":"170713097340300",
        "sitef_usn":"132030",
        "host_usn":"999132030",
        "tid": "000030000016",
        "payment_date":"07/08/2018T16:52",
        "amount":"1000",
        "payment_type":"C",
        "issuer":"2",
        "authorizer_merchant_id":"000000000000005",
        "acquirer_table_load_required":"0",
        "conciliation_authorizer_merchant_id":"6887542",
        "authorization_terminal":{
            "usn":"555845",
            "id":"SE111111"
        }
    },
    "resubmission_id": "0123456789012345"
}

Confirmação de Pagamento REST

Os campos a seguir são complementares aos menciados na documentação de Serviço de confirmação de pagamento.

Requisição de Confirmação

Parâmetro	Descrição	Formato	Obrigatório
issuer_scripts_results	Issuer Scripts Results Presente se a transação for efetuada com chip EMV.	= N/A AN	Cond.

Exemplo de Requisição de Confirmação

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr?confirm=true&issuer_scripts_results=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--header "merchant_id:xxxxxxxxxxxxxxx"
--header "merchant_key:xxxxxxxxxxx"
--verbose

Resposta de Confirmação

Não há campos adicionais.

Exemplo de Resposta de Confirmação

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "status": "CON"
    }
}

Cancelamento REST

Efetivação de Cancelamento REST

Os campos a seguir são complementares aos menciados na documentação de Serviço de cancelamento.

Requisição de Cancelamento

Parâmetro	Descrição	Formato	Obrigatório
terminal	Atributo do tipo terminal
card	Atributo do tipo card
authentication	Atributo do tipo authentication

Exemplo de Requisição de Cancelamento

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "card":{
        "crypto":{
            "ksn":"xxxxxxxxxxx"
        },
        "pos_entry_mode":{
            "value":"81",
            "pin_capability":"1"
        },
        "track_2":"****************************************",
        "expiry_date":"1222"
    },
    "terminal":{
        "id":"SE111111",
        "type":"0",
        "input_mode":"5",
        "pin_pad_physical_features":"3",
        "handling_type":"1",
        "reader_capabilities":"4",
        "chip_conditions":"2"
    },
    "authentication":{
        "pin":{
            "crypto":{
                "type":"002"
            }
        }
    },
    "amount":"1500"
}
--verbose

Resposta de Cancelamento

Parâmetro	Descrição	Formato	Obrigatório
cancellation	Atributo do tipo cancellation

Exemplo Resposta de Cancelamento

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "cancellation": {
        "authorizer_code": "00",
        "authorizer_message": "Sucesso",
        "status": "CON",
        "nit": "10f53cd3dab3222e5e37b725dfe368331958866a2d07c4ba7f382a8c5f42fd9e",
        "order_id": "03110843259",
        "customer_receipt": "=== RECIBO DE CANCELAMENTO ===",
        "authorizer_id": "2",
        "acquirer_id": "412",
        "acquirer_name": "FEPAS HUB",
        "authorizer_date": "03/09/2018T11:09",
        "authorization_number": "030020",
        "merchant_usn": "3110843259",
        "esitef_usn": "180903014387861",
        "sitef_usn": "000060",
        "host_usn": "999030021",
        "tid": "000030000014",
        "amount": "1500",
        "payment_type": "C",
        "authorizer_merchant_id": "000000000100250",
        "conciliation_authorizer_merchant_id": "000000000100250",
        "authorization_terminal": {
            "usn": "030021",
            "id": "F1000001"
        },
        "esitef_date": "03/09/2018T11:09",
        "is_host_cancel": "false"
    }
}

Logon REST

O Logon é uma funcionalidade exclusiva do roteamento FEPAS.

Caso o campo version enviado na requisição esteja diferente do campo acquirer_table_load.version da resposta, será necessário realizar a Carga de Tabelas.

Requisição de Logon

Parâmetro	Descrição	Formato	Obrigatório
authorizer_id	Código da autorizadora.	< 4 N	SIM
acquirer_id	Código do roteamento a ser utilizado na transação. Pode assumir os valores dos códigos descritos na tabela Códigos de Roteamento. Caso este campo não seja enviado, a configuração da autorizadora da loja será utilizada para definir o roteamento.	< 4 N	NÃO
version	Versão das tabelas de parâmetros presentes na rede de captura referente a um Autorizador. Cada Autorizador terá uma versão distinta de parâmetros. Nota: Caso ainda não haja tabelas no estabelecimento, enviar zeros.	< 8 N	SIM
terminal	Atributo do tipo terminal NOTA: Apenas o atributo id contido no atributo do tipo terminal é necessário no Logon.

Exemplo de Requisição de Logon

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/acquirer_tables"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "authorizer_id":"2",
    "version":"4",
    "terminal": {
        "id":"ES000001"
    }
}
--verbose

Resposta de Logon

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0 significa falha. Para maiores informações, consulte a seção de Códigos da API.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
acquirer_table	Atributo do tipo acquirer_table

Exemplo de Resposta de Logon

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "acquirer_table": {
        "code": "00",
        "message": "Sucesso",
        "acquirer_id": "5",
        "acquirer_name": "Redecard",
        "usn": "000230",
        "merchant_code": "000000000100250",
        "version": "40361885",
        "signature": "R8yxlnT24sSm1Zt77Jj44pohO8LapTNjWt1nqV8zGKg=",
        "date": "06/09/2018T11:32:31"
    }
}

Carga de Tabelas REST

A Carga de Tabelas é uma funcionalidade exclusiva do roteamento FEPAS. Esta requisição só pode ser executada após o Logon e reutiliza as informações retornadas por este, como os valores dos campos: acquirer_table.usn, authorizer_id, version e terminal.id.

Requisição de Carga de Tabelas

Parâmetro	Descrição	Formato	Obrigatório
authorizer_id	Código da autorizadora. Deve ser o mesmo valor do Logon.	< 4 N	SIM
acquirer_id	Código do roteamento a ser utilizado na transação. Pode assumir os códigos descritos na tabela Códigos de Roteamento. Caso este campo não seja enviado, a configuração da autorizadora da loja será utilizada para definir o roteamento.	< 4 N	NÃO
version	Versão das tabelas de parâmetros presentes na rede de captura referente a um Autorizador. Cada Autorizador terá uma versão distinta de parâmetros. Deve ser o mesmo valor do Logon NOTA: Caso ainda não haja tabelas no estabelecimento, enviar zeros.	< 4 N	SIM
terminal	Atributo do tipo terminal NOTA: Apenas o atributo id contido no atributo do tipo terminal é necessário na Carga de Tabelas.

Exemplo de Requisição de Carga de Tabelas

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/acquirer_tables/<valor do acquirer_table.usn>"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "authorizer_id":"2",
    "version":"4",
    "terminal": {
        "id":"ES000001"
    }
}
--verbose

Resposta de Carga de Tabelas

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0 significa falha. Para maiores informações, consulte a seção de Códigos da API.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
acquirer_table	Atributo do tipo acquirer_table

Exemplo de Resposta de Carga de Tabelas

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "acquirer_table": {
        "code": "00",
        "message": "Sucesso",
        "acquirer_id": "5",
        "acquirer_name": "Redecard",
        "usn": "000230",
        "merchant_code": "000000000100250",
        "version": "40361885",
        "signature": "R8yxlnT24sSm1Zt77Jj44pohO8LapTNjWt1nqV8zGKg=",
        "date": "06/09/2018T11:41:49",
        "credit_bins": [{
            "bin": {
                "start": "549202000",
                "end": "549202999"
            },
            "brand_code": "005",
            "is_voucher": "N",
            "features": "24",
            "subtype": "00"
        },
        {
            "bin": {
                "start": "549221000",
                "end": "549221999"
            },
            "brand_code": "005",
            "is_voucher": "N",
            "features": "24",
            "subtype": "00"
        }],
        "public_keys": [{
            "rid": "A000000004",
            "certification_authority_public_key_index": "F3",
            "certification_authority_public_key_exponent_size": "1",
            "certification_authority_public_key_exponent": "03",
            "certification_authority_public_key_modulus_size": "144",
            "certification_authority_public_key_modulus": "98F0C770F23864C2E",
            "checksum_status": "1",
            "certification_authority_public_key_checksum": "FCB86DA7076023DB8F38D992680175A839FFC9A6"
        },
        {
            "rid": "A000000004",
            "certification_authority_public_key_index": "F1",
            "certification_authority_public_key_exponent_size": "1",
            "certification_authority_public_key_exponent": "03",
            "certification_authority_public_key_modulus_size": "176",
            "certification_authority_public_key_modulus": "A0DCF4BDE19C3546B4B",
            "checksum_status": "1",
            "certification_authority_public_key_checksum": "55CD192717EE59A8E80A2B2D77528F6552F23BBE"
        }],
        "emv_params": [{
            "aid_code": "01",
            "aid_length": "07",
            "aid": "A0000000041010                 ",
            "application_type": "01",
            "application_name": "                ",
            "default_value": "03",
            "version_opt1": "0002",
            "version_opt2": "0002",
            "version_opt3": "0002",
            "terminal_country_code": "076",
            "transaction_currency_code": "986",
            "transaction_currency_exponent": "2",
            "merchant_id": "000000000100250",
            "merchant_category_code": "0000",
            "terminal_id": "00000000",
            "terminal_capabilities": "E0F0C8",
            "terminal_capabilities_additional": "FF80B0F001",
            "terminal_type": "22",
            "terminal_action_code_default": "FE50BCA000",
            "terminal_action_code_denial": "0000000000",
            "terminal_action_code_online": "FE50BCF800",
            "terminal_floor_limit": "00000000",
            "transaction_category_code": "R",
            "tdol": "9F02065F2A029A039C0195059F37040000000000",
            "ddol": "9F37040000000000000000000000000000000000",
            "authorization_response_code_offline_approved": "Y1",
            "authorization_response_code_offline_declined": "Z1",
            "authorization_response_code_unable_online_offline_approved": "Y3",
            "authorization_response_code_unable_online_offline_declined": "Z3",
            "contactless_zero_amount": "1",
            "contactless_mode": "4",
            "contactless_transaction_limit": "05F5E0FF",
            "contactless_floor_limit": "00000000",
            "contactless_cvm_limit": "00001389",
            "contactless_application_version": "0000",
            "contactless_selection_mode": "1",
            "contactless_terminal_action_code_default": "FC509C8800",
            "contactless_terminal_action_code_denied": "0000000000",
            "contactless_terminal_action_code_online": "FC509C8800"
        },
        {
            "aid_code": "02",
            "aid_length": "07",
            "aid": "A0000000043060                  ",
            "application_type": "02",
            "application_name": "                ",
            "default_value": "03",
            "version_opt1": "0002",
            "version_opt2": "0002",
            "version_opt3": "0002",
            "terminal_country_code": "076",
            "transaction_currency_code": "986",
            "transaction_currency_exponent": "2",
            "merchant_id": "000000000100250",
            "merchant_category_code": "0000",
            "terminal_id": "00000000",
            "terminal_capabilities": "E0D0C8",
            "terminal_capabilities_additional": "FF80B0F001",
            "terminal_type": "22",
            "terminal_action_code_default": "FE50BCA000",
            "terminal_action_code_denial": "0000000000",
            "terminal_action_code_online": "FE50BCF800",
            "terminal_floor_limit": "00000000",
            "transaction_category_code": "R",
            "tdol": "9F02065F2A029A039C0195059F37040000000000",
            "ddol": "9F37040000000000000000000000000000000000",
            "authorization_response_code_offline_approved": "Y1",
            "authorization_response_code_offline_declined": "Z1",
            "authorization_response_code_unable_online_offline_approved": "Y3",
            "authorization_response_code_unable_online_offline_declined": "Z3",
            "contactless_zero_amount": "1",
            "contactless_mode": "4",
            "contactless_transaction_limit": "05F5E0FF",
            "contactless_floor_limit": "00000000",
            "contactless_cvm_limit": "00001389",
            "contactless_application_version": "0000",
            "contactless_selection_mode": "1",
            "contactless_terminal_action_code_default": "FC501C8800",
            "contactless_terminal_action_code_denied": "0000800000",
            "contactless_terminal_action_code_online": "FC501C8800"
        }],
        "emv_tags": [{
            "aid_code": "46",
            "all_emv_tags": "9f269f109f379f36959c9f025f2a829f1a9f03"
        },
        {
            "aid_code": "45",
            "all_emv_tags": "9f269f109f379f36959c9f025f2a829f1a9f03"
        }],
        "mandatory_emv_tags": [{
            "aid_code": "46",
            "mandatory_emv_tags": "9f269f109f379f36959c9f025f2a829f1a9f03"
        },
        {
            "aid_code": "45",
            "mandatory_emv_tags": "9f269f109f379f36959c9f025f2a829f1a9f03"
        }],
        "optional_emv_tags": [{
            "aid_code": "46",
            "optional_emv_tags": "5f3484"
        },
        {
            "aid_code": "45",
            "optional_emv_tags": "5f3484"
        }],
        "brand_per_credit_aid": [{
            "aid_code": "01",
            "brand_code": "002"
        },
        {
            "aid_code": "01",
            "brand_code": "004"
        }],
        "brand_per_debit_aid": [{
            "aid_code": "02",
            "brand_code": "002"
        },
        {
            "aid_code": "02",
            "brand_code": "005"
        }]
    }
}

Tipos de Dados

authentication

Parâmetro	Descrição	Formato	Obrigatório
pin	Atributo do tipo authentication.pin

authentication.pin

Parâmetro	Descrição	Formato	Obrigatório
value	PIN Criptografado. Obrigatório quando for digitada a senha online do portador do cartão.	< 16	Cond.
crypto	Atributo do tipo pin.crypto

pin.crypto

Parâmetro	Descrição	Formato	Obrigatório
type	Processo de Criptografia do PIN. Pode assumir os valores dos códigos descritos na tabela Códigos de Processo de Criptografia. Obrigatório apenas quando o PIN é enviado.	= 3	Cond.
ksn	KSN da criptografia do PIN. Obrigatório quando for digitada a senha online do portador do cartão.	< 20 AN	Cond.

terminal

Parâmetro	Descrição	Formato	Obrigatório
id	Identificação do terminal.	< 8 AN	SIM
type	Tipo do Atendimento do Terminal. Pode assumir os valores dos códigos descritos na tabela Códigos de Tipo de Atendimento de Terminal.	= 1 N	SIM
input_mode	Capacidade de entrada do terminal. Pode assumir os valores dos códigos descritos na tabela Códigos de Capacidade de Entrada do Terminal.	= 1 N	SIM
pin_pad_physical_features	Características Físicas do PIN-pad. Pode assumir os valores dos códigos descritos na tabela Códigos de Características Físicas do Terminal.	= 1 N	SIM
handling_type	Tipo de tratamento da senha. Pode assumir os valores dos códigos descritos na tabela Códigos de Tipo de tratamento da Senha.	= 1 N	SIM
reader_capabilities	Habilitação de Leitores de Cartão. Pode assumir os valores dos códigos descritos na tabela Códigos de Habilitação de Leitores de Cartão.	= 1 N	SIM
chip_conditions	Condições do CHIP. Pode assumir os valores dos códigos descritos na tabela Códigos de Condições do CHIP.	= 1 N	SIM

card

Parâmetro	Descrição	Formato	Obrigatório
service_code	Service Code, campo obrigatório quando o tipo de transação for trilha ou chip. Este campo prevê 3 posições, sendo os 3 dígitos após a data de validade da trilha 2, de acordo com a norma ISO/IEC 7813. Exemplo de trilha 2: ;1234567890123445=99011200XXXX00000000?* Service Code: 120.	= 3 N	Cond.
bin	BIN do Cartão, campo obrigatório para transações digitadas, trilha ou chip. Este campo prevê 6 posições, sendo os 6 primeiros dígitos após a sentinela de início da trilha 2, de acordo com a norma ISO/IEC 7813. Exemplo de trilha 2: ;1234567890123445=99011200XXXX00000000?* Bin do cartão: 123456.	= 6 N	Cond.
last4	4 últimos dígitos do cartão, Campo obrigatório para transações digitadas, trilha ou chip. Este campo prevê 4 posições, sendo os 4 últimos dígitos antes do separador ("=") da trilha 2, de acordo com a norma ISO/IEC 7813. Exemplo de trilha 2: ;1234567890123445=99011200XXXX00000000?* 4 últimos dígitos: 3445.	= 6 N	Cond.
track_1	Início da trilha 1 criptografada, conforme regra acordada entre a Loja e a Software Express. Presente se lida a trilha 1.	AN N/A	Cond.
track_2	Leitura da Trilha 2 do cartão ou da identificação do cliente. Criptografado por hardware, conforme regra acordada entre a Loja e a Software Express. Presente se lida a trilha 2.	< 99	Cond.
subtype	Subtipo do cartão. Pode assumir os valores dos códigos descritos na tabela Códigos de Subtype. Obrigatório em caso de compra com cartão voucher.	= 2 AN	Cond.
crypto	Atributo do tipo card.crypto
pin	Atributo do tipo card.pin
pos_entry_mode	Atributo do tipo pos_entry_mode
emv	Atributo do tipo emv
number	Número do Cartão (PAN). Utilizado no(s) serviço(s) de: Cancelamento	LLvar n..99 N	Cond.
expiry_date	Data de Vencimento do Cartão. Utilizado no(s) serviço(s) de: Cancelamento	= 4 N	Cond.
security_code	Código de Segurança do Cartão. Utilizado no(s) serviço(s) de: Cancelamento	= 6 N	Cond.

card.crypto

Parâmetro	Descrição	Formato	Obrigatório
ksn	KSN da criptografia do PAN.	< 20 AN	NÃO

card.pin

Parâmetro	Descrição	Formato	Obrigatório
value	PIN Criptografado. Obrigatório quando for digitada a senha online do portador do cartão.	< 64	Cond.

resp_card

Parâmetro	Descrição	Formato
token	HASH de um cartão armazenado no e-SiTef. Não é permitido enviar um número de cartão aberto (campo 'number') e um cartão armazenado (campo 'token') na mesma requisição.	= 88 AN
par	PAR (Payment Account Reference).	= 29 AN

pos_entry_mode

Parâmetro	Descrição	Formato	Obrigatório
value	Modo de entrada do cartão. Pode assumir os valores dos códigos descritos na tabela Códigos de Modo de Entrada.	= 2 N	SIM
pin_capability	Capacidade do terminal em relação à entrada de PIN. Pode assumir os valores dos códigos descritos na tabela Códigos de Capacidade de Entrada PIN.	= 1 N	SIM

emv

Parâmetro	Descrição	Formato	Obrigatório
card_sequence_number	Número de sequência do Cartão. Corresponde à via do cartão EMV em tratamento (tag 5F34). Só enviar se a transação efetuada for com chip EMV e o cartão informar este dado.	< 3 N	Cond.
data	Contém as tags EMV, em transações processadas por meio de chip EMV. Seu conteúdo é enviado em bytes no formato ASCII seguindo o formato TLV: tipo, tamanho, conteúdo. Por exemplo, se formos enviar: Tag: 82 - (Application Interchange Profile), tamanho: 2, valor: 5800; Tag: 9F27 - (Cryptogram Information Data), tamanho: 1, valor: 80; Tag: 9F26 - (Application Cryptogram), tamanho: 8, valor: b42433f98916b331. O campo resultante ficaria: "data":"820258009F2701809F2608B42433F98916B331"	< 999 N/A	Cond.

mtt

Parâmetro	Descrição	Formato	Obrigatório
id	ID transação MTT (Mass Transport Transaction). Informa qual o tipo da transação solicitada. Pode assumir os valores dos códigos descritos na tabela Códigos de ID de Transação MTT.	= 1 N	Cond.
first_journey_date	Data da primeira viagem de transação MTT. Segue o formato: MMDD.	= 4 N	Cond.

payment

Parâmetro	Descrição	Formato
acquirer_table_load_required	Informa se a Loja necessita realizar uma Carga de Tabelas junto a um Autorizador. 0 - Parâmetros atualizados. 1 - Parâmetros desatualizados - Loja necessita realizar Carga de Tabelas.	= 1 N
conciliation_authorizer_merchant_id	Código de Estabelecimento da Venda.	= 15
authorization_terminal	Atributo do tipo authorization_terminal

cancellation

Parâmetro	Descrição	Formato
acquirer_table_load_required	Informa se a Loja necessita realizar uma Carga de Tabelas junto a um Autorizador. 0 - Parâmetros atualizados; 1 - Parâmetros desatualizados - Loja necessita realizar Carga de Tabelas.	= 1 N
conciliation_authorizer_merchant_id	Código de Estabelecimento da Venda.	= 15 N
authorization_terminal	Atributo do tipo authorization_terminal

authorization_terminal

Parâmetro	Descrição	Formato
usn	NSU do Terminal da Autorização.	= 6 N
id	Identificação do Terminal da Autorização.	= 8 AN

acquirer_table

Parâmetro	Descrição	Formato
code	Código de resposta da operação no FEPAS.	= 2 AN
message	Mensagem de resposta do FEPAS.	< 999 AN
usn	NSU da operação.	= 6 N
date	Data e hora local.	= 19 N
authorizer_id	Código da autorizadora.	< 4 N
merchant_code	Código do estabelecimento.	< 15 AN
version	Versão das tabelas de parâmetros presentes na rede de captura referente a um Autorizador. Cada Autorizador terá uma versão distinta de parâmetros. NOTA: Caso ainda não haja tabelas no estabelecimento, serão enviados zeros.	< 8 N
signature	Identificação do Terminal da Autorização.	< 999 AN
acquirer_id	Código da adquirente. Retornado no(s) serviço(s) de: Carga de Tabelas	< 4 N
acquirer_name	Nome da adquirente. Retornado no(s) serviço(s) de: Carga de Tabelas	N/A AN
credit_bins[]	Atributo do tipo product_bins Retornado no(s) serviço(s) de: Carga de Tabelas
debit_bins[]	Atributo do tipo product_bins Retornado no(s) serviço(s) de: Carga de Tabelas
emv_params[]	Atributo do tipo emv_params Retornado no(s) serviço(s) de: Carga de Tabelas
public_keys[]	Atributo do tipo public_keys Retornado no(s) serviço(s) de: Carga de Tabelas
mandatory_emv_tags[]	Atributo do tipo mandatory_emv_tags Retornado no(s) serviço(s) de: Carga de Tabelas
optional_emv_tags[]	Atributo do tipo OPTIONAL_EMV_TAGS Retornado no(s) serviço(s) de: Carga de Tabelas
emv_tags[]	Atributo do tipo emv_tags Retornado no(s) serviço(s) de: Carga de Tabelas
brand_per_credit_aid[]	Atributo do tipo brand_per_x_aid Retornado no(s) serviço(s) de: Carga de Tabelas
brand_per_debit_aid[]	Atributo do tipo brand_per_x_aid Retornado no(s) serviço(s) de: Carga de Tabelas

product_bins

Parâmetro	Descrição	Formato
brand_code	Contém o código identificando a bandeira do range. Pode assumir os valores dos códigos descritos na tabela Códigos de Bandeira.	= 2 AN
is_voucher	Informa se o cartão é do tipo Voucher. Valores possíveis: S - Sim N - Não	= 1 AN
features	Mapa de bits composto por 1 byte binário (2 caracteres ASCII hexadecimal) indicando as características da coleta da transação. A posição 8 corresponde ao bit mais significativo. Se o bit estiver ligado, a funcionalidade correspondente estará habilitada. Ordem do byte: 87654321 A relação dos bits pode ser consultada no Mapa de Features.	= 2 AN
subtype	Subtipo do cartão. Pode assumir os valores dos códigos descritos na tabela Códigos de Subtype.	= 2 AN
bin	Atributo do tipo bin

bin

Parâmetro	Descrição	Formato
start	Contém o BIN inicial do Range.	= 9 N
end	Contém o BIN final do Range (este campo é igual ao anterior quando tratamento individual de BIN).	= 9 N

emv_params

Parâmetro	Descrição	Formato
aid_code	Código do AID.	= 2 N
aid_length	Tamanho do AID, em bytes (de 05 a 16).	= 2 N
aid	AID - Application Identifier (alinhado à esquerda).	= 32 H
application_type	Tipo de Aplicação. Valores possíveis: 01 - Crédito 02 - Débito	= 2 N
application_name	Etiqueta default da aplicação.	= 61 AN
default_value	Padrão da aplicação. 03 - EMV.	= 2 N
version_opt_1	Application Version Number (Terminal) - opção #1.	= 4 h
version_opt_2	Application Version Number (Terminal) - opção #2.	= 4 h
version_opt_3	Application Version Number (Terminal) - opção #3.	= 4 h
terminal_country_code	Terminal Country Code.	= 3 N
transaction_currency_code	Transaction Currency Code.	= 3 N
transaction_currency_exponent	Transaction Currency Exponent.	= 1 N
merchant_id	Merchant Identifier.	= 15 AN
merchant_category_code	Merchant Category Code.	= 4 N
terminal_id	Terminal Identification.	= 8 AN
terminal_capabilities	Terminal Capabilities. É o mapa de bits indicando as capacidades do terminal. O formato e os valores podem ser consultados no Mapa de Capacidades do Terminal.	= 6 H
terminal_capabilities_additional	Additional Terminal Capabilities.	= 10 H
terminal_type	Terminal Type. Pode assumir os valores dos códigos descritos na tabela Códigos de Tipo de Terminal.	= 2 N
terminal_action_code_default	Terminal Action Code - Default.	= 10 H
terminal_action_code_denial	Terminal Action Code – Denial.	= 10 H
terminal_action_code_online	Terminal Action Code – Online.	= 10 H
terminal_floor_limit	Terminal Floor Limit.	= 8 H
transaction_category_code	Transaction Category Code.	= 1 AN
tdol	Transaction Category Code. Default Transaction Certificate Data Object List (TDOL) (completado com bytes "00" à direita).	= 40 H
ddol	Default Dynamics Data Authentication Data Object List (DDOL) (completado com bytes "00" à direita).	= 40 H
authorization _response_code _offline_approved	Authorization Response Code - offline approved.	= 2 AN
authorization _response_code _offline_declined	Authorization Response Code - offline declined.	= 2 AN
authorization _response_code _unable_online_offline_approved	Authorization Response Code - unable to go online - offline approved.	= 2 AN
authorization _response_code _unable_online_offline_declined	Authorization Response Code - unable to go online - offline declined.	= 2 AN
contactless_zero_amount	Indica a ação para cartão com chip sem contato se o valor da transação estiver zerado. Valores possíveis: 0 - Não suporta. 1 - Suporta, porém somente online.	= 1 N
contactless_mode	Capacidade de tratamento do terminal para o referido AID, caso este seja localizado em um cartão com chip sem contato. Pode assumir os valores dos códigos descritos na tabela Códigos de Capacidade de Tratamento de Terminal.	= 1 N
contactless_transaction_limit	Terminal/Reader Contactless Transaction Limit.	= 8 H
contactless_floor_limit	Terminal/Reader Contactless Floor Limit.	= 8 H
contactless_cvm_limit	Terminal/Reader CVM Required Limit.	= 8 H
contactless_application_version	PayPass Mag Stripe Application Version Number (Terminal).	= 4 H
contactless_selection_mode	Indica a forma de seleção da aplicação do cartão sem contato. Valores possíveis: 0 - A aplicação é selecionada automaticamente pela prioridade. 1 - Deve ser mostrado menu de seleção caso exista outra aplicação compatível.	= 1 N
contactless _terminal_action _code_default	Terminal Action Code – Default (para cartões sem contato).	= 10 H
contactless _terminal_action _code_denied	Terminal Action Code – Denied (para cartões sem contato).	= 10 H
contactless _terminal_action _code_online	Terminal Action Code – Online (para cartões sem contato).	= 10 H

public_keys

Parâmetro	Descrição	Formato
rid	RID - Registered Application Provider Identifier.	= 10 H
certification_authority _public_key_index	Certification Authority Public Key Index.	= 2 H
certification_authority _public_key_exponent_size	Tamanho em bytes do Certification Authority Public Key Exponent (1 ou 3).	= 1 N
certification_authority _public_key_exponent	Certification Authority Public Key Exponent (alinhado à esquerda).	= 6 H
certification_authority _public_key_modulus_size	Tamanho em bytes do Certification Authority Public Key Modulus (até 248).	= 3 N
certification_authority _public_key_modulus	Certification Authority Public Key Modulus (alinhado à esquerda).	= 496 H
checksum_status	Status do Check Sum (Hash SHA-1). Valores possíveis: 0 - Não utilizado. 1 - Presente.	= 1 N
certification_authority _public_key_checksum	Certification Authority Public Key Check Sum (Hash SHA-1).	= 40 h

mandatory_emv_tags

Parâmetro	Descrição	Formato
aid_code	Código AID.	= 2 N
mandatory_emv_tags	Contém a lista de Tags EMV obrigatórias a serem enviadas nos dados EMV das mensagens de solicitação ou advice de transações do fluxo EMV Completo, tanto online como off-line, após o First Generate AC. Exemplo: 9F269F27959F10.	N/A AN

optional_emv_tags

Parâmetro	Descrição	Formato
aid_code	Código AID.	= 2 N
optional_emv_tags	Contém a lista de Tags EMV opcionais a serem enviadas nos dados EMV das mensagens de solicitação ou advice de transações do fluxo EMV Completo, tanto online como off-line, após o First Generate AC.	N/A AN

emv_tags

Parâmetro	Descrição	Formato
aid_code	Código AID.	= 2 N
all_emv_tags	Contém a lista de Tags EMV a serem enviadas no Bit 55 das mensagens de confirmação ou advice de transações do fluxo EMV Completo, tanto online como off-line, após o Second Generate AC. Exemplo: 9F269F27959F10.	N/A AN

brand_per_x_aid

Parâmetro	Descrição	Formato
aid_code	Código AID.	= 2 N
brand_code	Contém o código AID.	= 3 N

Tabelas & Mapas

Códigos de Roteamento

Código	Descrição
2005	Rede
2013	GoodCard
2047	Sorocred
2052	Tricard
2054	Up Brasil
2072	Bigcard
2077	Valecard
2094	Cabal
2125	Cielo
2201	VR
2206	Global Payments
2265	Stone
2309	Adiq
5001	Alelo

Códigos de Bandeira

Código	Descrição
001	Visa
002	Mastercard
003	Amex
005	Hipercard
006	Diners
008	JCB
012	Sorocred
014	Policard
016	Elo
017	Cabal
043	Tricard
054	Valecard
058	VR
065	Alelo
158	Bigcard
235	Up
999	Bandeira desconhecida

Mapa de Features

Bit	Descrição
8	Reservado para uso futuro.
7	Transação magnética solicita os quatro últimos dígitos.
6	Permite Fallback magnético.
5	Reservado para uso futuro.
4	Reservado para uso futuro.
3	Transação magnética solicita CVV2/CVC2.
2	Reservado para uso futuro.
1	Permite CVV inexistente ou ilegível.

Códigos de Subtype

Código	Descrição
01	Débito/Voucher Alimentação
02	Débito/Voucher Refeição
03	Débito/Voucher Cultura
00	O cartão não é um débito/voucher

Mapa de Capacidades do Terminal

Formato:

ABCxxxxx DEFGKxxx HIJMxxxx

Posição	Descrição
A	Digitação de número do cartão.
B	Cartão magnético.
C	Cartão com chip de contatos.
D	Verificação em cartão com chip de PIN "em aberto".
E	Verificação online de PIN com criptografia.
F	Assinatura em papel.
G	Verificação em cartão com chip de PIN com criptografia.
K	Aceita o método "No CVM" (sem verificação do portador).
H	SDA - Autenticação estática de dados do cartão com chip.
I	DDA - Autenticação dinâmica de dados do cartão com chip.
J	Captura de cartão.
M	Autenticação offline CDA.

Códigos de Tipo de Terminal

Código	Descrição
21	Online.
22	Off-line com capacidade online.
23	Somente off-line.
24	Online, não atendido.
25	Off-line com capacidade online, não atendido.
26	Somente off-line, não atendido.

Códigos de Capacidade de Tratamento de Terminal

Código	Descrição
0	Não suporta.
1	Suporta VISA MSD.
2	Suporta VISA qVSDC.
3	Suporta MasterCard PayPass Mag Stripe.
4	Suporta MasterCard PayPass M/Chip.
5	Suporta Amex Expresspay Magstripe Mode.
6	Suporta Amex Expresspay EMV Mode.

Códigos de Processo de Criptografia

Código	Descrição
001	3DES entre Loja e Autorizador (bypass Software Express).
002	3DES entre Loja e Software Express, que realiza o translate para Autorizador.
003	DUKPT 3DES entre Loja e Autorizador (bypass Software Express).
004	DUKPT 3DES entre Loja e Software Express, que realiza o translate para Autorizador.

Códigos de Tipo de Atendimento do Terminal

Código	Descrição
0	Terminal com atendimento (estabelecimento possui operador para o terminal).
2	Terminal com auto-atendimento.

Códigos de Capacidade de Entrada do Terminal

Código	Descrição
0	Indefinido.
2	Sem terminal (URA/Voz).
5	Leitor de chip.

Códigos de Características Físicas do Terminal

Código	Descrição
3	PIN-pad com leitor de chip.
6	PIN-pad com leitor de chip e cartão sem contato.

Códigos de Tipo de tratamento da Senha

Código	Descrição
1	Sem senha.
2	Senha online.
3	Senha off-line.

Códigos de Habilitação de Leitores de Cartão

Código	Descrição
4	Leitor tarja e chip habilitados.
5	Leitor tarja e cartão sem contato habilitado.
6	Leitor chip e cartão sem contato habilitado.
7	Leitor tarja, chip e cartão sem contato habilitado. PIN-pad com leitor de chip.

Códigos de Condições do CHIP

Código	Descrição
1	Trilha sem fallback.
2	Trilha com fallback.

Códigos de Modo de Entrada

Código	Descrição
01	Entrada manual do número do cartão (digitado).
02	Tarja magnética.
05	Chip.
07	Contactless chip.
81	Fallback para tarja magnética (usado quando ocorre falha na leitura do chip e a posição 1 do Service Code da trilha = 2 ou 6, sinalizando cartão com chip).
91	Contactless tarja magnética.

Códigos de Capacidade de Entrada PIN

Código	Descrição
1	Tem capacidade de entrada de PIN;
2	Não tem capacidade de entrada de PIN.

Códigos de ID de Transação MTT

Código	Descrição
1	AVR (transação deve vir com o valor zerado).
2	Transação Crédito MTT.
3	Debt Recovery (ressubmissão, necessário enviar o campo resubmission_id).
4	Debt Recovery e-commerce/MOTO (para transações digitadas).
5	Debt Recovery tap online (para transações contactless).

Getnet WS

A loja tem a possibilidade de configurar o roteamento de transações feitas com cartão de crédito no e-SiTef por vários meios de pagamento, um desses meios é a Getnet.

Nesta página será usada a nomenclatura "GetnetWS" para referenciar o roteamento no e-SiTef.

Assim, a loja pode configurar o e-SiTef para que as transações feitas com cartões VISA, por exemplo, sejam roteadas pela GetnetWS enquanto que as feitas com MASTERCARD sejam roteadas pela CIELO.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento GetnetWS:

• Pagamento REST
• Pré-Autorização REST
• Cancelamento REST
• Pagamento HTML
• Pré-Autorização HTML

Autorizadoras permitidas

As seguintes autorizadoras são suportadas pelo roteamento GetnetWS:

• VISA
• MASTERCARD
• ELO
• AMERICAN EXPRESS
• HIPERCARD
• VISA ELECTRON
• MAESTRO

Credenciais necessárias

A loja deve obter com a GetnetWS as credenciais listadas abaixo, e repassá-las à Software Express ou fazer o cadastro como explicado mais a frente neste mesmo documento.

Campo	Descrição	Formato
username	Usuário de acesso.	< 20 N
password	Senha de acesso.	< 40 AN
merchantID	Código de EC cadastrado na GetnetWS.	< 10 AN
terminal	Identificação do Terminal.	< 7 AN
subMerchantId	ID do Sub comércio.	< 15 AN

Importante para Pagamento HTML: No caso de uma autorizadora da loja não ter cadastrado essas credenciais, essa autorizadora não será exibida na tela de seleção de cartão de crédito durante a operação de pagamento.

Cadastro das informações pelo portal do lojista

O próprio lojista pode cadastrar as informações obtidas com a GetnetWS no Portal do Lojista do e-SiTef. Nesse ambiente será possível alterar as configurações e a senha de autenticação das transações. Para essa finalidade, o lojista deve selecionar a autorizadora e entrar na tela de edição como no exemplo exibido abaixo:

No Portal do Lojista, no ambiente de edição da Autorizadora, é possível alterar a senha cadastrada no ambiente e-SiTef. Nesse caso, a alteração ocorrerá somente para esta autorizadora. Note que se as lojas utilizam a mesma conta na Getnet, será necessário que os lojistas alterem manualmente as senhas pra todas as outras autorizadoras.

Ainda nesse ambiente, pode-se também alterar a senha de cadastro na Getnet. É importante lembrar que ao alterar essa senha no ambiente da Getnet todas as lojas associadas à essa conta na Getnet terão que alterar também a senha cadastrada no ambiente e-SiTef indo na tela de edição de suas autorizadoras, caso contrário terão suas transações negadas pela Getnet.

A tela de exemplo de alteração de senha na Getnet segue abaixo:

A nova senha deve seguir as regras definidas pela Getnet. Essas regras encontram-se no documento de integração.

Subadquirência

Informações referentes a subadquirência são cadastradas pela nossa equipe de suporte. Os seguintes dados são necessários:

Parâmetro	Formato
ID do subcomércio	< 15 AN
Cidade do subcomércio	< 13 A
Estado do subcomércio	= 2 A
CEP do subcomércio	= 8 N
CNPJ ou CPF do subcomércio	< 15 AN
Logradouro do subcomércio	< 40 AN
MCC	= 4 N
Soft-Descriptor	< 22 AN Saiba mais sobre esse recurso.

Também é possível enviar os campos abaixo nas requisições feitas ao e-SiTef:

Parâmetro	Campo	Observações
ID do subcomércio	subacquirer_merchant_id	Enviado no serviço de efetivação da transação.
MCC	mcc	Enviado no serviço de efetivação da transação.
Soft-Descriptor	soft_descriptor	Enviado no serviço de criação da transação.

Caso os campos acima estejam cadastrados na loja do e-SiTef e sejam enviados na requisição, o valor que consta na requisição tem prioridade.

Recorrências

Para que as recorrências sejam reconhecidas pela GetnetWS, existem algumas regras que explicaremos a seguir.

Os campos usados para a recorrência são apresentados na tabela abaixo.

Campo	Descrição	Formato
acquirer.recurrency	Enviado na requisição. Flag que define se o pagamento é ou não recorrente.	< 5 T/F
acquirer.recurrency_tid	Enviado na requisição. ID da transação da primeira transação da recorrência. Identificador que diferencia a primeira recorrência das subsequentes.	= 18 N
acquirer.recurrency_seq_id	Enviado na requisição. Número da parcela da recorrência.	< 3 N
payment.tid	Recebido na resposta. ID da transação no adquirente.	= 18 N

Caso o lojista opte por fazer as recorrências por conta própria, deverá seguir os passos:

• Passo 1: Primeira recorrência:
  • Enviar acquirer.recurrency com valor true;
  • Armazenar o payment.tid para usar nas recorrências seguintes.
• Passo N: Recorrências seguintes:
  • Enviar acquirer.recurrency com valor true;
  • Enviar acquirer.recurrency_tid com o valor retornado no payment.tid do Passo 1;
  • Enviar acquirer.recurrency_seq_id com o número da parcela correspondente a recorrência feita (de 1 até 999 no máximo).

Caso o lojista opte por fazer as recorrências por meio do serviço de agendamento do e-SiTef, os parâmetros de recorrência serão enviados automaticamente e o acompanhamento poderá ser feito pelo relatório de agendamentos normalmente.

Caso o lojista opte por fazer as recorrências por meio do serviço de pagamento com agendamento do e-SiTef, os parâmetros de recorrência serão enviados automaticamente e o acompanhamento poderá ser feito pelo relatório de agendamentos normalmente. Porém, uma peculiaridade é que o ID usado para identificar a primeira transação da recorrência é o ID do pagamento inicial e não o ID do primeiro agendamento.

Fluxos

Nesta seção serão apresentadas as particularidades do fluxo transacional GetnetWS.

Pagamento HTML

É possível realizar um pagamento com autenticação 3DS. Para isso, basta enviar o parâmetro authorizer_authentication com valor true na etapa de criação da transação.

Pré-Autorização

Não é possível realizar uma pré-autorização com parcelamento via emissor.

Alteração de Pré-Autorização

É possível re-enviar a requisição de efetivação de pré-autorização acrescida do campo amount para alterar seu valor.

Parâmetro	Descrição	Formato	Obrigatório
amount	Novo valor da pré-autorização em centavos.	< 12 N	SIM

Pagamento e Pré-Autorização REST

• O campo card.holder é obrigatório.
• A GetnetWS aceita o envio dos dados de autenticação eci, xid e cavv.

Parâmetro	Descrição	Formato	Obrigatório
card.holder	Nome do portador impresso no cartão	< 26 AN	SIM
external_authentication.eci	Código ECI da transação Autenticada 3D Secure.	= 2 N	NÃO
external_authentication.xid	Identificador do MPI para cada transação autenticada.	< 40 AN	NÃO
external_authentication.cavv	Código de autenticação criptografado pela Bandeira.	< 40 AN	NÃO

Cancelamento

O Cancelamento de uma transação pode ser feito no Portal do Lojista. Só poderão ser canceladas as transações efetuadas no dia corrente do cancelamento. O lojista pode cancelar transações de pré-autorização com ou sem captura e transações de pagamento. No caso de cancelar uma transação de pré-autorização com captura, a Getnet efetua o cancelamento da captura, porém, o e-SiTef exibirá essa transação de pré com status cancelada (e captura confirmada).

GlobalPayments WS

A loja tem a possibilidade de configurar o roteamento de transações feitas com cartão de crédito no e-SiTef por vários meios de pagamento, um desses meios é a GlobalPayments.

Neste documento será usada a nomenclatura "GlobalPaymentsWS" para referenciar o roteamento no e-SiTef.

Assim, a loja pode configurar o e-SiTef para que as transações feitas com cartões VISA, por exemplo, sejam roteadas pela GlobalPaymentsWS enquanto que as feitas com MASTERCARD sejam roteadas pela CIELO.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento GlobalPaymentsWS:

• Pagamento REST
• Pré-Autorização REST
• Cancelamento REST
• Pagamento HTML
• Pré-Autorização HTML
• Cancelamento via Portal do Lojista

Observação: Esta integração também aceita o envio de dados de autenticação 3DS (eci, xid e cavv). Saiba mais.

Autorizadoras permitidas

Para maiores informações sobre quais autorizadoras são permitidas pela GlobalPaymentsWS, por favor, entrar em contato com ela.

Credenciais necessárias

A loja deve obter com a GlobalPaymentsWS as credenciais listadas abaixo, e repassá-las à Software Express ou fazer o cadastro como explicado mais a frente neste mesmo documento.

Campo	Descrição	Formato
terminal	Número de terminal que será definido pela GlobalPaymentsWS.	< 3 N
merchantCode	Número do estabelecimento definido pela GlobalPaymentsWS.	< 15 N
secretKey	Chave secreta do lojista na GlobalPaymentsWS.	AN

Cadastro das informações pelo portal do lojista

O próprio lojista pode cadastrar as informações obtidas com a GlobalPaymentsWS no Portal do Lojista do e-SiTef. Nesse ambiente será possível alterar as configurações. Para essa finalidade, o lojista deve selecionar a autorizadora e entrar na tela de edição como no exemplo exibido abaixo:

Fluxos

Nesta seção serão apresentadas as particularidades do fluxo transacional GlobalPaymentsWS.

Pré-Autorização REST

Serviço de efetivação de pré-autorização

Apesar da interface do e-SiTef possibilitar o envio das parcelas na Captura, a GlobalPaymentsWS requer o envio dessa informação na chamada da Pré-Autorização. Saiba mais.

Serviço de captura de pré-autorização

Na operação de captura, o valor da transação deve ser igual ou menor do que valor da transação de Pré-Autorização.

A GlobalPaymentsWS requisita o envio das parcelas na chamada de Pré-Autorização. Por este motivo, o envio de algum valor para este campo não será considerado na interface de Captura.

A GlobalPaymentsWS assume que todo parcelamento será considerado como sendo SEM Juros. Por isto, o envio de algum valor para o campo installment_type não será considerado na interface de Captura.

Pagamento REST

Essa interface suporta o envio da flag de recorrência, de campos de autenticação externa, além do soft descriptor.

Confirmação tardia

O pagamento REST possui o campo postpone_confirmation, que indica se o pagamento será feito com confirmação automática ou manual, sendo que esta última opção é feita através do serviço de confirmação de pagamento. Porém, por questões da API GlobalPaymentsWS, ao chamar o serviço de efetivação de pagamento com confirmação tardia, na prática é chamada uma requisição de pré-autorização e o serviço de confirmação gera uma requisição de captura.

Serviço de consulta de cartão

Este serviço permite uma consulta para validar o cartão que será utilizado no pagamento, na API da GlobalPaymentsWS. Para seu correto funcionamento, é necessário que a função ZeroDollar esteja habilitada no cadastro da loja na GlobalPayments.

Pagamento HTML

Para pagamentos HTML, na criação da transação no e-SiTef o campo postpone_confirmation permite que a transação de pagamento se torne pendente ao final da interação do usuário com as telas de e-SiTef, e posteriormente esta pode ser confirmada ou desfeita pela Interface REST de Confirmação de Pagamentos HTML.

Neste caso também existe a particularidade de que, quando a transação é criada com o campo postpone_confirmation com valor true, na prática é feita uma requisição de pré-autorização à API GlobalPaymentsWS, e consequentemente, a confirmação feita pela interface REST gera uma requisição de captura.

Cancelamento

Só poderão ser canceladas as transações capturadas ou confirmadas no dia corrente (até as 23:59:59).

O lojista poderá cancelar uma transação via a interface de cancelamento REST ou pelo Portal do Lojista.

A GlobalPaymentsWS aceita cancelamentos parciais apenas de transações de Pré-Autorização. Para as demais transações o cancelamento deve ser feito para o mesmo valor.

Autenticação via HTML

Caso esteja sendo utilizada a interface de Pagamento/Pré Autorização HTML, para realizar a autenticação o seguinte campo deve ser enviado na requisição:

Parâmetro	Descrição	Formato	Obrigatório
authorizer_authentication	Este campo deve ser enviado com valor true caso se deseje uma transação com autenticação. Saiba mais.	< 5 AN	SIM

Cartões de testes GlobalPaymentsWS

A GlobalPaymentsWS disponibiliza os seguintes números de cartões para o ambiente de testes, que podem ser utilizados no ambiente de Certificação / Homologação do e-SiTef.

Opção / Resultado	Número do cartão de crédito	Vencimento	CVV
À Vista	4548812049400004	12/20	123
Parcelado	4761120000000148	12/17	111
Negado	1111111111111117	11/20	-

IPG

A loja tem a possibilidade de configurar o roteamento de transações feitas com cartão de crédito no e-SiTef por vários meios de pagamento, um desses meios é a IPG (Internet Payment Gateway) da First Data/fiserv.

Assim, a loja pode configurar o e-SiTef para que as transações feitas com cartões VISA, por exemplo, sejam roteadas pela IPG enquanto que as feitas com MASTERCARD sejam roteadas pela BIN.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento IPG:

• Pagamento REST
  • Consulta de cartão REST
• Pré-Autorização REST
• Cancelamento REST

Autorizadoras permitidas

As seguintes autorizadoras são suportadas pelo roteamento IPG:

• VISA
• MASTERCARD
• ELO
• AMERICAN EXPRESS
• HIPER
• SOROCRED
• CABAL

Credenciais necessárias

A loja deve obter com a IPG as credenciais listadas abaixo, e repassá-las à Software Express ou fazer o cadastro como explicado mais a frente neste mesmo documento.

Campo	Descrição	Formato
ipgMerhantApiKey	Identificação da loja na IPG.	< 32 AN
ipgMerchantApiSecret	Chave de acesso da loja gerado pelo IPG.	< 16 AN
ipgEndPointURL	URL da IPG API REST	< 200 AN

Cadastro das informações pelo portal do lojista

O próprio lojista pode cadastrar as informações obtidas com a IPG no Portal do Lojista do e-SiTef. Para essa finalidade, o lojista deve selecionar a autorizadora e entrar na tela de edição como no exemplo exibido abaixo:

No Portal do Lojista, no ambiente de edição da Autorizadora, é possível alterar as configurações cadastradas no ambiente e-SiTef. Nesse caso, a alteração ocorrerá somente para esta autorizadora. Note que se as lojas utilizam a mesma conta, será necessário que os lojistas alterem manualmente as senhas pra todas as outras autorizadoras.

Fluxos

As particularidades do fluxo transacional da IPG são explicitadas coforme a seguir:

Consulta de cartão

Para solicitação de consulta de cartão com o campo "routing-id" definido como IPG, serão retornados os detalhes do cartão fornecidos pelo IPG. Para maiores detalhes, clique aqui

Pagamento indicando recorrência

No roteamento da IPG é possível realizar pagamentos indicando que este é um pagamento recorrente (Saiba mais). Para realizar pagamentos indicando recorrência, envie os seguintes parâmetros no pagamento:

• acquirer.recurrency com o valor true;
• acquirer.is_first_recurring com o valor true para indicar que a transação é a primeira de uma série de transações recorrentes, ou false caso contrário.

Itaú Shopline

O e-SiTef permite a integração do site do lojista com pagamentos pelo Itaú Shopline, onde o comprador acessa a própria conta pela interface do Itaú para efetuar o pagamento via boleto bancário, transferência bancária ou utilizando cartões Itaucard.

Nesta página será usada a nomenclatura "Itaú Shopline" para referenciar o roteamento no e-SiTef.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento Itaú Shopline:

• Pagamento HTML
• Reemissão de Boletos

Autorizadoras permitidas

As seguintes autorizadoras são suportadas pelo roteamento Itaú Shopline:

• Itaú Shopline

Credenciais necessárias

A loja deve obter com o Itaú as credenciais listadas abaixo, e repassá-las à Software Express.

Campo	Descrição do campo	Formato
codigoEmpresa	Código da empresa (loja) no Itaú.	= 26 AN
chave	Chave de criptografia para troca de informações com o Itaú Shopline.	= 16 AN

Configurações necessárias no Portal do Itaú Shopline

Algumas configurações devem ser feitas na conta do lojista no Itaú Shopline para a perfeita integração com o e-SiTef.

URL de Retorno

Para um correto funcionamento da confirmação do pagamento, é necessário que o lojista entre no Itaú Bankline com suas credenciais e configure o campo URL de Retorno do Shopline para a URL do e-SiTef abaixo:

Ambiente de Produção
https://esitef-ec.softwareexpress.com.br/e-sitef/itau.se
Ambiente de Homologação
https://esitef-homologacao.softwareexpress.com.br/itau.se

Esta URL é utilizada para que o Itaú confirme o pagamento no e-SiTef. Existe uma limitação no Itaú Shopline de 60 caracteres para a URL, portanto bastante cuidado no cadastro da URL, que são diferentes para a homologação e para a produção.

Note que as alterações no ambiente do Itaú podem demorar um dia útil para ficar disponíveis.

Abaixo segue cópia do manual técnico do Itaú Shopline para acesso aos dados cadastrais.

(Extraído do manual técnico do Itaú Shopline)

Dentro do Itaú Bankline, a rota de acesso a esta função é: Produtos e Serviços > Itaú Shopline > Informações Cadastrais

(...)

Atenção: Qualquer informação alterada neste ambiente estará disponível para utilização 1(um) dia útil após a alteração. Para acessar o Itaú Bankline, é necessário entrar no site o Itaú (http://www.itau.com.br/) e digitar:

• dados de Agência, Conta Corrente e Senha Eletrônica na barra de acesso ao Itaú Bankline Empresa;
• ou dados de Usuário Operador e Senha Eletrônica na barra de acesso ao Itaú Bankline Empresa Plus.

Fluxo de Pagamento com Itaú Shopline

Após ter sido configurado essa forma de pagamento para a loja, o fluxo de pagamento ocorre da seguinte forma:

1. O usuário inicia o pagamento pelo e-SiTef;
2. A lista de autorizadoras configurada na loja é apresentada para o usuário;
3. O usuário escolhe a forma de pagamento Itaú Shopline;
4. Nesse momento será aberta uma nova janela redirecionando o usuário para o site do Itaú Shopline;
5. O usuário inicia o processo de pagamento no site do Itaú Shopline.
6. O usuário finaliza o pagamento no ambiente do Itaú Shopline;
7. O Itaú Shopline redireciona o usuário para o e-SiTef, conforme URL de retorno configurada.
8. Ao receber o redirecionamento do usuário, o e-SiTef efetua uma consulta ao Itaú e atualiza o status da transação no e-SiTef.
9. Caso a loja tenha configurado o redirecionamento automático, o usuário é redirecionado à URL de Sucesso ou Fracasso configurado no e-SiTef.
10. Por fim, caso haja o redirecionamento automático, o usuário retorna ao site da loja. Na figura abaixo podemos visualizar no diagrama o fluxo descrito acima:

Um caso de exceção a esse fluxo é o caso onde a URL de Retorno não foi cadastrada no Itaú. Assim, não haverá redirecionamento do usuário após a finalização do pagamento no Itaú Shopline.

Outro caso possível é iniciar a transação com a autorizadora pré-fixada, onde os passos 2 e 3 não são necessários.

Logo, sugerimos que a configuração descrita em URL de Retorno seja feita corretamente, para possibilitar uma melhor experiência de compra ao usuário.

Aviso de Status

Para cada alteração de status de transação no e-SiTef, resultante de comunicação entre o e-SiTef e o Itaú, é enviado ao servidor da loja um Aviso de Status. Para mais detalhes sobre esta funcionalidade, consulte o Pagamento HTML no item Aviso de Status.

Parâmetros para transação via Itaú Shopline

Os parâmetros usados para se criar uma transação de pagamento com o Itaú Shopline são os mesmos que os apresentados no Pagamento HTML no item Iniciando uma transação de pagamento.

Para pagamentos com Itaú Shopline, as seguintes particularidades devem ser consideradas:

Código de Pedido

Para utilizar a forma de pagamento Itaú Shopline, é necessário que o código de pedido seja sempre diferente para cada transação, e tenha somente oito dígitos. Este código de pedido não pode se repetir por 60 dias (segundo informação do Itaú em 12/2010), e deve ser numérico. Caso a loja envie maior que oito ou contendo caracteres alfanuméricos, o e-SiTef irá:

• Retirar todos os caracteres não numéricos
• Manter os oito últimos dígitos que sobrarem (à direita).
• Enviar “0” caso não sobre nada.

Importante: O e-SiTef não irá verificar se os códigos estão se repetindo, e Itaú Shopline pode até aceitar códigos de pedidos repetidos, porém poderão ocorrer erros como pedidos novos não pagos retornarem como confirmados pelo Itaú. O e-SiTef não se responsabiliza por códigos de pedido repetidos.

Pagamentos Itaú Shopline via Boleto Bancário

No caso do usuário escolher o pagamento Itaú Shopline via boleto bancário, a confirmação do pagamento pode demorar até um dia útil para acontecer por parte do Itaú, e manter-se em status Pendente no e-SiTef durante este período.

Como o Itaú não informa ao e-SiTef quando o pagamento do boleto foi efetuado, o e-SiTef pode demorar mais um dia para confirmar, pois a sonda que atualiza os status de pagamentos de boleto é executada apenas de madrugada. Neste caso, o redirecionamento para a URL de sucesso por parte do e-SiTef no caso de escolha via boleto irá acontecer no momento em que o boleto for gerado pelo Itaú. Caberá à loja verificar o status final da transação junto ao e-SiTef.

Se for constatado que a data do boleto passou dos dias configurados para cancelamento, então será alterado o status da transação para Expirada, para que sejam finalizadas as consultas da situação do pagamento do boleto no Itaú. Caso uma transação de pagamento com status Expirada no e-SiTef seja efetuada no ambiente do Itaú, uma vez que o Itaú notifique o e-SiTef que o pagamento foi realizado com sucesso, a transação será retomada e o pagamento será realizado normalmente, se o pagamento for realizado com sucesso, a transação tem seu status alterado de Expirada para Confirmada.

Atenção ao fato de que, para toda atualização de status em transações do e-SiTef, será enviado um post para a URL de Aviso de Status da loja cadastrada no e-SiTef.

Para que um pagamento via boleto bancário seja feito pelo usuário, é necessário que a loja envie para o e-SiTef as seguintes informações:

Campo	Descrição	Formato	Obrigatório
identification_number	Número de inscrição do sacado (CPF ou CNPJ) Se o número de inscrição do sacado for maior que 11 dígitos o campo será considerado CNPJ.	< 20 N	SIM
name	Nome completo do sacado. Para o Itaú Shopline, o nome e sobrenome mais um espaço separador entre eles devem ter, no máximo 200 caracteres alfanuméricos.	< 200 AN	SIM
surname
address_street_name	Endereço do sacado. Para o Itaú Shopline, o logradouro, número, o complemento do endereço mais os espaços separadores entre eles devem ter no máximo 200 caracteres alfanuméricos.	< 200 AN	SIM
address_street_number
address_street_complement
address_zip_code	CEP do sacado	= 8 N	SIM
city	Cidade do sacado	< 100 AN	SIM
state	Estado do sacado	= 2 AN	SIM
neighborhood	Bairro do sacado	< 15 AN	SIM

Segue abaixo exemplo de uso na Interface HTML do e-SiTef, com o JSON do objeto request enviado no POST:

JSON

{
   "merchant_id":"codigoDaLoja",
   "merchant_usn":"98765",
   "order_id":"abc123456",
   "redirect":"A",
   "authorizer_id":"7",
   "amount":"1000",
   "installments":"1",
   "installment_type":"4",
   "additional_data":{
      "payer":{
         "name":"Jose",
         "surname":"Silva",
         "identification_number":"09719224703",
         "address_street_name":"Rua Jose Ninguem",
         "address_street_number":"11",
         "address_street_complement":"ap 12",
         "address_zip_code":"01230120",
         "city":"Sao Paulo",
         "state":"SP",
         "neighborhood":"Campos Eliseos"
      }
   }
}

Reemissão de boletos

É possível disponibilizar aos compradores a Reemissão de boletos do Itaú Shopline.

Esta funcionalidade está disponível através da URL:

Ambiente de Produção
https://esitef-ec.softwareexpress.com.br/e-sitef/reissue.se?nit=XXX
Ambiente de Homologação
https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/reissue.se?nit=XXX

Deve-se informar como parâmetro do POST o nit utilizado da transação original de pagamento, feita via Itaú Shopline. O simples acesso a esta URL já permite a visualização direta do boleto reemitido com os mesmos dados da primeira emissão.

Caso a transação de pagamento não esteja no estado esperado, é apresentada uma mensagem de erro.

Atenção

Nunca deve ser usado o IP ao invés do domínio esitef-ec.softwareexpress.com.br (ou esitef- homologacao.softwareexpress.com.br para ambiente de homologação). O IP pode mudar a qualquer instante e sem aviso prévio, logo é importante sempre utilizar o domínio para acessar o e-SiTef.

Mercado Pago

Esta documentação descreve a integração do e-SiTef com a plataforma de pagamento Mercado Pago. Além de explicar sobre as configurações que devem ser, necessariamente, efetuadas no ambiente do e-SiTef.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento Mercado Pago:

• Pagamento HTML

Credenciais necessárias

A loja deve obter no portal do Mercado Pago as credenciais listadas abaixo, e repassá-las à Software Express ou fazer o cadastro no Portal do Lojista do e-SiTef.

Parâmetro	Descrição	Obrigatório
public_key	Chave pública da aplicação para saber, por exemplo, os meios de pagamento e criptografar os dados do cartão.	SIM
access_token	Chave privada da aplicação para gerar pagamentos.	SIM

Códigos de autorizadora

Abaixo estão os códigos a serem utilizados nessa integração:

• 440: PIX
• 402: demais formas de pagamento com Mercado Pago

Atenção: No ambiente de homologação do Mercado Pago não é possível simular uma transação PIX aprovada. A transação ficará pendente.

Parâmetros específicos do Mercado Pago

Serviço de criação de pagamento HTML

Abaixo estão os parâmetros de requisição específicos do Mercado Pago para o serviço de criação de pagamento HTML:

Parâmetro	Descrição	Tamanho	Obrigatório
additional_data	Dados adicionais da transação.
application_fee	Valor de comissão do Mercado Pago em centavos	< 12 N	NÃO
binary_mode	Modo binário de aprovação. Quando definido como true, o pagamento só pode ser aprovado ou negado (não fica pendente).	< 5 AN	NÃO
discount_campaign_id	Identificador da campanha de desconto	< 1024 AN	NÃO
discount_amount	Valor do cupom de desconto em centavos	< 12 N	NÃO
acquirer_expiry_date	Data de expiração do pagamento no formato AAAA-MM-DDTHH:MM:SS	= 19 AN	NÃO
acquirer_expiry_date_from	Data a partir da qual a iniciação do pagamento estará ativa no formato AAAA-MM-DDTHH:MM:SS	= 19 AN	NÃO
acquirer_expiry_date_to	Data de expiração da iniciação do pagamento no formato AAAA-MM-DDTHH:MM:SS	= 19 AN	NÃO
acquirer_expires	Booleano que indica se a iniciação do pagamento expira.	< 5 AN	NÃO
description	Razão de pagamento ou título do item	< 1024 AN	NÃO
extra_info	Informações adicionais.	< 1024 AN	NÃO
max_installments	Número máximo de parcelas.	< 2 N	NÃO
additional_data .items[]	Dados de carrinho de compras. Obrigatório o envio de pelo menos um item, e a soma dos preços do carrinho deve ser igual ao valor total da transação (campo amount, na raiz do JSON).
id	ID do produto.	< 1024 AN	NÃO
title	Nome do item.	< 1024 AN	NÃO
description	Descrição do item.	< 1024 AN	NÃO
picture_url	URL da imagem do item.	< 1024 AN	NÃO
category_id	Categoria do item: art, baby, coupon, donation, computing, camera, video_game, television, car_eletronic, automotive, entertainment, fashion, game, home, musical, phone, service, learning, ticket, travel, virtual_good ou other	< 1024 AN	NÃO
quantity	Quantidade do item.	< 7 N	SIM
unit_price	Preço unitário do item em centavos.	< 12 N	SIM
additional_data .payer	Dados do comprador.
name	Nome do comprador.	< 1024 AN	NÃO
surname	Sobrenome do comprador.	< 1024 AN	NÃO
email	E-mail do comprador.	< 1024 AN	NÃO
creation_date	Data da criação da conta no formato DD/MM/AAAA	= 10 AN	NÃO
identification_type	Tipo de identificação do comprador.	< 1024 AN	NÃO
identification_number	Número de identificação do comprador.	< 1024 AN	NÃO
type	Tipo de identificação do pagador associado: guest, customer ou registered	< 10 AN	NÃO
additional_data .payer .phones[]	Telefone do comprador.
ddd	Código da área do telefone.	< 1024 AN	NÃO
number	Número do telefone do comprador.	< 1024 AN	NÃO
additional_data .payer .address	Endereço do comprador.
street_name	Endereço do comprador.	< 1024 AN	NÃO
street_number	Número do endereço do comprador.	< 1024 AN	NÃO
zip_code	CEP do comprador.	< 1024 AN	NÃO
additional_data .shipment	Endereço de entrega.
mode	Modo de envio: custom = Customizado me2 = Mercado Envios not_specified = Não especificado	< 1024 AN	NÃO
local_pickup	Preferência de remoção de pacotes em agência (booleano). Apenas para mode = me2.	< 5 AN	NÃO
dimensions	Tamanho do pacote em cm x cm x cm, gr. Apenas para mode = me2.	< 1024 AN	NÃO
default_shipping_method	Escolha um método de envio padrão no checkout. Apenas para mode = me2.	< 1024 AN	NÃO
cost	Custo do transporte em centavos. Apenas para mode = custom.	< 12 N	NÃO
free_shipment	Preferência de frete grátis (booleano). Apenas para mode = custom.	< 5 AN	NÃO
additional_data .shipment .free_methods[]	Oferecer um método de frete grátis. Apenas para mode = me2.
id	Identificador do método de envio	< 1024 AN	NÃO
additional_data .shipment .address	Endereço de entrega.
zip_code	CEP do endereço de entrega.	< 1024 AN	NÃO
street_number	Número do endereço de entrega.	< 1024 AN	NÃO
street_name	Nome da rua de entrega.	< 1024 AN	NÃO
floor	Número do andar de entrega.	< 1024 AN	NÃO
apartment	Número do apartamento de entrega.	< 1024 AN	NÃO
city	cidade de entrega.	< 1024 AN	NÃO
state	Estado de entrega.	< 1024 AN	NÃO
additional_data .payment_method .excluded_payment_methods[]	Métodos de pagamento a serem excluídos do fluxo de pagamento Mercado Pago.
id	ID do método de pagamento a ser excluído: debelo = Elo Debito debmaster = Mastercard Débito visa = Visa master = Mastercard hipercard = Hipercard amex = American Express elo = Elo debvisa = Visa Débito pec = Pagamento na lotérica sem boleto bolbradesco = Boleto	< 1024 AN	NÃO
additional_data .payment_method .excluded_payment_types[]	Tipos de pagamento a serem excluídos do fluxo de pagamento Mercado Pago.
id	ID do tipo de pagamento a ser excluído: debit_card, credit_card ou ticket.	< 1024 AN	NÃO
additional_data .payment_method .ad_tracks[]	Tracks que serão executados durante a interação do usuário no fluxo de Pagamento.
type	Tipo da track: google_ad: Configure uma tag de acompanhamento de conversões do Google Ads no GTM. Valores necessários: conversion_id e conversion_label. facebook_ad: Permite configurar um pixel do Facebook. Valores necessários: pixel_id.	< 1024 AN	NÃO
conversion_id	Conversion ID da track.	< 1024 AN	NÃO
conversion_label	Conversion Label da track.	< 1024 AN	NÃO
pixel_id	Pixel ID da track.	< 1024 AN	NÃO

Exemplo de JSON:

{
   "merchant_id":"LOJAMERCADOPAGO",
   "merchant_usn":"123456",
   "amount":"100",
   "soft_descriptor":"softDescriptor",
   "additional_data":{
      "extra_info":"extraInfo",
      "items":[
         {
            "title":"Camiseta",
            "quantity":"1",
            "unit_price":"100",
            "picture_url":"https://abc.def/item/552292339/zoom/10.jpg",
            "category_id":"fashion",
            "description":"Camiseta Preta",
            "id":"id"
         }
      ],
      "payer":{
         "name":"Jonas",
         "surname":"Melo",
         "email":"a@b.com",
         "date_created":"11/02/2015",
         "address":{
            "zip_code":"12345678",
            "street_number":"751",
            "street_name":"Rua Major Vitor"
         },
         "phones":[
            {
               "number":"912341234",
               "ddd":"11"
            }
         ],
         "identification_type":"CPF",
         "identification_number":"86670573049"
      },
      "payment_method":{
         "excluded_payment_methods":[
            {
               "id":"debelo"
            }
         ],
         "excluded_payment_types":[
            {
               "id":"debit_card"
            }
         ]
      },
      "shipment":{
         "mode":"not_specified",
         "local_pickup":"true",
         "dimensions":"23x23x23, 23g",
         "default_shipping_method":"45",
         "cost":"2",
         "free_shipment":"true",
         "address":{
            "zip_code":"87654321",
            "street_number":"920",
            "street_name":"Rua General Henrique",
            "floor":"1",
            "apartment":"23",
            "city":"São Mateus",
            "state":"AM"
         },
         "free_methods":[
            {
               "id":"621"
            }
         ]
      },
      "max_installments":"12",
      "application_fee":"1",
      "acquirer_expiry_date":"2021-06-02T11:05:27",
      "acquirer_expiry_date_from":"2021-06-01T11:05:27",
      "acquirer_expiry_date_to":"2021-06-03T11:05:27",
      "acquirer_expires":"false",
      "ad_tracks":[
         {
            "conversion_id":"conversionId",
            "type":"google_ad",
            "conversion_label":"conversionLabel"
         }
      ]
   }
}

PagSeguro

Esta documentação descreve a integração com a plataforma de pagamento PagSeguro e as configurações necessárias no ambiente do e-SiTef.

ATENÇÃO: Em ambiente de homologação, o comportamento do PagSeguro será simulado pelo e-SiTef a fim de tornar o processo de homologação mais confiável e satisfatório, uma vez que o ambiente de testes (Sandbox) do PagSeguro ainda não fornece todas as funcionalidades disponíveis em produção.

Dessa maneira, o comportamento das transações feitas com a autorizadora PagSeguro no ambiente de homologação pode não refletir o ambiente de produção.

Apesar do esforço empregado em manter o simulador sempre atualizado, mudanças efetuadas pelo PagSeguro podem ocorrer sem que haja aviso prévio à equipe e-SiTef.

Interfaces suportadas

• Pagamento HTML
• Cancelamento REST
• Cancelamento Portal

Configurações necessárias no e-SiTef

Antes de efetuar transações PagSeguro com o e-SiTef, devem ser seguidos os passos de configuração apresentados a seguir.

Dados cadastrais do PagSeguro

• A loja deve possuir um cadastro ativo no PagSeguro. Mais informações no site oficial do PagSeguro
• A tabela a seguir mostra as credenciais PagSeguro que devem ser obtidas pela loja, e que posteriormente serão cadastradas no e-SiTef:

Parâmetro	Descrição	Obrigatório
email	Identificação do cliente	SIM
token	Chave de acesso	SIM

Inserir dados cadastrais no e-SiTef

• Tendo em mãos os dados cadastrais PagSeguro citados acima, o lojista deve solicitar à equipe de atendimento do e-SiTef:

  • A ativação do PagSeguro como uma autorizadora ativa no cadastro do e-SiTef.
  • Caso não possua, um usuário e senha de acesso ao Portal do Lojista no e-SiTef.

• Assim que a Autorizadora PagSeguro estiver associada à loja, o lojista deve acessar o Portal do Lojista e informar os dados cadastrais do PagSeguro no item "Configuração de Autorizadoras". Além dos parâmetros email e token citados anteriormente.

Para mais detalhes de como cadastrar os dados no portal do lojista, consulte a seção específica do Portal do Lojista.

Código de Autorizadora para PagSeguro no e-SiTef

Para realizar pagamentos com a autorizadora pré-definida, envie o código 403 que se refere a autorizadora PagSeguro.

Parâmetros para transação via PagSeguro

Os parâmetros usados para fazer uma transação de pagamento com o PagSeguro devem ser enviados ao e-SiTef obrigatoriamente no formato JSON, através da URL do ambiente de homologação disponibilizada:

https://esitef-homologacao.softwareexpress.com.br/e-sitef/init.se

Para maiores informações sobre a interface de pagamento HTML, consulte a seção específica nessa documentação.

ATENÇÃO: Transações que entrarem em disputa no PagSeguro permanecerão com o status confirmado (CON) no e-SiTef assim como os seus possíveis resultados (devolução ou pagamento confirmado). Cabe ao comprador verificar a situação da transação junto ao PagSeguro.

Abaixo estão listados os parâmetros que a loja pode enviar ao e-SiTef para possibilitar ao comprador fazer um pagamento no PagSeguro.

Parâmetro	Descrição	Formato	Obrigatório
	additional_data
extra_info	Informações adicionais.	< 1024	NÃO
currency	Indica a moeda na qual o pagamento será feito, no formato ISO 4217. No momento, a única opção disponível é BRL (Real).	< 1024	NÃO
extra_amount	Especifica um valor extra que deve ser adicionado ou subtraído ao valor total do pagamento. Esse valor pode representar uma taxa extra a ser cobrada no pagamento ou um desconto a ser concedido, caso o valor seja negativo. Formato: centavos. Exemplo: 123456 (R$ 1234, 56) ou -123456 (R$-1234,56)	< 1024	NÃO
	additional_data .items[]
id	Identificação do item.	< 1024	NÃO
title	Título do item.	< 1024	SIM
quantity	Quantidade do item.	< 1024	SIM
unit_price	Preço unitário do item em centavos.	< 1024	SIM
description	Descrição do item.	< 1024	NÃO
shipping_cost	Representam os custos de frete de cada item sendo pago.	< 1024	NÃO
weight	Correspondem ao peso (em gramas) de cada item sendo pago. Utilizado para calcular o frete, caso não seja informado o custo do frete (shipping_cost). Exemplo: 3000 (3kg)	< 1024	NÃO
	additional_data .payer
name	Nome do comprador.	< 1024	NÃO
surname	Sobrenome do comprador.	< 1024	NÃO
email	E-mail do comprador.	< 1024	NÃO
phone_area_code	Código da área do telefone.	< 1024	NÃO
phone_number	Número do telefone do comprador.	< 1024	NÃO
identification_type	Tipo de identificação do comprador. Somente o valor CPF é aceito.	< 1024	NÃO
identification_number	Número de identificação do comprador.	< 1024	NÃO
address_street_name	Endereço do comprador.	< 1024	NÃO
address_street_number	Número do endereço do comprador.	< 1024	NÃO
born_date	Especifica a data de nascimento do comprador que está realizando o pagamento. Formato ISO 8601.	< 1024	NÃO
	additional_data .shipment
cost	Informa o valor total de frete do pedido. Formato: centavos. Exemplo: 123456 (R$ 1234, 56)	< 1024	NÃO
type	Informa o tipo de frete a ser usado para o envio do produto. Valores aceitos: 1 – Encomenda Normal (PAC) 2 – SEDEX 3 – Tipo de frete não especificado.	< 1024	NÃO
	additional_data .shipment .receiver_address
zip_code	CEP do endereço a ser entregue. Formato: Número de 8 dígitos. Exemplo: 12345678	< 1024	NÃO
street_number	Número do endereço a ser entregue.	< 1024	NÃO
street_name	Endereço a ser entregue.	< 1024	NÃO
floor	Número do andar a ser entregue.	< 1024	NÃO
apartment	Número do apartamento a ser entregue.	< 1024	NÃO
district	Informa o bairro do endereço de envio do produto.	< 1024	NÃO
complement	Informa o complemento (bloco, apartamento, etc.) do endereço de envio do produto.	< 1024	NÃO
city	Informa a cidade do endereço de envio do produto.	< 1024	NÃO
state	Informa o estado do endereço de envio do produto. Exemplo: SC (Santa Catarina), SP (São Paulo), etc.	< 1024	NÃO
country	Informa o país do endereço de envio do produto. No momento apenas o valor BRA é permitido	< 1024	NÃO
	additional_data .extra_param .metadata[]
key	Permite adicionar informações extras, agrupadas ou não, em sua requisição de pagamento. São aceitos apenas os valores descritos aqui.	< 1024	NÃO
value	Permite especificar valores para os metadados definidos em sua requisição de pagamento.	< 1024	NÃO
group	Permite agrupar dois ou mais metadados, como por exemplo CPF e nome de um mesmo passageiro.	< 1024	NÃO

Fluxo de pagamento PagSeguro

Após enviar os dados de criação da transação e escolher o meio de pagamento PagSeguro, o seguinte fluxo de telas será iniciado:

• Uma Janela LightBox do PagSeguro será aberta no browser para efetuar o pagamento:

• Caso a transação seja abortada, a seguinte tela será exibida:

• Caso a transação seja confirmada, a tela a seguir será apresentada:

d

• Caso a transação não seja confirmada, a seguinte tela será apresentada:

Aviso de Status - dados específicos

No Aviso de Status para pagamento feitos com o PagSeguro, são retornados adicionalmente os seguintes campos:

Parâmetro	Descrição	Tamanho
pagseguro_status_payment	Status da transação no PagSeguro. 1 = Aguardando pagamento 2 = Em análise 3 = Paga 4 = Disponível 5 = Em disputa 6 = Devolvida 7 = Cancelada	< 15 AN
pagseguro_type	Tipo da transação no PagSeguro. Normalmente, tipo 1 = Pagamento	< 5 AN
pagseguro_cancellation_source	Origem do cancelamento no PagSeguro, apenas quando o parâmetro pagseguro_payment_status for igual a 7. INTERNAL = PagSeguro EXTERNAL = Instituições Financeiras	< 10 AN
pagseguro_discount_amount	Valor do desconto dado.	< 10 AN
pagseguro_fee_amount	Valor total das taxas cobradas.	< 10 AN

ATENÇÃO: os dados apresentados são dados devolvidos pelo PagSeguro, logo o e-SiTef não possui controle sobre estes. Além disso, estes podem não retornar sempre.

Transação de Estorno - Cancelamento REST

Para realizar o estorno de uma transação PagSeguro, utilize a interface de Cancelamento REST. Para mais detalhes, consulte a seção específica na documentação.

Portal do Lojista

Para orientações gerais sobre o Portal do Lojista, por favor consulte a seção específica nesta documentação.

URL de acesso ao Portal do Lojista - Produção:

https://esitef-ec.softwareexpress.com.br/e-sitef-loja

URL de acesso ao Portal do Lojista - Homologação:

https://esitef-homologacao.softwareexpress.com.br/e-sitef-loja/

• Para realizar o estorno de uma transação PagSeguro, acesse o Portal do Lojista e clique no menu Cancelamento, conforme imagem abaixo:

Procure pela transação que se deseja realizar o estorno utilizando os filtros:

Clique na transação que se deseja realizar o estorno, a seguinte tela se abrirá:

• Verifique se os dados estão corretos e clique em Cancelar Pagamento e, em seguida, confirme. Caso a transação seja estornada com sucesso, um comprovante de estorno semelhante ao abaixo será apresentado:

Apêndices

Valores de chave para Metadata

Valor	Descrição	Formato
PASSENGER_CPF	CPF do passageiro	[0-9]{11}
PASSENGER_PASSPORT	Passaporte do passageiro	.+
ORIGIN_CITY	Cidade de origem	.+
DESTINATION_CITY	Cidade de destino	.+
ORIGIN_AIRPORT_CODE	Código do aeroporto de origem	.+
DESTINATION_AIRPORT_CODE	Código do aeroporto de destino	.+
GAME_NAME	Nome do jogo	.+
PLAYER_ID	ID do jogador	.+
TIME_IN_GAME_DAYS	Tempo no jogo em dias	[0-9]+
MOBILE_NUMBER	Celular de recarga	([0-9]{2})?([0-9]{2})([0-9]{4,5}[0-9]{4})
PASSENGER_NAME	Nome do passageiro	.+

Exemplo de JSON

{
    "merchant_id": "CODIGO_LOJA",
    "order_id": "1123456",
    "redirect": "M",
    "authorizer_id": "600",
    "amount": "2000",
    "installments": "1",
    "back_url": {
        "url_success": "url relativa de sucesso cadastrada no e-SiTef",
        "url_failure": " url relativa de fracasso cadastrada no e-SiTef",
        "url_cancel": " url relativa de cancelameto cadastrada no e-SiTef"
    },
    "additional_data": {
        "extra_info": "dados extras",
        "currency":"BRL",
        "items": [
            {
                "description": "descricao",
                "id": "123",
                "quantity": "2",
                "title": "Produto 1",
                "unit_price": "1000",
                "weight": "4000",
                "shipping_cost": "1000"
            },
            {
                "description": "descricao",
                "id": "1234",
                "quantity": "3",
                "title": "Produto 2",
                "unit_price": "2000",
                "weight": "3000",
                "shipping_cost": "1000"
            }
        ],
        "payer": {
            "name": "João",
            "surname": "Silva",
            "email": "joao.silva@exemplo.com",
            "phone_area_code": "11",
            "phone_number": "78945123",
            "identification_type": "CPF",
            "identification_number": "12345678906",
            "address_street_name": "Rua do Exemplo",
            "address_street_number": "123",
            "born_date": "12/12/1900"
        },
        "shipment": {
            "cost": "2000",
            "type": "1",
            "receiver_address": {
                "zip_code": "12345678",
                "street_number": "Rua do Exemplo",
                "street_name": "123",
                "floor": "3",
                "apartment": "901",
                "city": "São Paulo",
                "complement": "Sobreloja 3",
                "country": "BRA",
                "district": "Jardim do Exemplo",
                "state": "SP"
            }
        },
        "extra_param": {
            "metadata": [
                {
                    "key": "PASSENGER_CPF",
                    "value": "12345678901",
                    "group": "1"
                },
                {
                    "key": "PASSENGER_PASSPORT",
                    "value": "1594825512",
                    "group": "1"
                }
            ]
        }
    }
}

PayPal

Esta página tem como objetivo apresentar as configurações e procedimentos necessários para a integração do site do lojista como meio de pagamento PayPal, através da Interface de Pagamento HTML do e-SiTef, e também para estornos via interface WebService e pelo Portal do Lojista.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento Paypal:

• Interface de Pagamento HTML 2.0
• Interface WebService Refund para estornos
• Portal do Lojista para estornos

Código de Autorizadora no e-SiTef para PayPal

O código de autorizadora para a utilização ddo PayPal é o 400. Para mais códigos de autorizadora, visite a página de Autorizadoras.

Credenciais necessárias

Antes de efetuar transações PayPal com o e-SiTef, devem ser seguidos os passos de configuração apresentados a seguir.

Dados de cadastro da loja no PayPal

A loja deverá criar um cadastro no PayPal caso já não o possua. Mais informações em www.paypal.com.br. Siga as instruções em Criar conta PayPal. Dentro da sua conta, crie as credenciais necessárias.

O PayPal permite, a partir da conta cadastrada como Empresarial (ou Business), que sejam criadas contas virtuais para o sandbox - o ambiente de testes do PayPal. Para o processo de homologação no e-SiTef, sugere-se que seja criada uma conta no sandbox. Procure pela opção no site dentro da sua conta PayPal.

Abaixo estão os dados Cadastrais PayPal da loja que devem ser obtidas pela sistema PayPal:

Nome do campo no e-SiTef	Descrição do campo	Obrigatório
USER	Nome de Usuário associado à conta PayPal	SIM
PWD	Senha do USER	SIM
SIGNATURE	Assinatura associada ao USER	SIM

Importante: As credenciais do sandbox do PayPal podem ser utilizados no processo de homologação. Porém no ambiente de produção, devem ser cadastradas as credenciais da conta real da loja no PayPal.

Inserir dados cadastrais no e-SiTef

Tendo os dados cadastrais PayPal citados acima em mãos, o lojista deve solicitar à equipe de atendimento do e-SiTef:

• A ativação da Autorizadora PayPal no cadastro da loja no e-SiTef.
• Caso não possua, um usuário e senha de acesso para o Portal do Lojista do e-SiTef.

O próprio lojista pode cadastrar as informações obtidas com a PayPal no Portal do Lojista do e-SiTef. Para mais informações, acesse a página de Configuração de Autorizadora no Portal do Lojista.

Imagem de cabeçalho ou logotipo customizado na página PayPal

O lojista poderá optar entre um logotipo ou um imagem de cabeçalho (header) para ser apresentado na tela do PayPal. As dimensões do logotipo são 190 pixels x 60 pixels e as dimensões do header são 915 pixels x 85 pixels. A imagem deverá ser enviada à equipe do PayPal, que se encarregará de editar a mesma, combinando com o logotipo do e-SiTef.

Fluxo de Pagamento com PayPal

O PayPal proporciona um modelo de pagamento seguro por meio do Express Checkout, uma solução de pagamento em que as chamadas são feitas com dados exclusivos para cada cliente e um token único é retornado para cada transação criada. O e-SiTef se integra ao PayPal utilizando esta API.

O fluxo do processo de pagamento no e-SiTef via PayPal segue como abaixo:

1. O usuário inicia o pagamento pelo e-SiTef;
2. A lista de autorizadoras configurada na loja é apresentada para o usuário;
3. O usuário escolhe a forma de pagamento PayPal;
4. Nesse momento será aberta uma nova janela redirecionando o usuário para o site PayPal;
5. O usuário inicia o processo de pagamento no site do PayPal, onde ocorre a autenticação do usuário e a autorização do pagamento;
6. O usuário finaliza o pagamento no ambiente do PayPal;
7. O PayPal redireciona o usuário para o e-SiTef.
8. Ao receber o redirecionamento do usuário, o e-SiTef efetua uma consulta ao PayPal e atualiza o status da transação no e-SiTef.
9. Caso a loja tenha configurado o redirecionamento automático, o usuário é redirecionado à URL de Sucesso ou Fracasso configurado no e-SiTef.

O diagrama de fluxo abaixo ilustra um fluxo de pagamento PayPal via e-SiTef:

Um caso de exceção a esse fluxo é o caso onde se inicia a transação com a autorizadora PayPal pré-fixada, onde os passos 2 e 3 não são necessários.

Aviso de Status

Para cada alteração de status de transação no e-SiTef, resultante de comunicação entre o e-SiTef e o PayPal, é enviado ao servidor da loja um Aviso de Status. Para mais detalhes sobre esta funcionalidade, consulte a página sobre Aviso de Status.

Parâmetros para transação de pagamento via PayPal

Os parâmetros usados para se criar uma transação de pagamento com o PayPal são os mesmos que os apresentados no documento de Criação de transação de pagamento via HTML.

Em adição aos parâmetros comuns, é possível enviar na requisição os campos específicos para o Paypal descritos abaixo:

Nome do parâmetro	Descrição	Tamanho	Obrigatório
additional_data	Objeto do tipo ADDITIONALDATA		NÃO

ADDITIONALDATA (additional_data)

Nome do parâmetro	Descrição	Tamanho	Obrigatório
extra_info	Informações adicionais.	< 127 AN	NÃO
item_amount	Soma dos valores dos itens do pedido em centavos. Aqui se devem multiplicar os valores unitários (unit_price) dos itens com sua respectiva quantidade (quantity), para cada item. Limitado a US$10000 em qualquer moeda.	< 1024 N	NÃO
purchase_summary	Campo para envio de texto customizado para o texto "Resumo da Compra" na tela de pagamento.	< 1024 AN	NÃO
insurance_amount	Total dos valores de seguro dos itens do pedido em centavos. Limitado a US$10000 em qualquer moeda.	< 1024 N	NÃO
handling_amount	Custo de processamento da venda em centavos. Limitado a US$10000 em qualquer moeda.	< 1024 N	NÃO
tax_amount	Total das taxas inclusas nos itens do pedido em centavos. Limitado a US$10000 em qualquer moeda.	< 1024 N	NÃO
items	Objeto do tipo ITEMS		NÃO
payer	Objeto do tipo PAYER		NÃO
shipment	Objeto do tipo SHIPMENT		NÃO
extra_param	Objeto do tipo EXTRAPARAM		NÃO

ITEMS (items)

Nome do parâmetro	Descrição	Tamanho	Obrigatório
id	Identificação do item.	< 127 AN	NÃO
title	Título do item.	< 127 AN	NÃO
url	URL do item.	< 1024 AN	NÃO
quantity	Quantidade do item.	< 10 N	NÃO
unit_price	Preço unitário do item em centavos. Limitado a US$10000 em qualquer moeda.	< 1024 N	NÃO
weight	Correspondem ao peso de cada item do pedido. Unidade de medida em gramas(g). Ex: 2,3 kg -> 2300	< 10 N	NÃO
description	Descrição do item.	< 127 AN	NÃO
tax_amount	Valor da taxa do item em centavos. Limitado a US$10000 em qualquer moeda.	< 1024 N	NÃO
length	Comprimento do item. Unidade de medida em centímetros (cm).	< 10 N	NÃO
width	Largura do item. Unidade de medida em centímetros (cm).	< 10 N	NÃO
height	Altura do item. Unidade de medida em centímetros (cm).	< 10 N	NÃO
type	Tipo do item: Digital – O item é um produto digital. Ex: e-books, músicas, etc. Physical – O item é um produto físico.	< 10 N	NÃO

PAYER (payer)

Nome do parâmetro	Descrição	Tamanho	Obrigatório
email	E-mail do comprador.	< 127 AN	NÃO
identification_type	Tipo de identificação do comprador. Para o Brasil: BR_CPF - CPF do comprador BR_CNPJ - CNPJ do comprador.	< 10 A	SIM (NO BRASIL)
identification_number	Número de identificação do comprador.	< 14 AN	SIM (NO BRASIL)

SHIPMENT (shipment)

Nome do parâmetro	Descrição	Tamanho	Obrigatório
cost	Informa o valor total de frete do pedido. Formato: centavos. Limitado a US$10000 em qualquer moeda. Ex: 123456 (R$ 1234,56)	< 1024 N	NÃO
discount_amount	Desconto aplicado ao frete, em centavos. Limitado a US$10000 em qualquer moeda.	< 1024 N	NÃO
receiver_address	Objeto do tipo RECEIVERADDRESS		NÃO

RECEIVERADDRESS (receiver_address)

Nome do parâmetro	Descrição	Tamanho	Obrigatório
zip_code	CEP do endereço a ser entregue.	< 20 AN	SIM (*)
street_name	Endereço a ser entregue. Até 100 caracteres combinados com o campo street_number.	< 100 AN	SIM (*)
street_number	Número do endereço a ser entregue. Até 100 caracteres combinados com o campo street_name.	< 100 AN	SIM (*)
complement	Informa o complemento (bloco, apartamento, etc.) do endereço de envio do produto.	< 100 AN	SIM (*)
city	Informa a cidade do endereço de envio do produto.	< 40 AN	SIM (*)
state	Informa o estado do endereço de envio do produto. Exemplo: SC (Santa Catarina), SP (São Paulo), etc.	< 2 AN	SIM (*)
country	Informa o país do endereço de envio do produto. Segue o padrão ISO 3166-1 alpha-3 (3 letras). Ex: Brasil: BRA	< 2 A	SIM (*)
name	Nome de referência da pessoa do endereço de envio do produto.	< 32 AN	SIM (*)
phone_area_code	Código do área do telefone do endereço de envio do produto. Até 20 caracteres combinados com o campo phone_number.	< 20 AN	SIM (*)
phone_number	Número do telefone do endereço de envio do produto. Até 20 caracteres combinados com o campo phone_area_code.	< 20 AN	SIM (*)

EXTRAPARAM (extra_param)

Nome do parâmetro	Descrição	Tamanho	Obrigatório
acquirer_params	Objeto do tipo ACQUIRERPARAMS		NÃO

ACQUIRERPARAMS (acquirer_params) (**)

Nome do parâmetro	Descrição	Tamanho	Obrigatório
key	Chave do parâmetro a ser enviado para a adquirente ou autorizadora.	< 1024 AN	NÃO
value	Valor do parâmetro a ser enviado para a adquirente ou autorizadora.	< 1024 AN	NÃO

(*) Esse campo deixa de ser obrigatório quando o item em questão for exclusivamente digital, ou seja, não houver entrega de produto físico. Exemplo: livro digital, música, etc.

ATENÇÃO: O campo que define se o item é digital ou não é o campo type do objeto item.

(**) acquirer_params: Este objeto coleta conjunto de parâmetros em formato chave+valor (key+value), quando existem parâmetros específicos que devem ser enviados para um adquirente ou autorizadora. No caso do PayPal, os seguintes parâmetros são possíveis de envio:

Chave	Valor
reqConfirmShipping	Indica se é necessário que o endereço de envio existente no PayPal precisa ser um endereço validado. Para isso deve atribuir à variável um dos valores abaixo: 0 - Se não é necessário que o endereço de envio seja um endereço confirmado; 1 - Se é necessário que o endereço de envio seja um endereço confirmado. Para produtos digitais ou virtuais (Ex: livros eletrônicos e músicas digitais - produtos que são entregues via web), o parâmetro é obrigatório e deve receber o valor 0 (zero).
noShipping	Determina se a página do PayPal deve mostrar os campos de endereço para envio do pedido. Para produtos digitais ou virtuais (Ex: livros eletrônicos e músicas digitais - produtos que são entregues via web), este parâmetro é obrigatório e deve ser 1. 0 - É mostrado o endereço de envio na página do PayPal; 1 - PayPal não mostra campos do endereço de envio; 2 - Se a loja não passa o endereço de envio, PayPal obtém ele por meio do perfil da conta do comprador.
allowNote	Torna possível para o comprador enviar uma nota para a loja a partir da página do PayPal. Valores possíveis para o parâmetro: 0 - O comprador não é capaz de enviar uma nota para a loja; 1 - O comprador é capaz de enviar uma nota para a loja.
addrOverride	Determina se a página do PayPal deve mostrar o endereço de envio encaminhado pela loja e não o existente no sistema do PayPal para um determinado cliente. O cliente não consegue editar o endereço, se o mostrado for oriundo do PayPal. Valores possíveis para o parâmetro: 0 - O PayPal mostra o endereço de envio proveniente da loja. 1 - O PayPal não mostra o endereço de envio proveniente da loja
localeCode	Código da localidade da página do PayPal mostrada durante o processo de compra. O parâmetro pode assumir um dos seguintes valores, de acordo com a localidade: AU - Austrália AT - Áustria BE - Bélgica BR - Brasil CA - Canadá CH - Suíça CN - China DE - Alemanha ES - Espanha GB - Reino Unido FR - França IT - Itália NL - Holanda PL - Polônia PT - Portugal RU - Rússia US - Estados Unidos Para línguas específicas em um país: da_DK - Dinamarquês (somente para a Dinamarca) he_IL - Hebraico (todas as localidades) id_ID - Indonésio (apenas para a Indonésia) jp_JP - Japonês (somente para o Japão) no_NO - Norueguês (somente para a Noruega) pt_BR - Português Brasileiro (apenas para Portugal e Brasil) ru_RU - Russo (para a Lituânia, Letônia, e Ucrânia) sv_SE - Sueco (apenas para a Suécia) th_TH - Tailandês (apenas para a Tailândia) tr_TR - Turco (Somente para a Turquia) zh_CN - Chinês simplificado (apenas para China) zh_HK - Chinês tradicional (apenas para Hong Kong) zh_TW - Chinês tradicional (apenas para Taiwan) NOTA: Se o parâmetro não existir, o PayPal seleciona a língua com base nos dados da loja, do cliente e da sessão.
pageStyle	Nome do estilo da página customizada para páginas de pagamento associadas a um botão ou link. Corresponde a variável Page_style em HTML.
hdrBorderColor	Cor (em HTML hexadecimal de 6 dígitos) da borda do cabeçalho da página de pagamento. A cor padrão é preta.
hdrBackColor	Cor (em HTML hexadecimal de 6 dígitos) de fundo do cabeçalho da página de pagamento. A cor padrão é branca.
payFlowColor	Cor (em HTML hexadecimal de 6 dígitos) de fundo da página de pagamento. A cor padrão é branca.
cartBorderColor	Cor (em HTML hexadecimal de 6 dígitos) da borda do resumo do pedido ou carrinho. A cor da borda é branca no topo da borda e gradativamente ela vai acentuando-se até a cor de referência ao decorrer da borda.
landingPage	Tipo de página de acesso. Valores possíveis para o parâmetro: Billing - Quando o usuário não tem conta no PayPal é aberta uma página de cadastro. Login - É aberta uma página de login no PayPal. Se o parâmetro não for declarado explicitamente, o valor padrão é Login.
buyerEmailOptinenable	Permite que o comprador possa inserir seu endereço de e-mail na página do PayPay para ser notificado de promoções ou eventos especiais. Valores possíveis para o parâmetro: 0 - PayPal não habilita o comprador a opção de cadastrar seu e-mail para eventuais avisos. 1 - Habilita o comprador a opção de cadastrar seu e-mail para eventuais avisos.
paymentRequest_0_paymentReason	Identificador do tipo de transação. Valores possíveis para o parâmetro: None - Transação sem tipo. Refund - Transação de reembolso.
paymentRequest_0_insuranceOptionOffered	Indica se o comprador terá a opção de seguro na página de “review” do PayPal. Pode ser especificado para até 10 pagamentos em um transação de compra, em que o valor de n varia entre 0 e 9, inclusive . Valores possíveis para o parâmetro: true - Com opção. false - Sem opção.
paymentRequest_0_custom	Campo de livre uso. Pode ser especificado para até 10 pagamentos em um transação de compra, em que o valor de n varia entre 0 e 9, inclusive.
paymentRequest_0_noteText	Nota para o lojista. Pode ser especificado para até 10 pagamentos em um transação de compra, em que o valor de n varia entre 0 e 9, inclusive.

Importante: Apesar do PayPal oferecer suporte a vários grupos de itens, o e-SiTef suporta apenas 1 grupo por compra.

Exemplos de request JSON para iniciar transações PayPal

Seguem exemplos de requests JSON para iniciar uma transação PayPal. Exemplo de request mínimo:

Objeto JSON request mínimo:

{
    "merchant_id":"CODIGOLOJA",
    "amount":"1000",
    "authorizer_id":"400",
    "additional_data":{
        "currency":"BRL",
        "payer":{
            "identification_type":"BR_CPF",
            "identification_number":"12345678901"
        }
    }
}

Exemplo de request completo:

{
    "merchant_id":"CODIGOLOJA",
    "merchant_usn":"1234567890",
    "order_id":"pedido45687",
    "authorizer_id":"400",
    "amount":"1000",
    "redirect":"M",
    "style":"P",
    "soft_descriptor":"MINHALOJA",
    "additional_data":{
        "item_amount":"1000",
        "tax_amount":"0",
        "insurance_amount":"0",
        "handling_amount":"0",
        "extra_info":"descricao",
        "currency":"BRL",
        "items":[
            {
                "id":"1",
                "title":"bola 1",
                "quantity":"1",
                "unit_price":"500",
                "currency":"BRL",
                "url":"http://sportv.globo.com/platb/files/1103/2011/08/bola_futebol.gif",
                "type":"Physical",
                "description":"bola para jogar 1",
                "weight": "100",
                "length": "20",
                "width": "20",
                "height": "20",
                "tax_amount": "0"
            },
            {
                "id":"2",
                "title":"bola 2",
                "quantity":"2",
                "unit_price":"250",
                "currency":"BRL",
                "url":"http://sportv.globo.com/platb/files/1103/2011/08/bola_futebol.gif",
                "type":"Physical",
                "description":"bola para jogar 2",
                "weight": "200",
                "length": "20",
                "width": "20",
                "height": "20",
                "tax_amount": "0"
            }
        ],
        "payer":{
            "email":"js@softexpress.com.br",
            "identification_type":"CPF",
            "identification_number":"09719224703"
        },
        "shipment":{
            "cost": "0",
            "discount_amount": "0",
            "receiver_address":{
                "zip_code": "12345678",
                "street_number": "Rua do Exemplo",
                "street_name": "123",
                "name": "Rafael do Mel",
                "phone_area_code": "11",
                "phone_number": "912341234",
                "city": "São Paulo",
                "complement": "Sobreloja 3",
                "country": "BRA",
                "state": "SP"
            }
        },
        "extra_param": {
            "acquirer_params": [
                {
                    "key": "reqConfirmShipping",
                    "value": "0"
                },
                {
                    "key": "noShipping",
                    "value": "1"
                },
                {
                    "key": "allowNote",
                    "value": "1"
                },
                {
                    "key": "addrOverride",
                    "value": "1"
                },
                {
                    "key": "localeCode",
                    "value": "pt_BR"
                },
                {
                    "key": "pageStyle",
                    "value": ""
                },
                {
                    "key": "hdrBorderColor",
                    "value": ""
                },
                {
                    "key": "hdrBackColor",
                    "value": ""
                },
                {
                    "key": "payFlowColor",
                    "value": ""
                },
                {
                    "key": "cartBorderColor",
                    "value": ""
                },
                {
                    "key": "landingPage",
                    "value": ""
                },
                {
                    "key": "buyerEmailOptinenable",
                    "value": "0"
                },
                {
                    "key": "paymentRequest_0_paymentReason",
                    "value": "none"
                },
                {
                    "key": "paymentRequest_0_insuranceOptionOffered",
                    "value": "false"
                },
                {
                    "key": "paymentRequest_0_custom",
                    "value": ""
                },
                {
                    "key": "paymentRequest_0_noteText",
                    "value": "Obrigado por comprar na Loja Teste!"
                }
            ]
        }
    }
}

Cancelamento de transações PayPal

O cancelamento ou estorno de transações PayPal estão disponíveis no e-SiTef através de duas interfaces:

• WebService Cancel REST e;
• Portal do Lojista.

Cancelamento via Portal do Lojista

Ao realizar um cancelamento de uma transação PayPal via Portal do Lojista a seguinte tela será exibida durante o processo:

Abaixo estão as descrições dos campos do formulário:

Nome do parâmetro	Descrição	Obrigatório
Valor	Valor a ser estornado na transação.	SIM
Tipo de Reembolso	Tipo de estorno que se deseja realizar sobre o pagamento. Valores permitidos: Total - É desejado o estorno completo do pagamento. Parcial – É desejado o estorno parcial do pagamento.	SIM
Fonte do Reembolso	Fonte de fundos do lojista que será utilizado para realizar o estorno. Valores permitidos: Qualquer disponível – O lojista não tem preferência. Será utilizado qualquer fonte de fundos disponível. Padrão - Será utilizado a fonte de fundos configurada na conta do lojista. Imediato - Será utilizado o balanço do vendedor como fonte de fundos. eCheck - Será utilizado a opção eCheck como fonte de fundos. Se o balanço do lojista puder cobrir o estorno, será utilizado o balanço.	SIM
Tentar novamente até	formato AAAA-MM-DDTHH:MM:SS. Data e hora limite até a qual será realizada a tentativa do estorno.	NÃO
Invoice ID	Código de pedido do estorno próprio do lojista para futura consulta ou rastreamento.	NÃO
Message ID	Esse ID identificará de maneira única a mensagem e poderá ser utilizado para requisitar os últimos resultados de um requisição anterior sem a necessidade de criar uma nova requisição. Isso pode ser realizado, por exemplo, em chamadas que foram canceladas por timeout ou erros durante o processo.	NÃO
Store ID	Utilizado caso seja um Ponto de Venda.	NÃO
Terminal ID	Utilizado caso seja um Ponto de Venda.	NÃO
Refund Advice	Indicador para cliente que já foi recebido algum estorno da determinada transação. Valores permitidos: Verdadeiro - caso o cliente já tenho realizado algum estorno na determinada transação. Falso - caso o cliente não tenha feito nenhum estorno na determinada transação.	NÃO
Anotações	Mensagem personalizada para lembretes sobre o estorno.	NÃO
Detalhes da loja	Informações sobre o estabelecimento do lojista.	NÃO

SafraPay

A loja tem a possibilidade de configurar o roteamento de transações feitas com cartão de crédito no e-SiTef por vários meios de pagamento, um desses meios é o SafraPay.

Nesta página será usada a nomenclatura "SafraPay" para referenciar o roteamento no e-SiTef.

Assim, a loja pode configurar o e-SiTef para que as transações feitas com cartões VISA, por exemplo, sejam roteadas pela SafraPay enquanto que as feitas com MASTERCARD sejam roteadas pela CIELO.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento SafraPay:

• Pagamento REST
• Pré-autorização REST
• Pagamento HTML
• Pré-autorização HTML
• Cancelamento REST
• Cancelamento via Portal

Autorizadoras permitidas

As seguintes autorizadoras são suportadas pelo roteamento SafraPay:

• VISA
• MASTERCARD
• ELO
• AMERICAN EXPRESS
• HIPERCARD

Credenciais necessárias

A loja deve obter com a SafraPay as credenciais listadas abaixo, e repassá-las à Software Express ou fazer o cadastro como explicado mais a frente neste mesmo documento.

Campo	Descrição	Formato
merchantID	Código de EC cadastrado na SafraPay.	< 15 AN
terminalId	Identificação do Terminal.	< 8 AN

Importante para Pagamento HTML: No caso de uma autorizadora da loja não ter cadastrado essas credenciais, essa autorizadora não será exibida na tela de seleção de cartão de crédito durante a operação de pagamento.

Cadastro das informações pelo Portal do Lojista e-SiTef

O próprio lojista pode cadastrar as informações obtidas com a SafraPay no Portal do Lojista do e-SiTef. Para essa finalidade, o lojista deve selecionar a autorizadora e entrar na tela de edição como no exemplo exibido abaixo:

Saiba mais detalhes sobre o Portal do Lojista.

Fluxos

Nesta seção serão apresentadas as particularidades do fluxo transacional SafraPay.

Pagamento REST/HTML

Abaixo estão listados os campos que são diferenciados e são relevantes para o SafraPay:

REST Begin / HTML Init

Campos relevantes na chamada descrita no Serviço de criação de transação HTML e no Serviço de criação de transação REST:

Parâmetro	Descrição	Formato	Obrigatório
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais	< 30 AN	NÃO
additional_data	Elemento para envio de dados adicionais.
postpone_confirmation	Campo que permite que loja mantenha a transação como Pendente de Confirmação, e posteriormente, confirmá-la ou desfazê-la.	< 5 A	NÃO
transaction_initiated_by	Indica se a transação foi iniciada pelo Lojista ou pelo Comprador. Relevante quando utilizado em conjunto com, por exemplo, transações recorrentes que são iniciadas pelo Lojista (merchant). Valores permitidos: customer – Transação iniciada pelo Comprador. merchant – Transação iniciada pelo Lojista.	< 8 AN	NÃO
total_order_amount	Montante final da compra.	< 8 AN	NÃO
tax_amount	Montante da taxa.	< 8 AN	NÃO
additional_data.payer	Elemento para envio de dados referentes ao comprador.
id	Identificação do comprador.	< 200 AN	NÃO
name	Nome do comprador. Obs.: a concatenação de nome com o sobrenome não pode ultrapassar 255 caracteres.	< 200 AN	NÃO
surname	Sobrenome do comprador. Obs.: a concatenação do nome com o sobrenome não pode ultrapassar 255 caracteres.	< 200 AN	NÃO
identification_number	Número de identificação do comprador.	< 200 AN	NÃO
identification_type	Tipo da identificação informada pelo comprador (RG, CPF, etc.).	< 200 AN	NÃO
email	E-mail do comprador.	< 255 AN	NÃO
additional_data. payer.phones[]	Apenas 1 telefone será repassado para o Safrapay.
ddi	DDI do telefone.	< 255 AN	NÃO
ddd	DDD do telefone.	< 15 AN	NÃO
number	Número do telefone.	< 50 AN	NÃO
additional_data. shipment.receiver_address	Elemento para envio de dados referentes ao endereço de entrega.
street_name	Endereço de entrega.	< 255 AN	NÃO
street_number	Número do endereço de entrega.	< 15 AN	NÃO
complement	Complemento do endereço de entrega.	< 50 AN	NÃO
county	Bairro do endereço de entrega.	< 150 AN	NÃO
zip_code	CEP do endereço de entrega. Ex.: 21241-140.	< 9 AN	NÃO
city	Cidade do endereço de entrega.	< 50 AN	NÃO
state	Estado do endereço de entrega.	= 2 AN	NÃO
country	País do endereço de entrega seguindo a AN 3166-1. Ex.: BRA	= 3 AN	NÃO
additional_data. billing_data.address	Elemento para envio de dados referentes ao endereço de cobrança.
street_name	Endereço de cora.	< 255 AN	NÃO
street_number	Número do endereço de cora.	< 15 AN	NÃO
complement	Complemento do endereço de cora.	< 50 AN	NÃO
county	Bairro do endereço de cora.	< 150 AN	NÃO
zip_code	CEP do endereço de cora. Ex.: 21241-140.	< 9 AN	NÃO
city	Cidade do endereço de cora.	< 50 AN	NÃO
state	Estado do endereço de cora.	= 2 AN	NÃO
country	País do endereço de cora seguindo a AN 3166-1. Ex.: BRA	= 3 AN	NÃO
additional_data.items[]	Elemento para envio de dados referentes aos produtos do comprador.
title	Nome do produto.	< 255 AN	NÃO
quantity	Quantidade do produto a ser adquirido.	< 15 N	NÃO
id	Código comerciante identificador do produto.	< 255 AN	NÃO
unit_price	Preço unitário do produto em centavos.	< 15 N	NÃO
discount_amount	Valor em centavos de desconto sobre o produto	< 12 AN	NÃO

Atualmente, o SafraPay não permite parcelamento com juros da administradora do cartão, ou seja, o campo installments_type não pode receber o valor 3 e o valor 6.

Efetivação de Pagamento

Campos relevantes na chamada descrita no Serviço de efetivação de pagamento:

Parâmetro	Descrição	Formato	Obrigatório
external_authentication	Este elemento recebe campos de autenticação MPI.
eci	Eletronic Commerce Indicator – indica o nível de segurança da transação com autenticação do dono do cartão	< 3 N	NÃO
xid	Identificador da transação de autenticação do dono do cartão, feita em serviço externo ao e-SiTef	< 40 N	NÃO
cavv	Cardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão.	< 40 N	NÃO
cavv_key_indicator	Indicador de 2 digitos utilizado pela bandeira ELO.	< 2 N	NÃO
unpredictable_number	Indicador numérico utilizado pela bandeira ELO.	-	NÃO
auth_tracking_number	Indicador numérico utilizado pela bandeira ELO.	-	NÃO

Entre os campos de resposta do Serviço de efetivação de pagamento, o campo issuer será preenchido com o código de bandeira do cartão que foi reconhecido no pagamento. Abaixo está a lista de códigos e bandeira:

Código	Bandeira
1	VISA (crédito)
20002	VISA (débito)
2	MASTERCARD
20001	MASTERCARD (débito)
4	AMEX
12	HIPERCARD (crédito)
20037	HIPERCARD (débito)
31	ELO (crédito)
20032	ELO (débito)

Confirmação de Pagamento

É possível confirmar um valor inferior ao valor das autorizações criadas via HTML e via via REST utilizando o campo additional_data.postpone_confirmation igual a true.

Para isso, envie na chamada de confirmação REST o valor de amount desejado:

Parâmetro	Descrição	Formato	Obrigatório
confirm	Este campo deve ser enviado com o valor true caso se deseje confirmar a transação, ou false, caso queira desfazer o pagamento.	< 5 T/F	SIM
amount	Valor em centavos do valor que será confirmado. Caso não seja enviado, o valor completo da transação será confirmado.	< 12 N	NÃO

Recorrência

O SafraPay aceita o parâmetros de sinalização de recorrência de transações. Para isso, envie na chamada de efetivação de pagamento REST o campo acquirer.recurrency com o valor true.

Para mais informações consulte a página sobre o Serviço de Efetivação de Pagamento REST.

Pré-Autorização

Normalmente, o parcelamento de uma pré-autorização é processado no Serviço de Captura de Pré-Autorização, mas o SafraPay é uma das exceções. O preenchimento dos campos installments e installment_type será processado na efetuação da pré-autorização ou na inicialização de uma transação de pré-autorização. Para maiores detalhes do preenchimento deste campo, veja:

• Criar uma Pré-autorização REST.
• Efetuar uma Pré-Autorização REST
• Criar uma Pré-autorização HTML

Atualmente, o SafraPay não permite parcelamento com juros da administradora do cartão, ou seja, o campo installments_type não pode utilizar o valor 3 e o valor 6 (IATA).

Cancelamento

O Cancelamento de uma transação pode ser feito no Portal do Lojista ou via Web Service REST. Poderão ser canceladas as transações efetuadas no dia corrente do cancelamento (D+0) ou em outros dias (D+N). O lojista pode cancelar transações de pagamento que foram confirmadas como também as que ainda não foram.

É possível também cancelar valores inferiores aos do pagamento original, tanto nas transações confirmadas e não confirmadas. No caso de transações não confirmadas é possível realizar apenas um cancelamento parcial.

O processamento de transações de cancelamento do SafraPay ocorre na janela entre 0 hora até às 6 horas da manhã. Aconselhamos que os cancelamentos não sejam efetuados nesse período.

IATA

O roteamento SafraPay suporta pagamentos com IATA (International Air Transport Association). Portanto, os campos departure_tax e first_installment serão processados no serviço de criação de transação do pagamento REST.

Stone WS

A loja tem a possibilidade de configurar o roteamento de transações feitas no e-SiTef por vários meios de pagamento, um desses meios é o e-commerce Stone, daqui em diante citado como StoneWS.

Nesta página será usada a nomenclatura "StoneWS" para referenciar o roteamento no e-SiTef.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento StoneWS:

• Pagamento REST
• Pré-Autorização REST
• Cancelamento REST
• Pagamento HTML
• Pré-Autorização HTML

Autorizadoras permitidas

Para maiores informações sobre quais autorizadoras são permitidas pela StoneWS, por favor, entrar em contato com a mesma.

Credenciais necessárias

Para começar a transacionar com a StoneWS, a loja deve obter o SAK(Sale Affliation Key), chave para integração no ambiente da Stone. Para isso, a loja deve solicitar sua credencial de acesso através do e-mail integracoes@stone.com.br, com as seguintes informações:

• O nome da empresa parceira que realizará transações na Stone
• O CNPJ da empresa
• Uma descrição sucinta do negócio parceiro (em uma frase)
• E-mail para onde a credencial deve ser enviada

Após recebimento, o lojista deve encaminhar o SAK(Sale Affliation Key) para a equipe produção da Software Express. Esses dados podem ser cadastrados também no Portal do Lojista do e-SiTef no item de menu Configurar Autorizadoras.

Campo	Descrição	Tipo
salesAffiliationKey	Identificação do estabelecimento Comercial na adquirente Stone.	AN

Cancelamento

O cancelamento pode ser feito do valor parcial ou total das seguintes formas:

• Através do Cancelamento REST
• Através do Portal do Lojista

Subadquirência

A subadquirência é um recurso opcional e sua habilitação é feita inicialmente no cadastro da loja na StoneWS, e em paralelo, no sistema administrativo do e-SiTef.

O lojista deve solicitar à equipe de atendimento a habilitação da subadquirência StoneWS no sistema administrativo do e-SiTef.

Dados cadastrais necessários para subadquirência

Uma vez que a loja tenha a subadquirência habilitada, as seguintes informações sobre a loja devem ser cadastradas no sistema administrativo do e-SiTef:

Campo	Descrição	Formato
País	Código de país da Loja	= 3 A
Estado	Estado da Loja	= 2 A
Cidade	Cidade da Loja	< 25 A
CEP	CEP da Loja	< 9 N
SoftDescriptor	Descrição resumida que será apresentada na fatura do portador do cartão (mais detalhes no item SoftDescriptor).	< 30 AN

Todos os dados descritos serão enviados à StoneWS em todas as transações, assim que a subadquirência seja habilitada.

MCC dinâmico

Adicionalmente, o lojista pode alterar o MCC (Merchant Category Code) dinamicamente em transações que envolvam subadquirência. Caso o MCC não seja enviada nas transações, será considerado o MCC padrão definido no cadastro da loja na StoneWS. O MCC dinâmico pode ser enviado conforme os itens a seguir.

Campo	Descrição	Formato
MCC	Merchant Category Code - código que indica a categoria do merchant	= 4 N

Os valores possíveis de MCC podem ser consultados em uma página descritiva da Stone http://credenciamento.stone.com.br/docs/mcc (link ativo em 2017/09/15) ou pela ISO - 18245.

O campo mcc está descrito em: Serviço de efetivação de pagamento

Auxílio Emergencial

O e-SiTef permite a utilização do Auxílio Emergencial.

Para isso, as condições abaixo devem ser obedecidas.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a utilização do Auxílio Emergencial:

• Pagamento REST
• Pagamento HTML (incluindo Link de Pagamento)

Autorizadoras permitidas

As seguintes autorizadoras/bandeiras suportam a utilização do Auxílio Emergencial:

• ELO DÉBITO
• VISA ELECTRON

Roteamentos permitidos

O seguinte roteamento/adquirente suporta a utilização do Auxílio Emergencial:

• Cielo e-Commerce
• eRede REST
• SafraPay
• Getnet WS

Análise Antifraude

As seguinte entidades de análise antifraude suportam o Auxílio Emergencial:

• Cybersource

Atenção:

É possível enviar uma análise para a entidade de análise antifraude Konduto, porém a modalidade débito não é suportada e a chamada é apenas registrada sem que uma análise seja realizada.

Detalhes para a Análise Antifraude

As observações abaixo são válidas para a interface de Pagamento HTML.

Para utilizar a antifraude com o Auxílio Emergencial, o seguinte parâmetro deve ter obrigatóriamente o seguinte valor:

Campo	Valor Obrigatório
additional_data.anti_fraud	enabled_before_auth

Os valores dos campos abaixos serão ignorados:

Campo
authorizer_authentication
additional_data.postpone_confirmation

Carteiras Digitais

Uma Carteira Digital é uma aplicação que realiza o armazenamento de cartões de crédito/débito/auxílio de forma segura com o objetivo de facilitar o comprador na hora de realizar um pagamento.

Sozinha a Carteira Digital fornece apenas informações de cartão do pagador, sendo necessário um meio de pagamento para que se utilize desses dados para que de fato o pagamento seja efetuado.

É com o papel de ser o Gateway de Pagamento que o e-SiTef se encaixa nesse fluxo.

Está página tem como objetivo esclarecer, de um modo geral, como uma Carteira Digital se integra com os serviços do e-Sitef.

Carteiras Digitais integradas

O e-SiTef está integrado com as seguintes Carteiras Digitais:

• Google Pay
• Masterpass
• Samsung Pay
• Visa Chechout

Roteamento/Adquirentes com suporte a autenticação 3DS

Ao adicionar um cartão dentro de uma Carteira Digital é possivel (quando suportado) realizar a autenticação (3DS) durante o processo de cadastro. Quando um cartão é registrado dessa forma, Carteira Digital irá repassar estes dados de autenticação para o e-SiTef que por sua vez irá repassar estes dados para as adquirentes.

Os roteamentos/adquirentes que suportam dados de autenticação 3DS são:

• SiTef [*]
• Cielo e-Commerce
• e.Rede REST
• Getnet WS
• GlobalPayments WS
• SafraPay

[*] Consulte nossa equipe de suporte e-SiTef para mais informações sobre suporte a autenticação 3DS no SiTef.

Fluxo de integração via Pagamento REST

Para mais informações sobre o Pagamento REST, acesse a página Pagamento REST - Visão Geral.

Abaixo está apresendo o fluxo geral de integração de Carteiras Digitais com o e-SiTef pela interface de Pagamento REST.

Neste cenário, a integração com a Carteira Digital é dividida entre a Loja Virtual e o e-SiTef:

1. O Comprador fecha o carrinho de compras dentro da loja virtual e escolhe como meio de pagmento uma Carteira Digital.
2. A Loja Virtual, que fez a integração com a primeira etapa da integração da Carteira Digital (abertura da carteira) irá exibir para o Comprador a interface da Carteira Digital.
3. O Comprador irá escolher, dentro da Carteira Digital, o cartão que deseja utilizar para efetuar o pagamento da compra.
4. Após o Comprador escolher o cartão, a Carteira Digital irá devolver os dados de cartão e compra criptografados para a aplicação da Loja Virtual.
5. Com os dados criptografados em mãos, a Loja Virtual irá repassá-los para o nossa interface de Pagamento REST através do campo card.wallet_transaction_id.
6. O e-SiTef irá receber os dados criptografados e irá descriptografá-los, ou seja, terá acesso aos dados de cartão para enviá-los às adquirentes para efetivamente executar o pagamento.
7. O e-SiTef retorna para a Loja Virtual o resultado da transação.
8. A Loja Virtual por sua vez repassa a resposta do e-SiTef para o Comprador.

Fluxo de integração via Pagamento HTML

Para mais informações sobre o Pagamento HTML, acesse a página Pagamento HTML - Visão Geral.

Abaixo está apresendo o fluxo geral de integração de Carteiras Digitais com o e-SiTef pela interface de Pagamento HTML.

Neste cenário, a integração com a Carteira Digital é realizada integralmente pelo e-SiTef:

1. O Comprador fecha o carrinho de compras dentro da loja virtual.
2. A Loja Virtual inicializa uma transação e redireciona o Comprador para a página de checkout e-SiTef.
3. O Comprador, já redirecionado para a página de checkout e-SiTef, verifica as possibilidades de pagamento.
4. O Comprador escolhe como meio de pagamento uma Carteira Digital.
5. A interface da Carteira Digital será exibida para o Comprador que então escolher o cartão.
6. A Carteira Digital irá devolver os dados de cartão e compra criptografados para o e-SiTef.
7. O e-SiTef irá receber os dados criptografados de cartão/compra e irá descriptografá-los, ou seja, terá acesso aos dados de cartão para enviá-los às adquirentes para efetivamente executar o pagamento.
8. O e-SiTef retorna para o Comprador o resultado da transação.

Conteúdo do campo card.wallet_transaction_id

O conteúdo a ser enviado no campo card.wallet_transaction_id pela interface Pagamento REST varia de acordo com a Carteira Digital a ser integrada. Consulte a documentação específica para mais detalhes.

Carteira Digital VEE via CardSE

Esta documentação descreve a integração com a carteira digital VEE através do e-SiTef, utilizando o roteamento CardSE via SiTef.

Fluxo

1. O lojista efetua o pagamento junto ao e-SiTef, informando o token referente à transação, gerado no aplicativo VEE pelo comprador. Este token é informado no campo card.wallet_transaction_id. Saiba mais sobre os parâmetros de requisição no Pagamento REST..
2. O e-SiTef inicia o pagamento com a autorizadora VEE, repassando o token da transação.
3. A VEE abre a carteira digital no aplicativo do comprador.
4. O comprador escolhe a forma de pagamento em sua carteira digital e confirma a compra pelo aplicativo da VEE.
5. A autorizadora responde ao e-SiTef, aprovando ou negando a transação.
6. O e-SiTef repassa a resposta da autorizadora para o lojista.

Fluxo sem demora na resposta do comprador

Atenção:

Caso o comprador demore para escolher o meio de pagamento, a resposta da transação devolverá o status pendente (PEN) e o e-SiTef iniciará ciclos de consultas (ou sonda) a cada 30 segundos aproximadamente até que o status da transação seja resolvido.

Durante estes ciclos, o lojista deve consultar o status da transação no e-SiTef por meio da consulta de transações.

Se o status da transação permanecer pendente (PEN) após aproximadamente 3 (três) minutos, o e-SiTef irá desfazer a transação junto a autorizadora VEE.

Fluxo com demora na resposta do comprador e status resolvido antes do limite de tempo

Fluxo com demora na resposta do comprador e limite de tempo atingido

Pix via CardSE

Esta documentação descreve a integração com PIX através do e-SiTef, utilizando o roteamento CardSE via SiTef.

Informações cadastrais

Além das informações usuais para cadastro no e-SiTef, para integração com Pix será necessário mais um dado:

Campo	Descrição	Formato	Obrigatório
psp	Prestador de serviços de pagamento. Se não for enviado, será utilizado o valor cadastrado no SiTef.	< 8 N	NÃO

Pagamento REST

Fluxo

1. O lojista cria a transação no e-SiTef passando algumas informações adicionais do Pix e recebe o NIT como resposta.
2. A loja chama o serviço de efetivação de pagamento e recebe um QR code e a transação com status PEN (pendente).
3. A loja virtual exibe o QR code para o comprador.
4. O comprador escaneia o QR code com o aplicativo Pix e passa pelo procedimento de confirmação do pagamento solicitado pelo autorizador.
5. Enquanto o comprador finaliza o pagamento, o e-SiTef sondará a situação da compra no autorizador até que a transação se encerre.
6. A loja, por sua vez, deve consultar o status da transação do e-SiTef até que ela saia do status PEN.

Atenção:

Se o status da transação permanecer pendente (PEN) após aproximadamente 3 (três) minutos, o e-SiTef irá desfazer a transação junto ao Pix.

Informações adicionais na criação da transação

Para transações com Pix, deve ser utilizado authorizer_id = 440.

Abaixo estão parâmetros adicionais que podem ser enviados em transações Pix:

Parâmetro	Descrição	Formato	Obrigatório
additional_data
pix_psp	Prestador de serviços de pagamento. Se não for enviado, será utilizado o valor cadastrado no e-SiTef.	< 8 AN	NÃO
pix_question	Pergunta do lojista para o comprador (será exibida no aplicativo).	< 140 AN	NÃO
additional_data.pix_data[]	Lista de conteúdo livre. Permite enviar dados ao aplicativo do cliente como lista de serviços adquiridos, informações promocionais ou outros dados desejados.
key	Identificação do campo.	< 50 AN	NÃO
value	Valor do campo.	< 200 AN	NÃO
additional_data.items[]
ean	Código EAN do produto. Atenção: caso o EAN e o SKU sejam enviados simultaneamente, apenas o EAN será considerado.	< 255 AN	NÃO
sku	Código SKU do produto. Atenção: caso o EAN e o SKU sejam enviados simultaneamente, apenas o EAN será considerado.	< 255 AN	NÃO
description	Descrição do produto.	< 255 AN	NÃO
quantity	Quantidade do produto a ser adquirido.	< 15 N	NÃO
quantity_type	Tipo da quantidade: u - Unidades g - Gramas ml - Mililitros	< 2 AN	NÃO
unit_price	Preço unitário do produto em centavos.	< 12 N	NÃO

Exemplo:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"12042142155",
   "order_id":"12042142155",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"440",
   "amount":"1000",
   "additional_data":{
      "pix_psp":"12345678",
      "pix_question":"Deseja receber 10% de desconto para sua proxima compra?",
      "pix_data":[
         {
            "key":"Pontos Ganhos",
            "value":"23"
         },
         {
            "key":"NumPromo",
            "value":"234523452345"
         }
      ],
      "items":[
         {
            "description":"ItemTeste",
            "quantity":"1",
            "sku":"1487337308522",
            "unit_price":"1000",
            "quantity_type":"u"
         },
         {
            "description":"ItemTeste2",
            "quantity":"3",
            "ean":"9283746529384675",
            "unit_price":"2500",
            "quantity_type":"g"
         }
      ]
   }
}
--verbose

Requisição da efetivação do pagamento

Na integração com Pix, não será necessário o envio de nenhum dado do cartão.

Exemplo:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{}
--verbose

Retornos na efetivação do pagamento com tamanho diferente do padrão

Parâmetro	Descrição	Formato
authorization_number	Número de autorização.	< 100 AN

Retornos adicionais na efetivação do pagamento

Parâmetro	Descrição	Formato
payment
pix_psp	Prestador de serviços de pagamento.	< 8 AN
pix_answer	Resposta ao pix_question.	< 140 AN
qr_code	QR code a ser exibido ao comprador.	< 9999 AN

Atenção:

Em caso de erro de comunicação nesta operação, será necessário criar outra transação.

Exemplo:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"PEN",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13034649671",
      "authorizer_id":"2",
      "acquirer_id":"1271",
      "acquirer_name":"CardSE",
      "authorizer_date":"13/07/2017T15:52",
      "authorization_number":"132030",
      "merchant_usn":"13034649671",
      "esitef_usn":"170713097340300",
      "sitef_usn":"132030",
      "host_usn":"000000000",
      "payment_date":"13/07/2017T15:52",
      "amount":"1000",
      "authorizer_merchant_id":"000000000000005",
      "pix_psp":"12345678",
      "pix_answer":"No",
      "qr_code":"The quick brown fox jumps over the lazy dog"
   }
}

Pagamento HTML

Não há diferenças no fluxo para a loja.

Assim como no Pagamento REST, podem ser enviados parâmetros adicionais na criação da transação, usando o mesmo formato.

Cancelamento REST

Requisição da efetivação do cancelamento

Na integração com Pix, não será necessário o envio de nenhum dado do cartão.

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
{
   "amount":"1000"
}
--verbose

Retornos adicionais na efetivação do cancelamento

Parâmetro	Descrição	Formato
cancellation
pix_psp	Prestador de serviços de pagamento.	< 8 AN

Exemplo:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":" 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"09062259711",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"2",
      "acquirer_id":"1271",
      "acquirer_name":"CardSE",
      "authorizer_date":"09/11/2017T18:23",
      "authorization_number":"092423",
      "merchant_usn":"9062259711",
      "esitef_usn":"171109108051261",
      "sitef_usn":"092424",
      "host_usn":"999092424   ",
      "amount":"1000",
      "payment_type":"O",
      "authorizer_merchant_id":"000000000000000",
      "esitef_date":"09/11/2017T18:23",
      "pix_psp":"12345678"
   }
}

Geração de link de pagamento no Portal do Lojista

Também é possível fazer pagamentos com Pix através de funcionalidade de link de pagamento do Portal Lojista. No entanto, ainda não está disponível a possibilidade do envio das informações adicionais do Pix.

Cadastro de chaves Pix no Portal do Lojista

Ao acessar a configuração de uma autorizadora Pix, será exibido um botão para cadastrar suas chaves Pix:

Ao clicar no botão "Cadastrar Chaves", será exigido o código de autenticação em duas etapas para prosseguir com a operação. Caso esse método de autenticação não esteja habilitado, será exibida na tela instruções sobre qual procedimento deve ser tomado para continuar.

Para mais informações sobre a autenticação em duas etapas e como habilitá-la para realizar cadastro de chaves PIX, clique aqui.

Concluída a autenticação anterior, o usuário será redirecionado para uma tela contendo informações da loja e uma listagem de PSPs:

Selecione o PSP (prestador de serviços de pagamento) que deseja utilizar e clique em "Adicionar":

Preencha a sua chave Pix e suas informações de credencial e clique em "Salvar". Após submeter os seus dados, caso deseje alterar suas informações, clique em "Editar". Se quiser apagá-las, clique em "Remover":

Após realizar todas as alterações desejadas, clique em "Salvar".

Google Pay™

Google Pay permite que os seus clientes armazenem formas de pagamento na própria conta Google para fazer compras mais rápidas e com segurança.

Como Funciona

Quando o comprador clica no botão de pagamento do Google Pay, são exibidas as formas de pagamentos salvas na conta do Google dele. O comprador pode selecionar rapidamente a forma de pagamento desejada e opcionalmente preencher informações adicionais da compra. Após esta interação com a Google Pay, estes mesmos dados serão enviados/processados pelo e-SiTef para efetuar o fluxo de pagamento.

O Google Pay é suportado pelo e-SiTef, no entanto, não é suportado por todos os adquirentes e não está ativado por padrão na sua conta. Entre em contato com um membro de nossa equipe de suporte para obter mais informações.

Atenção: Ao utilizar o Google Pay pelo e-SiTef, o lojista deve estar ciente e aderente à Política de Utilização Aceitável e o mesmo aceita os Termos de Serviço da API Google Pay.

---

Pagamento REST

Integre-se ao Google Pay

Para começar a processar pagamentos com o Google Pay, você precisa se integrar ao Google via Web ou Android. Durante a integração, você verá que alguns parâmetros são necessários para processar o Google Pay através do e-SiTef:

• O parâmetro gatewayMerchantId deve ser preenchido com o merchant_id da loja no e-SiTef;
• O parâmetro gateway deve ser preenchido com softwareexpress;

Este é um exemplo da integração via web, em que é necessário configurar com os dados do e-SiTef:

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    'gateway': 'softwareexpress',
    'gatewayMerchantId': '<ESITEF_MERCHANT_ID>'
  }
};

Este é um trecho de exemplo da integração via Android, em que é necessário configurar com os dados do e-SiTef:

.setPaymentMethodTokenizationType(WalletConstants.PAYMENT_METHOD_TOKENIZATION_TYPE_PAYMENT_GATEWAY)
.addParameter("gateway", "softwareexpress")
.addParameter("gatewayMerchantId", "<ESITEF_MERCHANT_ID>")

Além disso, a loja precisa seguir as diretrizes de layout do Google Pay. Consulte a documentação do Google Pay para as diretrizes da marca.

As seguintes redes de cartões disponíveis no Google Pay são suportadas pelo e-SiTef: VISA, ELECTRON, MASTERCARD, MAESTRO, ELO, ELO_DEBIT, AMEX, DISCOVER e JCB. Os seguintes meios de autorização disponíveis no Google Pay são suportados pelo e-SiTef: PAN_ONLY e 3DS_CRYPTOGRAM. Entre em contato com nossa equipe de suporte para ativar as configurações adequadas para a sua loja.

As telas abaixo demonstram um fluxo de compra na Web recomendado pela Google Pay.

As telas abaixo demonstram um fluxo de compra no Android recomendado pela Google Pay.

Envie os dados para o e-SiTef

Ao concluir a integração com o Google, você terá todas as informações necessárias para realizar um pagamento com o e-SiTef.

O Google responderá com a resposta PaymentData, que inclui a carga criptografada (token). Da resposta do Google contendo as informações do cliente, extraia o token do Google Pay, seguindo as referências da API. Atualmente o token pode ser extraido de paymentData.paymentMethodData.tokenizationData.token. Utilize este token na requisição de efetivação de pagamento no campo card.wallet_transaction_id. Adicionalmente será necessário repassar o campo paymentData.paymentMethodData.info.cardNetwork para o campo wallet_returned_card_brand. Abaixo segue um exemplo desta requisição:

O conteúdo do paymentData.paymentMethodData.tokenizationData.token equivale a uma JSON, mas não há necessidade de tratar este conteúdo. Repasse o valor obtido sem realizar qualquer tratamento para o campo card.wallet_transaction_id.

curl -X POST \
  https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/<NIT> \
  --header "Content-Type: application/json" \
  --header "merchant_id: <MERCHANT_ID>" \
  --header "merchant_key: <MERCHANT_KEY>" \
  --data-binary '{
    "authorizer_id": "405",
    "card": {
        "wallet_transaction_id": "{\"signatures\":\"MEUCIH1PBdMmbWMvaR/ArH08R/OT41Or2yfLqbzj2JG9VGfJAiEA+6NPKT6sAKZeaLacm29wIS8v2tUwPE281JuRBf81imo\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEm1j1auejJXFzexs/H3TasImWFERsifrx93W7wxZb0dpLxk/FaK8hQN6Ypwep8DaYrEKSp6zvxeE4ezDrssf/Bg\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1576347458323\\\"}\",\"signatures\":[\"MEYCIQCbAolg3/K2yD0/p3K7gRFhXva79STrj+rZcYp/3vi6ogIhANGT/9GkO9S1lJtnu3C6QQ/kFSR2wxtPJRGfuqSKs9FE\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"Dcm8wxtB6Bp7CyHV1OBqTskStqX3K5x7I0fV/2V0KsMLkZHP5nn+IXC+HBLkZtPF0Ov6uBD1eLbOB2KQd1cVmBPm7f4xSsB4DaYTktfk2AaLpR0BZlb9errv4jl4QAxSLdxw8Hk3EKicSmvsUNE2SzFBOONPrvv1qe03ZnzB3Q0ID1ocsBJ09PQ/2jft0WY/Py6iAA4sccZKmxLdo83NJJc1VrfcGLcqwy5InUV4nSxmXrnr/eNQDIx9p4Yf3RSVlS6/t+bEpUjpUSwSNoHwzhlWOve3/Gm+yt+OKheXOWSsXiHJL1rV1ENgDroR2uMUb85OZCF1ulStb6U8xocRVKSKkhAxFVUehz568huQdlEjns+5MMWdZkNgH3cXMgTQxZ6DiUYxMthUhdT8HINXCUYxaT/od/Njh2JZHJb2R4u4HsfViUoIVRHojSaepXP3KI2z4G9hPwKX/MWeEMyiZRUiCHHe0VJoU/8xxg\\\\u003d\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BG0eCJ8xbPN55ht7b3oDZgFgwG4rZxkRWrOFnmW9wwxUrZS0A6oeMAySLKThMydaGuoTbbiAwK38zx8pnNKgirA\\\\u003d\\\",\\\"tag\\\":\\\"uPvitOn+aGk48RlrwzYSKgDicO5oYtmMEWXzj5rUewo\\\\u003d\\\"}\"}",
      "wallet_returned_card_brand" : "MASTER"
    },
}' 

No exemplo acima, foi definido no campo authorizer_id com o valor 405, que corresponde selecionar a Google Pay como forma de pagamento; e foi definido no campo wallet_transaction_id com o valor do token da Google Pay . Uma execução bem-sucedida do comando acima retornará um JSON semelhante à abaixo.

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"<NIT>",
      "order_id":"13034649671",
      "customer_receipt":"====CUPOM COMPRADOR====",
      "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
      "authorizer_id":"405",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"28/02/2020T08:57",
      "authorization_number":"132030",
      "merchant_usn":"13034649671",
      "esitef_usn":"170713097340300",
      "sitef_usn":"132030",
      "host_usn":"999132030",
      "payment_date":"13/07/2017T15:52",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"<MERCHANT_ID>"
   }
}

Para maiores detalhes, veja a documentação do fluxo de pagamento do e-SiTef.

---

Armazenamento REST

É possível realizar o armazenamento de cartão, sendo que existem algumas exceções de casos, dependendo de como o token da Google Pay foi gerada. Entre em contato com a nossa equipe de suporte para realizar as configurações necessárias para possibilitar este armazenamento.

O armazenamento de cartão REST funciona como se fosse armazenar um cartão qualquer, porém com os seguintes cuidados:

• Ao invés de enviar os número do cartão, envie o campo wallet_transaction_id.
• O envio do campo authorizer_id deve ser '405' (Google Pay).

Para maiores detalhes, veja aqui.

Pagamento HTML

Para utilizar o Google Pay com o pagamento HTML, entre em contato com um membro de nossa equipe de suporte para realizar a configuração necessária. É possível determinar quais bandeiras serão aceitas no Google Pay na integração HTML.

Visa Checkout

O e-SiTef possui a carteira digital Visa Checkout como funcionalidade para integração da aplicação da loja.

Esta permite ao lojista não ter contato direto com a coleta de dados de cartão e dados pessoais do usuário, utilizando a interface e estrutura de comunicação desenvolvida pela VISA para pagamentos utilizando essa tecnologia.

Roteamentos suportados

Atualmente, a integração Visa Checkout via Web Services é suportado para pagamentos roteados via SiTef, Cielo e-Commerce e Stone WS.

Interfaces e-SiTef suportadas

As interfaces suportadas no e-SiTef para o uso do Visa Checkout são:

• Pagamento REST
• Cancelamento REST
• Pré-Autorização REST

Configurações necessárias no e-SiTef

Para que uma loja utilize a carteira digital Visa Checkout no e-SiTef, basta solicitar à equipe de suporte / atendimento do e-SiTef para que esta configuração seja feita.

Requisito para integração REST

A aplicação da loja precisa cumprir com o requisito de estar integrado com o Visa Checkout em sua interface gráfica e na comunicação JavaScript dos call-backs, a fim de obter o parâmetro callid. Este é necessário para a integração com a interface de pagamento REST do e-SiTef. Para mais detalhes sobre esta integração, o lojista deve solicitar à VISA o guia de integração e desenvolver a integração com o Visa Checkout Button e o LightBox.

Fluxo de pagamento REST

O fluxo de pagamento para utilizar o e-SiTef com Visa Checkout via Web Services pressupõe que a aplicação da loja já esteja cumprindo os requisitos apresentados no item anterior, isto é, que a aplicação já seja capaz de utilizar as Web Services do e-SiTef com o callid em mãos.

A figura seguinte apresenta o diagrama de fluxos para a integração com o e-SiTef com Visa Checkout via Web Services (REST):

Para pagar transações Visa Checkout via WS, a aplicação do lojista deve enviar o wallet_transaction_id ao invés do número do cartão (number) no objeto card. Opcionalmente, também pode-se enviar o initial_wallet_transaction_id, que informa se é a primeira vez que este wallet_transaction_id está sendo utilizado. Caso não seja definido, considera-se que o valor de initial_wallet_transaction_id é true. Abaixo segue um exemplo com a aplicação curl onde a adquirente solicita o envio do código de segurança para o pagamento:

curl 
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/xxxxxxxxxxxx...xxxxxxxxxxxxx"
--header "Content-Type: application/json"
--header "merchant_id:wwwwwww"
--header "merchant_key:yyyyyyyyyyyyyyyyyyyyyy"
--data-binary
{
   "card":{
      "wallet_transaction_id":"callid_de_teste",
      "initial_wallet_transaction_id":"false",
      "security_code":"123"
   }
}
--verbose

Saiba mais.

Fluxo de Pré Autorização REST

Assim como no pagamento REST, a interface de pré-autorização também pode receber os campos wallet_transaction_id e initial_wallet_transaction_id.

Em caso de pagamentos com valores promocionais pelo uso do Visa Checkout, a VISA sugere que os campos subtotal, discount e promo_code sejam enviados adicionalmente tanto no serviço de efetivição de pré-autorização, quanto no serviço de captura de pré-autorização. Saiba mais.

O envio destes campos não é obrigatório, porém é fortemente recomendado pela VISA para enriquecimento de dados estatísticos de uso do Visa Checkout e melhoria dos serviços relacionados. Estes campos são enviados aos sistemas do Visa Checkout juntamente com informações sobre valor total, moeda e código de pedido (orderId). Para tornar mais claro o uso desses campos, segue um exemplo: supondo uma transação de um produto cujo valor seja R$ 80,00, com um desconto de 10% (R$ 8,00) e resultando num valor líquido de R$ 72,00, os campos devem ser preenchidos conforme a fórmula:

amount: R$ 72,00
subtotal: R$ 80,00
discount: R$ 8,00
amount = subtotal - discount = R$ 80,00 - R$ 8,00 = R$ 72,00

Fluxo de Cancelamento / Estorno REST

Para cancelar ou estornar transações Visa Checkout via WS, a aplicação do lojista deve enviar o wallet_transaction_id ao invés do número do cartão (number) no objeto card. Abaixo segue um exemplo com a aplicação curl onde a adquirente solicita o envio do código de segurança para o estorno:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations/xxxxxxxxxxxx...xxxxxxxxxxxxx"
--header "Content-Type:application/json"
--header "merchant_id:wwwwwww"
--header "merchant_key:yyyyyyyyyyyyyyyyyyyyyy"
--data-binary
{
   "card":{
      "security_code":"zzz",
      "wallet_transaction_id":"callid_de_teste",
   },
   "amount":"1000"
}
--verbose

Saiba mais.

Masterpass

O e-SiTef permite a integração do e-commerce do lojista com pagamentos que fazem autenticação através da carteira digital Masterpass. O comprador faz seu pagamento online sem inserir dados de seu cartão, utilizando apenas dados de usuário (e-mail ou celular) e senha. Para isso, o comprador precisa apenas abrir antes uma conta com a Masterpass e cadastrar suas informações de cartões de crédito e/ou débito.

É importante lembrar que o Masterpass não é um meio de pagamento, ou seja, não processa as transações. Trata-se de uma carteira digital que efetua a autenticação do comprador e fornece os dados para realização do pagamento para o comércio ou para os parceiros de processamento como o e-SiTef.

Interfaces e-SiTef suportadas para integração

As seguintes interfaces do e-SiTef podem ser utilizadas para a integração com Masterpass:

• Interface de Pagamento HTML 2.0 Saiba mais
• Interface Web Service de Cancelamento Saiba mais
• Cancelamentos via Portal do Lojista Saiba mais

Código de Autorizadora no e-SiTef para Masterpass

A cateira digital Masterpass é identificada pelo código (id) de autorizadora abaixo:

"authorizer_id": "407"

Configurações necessárias

Antes de efetuar transações Masterpass com o e-SiTef, devem ser seguidos os passos de configuração apresentados a seguir.

Criação do cadastro da loja no Portal Masterpass

A loja deve entrar em contato com a Software Express e solicitar o seu cadastro na Masterpass para a equipe de Suporte e-SiTef ou equipe Produção e-SiTef que efetuarão este serviço.

Configurações necessárias no e-SiTef

Com a conta criada na Masterpass, os seguintes parâmetros de autorizadora devem ser cadastrados no e-SiTef:

Nome do campo no e-SiTef	Descrição do campo	Obrigatório
merchantCheckoutId	Identificador único de checkout obtido durante o processo de cadastro da loja na Masterpass.	SIM
bandeirasPermitidas	Indica quais bandeiras serão apresentadas na carteira (wallet) do cliente no ambiente da Masterpass. Valores permitidos: - amex (American Express) - diners - discover - maestro - master (mastercard) - visa Os valores devem ser escritos como nos exemplos separados por vírgula (,). Exemplo permitindo master e visa: visa,master Exemplo permitindo visa, diner e discover: visa,diners,discover	SIM

Estes parâmetros devem ser informados à equipe de cadastro do e-SiTef.

Bandeiras permitidas

De acordo com a documentação (versão 1 – com última atualização no dia: 01 de fevereiro de 2017), as bandeiras permitidas atualmente pela Masterpass são:

• Mastercard
• Visa
• American Express
• Discover
• Maestro
• Diners

Porém, mudanças podem ocorrer, e, por isso, para uma informação mais atualizada sugerimos fortemente que a loja entre em contato com a Masterpass e confirme essas informações.

Fluxo de Pagamento Masterpass

O fluxo básico de pagamento utilizando a carteira digital Masterpass inicia-se conforme apresentado na integração de pagamentos HTML do e-SiTef.

Na figura abaixo se apresenta o fluxo de um pagamento com autenticação Masterpass:

Aviso de Status

Para cada alteração de status de transação no e-SiTef, resultante de comunicação entre o e-SiTef e a Masterpass, é enviado ao servidor da loja um Aviso de Status. Saiba mais

Propriedades para uma transação de pagamento com a carteira digital Masterpass

As propriedades usadas para se criar uma transação de pagamento com a carteira digital Masterpass são os mesmos que os apresentados no Pagamento HTML, Pré-Autorização HTML e Recarga HTML.

Estorno de pagamentos Masterpass

Os pagamentos feitos no e-SiTef com a carteira digital Masterpass podem ser estornados utilizando a Cancelamento REST ou pelo Portal do Lojista.

Note que é necessário ter o número do cartão em mãos para que o estorno seja possível. Para isso, é preciso armazenar o cartão e efetuar o cancelamento utilizando o token/hash do cartão (Saiba mais) OU entrar em contato direto com o portador do cartão para obter o número.

Samsung Pay

Como Funciona

Quando o comprador clica no botão de pagamento do Samsung Pay, são exibidas as formas de pagamentos salvas na conta do Samsung Pay. O comprador pode selecionar rapidamente a forma de pagamento desejada e opcionalmente preencher informações adicionais da compra. Após esta interação com a Samsung Pay, estes mesmos dados serão enviados/processados pelo e-SiTef para efetuar o fluxo de pagamento.

Para mais informações sobre o fluxo de pagamento com wallets, consulte a página de Visão Geral

---

Dados cadastrais necessários

Em casos de integração via API REST, será necessário que o lojista utilize o Service ID da Software Express junto a Samsung. Para obter o Service ID de ambiente de homologação/produção entre em contato com nossa equipe de suporte.

Bandeiras suportadas

As seguintes redes de cartões disponíveis na Samsung Pay (Brasil) são suportadas pelo e-SiTef:

Sigla na Samsung Pay	Bandeira
VI	Visa
MC	MasterCard

Pagamento/Pré-Autorização REST

Na modalidade de Pagamento ou Pré-Autorização o lojista deve realizar a primeira parte da integração com a Samsung Pay (todas as etapas de integração até a obtenção do Reference ID). por favor, entre em contato com o suporta da Samsung para mais detalhes.

O Reference ID deve então ser repassado para as nossas interfaces REST.

Envie os dados para o e-SiTef

Ao concluir a a primeira parte da integração com Samsung Pay, você terá em mãos o Reference ID.

Esse dado deve ser repassado pelo campo card.wallet_transaction_id da interface.

curl -X POST \
  https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/<NIT> \
  --header "Content-Type: application/json" \
  --header "merchant_id: <MERCHANT_ID>" \
  --header "merchant_key: <MERCHANT_KEY>" \
  --data-binary '{
    "authorizer_id": "410",
    "card": {
        "wallet_transaction_id": "exemploReferenceId"
    }
}' 

No exemplo acima, foi definido no campo authorizer_id com o valor 410, que corresponde selecionar a Samsung Pay como forma de pagamento; e foi definido no campo wallet_transaction_id com o valor do Reference ID da Samsung Pay . Uma execução bem-sucedida do comando acima retornará um JSON semelhante à abaixo.

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"<NIT>",
      "order_id":"13034649671",
      "customer_receipt":"====CUPOM COMPRADOR====",
      "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
      "authorizer_id":"410",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"28/02/2020T08:57",
      "authorization_number":"132030",
      "merchant_usn":"13034649671",
      "esitef_usn":"170713097340300",
      "sitef_usn":"132030",
      "host_usn":"999132030",
      "payment_date":"13/07/2017T15:52",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"<MERCHANT_ID>"
   }
}

Pagamento/Pré-Autorização HTML

Para utilizar o Samsung Pay com o pagamento/pré-autorização HTML, entre em contato com um membro de nossa equipe de suporte para realizar a configuração necessária. É possível determinar quais bandeiras serão aceitas no Samsung Pay para a integração HTML.

Captura de Pré-Autorização REST e Cancelamento REST/via Portal

O Samsung Pay não permite que um mesmo Reference ID seja utilizado mais de uma vez. Por conta disso operações de duas etapas como Pagamento/Cancelamento, Pré-Autorização/Captura exigem que o cartão do pagador seja armazenado no e-SiTef. O armazenamento pala interface HTML pode ser realizado junto com o pagamento/pre-autorização seguindo a documentação de Pagamento com armazenamento de cartão ou pela interface REST, como descrito no capítulo abaixo.

Armazenamento REST

É possível realizar o armazenamento de cartão utilizando o Reference ID da Samsung Pay. Entre em contato com a nossa equipe de suporte para realizar as configurações necessárias para possibilitar este armazenamento.

O armazenamento de cartão REST funciona como se fosse armazenar um cartão qualquer, porém com os seguintes cuidados:

• Ao invés de enviar os número do cartão, envie o campo wallet_transaction_id com o conteúdo do Reference ID.
• O envio do campo authorizer_id deve ser '410' (Samsung Pay).

Para maiores detalhes, veja aqui.

Apple Pay

O Apple Pay agora está disponível!

Vantagens

• Aumente as taxas de conversão com o Apple Pay.
• Expanda seus negócios facilitando o pagamento com Apple Pay e com o provedor de serviços de pagamento.
• Aumente as vendas oferecendo uma experiência de pagamento rápida, simples e segura com o Apple Pay.
• Melhore a privacidade e a segurança: Cada transação requer autenticação com reconhecimento facial (Face ID), impressão digital (Touch ID) ou senha.

O Apple Pay aumenta as taxas de conversão e adoção do usuário, tornando a compra mais fácil do que nunca. É uma maneira simples e segura de compradores on-line para agilizar a finalização da compra e para os negócios on-line aumentarem as vendas. É uma vitória para os compradores e para as empresas.

---

Introdução

O Apple Pay é uma carteira digital disponível somente para os dispositivos iOS que contam o Secure Element - um chip que armazena as informações de pagamento de forma segura. A lista dos dispositivos compatíveis encontra-se aqui.

A Apple Pay oferece 2 APIs JavaScript para integração na web - a Apple Pay JS API e o Payment Request API. Para integração com o e-SiTef, foi escolhida a Apple Pay JS API. Ambas APIs estão nativamente disponíveis no navegador Safari.

Como Funciona

Como mencionado anteriormente, devido a sua disponibilidade em dispositivos compatíveis, o botão de pagamento via Apple Pay será exibido somente nos mesmos. Uma vez que o comprador está na tela de pagamento com a forma de pagamento Apple Pay disponível, bastará clicar no botão da mesma para selecionar o cartão desejado para o pagamento. Nos momentos em que o comprador clica no botão da Apple Pay, seleciona o cartão e confirma a transação, ocorrem interações entre o e-SiTef e o Apple Pay, para criação da transação de pagamento e da confirmação do pagamento. Após a última interaçao com a Apple Pay, a transação é processada no e-SiTef para confirmação do pagamento.

Para mais informações sobre o fluxo de pagamento com wallets, consulte a página de Visão Geral

Dados cadastrais necessários

É necessário que o lojista cadastre seu Merchant ID no sistema da Apple. Esse cadastro funciona como a identificação da loja na Apple para o e-SiTef. Também é necessário associar esse registro ao certificado do e-SiTef e a um domínio, que seria o endereço da página de pagamento (onde é disponibilizado o botão de pagamento da Apple Pay). Para este 2º passo, entre em contato com nossa equipe de suporte.

Bandeiras suportadas

As seguintes redes de cartões disponíveis na Apple Pay (Brasil) são suportadas pelo e-SiTef: Visa e MasterCard.

Integre-se com a Apple Pay

Para começar a processar pagamentos com o Apple Pay, você precisa se integrar a Apple via Web. Durante a integração, você verá que alguns parâmetros são necessários para processar o Apple Pay através do e-SiTef:

• O parâmetro merchantIdentifier deve ser preenchido com o Merchant ID da loja no e-SiTef. Basta ter cadastrado o mesmo no portal da Apple Pay e na configuração da loja no e-SiTef que o mesmo será automaticamente preenchido e enviado na requisição para a Apple Pay;
• O parâmetro domainName deve ser preenchido com o domínio do site da loja. Basta ter o mesmo cadastrado no portal da Apple Pay, associado com o Merchant ID, que o mesmo será validado corretamente com a Apple Pay.

Esses parâmetros são utilizados na primeira requisição para a Apple Pay (quando o botão da Apple Pay é clicado), chamada "startSession", que tem como função criar a sessão de pagamento, identificando qual é a loja de onde vem a requisição. Os dados informados são validados no servidor da Apple e retornam erro quando os dados informados na requisição não correspondem aos dados cadastrados na Apple.

Segue exemplo de requisição para o startSession:

 curl --location --request POST 'https://apple-pay-gateway-cert.apple.com/paymentservices/startSession' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchantIdentifier": "merchant.br.com.softwareexpress.teste.e-SiTef",
    "domainName": "esitef-homologacao.softwareexpress.com.br",
    "displayName": "Teste Apple Pay para eSiTef"
}'

A API Apple Pay JS coordena todas as chamadas necessárias para a Apple Pay completar a transação. Após o startSession, o response deste último é repassado para o completeMerchantValidation. Neste momento, a janela de pagamento da Apple Pay validou com sucesso as credenciais da loja e está aguardando a confirmação do pagamento por parte do usuário. Quando o usuário confirma o pagamento, através de senha ou impressão digital, a função onpaymentauthorized é acionada, com a informação do pagamento criptografada dentro do objeto event.

// funcao que integra as operacoes da Apple Pay com as chamadas back-end
var _handleApplePayEvents = function (appleSession) {
    
    // validacao da identificacao da loja
    // primeira funcao chamada ao clicar no botao da Apple Pay
    appleSession.onvalidatemerchant = function (event) {
        // chamada para o startSession e, em seguida, o response é enviado ao completeMerchantValidation
        _validateApplePaySession(event.validationURL, function (merchantSession) {
            appleSession.completeMerchantValidation(merchantSession)
        })
    }

    // Funcao chamada quando o usuario confirma o pagamento pela Apple Pay
    appleSession.onpaymentauthorized = function (event) {
        // Chamada ao back-end do e-SiTef para concluir o pagamento.
        // Deve ser enviado ao back-end o conteúdo do objeto 'event.token'
        // para descriptografia e 
        // validação dos dados de pagamento para autorização.

        // ...
        // em caso de sucesso no processamento do pagamento
        // ...
        appleSession.completePayment(ApplePaySession.STATUS_SUCCESS)

        // em caso de fracasso no processamento do pagamento
        // ...
        appleSession.completePayment(ApplePaySession.STATUS_FAILURE)
        // ...
    }
}

Pagamento/Pré-Autorização REST

Na modalidade de Pagamento ou Pré-Autorização REST o lojista deve realizar a primeira parte da integração com a Apple Pay (todas as etapas descritas na seção anterior para obter o token). Para mais detalhes a respeito deste processo de obtenção do token, recomenda-se entrar em contato com o suporte da Apple Pay.

O token obtido deve então ser repassado para as nossas interfaces REST.

Envie os dados para o e-SiTef

Ao concluir a primeira parte da integração com a Apple Pay, você terá em mãos o token.

Esse dado deve ser repassado pelo campo card.wallet_transaction_id da interface.

curl -X POST \
  https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/<NIT> \
  --header "Content-Type: application/json" \
  --header "merchant_id: <MERCHANT_ID>" \
  --header "merchant_key: <MERCHANT_KEY>" \
  --data-binary '{
    "authorizer_id": "421",
    "card": {
        "wallet_transaction_id": "some token from Apple Pay"
    }
}' 

No exemplo acima, foi definido no campo authorizer_id com o valor 421, que corresponde selecionar a Apple Pay como forma de pagamento e foi definido no campo wallet_transaction_id com o valor do token da Apple Pay. Uma execução bem-sucedida do comando acima retornará um JSON semelhante à abaixo.

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"<NIT>",
      "order_id":"13034649899",
      "customer_receipt":"====CUPOM COMPRADOR====",
      "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
      "authorizer_id":"421",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"12/03/2021T14:33",
      "authorization_number":"132030",
      "merchant_usn":"13034649671",
      "esitef_usn":"170713097340300",
      "sitef_usn":"132030",
      "host_usn":"999132030",
      "payment_date":"12/03/2021T15:52",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"<MERCHANT_ID>"
   }
}

Pagamento/Pré-Autorização HTML

Para utilizar a Apple Pay com o pagamento/pré-autorização HTML, entre em contato com um membro de nossa equipe de suporte para realizar a configuração necessária. É possível determinar quais bandeiras serão aceitas no Apple Pay para a integração HTML.

Captura de Pré-Autorização REST e Cancelamento REST/via Portal

O Apple Pay não permite que um mesmo token seja utilizado mais de uma vez. Por conta disso, operações de duas etapas como Pagamento/Cancelamento, Pré-Autorização/Captura exigem que o cartão do pagador seja armazenado no e-SiTef. O armazenamento pela interface HTML pode ser realizado junto com o pagamento/pre-autorização, seguindo a documentação de Pagamento com armazenamento de cartão ou pela interface REST, como descrito na seção a seguir.

Armazenamento REST

É possível realizar o armazenamento de cartão utilizando o token da Apple Pay. Entre em contato com a nossa equipe de suporte para realizar as configurações necessárias para possibilitar este armazenamento.

O armazenamento de cartão REST funciona como se fosse armazenar um cartão qualquer, porém com os seguintes cuidados:

• Ao invés de enviar os número do cartão, envie o campo wallet_transaction_id com o conteúdo do token.
• O envio do campo authorizer_id deve ser '421' (Apple Pay).

Para maiores detalhes, veja aqui.

Gerenciamento de chaves do lojista

Para o correto processamento de uma transação pela ApplePay, é necessário haver um cadastro de chaves pública no Apple Server. As chaves públicas e privadas providas pelo Apple Server servirão de base para o decript do payload enviado pela biblioteca Apple JS. Este é o primeiro passo para a configuração de um Merchant para receber pagamentos ApplePay.

Neste guia é possível ver mais detalhes do cadastro de chaves no Apple Server.

Após o registro das chaves é necessário entrar em contato com o nosso suporte e informá-las, para que as mesmas sejam configuradas no cadastro da Loja. A Apple requer que seja possível o registro de dois pares de chaves. Cada chave tem um período de validade e ficará a cargo do logista o gerenciamento da validade e o informe das novas chaves ao suporte da Software Express.

Configurações para Carteiras Digitais

Nesta página serão apresentadas as possíveis configurações das carteiras digitais suportadas pelo e-SiTef (Ex.: Google Pay, Masterpass, Visa Checkout).

Os exemplo abaixo utilizam Google Pay, porém as configurações podem ser aplicadas para qualquer outra carteira.

Configuração de Roteamento/Adquirente

Roteamento/Adquirente único

Ao configurar uma carteira digital no e-SiTef é necessário selecionar o roteamento/adquirente que será responsável pelo processamento das transações realizadas pela carteira escolhida, como no exemplo abaixo:

Para mais informações sobre configuração de Autorizadoras/Roteamentos, acesse a página de Configuração de Autorizadoras no Portal do Loijista.

Na configuração ilustrada acima qualquer transação realizadas utilizando Google Pay, independente da bandeira do cartão, será roteada/capturada pela adquirente Cielo.

Roteamentos/Adquirentes múltiplos

Caso seja necessário, é possível configurar o roteamento/adquirente que irá processar a transação de acordo com a bandeira do cartão selecionado dentro da carteira digital:

Para mais informações sobre configuração de Adquirentes/Roteamentos, acesse a página de Configuração de Autorizadoras no Portal do Loijista.

Na configuração ilustrada acima as transações realizadas utilizando Google Pay com cartão de bandeira Mastercard serão processadas pela adquirente Rede (antiga Redecard).

As demais bandeiras (Visa, Maestro, etc.) serão processadas pela adquirente padrão configurada para a Google Pay, que neste exemplo será a Cielo.

Essa configuração pode ser realizada para quantas bandeiras forem necessárias.

Integração com soluções antifraude

Visão Geral

O e-SiTef é um gateway de pagamentos multisserviços com capacidade de processamento de transações de cartões de crédito, transferência bancária, geração de boletos, integração com opções de mobile payment e outros serviços que podem ser facilmente agregados à plataforma.

No grupo dos "outros serviços" encontram-se as soluções antifraude de várias empresas como ClearSale, CyberSource e Konduto. As soluções antifraude do e-SiTef incluem o serviço de análise de risco nos pagamentos.

Credenciais necessárias

O e-SiTef possui integração com várias empresas de análise antifraude de forma que o lojista pode escolher com quem fará a análise de risco. Após selecionar a instituição de análise antifraude, o lojista deve entrar em contato com essa instituição e solicitar as credenciais necessárias. Essas credenciais variam de instituição para instituição. Em seguida, o lojista deve passar essas credenciais para a equipe de Produção do e-SiTef que fará o cadastro desses dados. A habilitação do serviço antifraude nos pagamentos da loja só será possível depois do cadastro dessas credenciais no ambiente de produção do e-SiTef.

É importante lembrar que se deve também configurar informações de tempo de expiração e a ação que deve ser executada após esse tempo. Essa configuração é feita no Portal do Lojista. Saiba mais.

Para saber sobre as credenciais necessárias, consulte o capítulo correspondente à instituição desejada.

Restrições

A funcionalidade de análise antifraude pode ser utilizada nas seguintes interfaces do e-SiTef:

• Pagamento HTML
• Pagamento REST
• Pré-autorização REST

Atenção: Para as transações de PRÉ-AUTORIZAÇÃO com análise de risco (antifraude) e roteamentos não-SiTef, deve-se atentar aos cenários em que a análise de risco é feita APÓS a pré-autorização. Nestes cenários, a transação de pré-autorização é confirmada indepentemente do resultado da análise de risco, cabendo ao Lojista decidir - diante da avaliação de antifraude - pela efetivação da sua captura ou não. O mesmo se dá para os casos em que a análise de risco da transação é remetida a uma revisão manual pela instituição de antifraude.

Portanto, não é permitido fazer análise antifraude com as seguintes funcionalidades:

• Recarga
• Split

Em decorrência da natureza do próprio fluxo, os seguintes meios de pagamento não podem ser utilizados em conjunto com a análise antifraude:

• Banco do Brasil
• e-Commerce Cielo 1.5 (NPC)
• Itaú Shopline
• MercadoPago
• PagSeguro
• PayPal

Cartão de Débito

Para pagamentos efetuados com cartão de débito não se aplica o fluxo antifraude com a flag after auth.

Atenção: É importante que o lojista envie o máximo de informações ao utilizar os serviços anti-fraude pelo e-SiTef. A qualidade destas informações impactará diretamente e cumulativamente na qualidade da análise de fraudes, trazendo retornos diretos ao lojista.

Serviço de análise de risco na Interface HTML

Após realizar o alinhamento cadastral com o suporte do e-SiTef para habilitar a integração com o serviço de anti-fraude, na inicialização de uma transação Pagamento HTML (Saiba mais) o lojista deve configurar a propriedade anti_fraud e enviar os devidos parâmetros de anti-fraude (depende da instituição que a sua loja foi configurada), sendo que as duas propriedades devem estar no escopo do objeto additional_data.

O campo anti_fraud determina o modo de aplicação da anti-fraude e pode conter os seguintes valores:

• enabled_before_auth - A análise antifraude será realizada ANTES da autorização do pagamento. Caso a análise seja rejeitada, o pagamento não será iniciado.
• enabled_after_auth - A análise antifraude será realizada APÓS a autorização do pagamento. Caso a análise seja rejeitada, o pagamento que já foi autorizado será cancelado.

Parâmetros de anti-fraude

Os parâmetros dependem da instituição que fornece o serviço de anti-fraude. Portanto, nem todos os parâmetros de anti-fraude disponíveis no e-SiTef serão efetivamente utilizados.

Abaixo seguem todos os parametros de anti-fraude (independente da instituição). Alguns parâmetros podem aparecer repetidamente (por exemplo, a propriedade gift) e isto ocorre devido a característica de análise de risco de cada instituição. Para maiores detalhes de como cada instituição utiliza cada parametro de antifraude, consulte a página de cada integração de antifraude.

Propriedades	Descrição	Formato	Obrigatório
currency	Moeda a ser utilizada	3 A	Sim
b2b_b2c	Tipo do ecommerce	3 A	Não
item_amount	Valor em centavos da soma total dos valores dos itens	< 1024 N	Sim
total_order_amount	Valor em centravos dos pedidos	< 1024 N	Sim
delivery_time_cd	Prazo de entrega	< 50 A	Não
qty_payment_types	Quantidade de pagamentos	1 N	Não
ip (deprecated)	IP do pedido	< 50 A	Sim
gift	1 - É um presente 0 - Não é um presente	1 N	Não
gift_message	Mensagem do presente	< 8000 A	Não
obs	Observação do pedido	< 8000 A	Não
sla_custom	SLA de análise	4 N	Não
origin	Origem do pedido	< 150 A	Sim
reservation_date	Data de reserva de voo. Somente para empresas de passagens aéreas.	Formato da data: yyyy-mm-ddThh:mm:ss	Não
nationality	Nacionalidade do pedido (para pedido de análise internacional)	< 50 A	Não
list_type_id	ID do tipo de lista (somente para clientes que possuem lista específica)	1 N	Não
list_id	ID da lista na loja	< 200 A	Não
sequential	Sequência de realização do pagamento	1 N	Não
interest	Taxa de juros. Exemplo: 5.00	< 4 N	Não
interest_value	Valor absoluto dos juros em centavos. Exemplo: 1000 (10 reais).	< 20 N	Não
shipping_type	Id do tipo de entrega. Pode ser: 0 - Outros 1 - Normal 2 - Garantida 3 - ExpressaBR 4 - ExpressaSP 5 - Alta 6 - Econômica 7 - Agendada 8 - Extra Rápida 9 - Impresso 10 - Aplicativo 11 - Correio 12 - Motoboy 13 - Retirada Bilheteria 14 - Retirada Loja Parceira 15 - Cartão de Crédito Ingresso 16 - Retirada Loja	< 2 N	Não
items	Informações relativas aos itens da compra	Arrays de objeto json (Saiba mais)	Sim
payer	Informações relativas ao pagador	Objeto json (Saiba mais)	Sim
billing_data	Informações relativas a fatura	Objeto json (Saiba mais)	Sim
shipment	Informações relativas a entrega	Array de objeto json (Saiba mais)	Sim
browser	Informações relativas ao navegador utilizado na compra	Objeto json (Saiba mais)	Sim
travel	Informações relativas a passagem aérea	Objeto json (Saiba mais)	Condicional por instituição
passengers	Informações relativas ao passageiros	Array de objeto json (Saiba mais)	Sim, se o item for passagem aérea
connections	Informações relativas ao navegador utilizado na compra	Array de objeto json (Saiba mais)	Sim, se o item for passagem aérea
hotel_reservations	Informações relativas a reserva de hotel	Array de objeto json (Saiba mais)	Sim, se a compra for reserva de hotel
purchase_data	Informações relativas a data da compra	Objeto json (Saiba mais)	Sim
mdd	Informações relativas ao mdd (Merchant Data). Campo específico da Cybersource	Array de objeto json (Saiba mais)	Não

Objeto items

Propriedades	Descrição	Formato	Obrigatório
id	Identificação única do item	N	Sim
sku	Código de produto do item.	A	Condicional por instituição
title	Nome do produto	A	Sim
description	Descrição do produto	A	Não
quantity	Quantidade de itens	< 4 N	Sim
unit_price	Preço unitário do item	< 12 N	Sim
category_id	Id da Categoria do Item. Cada instituição de análise possui uma interpretação diferente.	Condicional por instituição	Condicional por instituição
category_name	Nome da categoria do produto	< 200 A	Não
gift	1 - É um presente 0 - Não é um presente	1 N	Não
tax_amount	Montante da taxa	N	Não
discount_amount	Valor de desconto em centavos	N	Não
creation_date	Data de publicação do produto no formato DD/MM/AAAA.	AN	Não

Objeto payer

Propriedades	Descrição	Formato	Obrigatório
id	Identificação do comprador. Normalmente é o CPF.	N	Sim
name	Nome do comprador. Cada instituição de análise possui uma interpretação diferente.	Condicional por instituição	Condicional por instituição
surname	Sobrenome do comprador	< 200 A	Sim
email	Email do comprador	A	Sim
date_created	Data de criação	A	Sim
password	Senha do comprador	Condicional por instituição	Condicional por instituição
city	Cidade do endereço sem abreviações	< 150 A	Sim
address_street_complement	Complemento do endereço sem abreviações	< 250 A	Não
address_country	País do endereço sem abreviações	< 150 A	Não
address_county	Bairro do endereço sem abreviações	< 150 A	Não
address_street_number	Número do endereço	< 15 A	Não
state	Sigla do estado do endereço - UF	2 A	Não
address_street_name	Nome do logradouro (sem abreviações)	< 200 A	Não
address_zip_code	CEP do endereço	< 10 N	Não
address_reference	Referência do endereço (sem abreviações)	< 250 A	Não
legal_document	Documento da pessoa de Cobrança	< 100 A	Não
phones	Contatos telefônicos do comprador	Array de objeto json (Saiba mais)	Não
address	Endereço do comprador	Objeto json (Saiba mais)	Não

Objeto phones do payer

Propriedades	Descrição	Formato	Obrigatório
ddi	DDI do telefone	3 N	Não
ddd	DDD do telefone	3 N	Não
number	Número do telefone	9 N	Não

Objeto address do payer

Propriedades	Descrição	Formato	Obrigatório
street_name	Nome do Logradouro.	< 200 A	Sim
street_name2	Complemento do do nome do endereço.	< 200 A	Não
street_number	Número do endereço	< 15 A	Sim
apartment	Apartamento se houver	N	Não
complement	Complemento do endereço sem abreviações	< 250 A	Não
county	Bairro do endereço sem abreviações	< 150 A	Sim
city	Cidade do endereço sem abreviações	< 150 A	Sim
state	Sigla do estado do endereço - UF	2 A	Sim
district	Distrito se houver	A	Não
country	País do endereço	< 150 A	Não
zip_code	CEP do endereço	< 10 N	Sim
reference	Referência do endereço sem abreviações	< 250 A	Não
building_number	Numero da casa. Exemplo: caso seja um condomínio fechado, seria o numero da casa dentro deste condomínio.	< 10 A	Não

Objeto billing_data

Propriedades	Descrição	Formato	Obrigatório
cliente_id	Código do cliente	< 50 A	Sim
person	1 - Pessoa Física 2 - Pessoa Jurídica	1 N	Sim
cnpj_cpf	CPF ou CNPJ	< 100 A	Sim
identification_number	RG ou inscrição estadual	< 100 A	Não
name	Nome do cliente	< 500 A	Sim
birth_date	Data de Nascimento.	Data no formato: yyyy-mm-ddThh:mm:ss	Sim
email	Email	< 150 A	Não
gender	M - masculino F - feminino	1 A	Não
address	Endereço da fatura	Objeto json (Saiba mais)	Não
phones	Contatos telefônicos da fatura	Array de objeto json (Saiba mais)	Não
documents	Documentos da fatura	Array de objeto json (Saiba mais)	Não

Objeto address do billing_data

Propriedades	Descrição	Formato	Obrigatório
street_name	Nome do Logradouro	< 200 A	Sim
street_name2	Complemento do nome do logradouro.	< 200 A	Não
street_number	Número do endereço	< 15 A	Sim
apartment	Apartamento se houver	N	Não
complement	Complemento do endereço sem abreviações	< 250 A	Não
county	Bairro do endereço sem abreviações	< 150 A	Sim
city	Cidade do endereço sem abreviações	< 150 A	Sim
state	Sigla do estado do endereço - UF	2 A	Sim
district	Distrito se houver	A	Não
country	País do endereço sem abreviações.	< 150 A	Não
zip_code	CEP do endereço	< 10 N	Sim
reference	Referência do endereço sem abreviações	< 250 A	Não
building_number	Número da casa. Exemplo: caso seja um condomínio fechado, seria o numero da casa dentro deste condomínio.	< 10 A	Não

Objeto phones do billing_data

Propriedades	Descrição	Formato	Obrigatório
type	Tipo de telefone: 0 - Não definido 1 - Residencial 2 - Comercial 3 - Recados 4 - Cobrança 5 - Temporário 6 - Celular	1 N	Sim
ddi	DDI do telefone	3 N	Não
ddd	DDD do telefone	3 N	Sim
number	Número do telefone	9 N	Sim
extension	Ramal do telefone	< 10 A	Não

Objeto documents do billing_data

Propriedades	Descrição	Formato	Obrigatório
type	Condicional por instituição.	A	Não
number	Número do documento	N	Sim

Objeto shipment

Propriedades	Descrição	Formato	Obrigatório
id	Código do cliente	< 50 A	Sim
cost	Valor em centavos do frete	< 1024 N	Não
type	Tipo de pessoa 1 - Pessoa Física 2 - Pessoa Jurídica	< 1 N	Sim
legal_document1	CPF ou CNPJ	< 100 A	Sim
legal_document2	RG ou Inscrição Estadual	< 100 A	Não
name	Nome do Cliente	< 500 A	Sim
surname	Sobrenome do Cliente	< 500 A	Sim
birth_date	Data de nascimento.	Data no formato: yyyy-mm-ddThh:mm:ss	Não
email	Email	< 150 A	Não
gender	M - masculino F - feminino	1 A	Não
address	Endereço para a entrega	Objeto json (Saiba mais)	Condicional por instituição
receiver_address	Endereço para a entrega	Objeto json (Saiba mais)	Condicional por instituição
phones	Contatos telefônicos da entrega	Arrays de objeto json (Saiba mais)	Sim

Objeto address do shipment

Também equivale ao objeto receiver_address do shipment

Propriedades	Descrição	Formato	Obrigatório
street_name	Nome do Logradouro.	< 200 A	Sim
street_name2	Complemento do nome do Logradouro.	< 200 A	Não
street_number	Número do endereço	< 15 A	Sim
apartment	Apartamento se houver	N	Não
complement	Complemento do endereço sem abreviações	< 250 A	Não
county	Bairro do endereço sem abreviações	< 150 A	Sim
city	Cidade do endereço sem abreviações	< 150 A	Sim
state	Sigla do estado do endereço - UF	2 A	Sim
country	País do endereço.	< 150 A	Sim
zip_code	CEP do endereço. Apenas números.	< 10 A	Sim
building_number	Numero da casa. Exemplo: caso seja um condomínio fechado, seria o numero da casa dentro deste condomínio.	< 10 A	Não

Objeto phones do shipment

Propriedades	Descrição	Formato	Obrigatório
type	Tipo de telefone: 0 - não definido 1 - Residencial 2 - Comercial 3 - Recados 4 - Cobrança 5 - Temporário 6 - Celular	1 N	Sim
ddi	DDI do telefone	3 N	Não
ddd	DDD do telefone	3 N	Sim
number	Número do telefone	9 N	Sim
extension	Ramal do telefone	< 10 A	Não

Objeto browser

Propriedades	Descrição	Formato	Obrigatório
ip_address	Endereço IP	15 A	Sim

Objeto travel

Propriedades	Descrição	Formato	Obrigatório
route	Concatenação das pernas dos vôos/trechos Para obter os códigos dos aeroportos, use este link	Valor deve respeitar formato: XXX-XXX:XXX-XXX	Sim
journey_type	Tipo de viagem: round_trip ou one_way	< 32 A	Sim
departure_date_time	Data e horário de partida do primeiro voo.	Formato da data: yyyy-mm-ddThh:mm:ss	Sim

Objeto passengers

Propriedades	Descrição	Formato	Obrigatório
id	Id do passageiro	< 32 A	Não
name	Condicional por instituição	< 100 A	Sim
last_name	Último nome do Passageiro	< 100 A	Condicional por instituição
frequente_flyer_card	Cartão de Milhagem (fidelidade)	< 32 A	Não
legal_document_type	Tipo de documento de identificação: 1 - CPF 2 - CNPJ 3 - RG 4 - IE 5 - Passaporte 6 - CTPS 7 - Título Eleitor	1 N	Sim
legal_document	Número do documento	< 50 A	Sim
birth_date	Data de nascimento.	Data no formato: yyyy-mm-ddThh:mm:ss	Não
email	Email do passageiro. Deve ser único na arrays de passengers.	Formato: name@domain.com	Não
status	Status da reserva da passagem. Exemplo: Reserved	< 32 A	Não
rating	Classificação do passageiro de acordo com preço do ticket.	< 32 A	Não
type	Classificação do passageiro. ADT: Adult CNN: Child INF: Infant YTH: Youth STU: Student SCR: Senior Citizen MIL: Military	< 32 A	Não
unit_price	Preço unitário da passagem.	Formato (em centavos): 1000 (10 reais)	Não
phones	Contatos telefônicos do passageiro	Arrays de objeto json (Saiba mais)	Sim

Objeto phones do passengers

Propriedades	Descrição	Formato	Obrigatório
ddi	DDI do telefone. Apenas números. Exemplo: 55 (Brasil)	3 N	Não
ddd	DDD do telefone. Apenas números. Exemplo: 11 (São Paulo)	3 N	Sim
number	Número do telefone. Apenas números. Exemplo: 12345789	9 N	Sim

Objeto connections

Propriedades	Descrição	Formato	Obrigatório
company	Nome da companhia aérea	< 50 A	Sim
flight_number	Número do voo	6 N	Sim
flight_date	Data e hora da partida da primeira perna do vôo.	Condicional por instituição	Sim
class	Classe do assento	< 10 A	Sim
from	Origem	Condicional por instituição	Sim
to	Destino	Condicional por instituição	Sim
departure_date	Data do embarque.	Data no formato: yyyy-mm-ddThh:mm:ss	Sim
arrival_date	Data do desembarque.	Data no formato: yyyy-mm-ddThh:mm:ss	Sim

Objeto hotel_reservations

Propriedades	Descrição	Formato	Obrigatório
hotel	Nome do hotel	< 200 A	Sim
city	Cidade do hotel sem abreviações	< 150 A	Sim
state	Estado do hotel sem abreviações	< 150 A	Sim
country	País do hotel	< 150 A	Sim
reservation_date	Data da Reserva.	Data no formato: yyyy-mm-ddThh:mm:ss	Sim
reservation_expiration_date	Data da expiração da reserva.	Data no formato: yyyy-mm-ddThh:mm:ss	Sim
checkin_date	Data da chegada.	Data no formato: yyyy-mm-ddThh:mm:ss	Sim
checkout_date	Data da saída.	Data no formato: yyyy-mm-ddThh:mm:ss	Sim

Objeto purchase_data

Propriedades	Descrição	Formato	Obrigatório
last_date_inserted_mail	Data da última alteração do email.	Data no formato: yyyy-mm-ddThh:mm:ss	Não
last_date_change_password	Data da última alteração da senha.	Data no formato: yyyy-mm-ddThh:mm:ss	Não
last_date_change_phone	Data da última alteração do telefone.	Data no formato: yyyy-mm-ddThh:mm:ss	Não
last_date_change_mobile_phone	Data da última alteração do telefone móvel.	Data no formato: yyyy-mm-ddThh:mm:ss	Não
last_date_inserted_address	Data da última alteração do endereço.	Data no formato: yyyy-mm-ddThh:mm:ss	Não
purchase_logged	Compra logado	1 N	Não
purchase_logged_with_facebook	Compra logado através do Facebook	1 N	Não

Objeto mdd

Propriedades	Descrição	Formato	Obrigatório
id	Pode variar de 1 a 100 definidos pelo comércio em acordo com a Cybersource	< 255 A	Não
value	Valor dos campos definidos pelo comércio em acordo com a Cybersource	< 255 A	Não

Retorno da análise de risco

O e-SiTef irá devolver na url de aviso de status o status da análise (aprovado, rejeitado, ou em análise), além do código e mensagem retornados pelo serviço, conforme tabela abaixo:

Campo	Descrição	Tamanho
analise.status	Resultado da análise de risco	= 3 A
analise.codigo	Código de retorno	< 3 N
analise.mensagem	Mensagem de retorno	< 30 N

O status da análise de risco pode ser:

Status	Descrição
NOV	Análise ainda não foi enviada
EXP	Transação de pagamento expirou antes da análise ser enviada
ACC	Transação aceita
REJ	Transação rejeitada pela instituição de análise de risco
REV	Transação requer revisão manual (Saiba mais)
INV	Análise inválida

É importante ressaltar que caso tenha acontecido algum erro, este será descrito em analise.mensagem da URL de retorno.

Para mais detalhes sobre códigos de retorno, cosulte a Lista de Códigos de Retorno da integração de antifraude desejada.

Fluxo da revisão manual

Ao solicitar a análise de anti-fraude, é possível que a instituição responda que a transação será avaliada manualmente. Considerando este cenário, o e-SiTef deixa a transação no estado PPC (Pagamento Pendente de Confirmação) e fica no aguardo de uma conclusão da análise manual.

A instituição deve enviar um aviso indicando a conclusão da análise manual em um determinada URL, o qual deve ser cadastrado na plataforma da instituição. O lojista deve entrar em contato com a instituição e solicitar o registro das seguintes URL para este aviso:

• Ambiente de Homologação: https://esitef-homologacao.softwareexpress.com.br/e-sitef/processarPost.se?loja=<MerchantID>
• Ambiente de Produção: https://esitef-ec.softwareexpress.com.br/e-sitef/processarPost.se?loja=<MerchantID> Sendo <MerchantID> a identificação do lojista no e-SiTef. Em caso de dúvida, entre em contato com o nosso suporte para obter essa identificação.

Quando o e-SiTef receber este aviso, algumas validações serão executadas antes de concluir a transação para um estado final. O lojista irá receber um aviso indicando o estado final desta mesma transação.

Configurar expiração para análise manual

Considere o seguinte cenário, a instituição indica que irá realizar a análise manual, mas a análise manual nunca é concluída. Para esta situação, o e-SiTef solicita uma configuração por parte da Loja, para que após um tempo de espera da resposta da análise de risco, uma decisão seja tomada e não mantenha a transação pendente.

Para isso devem-se configurar no Portal do Lojista os parâmetros necessários seguindo os seguintes passos:

Na figura abaixo, pode-se observar a opção de escolha de loja a ser configurada, caso exista mais de uma configurada para o usuário.

A seguir, são apresentados os campos que serão configurados:

• Tempo de expiração da análise de risco (dias): Tempo de espera da resposta da analise de risco - em dias – para que o e-SiTef tome uma atitude configurada pela loja.
• Atitude após o tempo de expiração: Após o Tempo Máximo de espera configurado, a decisão escolhida neste campo será tomada - ou CONFIRMAR ou CANCELAR a transação.

Assim que o botão Enviar for pressionado, a mensagem Configurado com sucesso! será apresentada, confirmando a alteração desta configuração.

ATENÇÃO: Lembrando que esta configuração apenas será alterada pela Loja, que assumirá a total responsabilidade da configuração feita. Caberá ao e-SiTef apenas a efetivação da ação escolhida, conforme configuração.

Serviço de marcação de fraude

Após uma transação com antifraude bem sucedida (pagamento com status CON, PPC, PPN ou EST), a loja pode vir a identificar que, na realidade, tratava-se de uma fraude. Nesse caso, a loja pode realizar uma chamada ao serviço de marcação de fraude para avisar a instituição de análise de risco sobre essa ocorrência. Isso irá refinar o processo de análise dessa instituição, tornando-o mais preciso e evitando mais fraudes futuramente.

Atualmente, esta API suporta as seguintes instituições de antifraude:

• Konduto
• Fraud Detect

Detalhes da chamada

• Recurso: /v1/transactions/{nit}/fraud
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM

Exemplos

Abaixo está um exemplo de chamada do serviço de marcação de fraude utilizando a ferramenta cURL.

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/fraud" 
--header "Content-Type: application/json" 
--header "merchant_id: xxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx" 
--data-binary 
{} 
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "analysis":{
      "code":"0",
      "message":"Sucesso"
   }
}

Parâmetros de requisição

Até o momento, não existem parâmetros a serem enviados no corpo da requisição.

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 201. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de marcação de fraude:

Parâmetro	Descrição	Formato
code	Código de resposta do e-SiTef. Qualquer código diferente de 0 significa falha. Saiba mais.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
	analysis
code	Código de resposta da instituição de análise de risco.	< 4 N
message	Mensagem de resposta da instituição de análise de risco.	< 500 AN

ClearSale

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 ClearSale exigem as seguintes credenciais:

• app_code (Merchant Code)
• entity_code - Identificação da loja na ClearSale

IMPORTANTE: As credenciais acima devem ser obtidas com a ClearSale. O lojista deve entrar em contato com a ClearSale 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.

Revisão manual

Conforme explicado no capítulo "Fluxo da revisão manual", a ClearSale é uma das instituições de antifraude que possui o fluxo de revisão manual. Logo, confirme que o cadastro das URL de aviso da revisão manual estão configuradas adequadamente na ClearSale. Em caso de dúvida, entre em contato com o nosso suporte.

Parâmetros antifraude da ClearSale

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

Propriedades e-SiTef	Propriedades ClearSale	Detalhe adicional
b2b_b2c	Order.B2B_B2C	-
item_amount	Order.TotalItems	-
total_order_amount	Order.TotalOrder	-
delivery_time_cd	Order.DeliveryTimeCD	-
qty_payment_types	Order.QtyPaymentTypes	-
ip (deprecated)	Order.IP	-
gift	Order.Gift	-
gift_message	Order.GiftMessage	-
obs	Order.Obs	-
sla_custom	Order.SlaCustom	-
origin	Order.Origin	-
reservation_date	Order.ReservationDate	-
nationality	Order.Nationality	-
list_type_id	Order.ListTypeID	-
list_id	Order.ListID	-
sequential	Payment.Sequential	-
interest	Payment.Interest	-
interest_value	Payment.InterestValue	-
shipping_type	Order.ShippingType	-
items		Arrays de objeto json (Saiba mais)
payer		Objeto json (Saiba mais)
billing_data		Objeto json (Saiba mais)
shipment		Array de objeto json (Saiba mais)
passengers		Array de objeto json (Saiba mais)
connections		Array de objeto json (Saiba mais)
hotel_reservations		Array de objeto json (Saiba mais)
purchase_data		Objeto json (Saiba mais)

Objeto items

Propriedades e-SiTef	Propriedades ClearSale	Detalhe adicional
id	Item.ID	-
title	Item.Name	-
quantity	Item.Qty	-
unit_price	Item.ItemValue	-
category_id	Item.CategoryID	Preenchimento opcional e numérico com tamanho 1
category_name	Item.CategoryName	-
gift	Item.Gift	-

Objeto payer

Propriedades e-SiTef	Propriedades ClearSale	Detalhe adicional
name	Payment.Name	Preenchimento opcional e formato <150 A
city	Payment.Address.City	-
address_street_complement	Payment.Address.Comp	-
address_country	Payment.Address.Country	-
address_county	Payment.Address.County	-
address_street_number	Payment.Address.Number	-
state	Payment.Address.State	-
address_street_name	Payment.Address.Street	-
address_zip_code	Payment.Address.ZipCode	-
address_reference	Payment.Address.Reference	-
legal_document	Payment.LegalDocument	-

Objeto billing_data

Propriedades e-SiTef	Propriedades ClearSale	Detalhe adicional
cliente_id	BillingData.ID	-
person	BillingData.Type	-
cnpj_cpf	BillingData.LegalDocument1	-
identification_number	BillingData.LegalDocument2	-
name	BillingData.Name	-
birth_date	BillingData.BirthDate	-
email	BillingData.Email	-
gender	BillingData.Gender	-
address		Objeto json (Saiba mais)
phones		Array de objeto json (Saiba mais)
documents		Array de objeto json (Saiba mais)

Objeto address do billing_data

Propriedades e-SiTef	Propriedades ClearSale	Detalhe adicional
street_name	BillingData.Address.Street	-
street_number	BillingData.Address.Number	-
complement	BillingData.Address.Comp	-
county	BillingData.Address.County	-
city	BillingData.Address.City	-
state	BillingData.Address.State	-
country	BillingData.Address.Country	-
zip_code	BillingData.Address.ZipCode	-
reference	BillingData.Address.Reference	-

Objeto phones do billing_data

Propriedades e-SiTef	Propriedades ClearSale	Detalhe adicional
type	BillingData.Phones.Phone.Type	-
ddi	BillingData. Phones. Phone.DDI	-
ddd	BillingData. Phones. Phone.DDD	-
number	BillingData. Phones. Phone.Number	-
extension	BillingData. Phones. Phone.Extension	-

Objeto documents do billing_data

Propriedades e-SiTef	Propriedades ClearSale	Detalhe adicional
type	BillingData.Type	Valores permitidos: CPF ou CNPJ

Objeto shipment

Propriedades e-SiTef	Propriedades ClearSale	Detalhe adicional
id	ShippingData.ID	-
cost	Order.ShippingPrice	-
type	ShippingData.Type	-
legal_document1	ShippingData.LegalDocument1	-
legal_document2	ShippingData.LegalDocument2	-
name	ShippingData.Name	-
birth_date	ShippingData.BirthDate	-
email	ShippingData.Email	-
gender	ShippingData.Gender	-
receiver_address		Objeto json (Saiba mais)
phones		Arrays de objeto json (Saiba mais)

Objeto receiver_address do shipment

Propriedades e-SiTef	Propriedades ClearSale	Detalhe adicional
street_name	ShippingData.Address.Street	-
street_number	ShippingData.Address.Number	-
complement	ShippingData.Address.Comp	-
county	ShippingData.Address.County	-
city	ShippingData.Address.City	-
state	ShippingData.Address.State	-
country	ShippingData.Address.Country	-
zip_code	ShippingData.Address.ZipCode	-

Objeto phones do shipment

Propriedades e-SiTef	Propriedades ClearSale	Detalhe adicional
type	ShippingData.Phones.Phone.Type	-
ddi	ShippingData.Phones.Phone.DDI	-
ddd	ShippingData.Phones.Phone.DDD	-
number	ShippingData.Phones.Phone.Number	-
extension	ShippingData.Phones.Phone.Extension	-

Objeto passengers

Propriedades e-SiTef	Propriedades ClearSale	Detalhe adicional
name	Passenger.Name	Preencher com o nome completo
frequente_flyer_card	Passenger.FrequentFlyerCard	-
legal_document_type	Passenger.LegalDocumentType	-
legal_document	Passenger.LegalDocument	-
birth_date	Passenger.BirthDate	-

Objeto connections

Propriedades e-SiTef	Propriedades ClearSale	Detalhe adicional
company	Connection.Compay	-
flight_number	Connection.FlightNumber	-
flight_date	Connection.FlightDate	-
class	Connection.Class	-
from	Connection.From	-
to	Connection.To	-
departure_date	Connection.DepartureDate	-
arrival_date	Connection.ArrivalDate	-

Objeto hotel_reservations

Propriedades e-SiTef	Propriedades ClearSale	Detalhe adicional
hotel	HotelReservation.Hotel	-
city	HotelReservation.City	-
state	HotelReservation.State	-
country	HotelReservation.Country	-
reservation_date	HotelReservation.ReservationDate	-
reservation_expiration_date	HotelReservation.ReservationExpirationDate	-
checkin_date	HotelReservation.CheckInDate	-
checkout_date	HotelReservation.CheckOutDate	-

Objeto purchase_data

Propriedades e-SiTef	Propriedades ClearSale	Detalhe adicional
last_date_inserted_mail	PurchaseInformationData.LastDateInsertedMail	-
last_date_change_password	PurchaseInformationData.LastDateChangePassword	-
last_date_change_phone	PurchaseInformationData.LastDateChangePhone	-
last_date_change_mobile_phone	PurchaseInformationData.LasteDateChangeMobilePhone	-
last_date_inserted_address	PurchaseInformationData.LastDateInsertedAddress	-
purchase_logged	PurchaseInformationData.PurchaseLogged	-
purchase_logged_with_facebook	PurchaseInformationData.PurchaseLoggedWithFacebook	-

Exemplo

Segue abaixo um exemplo de request com os parâmetros mínimos para iniciar uma transação de pagamento com análise de risco. Saiba mais sobre os parâmetros do pagamento.

{
    "merchant_id": "LOJATESTE",
    "merchant_usn": "9876",
    "order_id": "111",
    "redirect": "M",
    "authorizer_id": "",
    "amount": "1000",
    "installments": "",
    "installment_type": "",
    "style": "N",
    "store_card": "",
    "soft_descriptor": "",
    "authenticate": "0",
    "transaction_type": "payment",
    "additional_data": {
        "anti_fraud": "enabled_after_auth",
        "extra_info": "",
        "currency": "BRL",
        "item_amount": "12343",
        "total_order_amount": "13412",
        "interest": "10.3",
        "interest_value": "100",
        "items": [
            {
                "id": "1",
                "title": "bola 1",
                "quantity": "1",
                "unit_price": "50000",
                "currency": "BRL",
                "picture_url": "http://sportv.globo.com/platb/files/1103/2011/08/bola_futebol.gif",
                "category_id": "others",
                "description": "bola para jogar 1",
                "weight": "200",
                "shipping_cost": "1000"
            },
            {
                "id": "2",
                "title": "bola 2",
                "quantity": "2",
                "unit_price": "25000",
                "currency": "BRL",
                "picture_url": "http://sportv.globo.com/platb/files/1103/2011/08/bola_futebol.gif",
                "category_id": "others",
                "description": "bola para jogar 2",
                "weight": "200",
                "shipping_cost": "1000"
            }
        ],
        "payer": {
            "name": "Joaquim",
            "surname": "Severino",
            "email": "js@softexpress.com.br",
            "date_created": "2014-03-12T06:55:17.413-04:00",
            "phone_area_code": "11",
            "phone_number": "11111111",
            "identification_type": "CPF",
            "identification_number": "09719224703",
            "address_street_name": "Rua Jose Ninguem",
            "address_street_number": "11",
            "address_street_complement": "ap 12",
            "address_zip_code": "01230120",
            "born_date": "12/12/1900",
            "city": "Sao Paulo",
            "state": "SP",
            "address_country": "Brazil",
            "address_county": "Campos Eliseos"
        },
        "purchase_data": {
            "purchase_logged_with_facebook": "1",
            "purchase_logged": "1",
            "last_date_inserted_address": "2016-02-19T10:00:00",
            "last_date_change_phone": "2016-02-19T10:00:00",
            "last_date_change_password": "2016-02-19T10:00:00",
            "last_date_inserted_mail": "2016-02-19T10:00:00",
            "last_date_change_mobile_phone": "2016-02-19T10:00:00"
        },
        "billing_data": {
            "phones": [
                {
                    "number": "123123123",
                    "ddd": "11",
                    "ddi": "34",
                    "extension": "1234",
                    "type": "0"
                }
            ],
            "address": {
                "zip_code": "02932900",
                "street_number": "123",
                "street_name": "rua legal",
                "floor": "1",
                "apartment": "1200",
                "complement": "lala",
                "city": "sao paulo",
                "state": "SP",
                "country": "Brazil",
                "county": "jardim lala",
                "reference": "lalelo"
            },
            "email": "email@gmail.com",
            "birth_date": "1990-02-19T10:00:00",
            "name": "John",
            "identification_number": "48515484755",
            "cnpj_cpf": "54861548806",
            "person": "1",
            "client_id": "123",
            "gender": "M"
        },
        "shipment": {
            "id": "98765432",
            "cost": "2000",
            "type": "1",
            "name": "Joao",
            "legal_document1": "1092384",
            "receiver_address": {
                "zip_code": "12345678",
                "street_number": "Rua do Exemplo",
                "street_name": "123",
                "floor": "3",
                "apartment": "901",
                "city": "São Paulo",
                "complement": "Sobreloja 3",
                "country": "brazil",
                "district": "Jardim do Exemplo",
                "state": "SP",
                "county": "jardins"
            },
            "phones": [
                {
                    "number": "123123123",
                    "ddd": "11",
                    "ddi": "34",
                    "extension": "1234",
                    "type": "0"
                }
            ]
        }
    }
}

ATENÇÃO: As transações que ficam pendentes de pagamento podem ser confirmadas ou desfeitas por limite de tempo. Saiba mais.

O e-SiTef considera que o Payment da ClearSale possui os dados do usuário que faz a compra e o BillingData refere-se aos dados do dono do cartão. Considera também que o e-mail do pedido é o e-mail do comprador e a data do pedido é a data de criação da transação de pagamento.

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 ClearSale.

Código	Descrição	Reenviar
00	Transação Concluída	N
01	Usuário Inexistente	N
02	Erro na validação do XML	S
03	Erro ao transformar XML	S
04	Erro Inesperado	S
05	Pedido já enviado ou não está em reanalise	S
06	Erro no Plugin de Entrada	S
07	Erro no Plugin de Saída	N

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:

Campo	Descrição
anti_fraud	Objeto com campos de anti-fraude.
chargeback	Informa se o aviso para a CyberSource será realizado ou não. Valores permitidos: true ou false Valor default: false
marked_data	Informa 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
currency	PurchaseTotals_currency	-
items		Arrays de objeto json (Saiba mais)
shipment		Array de objeto json (Saiba mais)
browser		Objeto json (Saiba mais)
travel		Objeto json (Saiba mais). Obrigatório se o item for passagem aérea
passengers		Array de objeto json (Saiba mais)
connections		Array de objeto json (Saiba mais)
mdd		Array de objeto json (Saiba mais). Os valores permitidos podem ser consultados aqui.

Objeto items

Propriedades e-SiTef	Propriedades CyberSource	Detalhe adicional
id	Item_#_ID	-
sku	Item_#_ productSKU	Preenchimento obrigatório
title	Item_#_ productName	-
quantity	Item_#_Quantity	-
unit_price	Item_#_unitPrice	-
category_id	Item_#_productCode	Pode 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_amount	Item_#_taxAmount	-

Objeto shipment

Propriedades e-SiTef	Propriedades CyberSource	Detalhe adicional
name	shipTo_firstName	-
surname	shipTo_lastName	-
address		Objeto json (Saiba mais)
phones		Arrays de objeto json (Saiba mais)

Objeto address do shipment

Propriedades e-SiTef	Propriedades CyberSource	Detalhe adicional
street_name	shipto_street1	Enviar o número e o complemento. Lembrar de colocar o AP, APTO, LOTE, CASA ou BLOCO.
street_name2	shipto_street2	Enviar o número e o complemento. Lembrar de colocar o AP, APTO, LOTE, CASA ou BLOCO.
street_number	shipto_street1	-
apartment	Será concatenado em shipto_street2	-
complement	Será concatenado em shipto_street2	-
city	shipto_city	-
state	shipto_state	-
country	shipto_country	Enviar a sigla no padrão ISO
zip_code	shipto_postalCode	-
building_number	shipto_building_number	-

Objeto phones do shipment

Propriedades e-SiTef	Propriedades CyberSource	Detalhe adicional
ddi	shipTo_phoneNumber	-
ddd	shipTo_phoneNumber	-
number	shipTo_phoneNumber	-

Objeto browser

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

Objeto travel

Propriedades e-SiTef	Propriedades CyberSource	Detalhe adicional
route	decisionManager_travelData_completeRoute	-
journey_type	decisionManager_travelData_journeyType	-
departure_date_time	decisionManager_travelData_journeyType	-

Objeto passengers

Propriedades e-SiTef	Propriedades CyberSource	Detalhe adicional
id	item_#_passengerId	-
name	item_#_passengerFirstName	Preencher apenas com o primeiro nome
last_name	item_#_passengerLastName	Preenchimento obrigatório
frequente_flyer_card	item_#_passengerID	O campo billTocustomerID pode abrigar a mesma informação
email	item_#_passengerEmail	Se não único entre os passageiros, a transação será recusada pela CyberSource, com código 102.
status	item_#_passengerStatus	-
type	item_#_passengerType	-
unit_price	item_#_unitPrice	-
phones		Arrays de objeto json (Saiba mais)

Objeto phones do passengers

Propriedades e-SiTef	Propriedades CyberSource	Detalhe adicional
ddi	item_#_passengerPhone	-
ddd	item_#_passengerPhone	-
number	item_#_passengerPhone	-

Objeto connections

Propriedades e-SiTef	Propriedades CyberSource	Detalhe adicional
flight_date	decisionManager_travelData_departureDateTime	Os 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
from	decisionManager_travelData_leg_#_origin	Valor deve respeitar esta os códigos de aeroporto, desta referência.
to	decisionManager_travelData_leg_#_destination	Valor 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_date	decisionManager_travelData_departureDateTime	-

Objeto mdd

Propriedades e-SiTef	Propriedades CyberSource	Detalhe adicional
id	merchantDefinedData_mddField_id	Pode variar de 1 a 100 definidos pelo comércio em acordo com a Cybersource
value	merchantDefinedData_mddField_value	Valor 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:

ID	Resumo	Descrição
5	Canal de Venda	Canal de Venda do produto/serviço. Exemplo de valor: Web, App, Guichê, etc.)
6	SO	Sistema Operacional utilizado pelo cliente final. Exemplo de valor: Android, iOS, Windows, etc.
7	Versão da Aplicação	Versão da aplicação do cliente. Exemplo de valor: 1.0.12
8	Provisionado para futuros dados	Provisionado para futuros dados.
9	Provisionado para futuros dados	Provisionado para futuros dados.
10	Provisionado para futuros dados	Provisionado para futuros dados.
11	Nome utilizado no cadastro	Nome registrado no cadastro (Obs: em caso de compra guest, não enviar valor)
12	CPF utilizado no cadastro	CPF registrado no cadastro.
13	Tempo de cadastro do cliente em dias	Tempo de cadastro do cliente em dias. Formato: NNNNN
14	Dias desde primeiro pedido	Quantidade de dias passados desde o primeiro pedido. Formato: NNNNN
15	Dias desde último pedido	Quantidade de dias passados desde o último pedido. Formato: NNNNN
16	Quantidade total de pedidos	Quantidade total de pedidos realizados pelo CPF cadastrado. Formato: NNNNN
17	Dias desde última alteração cadastral	Quantidade de dias passados desde a última alteração cadastral. Formato: NNNNN
18	Provisionado para futuros dados	Provisionado para futuros dados.
19	Provisionado para futuros dados	Provisionado para futuros dados.
20	Provisionado para futuros dados	Provisionado 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ódigo	Descrição
100	Transação efetuada com sucesso e aprovada pelo Decision Manager
101	Um ou mais dos campos requeridos está faltando na requisição
102	Um ou mais dos campos requeridos contém dados inválidos
150	Erro: Falha geral de sistema
151	Erro: A requisição foi recebida mas ocorreu timeout. Esse erro não inclui timeout entre cliente e servidor
152	Erro: A requisição foi recebida, mas um serviço não finalizou no tempo de corrida
202	Cartão expirado

Konduto

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 Konduto exigem as seguintes credenciais:

• Chave Privada (Identificação da Loja) - Chave Privada do cadastro da loja na Konduto.
• Chave Pública (Merchant Code) - Chave Publica do cadastro da loja na Konduto.

IMPORTANTE: As credenciais acima devem ser obtidas com a Konduto. O lojista deve entrar em contato com a Konduto 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.

Configuração de URL Web Hook

Para que possamos receber as atualizações de status de transações de análise de risco, é necessário realizar a configuração da URL de Webhook no ambiente de configuração da Konduto.

URL de Produção:

https://esitef-ec.softwareexpress.com.br/e-sitef/processarPost.se?src=konduto

URL de Homologação:

https://esitef-homologacao.softwareexpress.com.br/e-sitef/processarPost.se?src=konduto

Essa URL deve ser configurada para qualquer troca de status. Para realizar essa configuração, por favor entre em contato com o Suporte da Konduto.

Bandeiras permitidas

A Konduto suporta qualquer bandeira de cartão.

IMPORTANTE: Apenas as transações de crédito serão efetivamente analisadas pela Konduto. Transações de débito serão enviadas para a instituição, porém serão apenas armazenadas para relatório e não serão analisadas.

Funcionalidades suportadas

• Link de Pagamento via Portal
• Link de Pagamento via HTML
• Pagamento REST
• Pré-Autorização REST

Parâmetros antifraude da Konduto (Link de Pagamento via HTML)

Por enquanto, os dados coletados para a análise de risco serão apenas os informados durante o checkout do comprador. Em breve novos campos poderão ser enviados na requisição de criação do pagamento.

Campos coletados durante o Checkout

Os campos coletados durante o checkout são:

Campo	Descrição do campo	Obrigatório
Primeiro Nome do Comprador	Primeiro nome do cliente que está realizando a compra.	Sim
Sobrenome do Comprador	Sobrenome do cliente que está realizando a compra.	Sim
CPF do Comprador	CPF do cliente que está realizando a compra.	Sim
Telefone	Telefone do cliente que está realizando a compra.	Sim
E-mail	E-mail do clinte que está realizando a compra.	Sim
Nome (como está no cartão)	Nome que está impresso no cartão utilizado para a compra.	Sim
Endereco completo	Endereço completo para cobrança.	Sim
Complemento	Complemento do endereço de cobrança.	Não
CEP	CEP do endereço de cobrança.	Sim
País	País do endereco de cobrança.	Sim
Estado	Estado do endereço de cobrança.	Sim
Cidade	Cidade do endereço de cobrança.	Sim

Exemplo

Exemplo da requisição de pagamento HTML com análise de risco na Konduto:

{
   "merchant_id":"KONDUTOTESTE",
   "merchant_usn":"803208495",
   "order_id":"866705726000010",
   "redirect":"A",
   "style":"N",
   "amount":"100000",
   "authenticate":"0",
   "transaction_type":"payment",
   "payment_link":"true",
   "additional_data":{
      "currency":"BRL",
      "anti_fraud":"enabled_after_auth"
   }
}

Antifraude Konduto no Link de Pagamento via Portal

Para habilitar a antifraude Konduto para Links de Pagamento gerados pelo Portal do Lojista, entre em contato com o suporte do e-SiTef.

Antifraude Konduto via REST

Após realizar o alinhamento cadastral com o suporte do e-SiTef para habilitar a integração com o serviço de anti-fraude, na inicialização de uma transação Pagamento REST (saiba mais) ou Pré Autorização REST (saiba mais) o lojista deve enviar a propriedade anti_fraud e enviar os devidos parâmetros de anti-fraude (depende da instituição que a sua loja foi configurada), sendo que as duas propriedades devem estar no escopo do objeto additional_data.

O campo anti_fraud determina o modo de aplicação da anti-fraude e pode conter os seguintes valores:

• enabled_before_auth - A análise antifraude será realizada ANTES da autorização do pagamento. Caso a análise seja rejeitada, o pagamento não será iniciado. No caso da pré autorização com roteamentos não-SiTef, caso a análise de risco fique como análise manual, o e-SiTef deixa a transação no estado PPC (Pagamento Pendente de Confirmação) e fica no aguardo de uma conclusão da análise manual.
• enabled_after_auth - A análise antifraude será realizada APÓS a autorização do pagamento. Caso a análise seja rejeitada, o pagamento que já foi autorizado será cancelado. No caso da pré autorização com roteamentos não-SiTef, o e-SiTef deixa a transação no estado PPC (Pagamento Pendente de Confirmação) e fica no aguardo de uma conclusão da análise manual.

Parâmetros antifraude da Konduto

Abaixo segue a relação de parâmetros antifraude processados pela Konduto.

Parâmetro	Descrição	Obrigatório	Formato
additional_data	Dados adicionais da transação
visitor_id	Identificador do visitante obtido no JavaScript da Konduto	NÃO	< 40 AN
additional_data .items[]	Informações relativas aos itens da compra
unit_price	Preço unitário do item em centavos	NÃO	< 10 N
sku	Código de produto do item	NÃO	< 100 AN
quantity	Quantidade de itens	NÃO	< 10 N
id	Identificação única do item que pode ser o código de barras ou UPC do produto.	NÃO	< 100 AN
title	Nome do produto ou serviço	NÃO	< 100 AN
discount_amount	Valor de desconto do produto em centavos	NÃO	< 10 N
description	Descrição do produto	NÃO	< 100 AN
creation_date	Indica a data de publicação do produto no site da loja (Formato: DD/MM/AAAA)	NÃO	= 10 AN
additional_data .payer	Informações relativas ao comprador
id	Identificador único do cliente. Pode ser qualquer valor (sequencial, documento, e-mail) desde que seja consistente em pedidos futuros.	SIM	< 100 AN
name	Nome do cliente	SIM	< 100 AN
surname	Sobrenome do cliente	SIM	< 100 AN
email	Endereço de e-mail do cliente	SIM	< 100 AN
born_date	Data de nascimento do cliente (formato : AAAA-MM-DDTHH:MM:SS)	NÃO	= 19 AN
identification_number	Número de documento fiscal do cliente	NÃO	< 100 AN
creation_date	Data de criação da conta ou cadastro do cliente no site (formato: DD/MM/AAAA )	NÃO	= 10 AN
is_new_client	Boolean indicando se o cliente está usando uma conta recém-criada nesta compra	NÃO	< 5 T/F
is_vip_client	Boolean indicando se este é um cliente VIP ou comprador frequente.	NÃO	< 5 T/F
additional_data .payer .phones[]	Informações relativas ao telefone do comprador
ddi	DDI do telefone do cliente	NÃO	< 100 AN
ddd	DDD do telefone do cliente	NÃO	< 100 AN
number	Número de telefone do cliente	NÃO	< 100 AN
additional_data .billing_data .address	Informações relativas à fatura
street_name	Rua da fatura do cliente com o banco	NÃO	< 255 AN
street_number	Número da rua da fatura do cliente com o banco	NÃO	< 255 AN
complement	Complemento do endereço de fatura.	NÃO	< 100 AN
city	Cidade do titular	NÃO	< 100 AN
state	Estado do titular	NÃO	< 100 AN
zip_code	CEP do titular	NÃO	< 100 A N
country	Código do país do titular, seguindo a ISO 3166-1 alfa-3	NÃO	= 3 AN
additional_data .shipment	Informações relativas à entrega
name	Nome do destinatário	NÃO	< 100 AN
surname	Sobrenome do destinatário	NÃO	< 100 AN
additional_data .shipment .address	Informações relativas ao endereço de entrega
street_name	Nome da rua do destinatário	NÃO	< 255 AN
street_number	Número da rua do destinatário	NÃO	< 255 AN
complement	Complemento do endereço do destinatário.	NÃO	< 255 AN
city	Cidade do destinatário	NÃO	< 100 AN
state	Estado do destinatário	NÃO	< 100 AN
zip_code	CEP do destinatário	NÃO	< 100 AN
country	Código do país do destinatário, seguindo a ISO 3166-1 alfa-3	NÃO	= 3 AN
additional_data .travel	Informações relativas à passagem aérea
transport_type	Tipo de viagem (flight ou bus)	SIM	< 6 AN
expiration_date	Data de expiração (formato: DD/MM/AAAA )	NÃO	= 10 AN
additional_data .connections[]	Informações relativas às conexões de viagem
journey_type	OUTWARD - para ida RETURN - para volta	SIM	< 7 AN
origin_city	Cidade de origem.	SIM, se transport_type=bus	< 100 AN
destination_city	Cidade de destino.	SIM, se transport_type=bus	< 100 AN
from	Código aeroportuário IATA para o aeroporto de origem	SIM, se transport_type=flight	= 3 AN
to	Código aeroportuário IATA para o aeroporto de destino.	SIM, se transport_type=flight	= 3 AN
departure_date	Date e hora do embarque (formato: AAAA-MM-DDTHH:MM:SS)	SIM	< 17 AN
class	Nome da classe (Ex: economy, business e first)	NÃO	< 8 AN
class_code	Código da classe	NÃO	< 20 AN
company	Nome da cia aérea	NÃO	< 20 AN
additional_data .passengers[]	Informações relativas aos passageiros
name	Primeiro nome do passageiro	SIM	< 100 AN
last_name	Sobrenome do passageiro	SIM	< 100 AN
legal_document	Número do documento	SIM	< 100 AN
legal_document_type	Tipo do documento (5 = passport, qualquer outro número = id)	SIM	< 8 AN
birth_date	Data de nascimento do passageiro (formato: AAAA-MM-DDTHH:MM:SS)	NÃO	< 17 AN
nationality	País de nascimento do passageiro, seguindo a ISO 3166-1 alfa-3	NÃO	= 3 AN
is_frequent_traveler	Flag de viajante frequente	NÃO	< 5 T/F
is_with_special_needs	Flag de viajante com necessidades especiais	NÃO	< 5 T/F
frequent_flyer_card	Tipo de programa de fidelidade	NÃO	< 255 AN
customer_class	Categoria do programa de fidelidade	NÃO	< 255 AN
additional_data .hotel_reservations[]	Informações relativas à reserva de hotel
hotel	Nome do hotel	SIM	< 100 AN
category	Categoria do hotel	NÃO	< 100 AN
additional_data .hotel_reservations[] .address	Informações relativas ao endereço do hotel
street_name	Rua do hotel	NÃO	< 255 AN
street_number	Número do hotel	NÃO	< 255 AN
complement	Complemento do endereço hotel.	NÃO	< 100 AN
city	Cidade do hotel	NÃO	< 100 AN
state	Sigla do estado do hotel	NÃO	< 100 AN
zip_code	CEP do hotel	NÃO	< 100 AN
country	País do hotel, seguindo a ISO 3166-1 alfa-3.	NÃO	= 3 AN
additional_data .hotel_reservations[] .rooms[]	Informações relativas a quartos do hotel
number	Número do quarto	NÃO	< 100 AN
code	Código do quarto	NÃO	< 100 AN
type	Tipo do quarto	NÃO	< 100 AN
check_in_date	Date e hora do entrada (formato: AAAA-MM-DDTHH:MM:SS)	SIM	< 17 AN
check_out_date	Date e hora de saída (formato: AAAA-MM-DDTHH:MM:SS)	NÃO	< 17 AN
number_of_guests	Número de pessoas	NÃO	< 9999 N
board_basis	Regime de alimentação	NÃO	< 100 AN
additional_data .hotel_reservations[] .rooms[] .guests[]	Informações relativas a hóspedes do quarto
name	Nome do hóspede	SIM	< 100 AN
document	Número do documento do hóspede	NÃO	< 8 AN
document_type	Documento usado pelo cliente: cpf rg passport id other	NÃO	< 8 AN
birth_date	Data de nascimento do cliente (formato: AAAA-MM-DDTHH:MM:SS)	NÃO	< 17 AN
nationality	Nacionalidade do hóspede, seguindo a ISO 3166-1 alfa-3.	NÃO	= 3 AN
additional_data .events[]	Informações relativas a dados de um evento
name	Nome do evento	SIM	< 255 AN
date	Date e hora do evento em UTC (formato AAAA-MM-DDTHH:MM:SS)	SIM	< 17 AN
type	Tipo do evento: show theater movies party festival course sports corporate	SIM	< 9 AN
subtype	Detalhe do tipo do evento	NÃO	< 255 AN
additional_data .events[] .venue	Informações relativas a dados de local de um evento
name	Nome do local	NÃO	< 255 AN
street_name	Nome da rua	NÃO	< 255 AN
street_number	Número da rua	NÃO	< 255 AN
city	Cidade do local	NÃO	< 255 AN
state	Estado do local	NÃO	< 255 AN
country	Pais do local, seguindo a ISO 3166-1 alfa-3.	NÃO	= 3 AN
capacity	Capacidade do local	NÃO	< 255 AN
additional_data .events[] .tickets[]	Informações relativas aos ingressos de um evento
id	Identificador único do ticket.	NÃO	< 255 AN
category	Categoria do ticket: student senior government social regular	SIM	< 10 AN
section	Seção do ticket	NÃO	< 255 AN
premium	Indicador de ticket premium	NÃO	< 5 T/F
additional_data .events[] .tickets[] .atendee	Informações relativas ao participante do evento
name	Nome do participante	NÃO	< 255 AN
document	Documento do participante	SIM	< 100 AN
document_type	Tipo de documento do participante: cpf cnpj rg passport other	NÃO	< 100 AN
birth_date	Data de nascimento do participante (formato: AAAA-MM-DDTHH:MM:SS)	NÃO	< 17 AN

Exemplo

Exemplo da requisição de criação pagamento REST com análise de risco na Konduto:

{
   "merchant_usn":"2423423434",
   "order_id":"2432342343",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"1300",
   "additional_data":{
      "anti_fraud":"enabled_before_auth",
      "visitor_id":"XKhas09jcks",
      "items":[
         {
            "title":"title1",
            "quantity":"1",
            "unit_price":"1111",
            "description":"description1",
            "id":"id1",
            "discount_amount":"111",
            "sku":"sku1",
            "creation_date":"11/01/2011"
         }
      ],
      "payer":{
         "name":"Marcos",
         "surname":"da Silva",
         "email":"marocs@dasilva.com",
         "born_date":"1990-01-01T11:11:11",
         "creation_date":"02/03/2004",
         "is_new_client":"true",
         "is_vip_client":"true",
         "phones":[
            {
               "number":"333333333",
               "ddd":"22",
               "ddi":"11"
            },
            {
               "number":"666666666",
               "ddd":"55",
               "ddi":"44"
            }
         ],
         "identification_number":"47764543004"
      },
      "shipment":{
         "name":"Fernando",
         "surname":"Bezerra",
         "address":{
            "zip_code":"98764312",
            "street_number":"987",
            "street_name":"Rua Shipment",
            "complement":"ap. 587",
            "city":"São Shipment",
            "state":"MA",
            "country":"BRA"
         }
      },
      "passengers":[
         {
            "name":"Miguel",
            "last_name":"Herrera",
            "frequent_flyer_card":"frequentFlyerCard",
            "legal_document_type":"1",
            "legal_document":"12312312312",
            "birth_date":"1980-07-28T10:40:00",
            "customer_class":"customerClass",
            "nationality":"BRA",
            "is_frequent_traveler":"true",
            "is_with_special_needs":"true"
         }
      ],
      "connections":[
         {
            "company":"Verde",
            "class":"first",
            "from":"GRU",
            "to":"CGH",
            "departure_date":"2023-09-07T07:09:00",
            "journey_type":"OUTWARD",
            "origin_city":"San Juan",
            "destination_city":"Homero Lopez",
            "class_code":"VIP"
         },
         {
            "company":"Rosa",
            "class":"economy",
            "from":"BSB",
            "to":"VCP",
            "departure_date":"2022-10-21T16:39:00",
            "journey_type":"RETURN",
            "origin_city":"San Pablo",
            "destination_city":"Juanito Cruz",
            "class_code":"ECONOMY"
         }
      ],
      "hotel_reservations":[
         {
            "hotel":"Hotel Green Tree",
            "address":{
               "zip_code":"83392019",
               "street_number":"529",
               "street_name":"Rua Hoteleira",
               "complement":"ap. 019",
               "city":"San Hotel",
               "state":"AC",
               "country":"EN"
            },
            "rooms":[
               {
                  "number":"902",
                  "code":"ROOM902",
                  "type":"King Size",
                  "check_in_date":"2020-01-09T12:30:00",
                  "check_out_date":"2020-01-19T13:00:00",
                  "number_of_guests":"1",
                  "board_basis":"Vegan",
                  "guests":[
                     {
                        "name":"José Aníbal",
                        "document":"98798798712",
                        "document_type":"cpf",
                        "birth_date":"12/03/1970",
                        "nationality":"BRA"
                     }
                  ]
               }
            ],
            "category":"categoryhotel"
         }
      ],
      "billing_data":{
         "address":{
            "zip_code":"12341234",
            "street_number":"666",
            "street_name":"Rua Billing",
            "complement":"ap. 2369",
            "city":"São Billing",
            "state":"AM",
            "country":"BRA"
         }
      },
      "travel":{
         "transport_type":"flight",
         "expiration_date":"2022-02-14T01:30:00"
      },
      "discount_info":"Informações de desconto",
      "events":[
         {
            "name":"Evento de Rock",
            "date":"2021-11-22T09:28:00",
            "type":"show",
            "subtype":"music",
            "venue":{
               "name":"Debicard Hall",
               "street_name":"Rua do Evento",
               "street_number":"928",
               "city":"Jardinópolis",
               "state":"MS",
               "country":"DO",
               "capacity":"300"
            },
            "tickets":[
               {
                  "id":"12h374612h4h",
                  "category":"social",
                  "section":"Seção 1",
                  "premium":"true",
                  "attendee":{
                     "name":"Daniel Almeida",
                     "document":"71728293945",
                     "document_type":"other",
                     "birth_date":"03/10/1990"
                  }
               }
            ]
         }
      ]
   }
}

Fraud Detect

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 do Fraud Detect exigem as seguintes credenciais:

• Chave Privada (Identificação da Loja) - Chave Privada do cadastro da loja no Fraud Detect.
• Chave Pública (Merchant Code) - Chave Publica do cadastro da loja no Fraud Detect.

IMPORTANTE: As credenciais acima devem ser obtidas com o Fraud Detect. O lojista deve entrar em contato com o Fraud Detect 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.

Configuração de URL Web Hook

Para que possamos receber as atualizações de status de transações de análise de risco, é necessário realizar a configuração da URL de Webhook no ambiente de configuração do Fraud Detect.

URL de Produção:

https://esitef-ec.softwareexpress.com.br/e-sitef/processarPost.se?src=fraud_detect

URL de Homologação:

https://esitef-homologacao.softwareexpress.com.br/e-sitef/processarPost.se?src=fraud_detect

Essa URL deve ser configurada para qualquer troca de status. Para realizar essa configuração, por favor entre em contato com o Suporte do Fraud Detect.

Bandeiras permitidas

O Fraud Detect suporta qualquer bandeira de cartão.

IMPORTANTE: Apenas as transações de crédito serão efetivamente analisadas pelo Fraud Detect. Transações de débito serão enviadas para a instituição, porém serão apenas armazenadas para relatório e não serão analisadas.

Funcionalidades suportadas

• Link de Pagamento via Portal
• Link de Pagamento via HTML
• Pagamento REST
• Pré-Autorização REST

Parâmetros antifraude do Fraud Detect (Link de Pagamento via HTML)

Por enquanto, os dados coletados para a análise de risco serão apenas os informados durante o checkout do comprador. Em breve novos campos poderão ser enviados na requisição de criação do pagamento.

Campos coletados durante o Checkout

Os campos coletados durante o checkout são:

Campo	Descrição do campo	Obrigatório
Primeiro Nome do Comprador	Primeiro nome do cliente que está realizando a compra.	Sim
Sobrenome do Comprador	Sobrenome do cliente que está realizando a compra.	Sim
CPF do Comprador	CPF do cliente que está realizando a compra.	Sim
Telefone	Telefone do cliente que está realizando a compra.	Sim
E-mail	E-mail do clinte que está realizando a compra.	Sim
Nome (como está no cartão)	Nome que está impresso no cartão utilizado para a compra.	Sim
Endereco completo	Endereço completo para cobrança.	Sim
Complemento	Complemento do endereço de cobrança.	Não
CEP	CEP do endereço de cobrança.	Sim
País	País do endereco de cobrança.	Sim
Estado	Estado do endereço de cobrança.	Sim
Cidade	Cidade do endereço de cobrança.	Sim

Exemplo

Exemplo da requisição de pagamento HTML com análise de risco no Fraud Detect:

{
   "merchant_id":"FRAUDDETECT",
   "merchant_usn":"803208495",
   "order_id":"866705726000010",
   "redirect":"A",
   "style":"N",
   "amount":"100000",
   "authenticate":"0",
   "transaction_type":"payment",
   "payment_link":"true",
   "additional_data":{
      "currency":"BRL",
      "anti_fraud":"enabled_after_auth"
   }
}

Antifraude Fraud Detect no Link de Pagamento via Portal

Para habilitar a antifraude Fraud Detect para Links de Pagamento gerados pelo Portal do Lojista, entre em contato com o suporte do e-SiTef.

Antifraude Fraud Detect via REST

Após realizar o alinhamento cadastral com o suporte do e-SiTef para habilitar a integração com o serviço de anti-fraude, na inicialização de uma transação Pagamento REST (saiba mais) ou Pré Autorização REST (saiba mais) o lojista deve enviar a propriedade anti_fraud e enviar os devidos parâmetros de anti-fraude (depende da instituição que a sua loja foi configurada), sendo que as duas propriedades devem estar no escopo do objeto additional_data.

O campo anti_fraud determina o modo de aplicação da anti-fraude e pode conter os seguintes valores:

• enabled_before_auth - A análise antifraude será realizada ANTES da autorização do pagamento. Caso a análise seja rejeitada, o pagamento não será iniciado. No caso da pré autorização com roteamentos não-SiTef, caso a análise de risco fique como análise manual, a transação de pré será confirmada, cabendo ao Lojista a posterior captura ou cancelamento da pré autorização.
• enabled_after_auth - A análise antifraude será realizada APÓS a autorização do pagamento. Caso a análise seja rejeitada, o pagamento que já foi autorizado será cancelado. No caso da pré autorização com roteamentos não-SiTef a transação sempre será confirmada, cabendo ao Lojista a posterior captura ou cancelamento da pré autorização.

Parâmetros antifraude do Fraud Detect

Abaixo segue a relação de parâmetros antifraude processados pelo Fraud Detect.

Parâmetro	Descrição	Formato	Obrigatório
additional_data	Dados adicionais da transação.
visitor_id	Identificador do visitante obtido no JavaScript do Fraud Detect	< 40 AN	NÃO
additional_data .items[]	Informações relativas aos itens da compra
unit_price	Preço unitário do item em centavos	NÃO	< 10 N
sku	Código de produto do item	NÃO	< 100 AN
quantity	Quantidade de itens	NÃO	< 10 N
id	Identificação única do item que pode ser o código de barras ou UPC do produto.	NÃO	< 100 AN
title	Nome do produto ou serviço	NÃO	< 100 AN
discount_amount	Valor de desconto do produto em centavos	NÃO	< 10 N
description	Descrição do produto	NÃO	< 100 AN
creation_date	Indica a data de publicação do produto no site da loja (Formato: DD/MM/AAAA)	NÃO	= 10 AN
additional_data .payer	Informações relativas ao comprador
id	Identificador único do cliente. Pode ser qualquer valor (sequencial, documento, e-mail) desde que seja consistente em pedidos futuros.	SIM	< 100 AN
name	Nome do cliente.	SIM	< 100 AN
surname	Sobrenome do cliente.	SIM	< 100 AN
email	Endereço de e-mail do cliente.	SIM	< 100 AN
born_date	Data de nascimento do cliente (formato : AAAA-MM-DDTHH:MM:SS)	NÃO	= 19 AN
identification_number	Número de documento fiscal do cliente	NÃO	< 100 AN
creation_date	Data de criação da conta ou cadastro do cliente no site (formato: DD/MM/AAAA )	NÃO	= 10 AN
is_new_client	Boolean indicando se o cliente está usando uma conta recém-criada nesta compra.	NÃO	< 5 T/F
is_vip_client	Boolean indicando se este é um cliente VIP ou comprador frequente.	NÃO	< 5 T/F
additional_data .payer .phones[]	Informações relativas ao telefone do comprador
ddi	DDI do telefone do cliente	NÃO	< 100 AN
ddd	DDD do telefone do cliente.	NÃO	< 100 AN
number	Número de telefone do cliente.	NÃO	< 100 AN
additional_data .billing_data .address	Informações relativas à fatura
street_name	Rua da fatura do cliente com o banco.	NÃO	< 255 AN
street_number	Número da rua da fatura do cliente com o banco.	NÃO	< 255 AN
complement	Complemento do endereço de fatura.	NÃO	< 100 AN
city	Cidade do titular.	NÃO	< 100 AN
state	Estado do titular.	NÃO	< 100 AN
zip_code	CEP do titular.	NÃO	< 100 A N
country	Código do país do titular, seguindo a ISO 3166-1 alfa-3.	NÃO	= 3 AN
additional_data .shipment	Informações relativas à entrega
name	Nome do destinatário.	NÃO	< 100 AN
surname	Sobrenome do destinatário.	NÃO	< 100 AN
additional_data .shipment .address	Informações relativas ao endereço de entrega
street_name	Nome da rua do destinatário.	NÃO	< 255 AN
street_number	Número da rua do destinatário.	NÃO	< 255 AN
complement	Complemento do endereço do destinatário.	NÃO	< 255 AN
city	Cidade do destinatário.	NÃO	< 100 AN
state	Estado do destinatário.	NÃO	< 100 AN
zip_code	CEP do destinatário.	NÃO	< 100 AN
country	Código do país do destinatário, seguindo a ISO 3166-1 alfa-3.	NÃO	= 3 AN
additional_data .travel	Informações relativas à passagem aérea
transport_type	Tipo de viagem. (flight ou bus)	SIM	< 6 AN
expiration_date	Data de expiração. (formato: DD/MM/AAAA )	NÃO	= 10 AN
additional_data .connections[]	Informações relativas às conexões de viagem
journey_type	OUTWARD - para ida RETURN - para volta	SIM	< 7 AN
origin_city	Cidade de origem.	SIM, se transport_type=bus	< 100 AN
destination_city	Cidade de destino.	SIM, se transport_type=bus	< 100 AN
from	Código aeroportuário IATA para o aeroporto de origem	SIM, se transport_type=flight	= 3 AN
to	Código aeroportuário IATA para o aeroporto de destino.	SIM, se transport_type=flight	= 3 AN
departure_date	Date e hora do embarque (formato: AAAA-MM-DDTHH:MM:SS)	SIM	< 17 AN
class	Nome da classe (Ex: economy, business e first)	NÃO	< 8 AN
class_code	Código da classe.	NÃO	< 20 AN
company	Nome da cia aérea.	NÃO	< 20 AN
additional_data .passengers[]	Informações relativas aos passageiros
name	Primeiro nome do passageiro	SIM	< 100 AN
last_name	Sobrenome do passageiro	SIM	< 100 AN
legal_document	Número do documento.	SIM	< 100 AN
legal_document_type	Tipo do documento (5 = passport, qualquer outro número = id)	SIM	< 8 AN
birth_date	Data de nascimento do passageiro (formato: AAAA-MM-DDTHH:MM:SS)	NÃO	< 17 AN
nationality	País de nascimento do passageiro, seguindo a ISO 3166-1 alfa-3.	NÃO	= 3 AN
is_frequent_traveler	Flag de viajante frequente	NÃO	< 5 T/F
is_with_special_needs	Flag de viajante com necessidades especiais	NÃO	< 5 T/F
frequent_flyer_card	Tipo de programa de fidelidade	NÃO	< 255 AN
customer_class	Categoria do programa de fidelidade.	NÃO	< 255 AN
additional_data .hotel_reservations[]	Informações relativas à reserva de hotel
hotel	Nome do hotel.	SIM	< 100 AN
category	Categoria do hotel.	NÃO	< 100 AN
additional_data .hotel_reservations[] .address	Informações relativas ao endereço do hotel
street_name	Rua do hotel.	NÃO	< 255 AN
street_number	Número do hotel.	NÃO	< 255 AN
complement	Complemento do endereço hotel.	NÃO	< 100 AN
city	Cidade do hotel.	NÃO	< 100 AN
state	Sigla do estado do hotel.	NÃO	< 100 AN
zip_code	CEP do hotel.	NÃO	< 100 AN
country	País do hotel, seguindo a ISO 3166-1 alfa-3.	NÃO	= 3 AN
additional_data .hotel_reservations[] .rooms[]	Informações relativas a quartos do hotel
number	Número do quarto.	NÃO	< 100 AN
code	Código do quarto	NÃO	< 100 AN
type	Tipo do quarto.	NÃO	< 100 AN
check_in_date	Date e hora do entrada (formato: AAAA-MM-DDTHH:MM:SS)	SIM	< 17 AN
check_out_date	Date e hora de saída (formato: AAAA-MM-DDTHH:MM:SS)	NÃO	< 17 AN
number_of_guests	Número de pessoas.	NÃO	< 9999 N
board_basis	Regime de alimentação.	NÃO	< 100 AN
additional_data .hotel_reservations[] .rooms[] .guests[]	Informações relativas a hóspedes do quarto
name	Nome do hóspede.	SIM	< 100 AN
document	Número do documento do hóspede.	NÃO	< 8 AN
document_type	Documento usado pelo cliente: cpf rg passport id other	NÃO	< 8 AN
birth_date	Data de nascimento do cliente (formato: AAAA-MM-DDTHH:MM:SS)	NÃO	< 17 AN
nationality	Nacionalidade do hóspede, seguindo a ISO 3166-1 alfa-3.	NÃO	= 3 AN
additional_data .events[]	Informações relativas a dados de um evento
name	Nome do evento.	SIM	< 255 AN
date	Date e hora do evento em UTC (formato AAAA-MM-DDTHH:MM:SS)	SIM	< 17 AN
type	Tipo do evento: show theater movies party festival course sports corporate	SIM	< 9 AN
subtype	Detalhe do tipo do evento.	NÃO	< 255 AN
additional_data .events[] .venue	Informações relativas a dados de local de um evento
name	Nome do local	NÃO	< 255 AN
street_name	Nome da rua	NÃO	< 255 AN
street_number	Número da rua	NÃO	< 255 AN
city	Cidade do local	NÃO	< 255 AN
state	Estado do local	NÃO	< 255 AN
country	Pais do local, seguindo a ISO 3166-1 alfa-3.	NÃO	= 3 AN
capacity	Capacidade do local	NÃO	< 255 AN
additional_data .events[] .tickets[]	Informações relativas aos ingressos de um evento
id	Identificador único do ticket.	NÃO	< 255 AN
category	Categoria do ticket: student senior government social regular	SIM	< 10 AN
section	Seção do ticket.	NÃO	< 255 AN
premium	Indicador de ticket premium	NÃO	< 5 T/F
additional_data .events[] .tickets[] .atendee	Informações relativas ao participante do evento
name	Nome do participante.	NÃO	< 255 AN
document	Documento do participante.	SIM	< 100 AN
document_type	Tipo de documento do participante: cpf cnpj rg passport other	NÃO	< 100 AN
birth_date	Data de nascimento do participante (formato: AAAA-MM-DDTHH:MM:SS)	NÃO	< 17 AN

Exemplo

Exemplo da requisição de criação pagamento REST com análise de risco no Fraud Detect:

{
   "merchant_usn":"2423423434",
   "order_id":"2432342343",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"1300",
   "additional_data":{
      "anti_fraud":"enabled_before_auth",
      "visitor_id":"XKhas09jcks",
      "items":[
         {
            "title":"title1",
            "quantity":"1",
            "unit_price":"1111",
            "description":"description1",
            "id":"id1",
            "discount_amount":"111",
            "sku":"sku1",
            "creation_date":"11/01/2011"
         }
      ],
      "payer":{
         "name":"Marcos",
         "surname":"da Silva",
         "email":"marocs@dasilva.com",
         "born_date":"1990-01-01T11:11:11",
         "creation_date":"02/03/2004",
         "is_new_client":"true",
         "is_vip_client":"true",
         "phones":[
            {
               "number":"333333333",
               "ddd":"22",
               "ddi":"11"
            },
            {
               "number":"666666666",
               "ddd":"55",
               "ddi":"44"
            }
         ],
         "identification_number":"47764543004"
      },
      "shipment":{
         "name":"Fernando",
         "surname":"Bezerra",
         "address":{
            "zip_code":"98764312",
            "street_number":"987",
            "street_name":"Rua Shipment",
            "complement":"ap. 587",
            "city":"São Shipment",
            "state":"MA",
            "country":"BRA"
         }
      },
      "passengers":[
         {
            "name":"Miguel",
            "last_name":"Herrera",
            "frequent_flyer_card":"frequentFlyerCard",
            "legal_document_type":"1",
            "legal_document":"12312312312",
            "birth_date":"1980-07-28T10:40:00",
            "customer_class":"customerClass",
            "nationality":"BRA",
            "is_frequent_traveler":"true",
            "is_with_special_needs":"true"
         }
      ],
      "connections":[
         {
            "company":"Verde",
            "class":"first",
            "from":"GRU",
            "to":"CGH",
            "departure_date":"2023-09-07T07:09:00",
            "journey_type":"OUTWARD",
            "origin_city":"San Juan",
            "destination_city":"Homero Lopez",
            "class_code":"VIP"
         },
         {
            "company":"Rosa",
            "class":"economy",
            "from":"BSB",
            "to":"VCP",
            "departure_date":"2022-10-21T16:39:00",
            "journey_type":"RETURN",
            "origin_city":"San Pablo",
            "destination_city":"Juanito Cruz",
            "class_code":"ECONOMY"
         }
      ],
      "hotel_reservations":[
         {
            "hotel":"Hotel Green Tree",
            "address":{
               "zip_code":"83392019",
               "street_number":"529",
               "street_name":"Rua Hoteleira",
               "complement":"ap. 019",
               "city":"San Hotel",
               "state":"AC",
               "country":"EN"
            },
            "rooms":[
               {
                  "number":"902",
                  "code":"ROOM902",
                  "type":"King Size",
                  "check_in_date":"2020-01-09T12:30:00",
                  "check_out_date":"2020-01-19T13:00:00",
                  "number_of_guests":"1",
                  "board_basis":"Vegan",
                  "guests":[
                     {
                        "name":"José Aníbal",
                        "document":"98798798712",
                        "document_type":"cpf",
                        "birth_date":"12/03/1970",
                        "nationality":"BRA"
                     }
                  ]
               }
            ],
            "category":"categoryhotel"
         }
      ],
      "billing_data":{
         "address":{
            "zip_code":"12341234",
            "street_number":"666",
            "street_name":"Rua Billing",
            "complement":"ap. 2369",
            "city":"São Billing",
            "state":"AM",
            "country":"BRA"
         }
      },
      "travel":{
         "transport_type":"flight",
         "expiration_date":"2022-02-14T01:30:00"
      },
      "discount_info":"Informações de desconto",
      "events":[
         {
            "name":"Evento de Rock",
            "date":"2021-11-22T09:28:00",
            "type":"show",
            "subtype":"music",
            "venue":{
               "name":"Debicard Hall",
               "street_name":"Rua do Evento",
               "street_number":"928",
               "city":"Jardinópolis",
               "state":"MS",
               "country":"DO",
               "capacity":"300"
            },
            "tickets":[
               {
                  "id":"12h374612h4h",
                  "category":"social",
                  "section":"Seção 1",
                  "premium":"true",
                  "attendee":{
                     "name":"Daniel Almeida",
                     "document":"71728293945",
                     "document_type":"other",
                     "birth_date":"03/10/1990"
                  }
               }
            ]
         }
      ]
   }
}

Autorizadoras

O e-SiTef possui o conceito de Autorizadora, que pode representar uma bandeira de cartão, um serviço de pagamento bancário online ou algum outro meio de pagamento online. Exemplos: Visa, Mastercard, American Express, Itaú Shopline, PayPal, PagSeguro, etc.

Troca de Autorizadora

O e-SiTef permite que o lojista configure o meio de pagamento responsável por autorizar as transações de uma determinada bandeira. Por exemplo, um lojista pode preferir que as transações com cartões Visa sejam roteadas pela Cielo enquanto que os cartões Mastercard sejam roteados pela Rede.

Esta flexibilidade para configuração do roteamento dá à loja a possibilidade de tratar promoções de acordo com a bandeira do cartão.

Pensando em como evitar que um usuário selecione a bandeira Visa, mas acabe informando o número de um cartão Mastercard o e-SiTef disponibiliza um mecanismo de verificação e troca da Autorizadora que responderá pela autorização da transação.

Quando for detectado que o comprador selecionou uma bandeira, mas informou um cartão de outra, o lojista pode optar por três ações a serem tomadas pelo e-SiTef:

• Não trocar a autorizadora

  O e-SiTef não toma nenhuma ação, seguindo normalmente com o processo de pagamento. Esta é a opção padrão adotada pelo e-SiTef para as lojas que nada informarem quanto à troca de Autorizadoras durante o pagamento.

• Trocar a autorizadora

  O e-SiTef segue com o processo de pagamento, mas faz a correção (para efeitos informativos) da Autorizadora responsável pelo cartão usado.

• Bloquear transações com troca de autorizadora

  O e-SiTef nega a transação de pagamento quando o cartão informado não corresponde à Autorizadora escolhida. Por exemplo, é escolhido o pagamento com cartão Visa, mas informado um cartão Mastercard.

Todas estas configurações são feitas no sistema de administração backoffice do e-SiTef.

O lojista pode informar no ato do cadastramento sobre qual opção de ação prefere que seja configurada, bem como pode entrar em contato futuramente pedindo para alterar a configuração.

Códigos de Autorizadoras no e-SiTef

Estes códigos podem ser alterados no futuro, e mais códigos de autorizadoras podem ser adicionados sem aviso prévio.

IMPORTANTE: As Autorizadoras que podem ser utilizadas no e-SiTef dependem das possibilidades disponibilizadas pelo roteamento escolhido pelo lojista.

Exemplo: Se o lojista possui um acordo com a adquirente Cielo, e esta garantiu pagamentos via cartão de crédito Visa, a opção Visa roteado pela Cielo será possível pelo e-SiTef.

A coluna "Cód." corresponde ao parâmetro authorizer_id.

Cód.	Autorizadora	HTML	REST
1	VISA
2	MASTERCARD
3	AMERICAN EXPRESS
4	MULTICHECK
5	HIPER
6	AURA
7	ITAÚ SHOPLINE
8	BRADESCO TRANSFERÊNCIA
9	BANCO IBI
12	CABAL
13	POLICARD
15	BIGCARD
16	SUPERCARD
17	EXCARD
18	EDMCARD
19	COOPER CARD
20	CREDMAIS
21	DACASA
22	CREDISHOP
23	OBOÉ
24	SMARTSHOP
25	ACCREDITO
26	COOPLIFE
27	PAGGO
28	VALECARD
29	SOROCRED
30	MAXICRED
31	CREDSYSTEM
32	TREDENEXX
33	DINERS
34	BANESE
35	SICREDI
36	MULTIALIMENTAÇÃO
37	MULTICASH
38	ICARDSPL
40	FORTBRASIL
41	ELO
42	GOODCARD
43	JCB
44	DISCOVER
45	CHINA UNION PAY
46	CREDZ
47	AGIPLAN
48	VEROCHEQUE
49	SAVEGNAGO
50	MASTERCARD ALIMENTAÇÃO
51	MASTERCARD REFEIÇÃO
52	TRICARD
53	ABASTECE AÍ
59	PERSONAL CARD
60	MUFFATO
61	BRASILCARD
62	RIACHUELO PRIVATE LABEL
72	TICKET CAR
73	TICKET CULTURA
81	BRADESCO BOLETO
82	BRADESCO CARTÃO
83	BRADESCO FINANCIAMENTO
86	MARISA PRIVATE LABEL
100	WAPPA REFEIÇÃO
101	WAPPA ALIMENTAÇÃO
115	BRADESCARD PRIVATE LABEL
116	COMPCARD
122	PAN
127	CARTÃO PRESENTE MARISA
160	ORBITALL
161	E-COMMERCE PERNAMBUCANAS
162	CLUB+
163	CARTÃO VUON PRIVATE LABEL
192	AVISTA CREDITO
193	CAMPEÃO PRIVATE LABEL
201	VISA PRIVATE LABEL
202	MASTERCARD PRIVATE LABEL
203	PEELA (GIFT)
206	RENNER REALIZE
207	VR ALIMENTAÇÃO
209	VR REFEIÇÃO
210	VR AUTO
211	VR CULTURA
218	HUG (GIFT)
221	VISA ELECTRON (DÉBITO)
222	VISA PRÉ-PAGO
223	ALELO CULTURA
224	ALELO REFEIÇÃO
225	ALELO ALIMENTAÇÃO
245	COOPERCARD CULTURA
246	COOPERCARD ALIMENTAÇÃO
250	COOP FACIL PRIVATE LABEL
266	CASSOL PRIVATE LABEL
267	EXTRABOM
271	VERDECARD PRIVATE LABEL
279	SODEXO VALE CULTURA
280	SODEXO VALE ALIMENTAÇÃO
281	SODEXO VALE REFEIÇÃO
282	SODEXO GIFT
283	SODEXO PREMIUM
284	SODEXO COMBUSTÍVEL
285	BANESCARD
286	MASTERCARD DÉBITO
287	KOERICH
288	ELO DÉBITO
289	VALECARD VOUCHER
300	SAFETYPAY
400	PAYPAL
401	BCASH
402	MERCADO PAGO
403	PAGSEGURO
404	BANCO DO BRASIL BOLETO
405	GOOGLE PAY
406	VISA CHECKOUT
407	MASTER PASS
408	BANCO DO BRASIL TRANSFERÊNCIA
409	ALELO AUTO
410	SAMSUNG PAY
411	BANRI COMPRAS À VISTA
412	BANRI COMPRAS PARCELADO
413	BANRI COMPRAS PRÉ-DATADO
414	CASA SHOW
415	BANCO DO BRASIL DÉBITO PF
416	BANCO DO BRASIL DÉBITO PF E PJ
417	BANCO DO BRASIL CREDIÁRIO
430	SENFF
431	VEE
433	VEROCARD
434	BRASIL CONVÊNIOS
436	VEROCARD CULTURA
437	VEROCARD ALIMENTAÇÃO
438	VEROCARD REFEIÇÃO
439	VEROCARD COMBUSTÍVEL
440	PIX
441	VEGAS CARD CRÉDITO
442	VEGAS CARD DÉBITO
443	VEGAS CARD ALIMENTAÇÃO
444	VEGAS CARD REFEIÇÃO

Também é possível identificar o authorizer_id das Autorizadoras cadastradas ao cliente, acessando o Portal do Lojista do e-SiTef através do site http://esitef-homologacao.softwareexpress.com.br/e-sitef-loja (para ambiente de homologação).

Na coluna ID da Autorizadora conforme o exemplo da figura abaixo, temos o valor do authorizer_id.

Lembrando que as autorizadoras são sempre associadas a um Roteamento no BackOffice do e-SiTef.

Este Roteamento define, por exemplo, a adquirente responsável pelo roteamento das transações via crédito.

Orientações para o uso de Certificados Digitais

Introdução

O propósito deste documento é orientar o cliente que integrará seu produto com o e-SiTef sobre o uso de Certificados Digitais.

O intuito deste é apresentar de forma simplificada pequenas orientações sobre o uso destes para garantir a segurança da comunicação entre o e-SiTef e o produto do cliente.

Caso seja necessário um aprofundamento maior sobre os assuntos apresentados, sugerimos consultar outras literaturas e/ou fontes na Internet.

Certificado Digital

O Certificado Digital ou Certificado de chave pública (apenas ‘certificado’ daqui em diante) é um documento digital que tem o propósito de certificar a identidade de uma pessoa, ou entidade na comunicação digital. Uma forma de comunicação digital segura muito utilizada na Internet é o HTTPS, que é uma abreviação de HTTP via SSL/TLS.

O certificado em geral é solicitado pela pessoa ou entidade e emitido por uma CA (Autoridade Certificadora, ou Certification Authority, em inglês) como Verisign, CertSign, etc. Um certificado válido é aquele que, entre outros requisitos, esteja dentro da sua data de validade e assinado por uma CA confiável.

Como exemplo de seu uso, quando utilizamos um browser (Firefox, Chrome, etc..) para acessar um site que oferece segurança na comunicação usando HTTPS, em geral é apresentado o certificado utilizado pelo servidor do site, em geral simbolizado por um ícone de cadeado que se localiza próximo ao local que se apresenta a URL. Clicando neste ícone cadeado é possível observar as características deste certificado.

A característica principal de um certificado é o nome para qual ele é emitido, isto é, qual é o nome identificado no certificado. Na imagem abaixo podemos visualizar as informações, onde o certificado é emitido pela CA “Network Solutions DV Server” e emitido para o nome esitef.softwareexpress.com.br

Certificados self-signed

Para ambientes de testes, existem casos em que a obtenção de um certificado válido não é viável, então algumas vezes é utilizado um certificado auto-assinado ou self-signed.

Um certificado self-signed é gerado e assinado pela própria pessoa/entidade, e não é aceito como confiável para uma comunicação segura. Como exemplo, quando se acessa um site via browser via HTTPS, onde o servidor utiliza um certificado self-signed, um aviso semelhante às imagens abaixo é apresentado no browser:

Firefox

Chrome

Internet Explorer

Ao navegar nesses sites que utilizam certificados self-signed, temos a opção de confiar no site e acessá-los, mesmo sabendo que o certificado apresentado neles não é confiável, assumindo o risco de acessar e enviar informações para um site que não possui o certificado confiável ou até com um certificado que não possui a identidade de quem ele diz ser. Isto pode ser aplicado também na comunicação entre servidores.

Comunicação do e-SiTef com servidores de clientes

O e-SiTef frequentemente se comunica com servidores de clientes via POST’s HTTPS, para validar a autenticidade da requisição, como em transações de recarga e estorno de pagamentos. Para esta comunicação, é necessário que o servidor do cliente apresente certificados válidos para garantir a segurança das informações transmitidas. No ambiente de produção do e-SiTef, em geral todos os clientes já possuem uma infraestrutura pronta, com servidores com seus respectivos certificados válidos e assinados por CA’s reconhecidas no mercado.

Porém, na etapa de homologação, muitos sistemas ainda estão em fase de testes ou em desenvolvimento, utilizando certificados temporários, e muitas vezes self-signed. Neste caso, utilizamos uma abordagem semelhante à citada no item anterior, abrindo exceções para que o e-SiTef confie em um servidor que apresente um certificado self-signed. Isso é feito importando-o em uma lista de certificados confiáveis. Assim facilitamos o processo de homologação dos sistemas de clientes.

Como a tecnologia utilizada no e-SiTef segue a especificação de comunicação HTTPS RFC-2818, esta abordagem possui algumas restrições:

• O certificado precisa estar válido, isto é, no mínimo deve estar com sua data de validade adequada para o período em uso;

• A identificação do servidor do cliente deve ser compatível com o nome apresentado no certificado. Logo, as seguintes situações irão resultar em fracasso na comunicação:

  • Um certificado emitido para www.dominio.com não será compatível para um servidor identificado como dominio.com ou testes.dominio.com, pois são consideradas identificações diferentes.
  • Um servidor com um IP único, mas com múltiplos domínios e respectivamente múltiplos certificados, pode ser identificado de formas diferentes e inesperadas.

• A especificação não permite certificados emitidos para o endereço IP de um servidor, a não ser que Nomes Alternativos(Subject Alternative Names) de IP’s ou domínios sejam adicionados ao certificado.

Logo, certificados que estejam em condições fora da especificação não serão aceitos na comunicação HTTPS mesmo que sejam importados na lista de certificados confiáveis no e-SiTef. Esta exigência no ambiente de homologação do e-SiTef acaba por preparar o cliente a fim de garantir o uso de um certificado corretamente emitido por uma CA para o sistema no ambiente de produção.

Criação de certificados self-signed

Existem várias formas já conhecidas para gerar certificados auto-assinados ou self-signed. Aqui iremos apresentar uma delas, utilizando a ferramenta openssl, que pode ser encontrada em pacotes do servidor web Apache. Todos as referências e comandos apresentados a seguir são baseados nas versões Apache HTTP 2.2 e openssl 0.9.8 em ambiente Windows. Caso seja da preferência do cliente, um procedimento análogo pode ser executado em ambiente Linux, com as devidas ferramentas e adaptações.

Como preparação de ambiente, sugerimos:

• Crie uma pasta separada de nome openssl (ou escolha outro nome qualquer) e copie três arquivos existentes em %APACHE_HOME%/bin: libeay32.dll, ssleay.dll e zlib1.dll. Copie esses arquivos no diretório: Windows\System32.
• Copie o arquivo openssl.exe existente em %APACHE_HOME%/bin para o diretório openssl.
• Copie o arquivo openssl.cnf existente em %APACHE_HOME%/conf para o diretório openssl.

Configuração do openssl: openssl.cnf

O arquivo openssl.cnf contém as configurações para a geração de certificados. Inicialmente, crie uma cópia deste com outro nome (por exemplo openssl_editado.cnf ou um nome da sua preferência).

Sugerimos editar os seguintes campos do arquivo openssl_editado.cnf para facilitar o seu uso futuro:

• Descomente (remova o caractere #) do início da seguinte linha:

  req_extensions = v3_req # The extensions to add to a certificate request

• Logo abaixo, adicione ou altere valores default para os campos:

  • countryName_default = BR (ou outro país)
  • stateOrProvinceName_default = <nome do estado>
  • localityName_default = <Nome da cidade>
  • 0.organizationName_default = <Nome da Empresa>
  • organizationalUnitName_default = <nome do setor, equipe>
  • commonName_default = <nome comum a ser registrado>
  • emailAddress_default = <email>

• Após o trecho:

    [ v3_req ]
  
    # Extensions to add to a certificate request
  
    basicConstraints = CA:FALSE
    keyUsage = nonRepudiation, digitalSignature, keyEncipherment
  

• Adicionar:

    subjectAltName=@alt_names
  
    [alt_names]
  

• E então, logo abaixo adicionar nome alternativos ao commonName, em forma de DNS ou IP como nos exemplos abaixo, conforme necessidade de identificação do servidor:

    DNS.1 = www.dominio.com
    DNS.2 = *.dominio.com
    ...
    IP.1 = 192.168.4.34
    IP.2 = 200.122.10.66
    ...
  

Assim se finaliza a customização do arquivo de configuração do openssl.

Comandos openssl para gerar o certificado

Supondo que queremos gerar um certificado de nome dominio.

• Criar uma chave privada RSA de 2048 bits executando o seguinte comando no diretório openssl:

    openssl genrsa -out dominio.pem 2048
  

• Execute o comando abaixo para requisitar a criação do certificado

    openssl req -config openssl_editado.cnf -extensions v3_req -new -out dominio.cer -keyout dominio.pem
  

Após a execução desse comando serão pedidos alguns dados (Pais, Estado, Cidade, Nome e Unidade da Organização, email) de preenchimento opcional e dois de preenchimento obrigatório: o Common Name que é o domínio associado ao certificado (ou o IP do servidor) e uma senha para ser associada a chave privada. Por padrão, aceite as opções default sugeridas.

• A seguir execute o comando abaixo para criar a chave privada não protegida por senha (a senha associada à chave privada será removida). Dessa forma, a chave será legível apenas para o servidor Apache e o administrador:

    openssl rsa –in dominio.pem –out dominio.key
  

Após a execução desse comando será pedida a senha da chave privada.

É recomendado a remoção do arquivo .rnd, pois ele contém informações sigilosas a respeito da criação da chave. Removendo-o evita-se ataques criptográficos contra a chave privada.

• Por último, execute o comando abaixo para criar o certificado assinado que durará um ano:

    openssl x509 -in dominio.cer -out dominio.cer -req -signkey dominio.key -days 365 -extensions v3_req extfile openssl_editado.cnf
  

Os arquivos dominio.cer e dominio.key serão usados no servidor.

Instalação do certificado self-signed gerado no servidor Apache

Aqui apresentaremos um exemplo de instalação do certificado no servidor HTTP Apache 2.2.

• Na pasta onde o Apache está instalado, abrir a pasta conf e abrir o arquivo de configuração httpd-ssl.conf;

• Editar os seguintes itens abaixo no arquivo httpd-ssl.conf:

    ServerName <nome/dominio ou IP do servidor> 
  

  Ex: www.dominio.com.br ou IP 200.###.###.###

    SSLCertificateFile <caminho+nome do certificado> 
    Ex: `%APACHE_HOME%/conf/dominio.cer`
  
    SSLCertificateKeyFile <caminho+nome do arquivo de chave do certificado> 
  

  Ex: %APACHE_HOME%/conf/dominio.key

• Reiniciar o Apache

Verificação do certificado gerado

Para verificar se o certificado foi gerado e instalado corretamente, abra um browser de sua preferência e digite a URL por qual o Apache responde, e clique no ícone do cadeado para abrir o certificado. As figuras abaixo ilustram a visualização do certificado em diferentes ambientes:

Detalhe do certificado no ambiente Windows

Detalhe do certificado no Firefox

Códigos da API

Status de transações do e-SiTef

Código	Nome	Descrição
NOV	Nova	Transação recém-criada.
INV	Inválida	Transação não foi criada com sucesso, provavelmente a loja enviou algum parâmetro incorreto, e não foi possível inicializar a transação corretamente.
PPC	Pendente de confirmação	Pagamento pendente de confirmação.
PPN	Desfeita	Pagamento pendente não confirmado (cancelado).
PEN	Aguardando pagamento	Transação aguardando resposta da instituição financeira.
CON	Efetuada	Transação confirmada pela instituição financeira.
NEG	Negada	Transação negada pela instituição financeira.
ERR	Erro ao efetuar pagamento	Erro na comunicação com a autorizadora. Tente novamente.
BLQ	Bloqueada	Transação bloqueada após múltiplas tentativas de consulta de cartão.
EXP	Expirada	A transação expirou devido ao prazo de validade do NIT.
EST	Estornada	Pagamento estornado.
AGU	Aguardando Usuário	Transação aguardando ação do usuário.
ABA	Abandonada	Transação expirou devido a tempo excessivo sem atualização por parte do usuário.
CAN	Cancelada	Transação cancelada pelo usuário/comprador.
RET	Retentativa	Transação negada pela instituição financeira, porém agendada para retentativa.

Status de agendamento

Código	Nome	Descrição
NOV	Novo	Transação recém-criada.
INV	Inválido	Transação não foi criada com sucesso, provavelmente a loja enviou algum parâmetro incorreto e não foi possível inicializar a transação corretamente.
PEN	Pendente de confirmação	Agendamento pendente de confirmação.
DES	Desfeito	Agendamento pendente desfeito.
ATV	Ativo	Agendamento ativo para execução de transações recorrentes.
INA	Inativo	Agendamento está inativo e não executará pagamentos recorrentes.
ERR	Erro	Erro ao ativar agendamento.
FIN	Finalizado	Agendamento já executou todos os pagamentos recorrentes e foi finalizado.
EXP	Expirado	A transação expirou devido ao prazo de validade do SID.

Status de armazenamento

Código	Nome	Descrição
CON	Confirmado	Armazenamento realizado com sucesso.
INV	Inválido	Armazenamento não foi realizado com sucesso, provavelmente a loja enviou algum parâmetro incorreto e não foi possível inicializar a transação corretamente.
NEG	Negado	O cartão foi consultado no SiTef e foi categorizado como inválido.
DUP	Duplicado	Tentativa de armazenar um cartão já guardado no e-SiTef pela loja.
CAN	Cancelado	Armazenamento do cartão cancelado pelo cliente. Dados removidos do e-SiTef a pedidos da loja.
DEL	Deletado	Dados do cartão foram removidos do e-SiTef a pedidos do dono do cartão.
BLQ	Bloqueado	Armazenamento bloqueado por possível tentativa de fraude.

Códigos de resposta

Código	Descrição
0	Transação OK
1	Campo NIT nulo
2	Request enviado é nulo
3	Campo NIT inválido
4	Campo authorizerId nulo
5	Campo authorizerId inválido
6	Campo autoConfirmation nulo
7	Campo autoConfirmation vazio
8	Campo cardExpireDate nulo
9	Campo cardExpireDate inválido
10	Campo cardNumber nulo
11	Campo cardNumber inválido
12	Campo cardSecurityCode nulo
13	Campo cardSecurityCode inválido
14	Campo installments nulo
15	Campo installments inválido
16	Campo installmentType nulo
17	Campo installmentType inválido
18	Campo customerId nulo
19	Campo customerId inválido
20	Campo departureTax nulo
21	Campo departureTax inválido
22	Campo firstInstallment nulo
23	Campo firstInstallment inválido
24	Campo softDescriptor nulo
25	Campo softDescriptor inválido
26	Campo merchantKey nulo
27	Campo merchantKey inválido
28	Campo nsuSitef nulo
29	Campo nsuSitef inválido
30	Campo merchantId nulo
31	Campo merchantId inválido
32	Campo amount nulo
33	Campo amount inválido
34	Campo esitefUSN nulo
35	Campo esitefUSN invalid
36	Campo merchantUSN nulo
37	Campo merchantUSN inválido
38	Campo ordered inválido
39	Campo parameter inválido
40	Campo parameter nulo
41	Campo parameterNumber inválido
42	Campo jsonXml nulo
43	Campo jsonXml inválido
44	Método nulo
45	Método inválido
46	Campo url inválido
47	Campo redirect inválido
48	Campo card_hash nulo
49	Campo card_hash inválido
50	Campo financing_type nulo
51	Campo financing_type inválido
52	Campo sitef_ip inválido
53	Campo sitef_port inválido
54	Campo sitef_terminal inválido
55	Campo sitef_merchant_id inválido
56	Campo confirmation_data inválido
57	Campo confirmation_type inválido
58	Campo inner_transactions vazio ou nulo
59	Campo extra_field inválido
60	Campo prefixes / key vazio
61	Campo prefixes / value vazio
62	Campo additional_data inválido
63	Campo prefixes inválido
64	Campo financing_type com juros não permitido
68	Campo dealer_code nulo
69	Campo dealer_code inválido
70	Campo phone_ddd nulo
71	Campo phone_number nulo
72	Campo amount_key inválido
73	Campos card_number e card_token não podem ser utilizados simultaneamente
74	Campo amount não pode ser pré-fixado para recarga
75	Campo phone_ddd inválido
76	Campo phone_number inválido
77	Campo store_card inválido
78	Campo store_identification nulo
79	Campo recharge_included inválido
80	Autorizadora não implementada para mobile
81	Operação não permitida
82	Transação não encontrada
83	Campo store_identification inválido
84	Armazenamento não permitido para a autozadora escolhida
85	Campo purchase_summary invalido
86	Lista de itens vazia
87	Campo authenticate inválido
88	Cartão inválido. Verifique o número do cartão ou a forma de pagamento escolhida.
89	Erro ao recuperar a transação
100	Falha ao efetuar transação de pagamento
101	Falha ao confirmar transação de pagamento
102	Transação já finalizada ou em andamento
103	Tipo de transação inválido
104	Autorizadora para a transação inválida
105	Estilo da transação inválido
106	Loja sem permissão para a operação
107	Operação não permitida para o status da transação
108	Autorizadora inativa ou não habilitada para a loja.
109	Parcelas excedem o limite configurado na autorizadora
110	Loja inativa
111	Tipo de Autorizadora Inválida
112	Autorizadora com configuração inválida
113	Autorizadora não habilitada ou inativa para a Loja.
114	Transação Bloqueada.
115	Erro de autenticidade
116	Erro na consulta de transação. Por favor tente novamente mais tarde.
131	Falha de comunicação com o SiTef
132	Request mal formatado
134	Erro na consulta de cartão (card query)
135	Loja não possui permissão para pagamento Split.
136	Falha no rollback
137	Operação inválida.
138	Falha na escolha de autorizadora
139	Não existe autorizadora configurada
140	Consulta devolveu muitas autorizadoras, não foi possível identificar unicamente
141	A autorizadora passada não é roteada via SiTef
142	Erro ao consultar cartão: resposta inesperada da autorizadora
143	O número de cartão enviado não corresponde à forma de pagamento escolhida.
144	Loja sem permissão para Recarga V5 HTML
145	Loja sem permissão para Recarga V5 WebService
146	Erro na autenticação
147	Autenticação Negada
148	Autenticação não permitida para esta autorizadora
149	Loja sem dados cadastrais de autenticação ISA
150	Request inválido
157	Campo showTimesInvoice inválido
160	Loja sem permissão para transações HTML
161	Loja sem permissão para transações de pagamento
162	Loja sem permissão para transações IATA
163	Cadastro da Autorizadora com erros.
215	Venda com cartão tipo Gift não habilitada
216	Recarga de cartão tipo Gift não habilitada
217	Cancelamento de pagamento via cartão tipo Gift não habilitada
230	campo payer neighborhood inválido
231	campo payer uf inválido
232	campo payer name inválido
233	campo payer address_street_name / address_street_number inválido
234	campo payer identification_number inválido
235	campo payer city inválido
236	campo payer zipcode inválido
255	Pagamento negado
256	Aguardando resposta do cancelamento
257	Estorno negado
258	Recarga negada
259	Transação negada
260	Recarga desfeita por falha no pagamento
261	Recarga deve ser reenviada
300	Erro ao criar transação de refund
301	Campo card_number diferente
302	Falha de comunicação
304	Campo extra_info inválido
305	Campo currency inválido
306	Campo insurance_amt inválido
307	Campo handling_amt inválido
308	Campo tax_amount inválido
309	Campo inner_transaction order_id inválido
310	Campo inner_transaction merchant_id inválido
311	Campo inner_transaction merchant_usn inválido
312	Campo inner_transaction amount inválido
313	campo shipment type inválido
314	Campo shipment cost inválido
315	Campo shipment discount_amount inválido
316	Campo shipment receiver_address_apartment inválido
317	Campo shipment receiver_address_floor inválido
318	Campo shipment receiver_address_street_name inválido
319	Campo shipment receiver_address_street_number inválido
320	Campo shipment receiver_address_zip_code inválido
321	Campo shipment receiver_address_complement inválido
322	Campo shipment receiver_address_district inválido
323	Campo shipment receiver_address_city inválido
324	Campo shipment receiver_address_state inválido
325	Campo shipment receiver_address_country inválido
326	Campo shipment receiver_address_name inválido
327	Campo shipment receiver_address_phone_area_code inválido
328	Campo shipment receiver_address_phone_number inválido
329	Campo payment_method installments inválido
330	Campo payment_method excluded_payment_method id inválido
331	Campo payment_method excluded_payment_method name inválido
332	Campo payment_method excluded_payment_method payment_type_id inválido
333	Campo payment_method excluded_payment_method thumbnail inválido
334	Campo payment_method excluded_payment_method secure_thumbnail inválido
335	Campo payment_method excluded_payment_type id inválido
336	Campo payment_method excluded_payment_type name inválido
337	Campo payer phone_number inválido
338	Campo payer phone_area_code inválido
339	Campo payer date_created inválido
340	Campo payer email inválido
341	Campo payer born_date inválido
342	Campo payer mother_name inválido
343	Campo payer father_name inválido
344	Campo payer sex inválido
345	Campo payer phone_country_code inválido
346	Campo payer phone_extension inválido
347	Campo payer phone_extension_type inválido
348	Campo payer tax_type inválido
349	Campo payer address_type inválido
350	Campo item id inválido
351	Campo item description inválido
352	Campo item category_id inválido
353	Campo item picture_url inválido
354	Campo item unit_price inválido
355	Campo item quantity inválido
356	Campo item title inválido
357	Campo item weight inválido
358	Campo item shipping_cost inválido
359	Campo item quantity_itens_sum inválido
360	Campo item tax_amount inválido
361	Campo item weight_unit inválido
362	Campo item length inválido
363	Campo item length_unit inválido
364	Campo item width inválido
365	Campo item width_unit inválido
366	Campo item height inválido
367	Campo item height_unit inválido
368	Campo item url inválido
369	Campo item type inválido
370	Campo extra_param metadata_item key inválido
371	Campo extra_param metadata_item inválido inválido
372	Campo extra_param metadata_item group inválido
373	Campo extra_param prefix key inválido
374	Campo extra_param prefix value inválido
375	Campo extra_param acquirer_param key inválido
376	Campo extra_param acquirer_param value inválido
400	Transação abortada
723	Condições enviadas para a adquirentes não suportadas. / Credenciais da adquirente inválidas.
724	Campo max_installments inválido
910	Transação negada pela e-Rede.
920	Transação negada pela Cielo e-Commerce.
930	Erro na comunicação com a Visa Checkout.
934	Erro na autorizadora Masterpass ao transacionar.
940	Transação negada pela GetNet WS.
941	Usuário não autenticado na GetNet WS.
942	Nome de usuário inválido.
943	Senha inválida.
944	Id do comerciante inválido.
945	Faixa de ID do comerciante.
946	ID do terminal.
947	Campo de cartão nulo.
948	Id de pagamento nulo.
949	PARes nulo.
950	Transação negada pela Global Payments WS.
951	Requisição nula.
952	Código de comerciante inválido.
953	Terminal inválido.
954	Assinatura inválida.
970	Transação negada pela SafetyPay.
971	Motivo de reembolso nulo.
972	Credencial nula.
980	Titular do cartão nulo.
981	Chave de pedido nula.
989	Instituição antifraude inválida para notificar.
990	ID de comerciante nulo.
991	Código de comerciante nulo.
992	Tipo de pagamento inválido para antifraude.
993	Autorizadora inválida para antifraude.
994	Pagamento Split não permitido para antifraude.
995	Transação do tipo recarga não permitida para antifraude.
996	Entidade para análise antifraude não cadastrada.
997	Loja sem permissão para antifraude.
998	Análise antifraude rejeitada, inválida ou em revisão.
999	Item id do antifraude nulo.
1000	Erro inesperado no e-SiTef. Entre em contato com o suporte.
1003	Erro inesperado no e-SiTef. Entre em contato com o suporte.
1004	Erro inesperado no e-SiTef. Entre em contato com o suporte.
1010	Erro inesperado de acesso à base de dados do e-SiTef. Entre em contato com o suporte.
1135	Campo additional_data application_fee inválido
1136	Campo additional_data binary_mode inválido
1137	Campo additional_data discount_campaign_id inválido
1138	Campo additional_data acquirer_expiry_date inválido
1139	Campo additional_data description inválido
1140	Campo payer type inválido
1141	Campo additional_data acquirer_expiry_date_from inválido
1142	Campo additional_data acquirer_expiry_date_to inválido
1143	Campo additional_data acquirer_expires inválido
1144	Campo shipment mode inválido
1145	Campo shipment local_pickup inválido
1146	Campo shipment dimensions inválido
1147	Campo shipment default_shipping_method inválido
1148	Campo shipment free_shipment inválido
1149	Campo shipment free_methods id inválido
1150	Campo ad_tracks type inválido
1151	Campo ad_tracks conversion_id inválido
1152	Campo ad_tracks conversion_label inválido
1153	Campo ad_tracks pixel_id inválido
2000	Erro inesperado no e-SiTef. Entre em contato com o suporte.
5555	Erro inesperado no e-SiTef. Entre em contato com o suporte.

Códigos de resposta negativos (Roteamentos via SiTef)

Em roteamentos via SiTef é possível sejam retornados códigos de resposta negativos ( por exemplo, "-211"). Em casos como este, entre em contato com o nosso suporte.

Soft Descriptor

O soft-descriptor é um texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Este texto pode ser definido no cadastro da loja ou na requisição de criação de pagamento/pre-autorização.

O e-SiTef aceita até 30 caracteres alfanuméricos, porém conforme regras documentadas nas integração com as adquirentes, este pode ser truncado para o tamanho especificado. O soft-descriptor é um dado opcional.

Atenção: Sugere-se que o lojista sempre valide com a adquirente o tamanho, formato e as condições de apresentação desta funcionalidade.

Roteamentos via SiTef

Cada roteamento via SiTef que aceita soft-descriptor possui um formato específico. O tamanho excedido do soft-descriptor recebido pelo e-SiTef será removido.

Roteamento	Formato e Tamanho
Cielo	< AN 13
Stone	< AN 25
Getnet	< AN 22
Banrisul	< AN 22
Cabal	< AN 22
Rede	< AN 22
BIN	< AN 25
SiPAG	< AN 25

Roteamentos não-SiTef

Cielo e-Commerce

Apenas para cartões Visa e Mastercard. O tamanho limite é de 13 caracteres alfanuméricos.

e-Rede

O limite é de 13 caracteres alfanuméricos.

Exige a habilitação da função "identificação fatura" no cadastro da loja na e-Rede.

e.Rede REST

O limite é de 13 caracteres alfanuméricos para ser cadastrados no backoffice e-SiTef ou enviados na requisição da transação.

São apresentados na fatura 8 caracteres estáticos que representam o estabelecimento, mais um asterisco *, mais a parte dinâmica dos 13 caracteres citados acima.

Exemplo: nomeLoja*parteDinamica

Exige a habilitação da função "identificação fatura" no cadastro da loja na plataforma e.Rede REST.

Stone WS

Se a transação for Visa, o limite é 25 caracteres;

Se a transação for Mastercard, o limite é 22 caracteres;

Se for parcelado, a Visa utiliza os 8 primeiros caracteres do nome do lojista pra passar a informação de parcelamento, sobrando 17 caracteres.

Getnet WS

No caso do lojista não cadastrar ou não enviar o soft-descriptor no e-SiTef, a Getnet utilizará o nome fantasia do cadastro do Estabelecimento Comercial.

Este campo deve ser composto da seguinte forma:

• Identificação do Facilitador, com 3, 7 ou 12 caracteres
• Caractere de separação * (asterisco)
• Identificação do subcomércio

O tamanho máximo é de 20 caracteres.

PayPal

Para o PayPal, formato apresentado será o seguinte:

<PP *> ou <PAYPAL *><Nome Fantasia cadastrado nas preferências da loja na PayPal><espaço><soft-descriptor>

• Regras de caracteres permitidos para o campo soft descriptor:
  • Caracteres alfanuméricos
  • hífen -
  • asterisco *
  • ponto .
  • espaco
• Tamanho máximo de 22 caracteres para o texto totalizado.

Exemplo de uso:

• Prefixo definido como PAYPAL * nas configurações administrativas no PayPal;
• O nome fantasia cadastrado nas configurações do lojista na PayPal é EBAY
• O soft-descriptor passado via e-SiTef é Suzana Flores LTDA.
• O texto apresentado na fatura do portador do cartão será PAYPAL *EBAY Suzana Fl

SafraPay

Para o SafraPay, o campo soft descriptor permite um tamanho máximo de 22 caracteres, em que strings maiores enviadas nesse campo serão truncadas neste limite.

• São permitidos os seguintes caracteres:
  • alfanuméricos em letra maiúscula e sem acento;
  • % $ , . / & ( ) + = = < > - *
• Exemplo de campo válido: LOS*POLLOS*HERMANOS*2
• Exemplos de campo inválidos:
  • los*pollos*hermanos (letras minúsculas)
  • MOE'S_BAR (uso dos caractere especiais ' e _)

O campo soft descriptor pode ser enviado nas seguintes transações:

• Crédito com Captura Tardia
• Crédito com Captura Automática
• Estorno de Transação
• Desfazimento de Transação

GlobalPaymentsWS

Para a Global Payments, o soft descriptor deve conter um texto de até 13 caracteres que será impresso na fatura do portador, ao lado da identificação da loja, respeitando o comprimento das bandeiras:

• Visa: 25 caracteres
• Mastercard: 22 caracteres

[Nome da Loja] + [Asterico] + [Soft Descriptor] = [22 ou 25] caracteres

Na eventualidade da soma do nome da loja e soft descriptor exceder o limite de caracteres, o texto do soft descriptor será truncado da direita para esquerda. Lembrando ainda que o espaço em branco entre o nome da loja e o texto é contabilizado como 1 caractere.

Uso exclusivo de caracteres simples, sem acentuação e especiais.

Autenticação com assinatura

Para garantir maior comodidade e segurança aos seus clientes, o e-SiTef oferece, além da autenticação através da chamada POST à URL cadastrada (saiba mais), a opção de assinatura de mensagens, em que conteúdo e remetente passam a ter garantias de integridade e autenticidade, respectivamente. Dessa forma, a loja recebe as informações da transação recém-criada diretamente na resposta de sua chamada REST e não mais através do POST de autenticidade.

O que você precisará

• Cadastro ativo no ambiente de homologação do e-SiTef (obtido com nossa equipe de suporte);
• A criação de uma chave pública e o gerenciamento da sua respectiva chave privada;
• Cadastro da chave pública no e-SiTef (feito através da nossa equipe de suporte).

Criando as chaves pública e privada

Exemplos de como criar as chaves privada e pública:

• No Linux (utilizando o terminal):

# criando a sua chave privada:
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key

# criando uma chave pública a partir da chave privada criada:
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

• No Windows:

Utilizar ssh-keygen no prompt de comando

# criando a sua chave privada:
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key

Utilizar uma versão do openssl para windows, executar como administrador e executar o seguinte comando:

# criando uma chave pública a partir da chave privada criada:
rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

Atenção:

Esse arquivo de chave pública jwtRS256.key.pub é o único arquivo que você deverá enviar pra nossa equipe de suporte. Sempre mantenha seguros a sua chave privada e a sua senha, caso tenha cadastrado uma.

Algoritmo de assinatura

O algoritmo suportado pela aplicação é o RS256 em conjunto com o padrão JWT (RFC 7519).

Ao utilizar este padrão, uma assinatura é composta por três partes: cabeçalho, dados (payload) e a verificação de assinatura. A cada uma dessas partes, é aplicada uma codificação Base64.

Primeira parte (cabeçalho)

O cabeçalho deve conter o seguinte conteúdo fixo:

{
  "alg": "RS256",
  "typ": "JWT"
}

Cabeçalho Base64:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Segunda parte (payload)

A parte de dados (payload) varia de acordo com a operação a ser assinada. Exemplo:

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "order_id": "182367r12831t29b",
  "merchant_usn" : "92837429837",
  "timestamp": "1605034925174"
}

Payload Base64:

eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0

Composição do payload

Dependendo do serviço chamado, os campos do payload serão diferentes. Abaixo estão descritos os campos necessários para cada serviço.

Serviços de criação e listagem de lojas

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef.	= 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef.	< 80 AN	SIM
timestamp	Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.	< 13 N	SIM

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "timestamp": "1605034925174"
}

Serviços de edição e consulta de loja

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	= 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
timestamp	Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.	< 13 N	SIM
registered_merchant_id	Código da loja criada ou a ser criada no e-SiTef. Os códigos de produção e certificação serão diferentes.	= 15 AN	SIM

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "registered_merchant_id": "YYYYYYY",
  "timestamp": "1605034925174"
}

Serviços de criação de transação

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	= 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
order_id	Código do pedido definido pelo lojista.	< 40 AN	SIM
merchant_usn	Número sequencial único para cada pedido, criado pela loja.	< 12 N	SIM
timestamp	Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.	< 13 N	SIM

Exemplo:

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "order_id": "182367r12831t29b",
  "merchant_usn" : "92837429837",
  "timestamp": "1605034925174"
}

Demais serviços

Parâmetro	Descrição	Formato	Obrigatório
nit	Identificador da transação no e-SiTef.	= 64 AN	SIM
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	= 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
timestamp	Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.	< 13 N	SIM

Exemplo:

{
  "nit":"asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678",
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "timestamp": "1605034925174"
}

Terceira parte (verificação)

A terceira e última parte é o resultado da criptografia RSA das duas partes anteriores codificadas separadamente em Base64 e concatenadas por um ponto (".").

Duas partes anteriores codificadas seperadamente em Base64 e concatenadas por um ponto ("."), onde o primeiro segmento do texto - anterior ao ponto - corresponde ao cabeçalho e o segundo corresponde ao payload:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0

Por fim, uma criptografia RSA, usando a chave privada loja, deve ser feita neste conteúdo. Exemplo:

LLQ2kaC3dG0tsu78JyEIbvd8c1G05lo-1qLDBb0lBXsS2lrJ98-rcusEhuodhHDBE701a_RZwCfOH9ebPZXYdEtuLldqp_Q47y_AYOBYuz3eexuVC0sH3MvmljjHEiMYEIKtFyhsSFrBuQBFvBOT4tJCA779j_cP-JnW4MeDazDehsydEa6phsmkGg_0YfN2xdRzaaTrQqldYibUeI7_YEwLTYrZg0Ys7r45quT7veAzNFLEL4I3iJmMJUcBaCfIQl6NKvX7meoSBeFBaj_MRw8WwXnNTjCFXjU6w_iUiYPg0VVAAKGaEYKP7sHUcw1hn-BawMDMorLcvT9YwP4OxQ

Assinatura final

A assinatura final é a concatenação das 3 partes separadas por ("."):

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IlhYWFhYIiwibWVyY2hhbnRfa2V5IjoiWFhYWFhYWFhYWFhYWFhYIiwib3JkZXJfaWQiOiIxODIzNjdyMTI4MzF0MjliIiwibWVyY2hhbnRfdXNuIjoiOTI4Mzc0Mjk4MzciLCJ0aW1lc3RhbXAiOiIxNjA1MDM0OTI1MTc0In0.LLQ2kaC3dG0tsu78JyEIbvd8c1G05lo-1qLDBb0lBXsS2lrJ98-rcusEhuodhHDBE701a_RZwCfOH9ebPZXYdEtuLldqp_Q47y_AYOBYuz3eexuVC0sH3MvmljjHEiMYEIKtFyhsSFrBuQBFvBOT4tJCA779j_cP-JnW4MeDazDehsydEa6phsmkGg_0YfN2xdRzaaTrQqldYibUeI7_YEwLTYrZg0Ys7r45quT7veAzNFLEL4I3iJmMJUcBaCfIQl6NKvX7meoSBeFBaj_MRw8WwXnNTjCFXjU6w_iUiYPg0VVAAKGaEYKP7sHUcw1hn-BawMDMorLcvT9YwP4OxQ

Essas três partes da assinatura, representada pelo exemplo anterior, devem ser enviadas no header Authorization com valor Bearer <assinatura>. Com isso, o e-SiTef poderá validar a assinatura utilizando a chave pública da loja.

Utilizando site JWT para testes

É possível utilizar o site do JWT para criar uma assinatura válida para testes. Para isso é necessário selecionar o algoritmo RS256 e passar o respectivo payload e uma chave pública e privada.

Caso a chave pública não esteja válida a mensagem "Invalid Signature" será exibida.

Cadastros de Lojas em Lote

Visão Geral

O e-SiTef possui uma interface para que sejam cadastradas várias lojas de um cliente, em lote.

Para isto, o lojista deve enviar à equipe de atendimento um arquivo de importação de lojas, seguindo um determinado formato para que os dados das lojas do lote sejam cadastrados corretamente e rapidamente. A importação de lojas é feita somente quando todas as lojas pertencerem a um mesmo grupo.

A ideia é que o desenvolvedor do cliente crie um programa que gera o arquivo de importação seguindo o formato apresentado, pois a geração manual deste arquivo seria trabalhosa e passível de erros.

Formato do arquivo de importação

ATENÇÃO: O arquivo de importação deve ser gerado com codificação UTF-8.

Campos Padrão

Formato a ser recebido (formatação por linha):

campo1;campo2;campo3;...;campo16;<autorizadora1>;<autorizadora2>;...;<autorizadoraN>

Campo	Descrição do campo	Tamanho e formato	Obrigatório
campo1	Código da Loja ou merchant Id. Este valor identifica a loja no e-SiTef de forma única. Logo sugere-se utilizar aqui o CNPJ da empresa, sem formatação, apenas com números, a fim de evitar conflitos de códigos entre lojas diferentes.	< 15 AN	Sim
campo2	Nome Fantasia	< 250 AN (s/ acentuação)	Sim
campo3	Razão Social	< 250 AN (s/ acentuação)	Sim
campo4	CNPJ	< 15 N	Opcional
campo5	Endereço (rua e número)	< 30 AN (s/ acentuação)	Opcional
campo6	Cidade	< 13 AN (s/ acentuação)	Opcional
campo7	Estado	= 2 A	Opcional
campo8	CEP não formatado (apenas números)	< 9 N	Opcional
campo9	Telefone (opcional)	> 5 e < 20 N	Opcional
campo10	e-mail (opcional)	> 5 e < 20 AN	Opcional
campo11	Domínio do site	< 50 AN (s/ acentuação)	Opcional
campo12	URL de Aviso de Status (HTTPS)	< 500 AN (s/ acentuação)	Opcional
campo13	URL de Autenticidade de transação (HTTPS)	< 500 AN (s/ acentuação)	Opcional
campo14	URL para envio de HASH (HTTPS)	< 500 AN (s/ acentuação)	Opcional
campo15	URL de Sucesso	< 500 AN (s/ acentuação)	Opcional
campo16	URL de Fracasso	< 500 AN (s/ acentuação)	Opcional
campo17	URL de Cancelamento	< 500 AN (s/ acentuação)	Opcional
autorizadoraN	Configurações de autorizadoras (vide seção Campos de configuração de autorizadoras abaixo.	-	Sim

Campos de configuração de autorizadoras

autorizadora1, autorizadora2, ..., autorizadoraN - Autorizadoras a serem cadastradas na loja. Podem ser enviadas N autorizadoras. O campo autorizadoraN devem ter o seguinte formato:

...;campoAut1|campoAut2|campoAut3|campoAut4|campoAut5|parametro1|parametro2|...|parametroN

Campo	Descrição do campo	Tamanho e formato
campoAut1	Código da Autorizadora. Para verificar os códigos de autorizadora permitidos, veja a seção Exemplos de Autorizadoras.	< 5 N
campoAut2	Código do roteamento. Para verificar os códigos de roteamento permitidos, veja a seção Exemplos de Roteamentos.	< 5 N
campoAut3	Valor mínimo por parcela em caso de pagamento parcelado, em centavos (*).	< 8 N
campoAut4	Parcelamento máximo com juros (*).	< 2 N
campoAut5	Parcelamento máximo sem juros (*).	< 2 N
parametro1, parametro2, parametroN	Parâmetros da autorizadora. Podem ser enviados N parâmetros. Verifique a seção Parâmetros dos roteamentos para verificar os necessários para cada roteamento.	-

(*) Campos utilizados apenas para configurar pagamentos e pré-autorizações via interface HTML.,

Exemplo

Campo	Valor
Código de Loja	cod_loja_comp
Nome Fantasia	Loja dos Computadores
Razão Social	Loja dos Computadores LTDA.
CNPJ	11137051003444
Endereço	R. dos Computadores, 3032
Cidade	S Joao do Sul
Estado	SC
CEP	07022000
Telefone	12341234
E-mail	email@email.com
Domínio	https://dominio.com.br
URL de Aviso de status	https://dominio.com.br/avisoStatus.jsp
URL de Autenticidade	https://dominio.com.br/autenticidade.jsp
URL de Armazenamento	https://dominio.com.br/envioHash.jsp
URL de Sucesso	https://dominio.com.br/sucesso.jsp
URL de Fracasso	http://dominio.com.br/fracasso.jsp
URL de Cancelamento	https://dominio.com.br/cancelamento.jsp
AUTORIZADORAS
AUTORIZADORA 1
Autorizadora	Visa [1]
Roteamento	Cielo [1125]
Valor mínimo de cada parcela	20 reais [2000]
Parcelamento máximo com juros	5 parcelas [5]
Parcelamento máximo sem juros	5 parcelas [5]
Código de Filiação Cielo	00000001
AUTORIZADORA 2
Autorizadora	Mastercard [2]
Roteamento	Rede (Redecard) [1005]
Valor mínimo de cada parcela	10 reais [1000]
Parcelamento máximo com juros	10 parcelas [10]
Parcelamento máximo sem juros	10 parcelas [10]
Código de Filiação Rede (Redecard)	00000002

Resultado

cod_loja_comp;Loja dos Computadores;Loja dos Computadores LTDA.;11137051003444;R. dos Computadores,3032;S Joao do Sul;SC;07022000;12341234;email@email.com.br;https://dominio.com.br; https://dominio.com.br/avisoStatus.jsp; https://dominio.com.br/autenticidade.jsp; https://dominio.com.br/envioHash.jsp; https://dominio.com.br/sucesso.jsp;http://dominio.com.br/fracasso.jsp; https://dominio.com.br/cancelamento.jsp;1|1125|2000|5|5|00000001;2|1005|10 00|10|10|00000002

Parâmetros dos roteamentos

Cada roteamento possui parâmetros necessários para que eles funcionem corretamente. Eles devem ser inseridos nos campos variáveis parametro1, parametro2, ..., parametroN:

ATENÇÃO: Os parâmetros devem ser enviados na ordem em que estão descritos nos exemplos a seguir.

Cielo via SiTef

Parâmetro necessários para o roteamento Cielo via SiTef:

• Código de filiação Cielo

Exemplo Cielo via SiTef

Campo	Valor
Autorizadora	Visa [1]
Roteamento	Cielo [1125]
Valor mínimo de cada parcela	10 reais [1000]
Parcelamento máximo com juros	10 parcelas [10]
Parcelamento máximo sem juros	10 parcelas [10]
Código de Filiação Cielo	00000001

...;1|1125|1000|10|10|00000001

Rede (Redecard) via SiTef

Parâmetros necessários para o roteamento Rede (Redecard) via SiTef:

• Código de filiação Rede (Redecard)

Exemplo Rede (Redecard) via SiTef

Campo	Valor
Autorizadora	Mastercard [2]
Roteamento	Rede (Redecard) [1005]
Valor mínimo de cada parcela	10 reais [1000]
Parcelamento máximo com juros	10 parcelas [10]
Parcelamento máximo sem juros	10 parcelas [10]
Código de Filiação Rede [Redecard]	00000002

...;1|1005|1000|10|10|00000002

Stone via SiTef

Parâmetros necessários para o roteamento Stone via SiTef:

• Código de filiação Stone
• Código Stone (alfanumérico tamanho 9)

Exemplo Stone via SiTef

Campo	Valor
Autorizadora	Visa [1]
Roteamento	Stone via SiTef [1265]
Valor mínimo de cada parcela	2,65 reais [265]
Parcelamento máximo com juros	10 parcelas [10]
Parcelamento máximo sem juros	10 parcelas [10]
Código de Filiação Stone	codigoFiliacaoDaLojaNaStone32Car
Código Stone	123456789

...;1|1265|265|10|10|codigoFiliacaoDaLojaNaStone32Car|123456789

BIN via SiTef

Parâmetros necessários para o roteamento BIN via SiTef:

• Código de filiação BIN
• Terminal Virtual (alfanumérico tamanho 8)

Exemplo BIN via SiTef

Campo	Valor
Autorizadora	Mastercard [2]
Roteamento	BIN via SiTef [1229]
Valor mínimo de cada parcela	2 reais [200]
Parcelamento máximo com juros	7 parcelas [7]
Parcelamento máximo sem juros	10 parcelas [10]
Código de Filiação BIN	12345678
Terminal Virtual	1TerVir8

...;2|1229|200|7|10|12345678|1TerVir8

Safra via SiTef

Parâmetros necessários para o roteamento Safra via SiTef:

• Código de filiação Safra
• Número Lógico Terminal TEF (alfanumérico tamanho 8)

Exemplo Safra via SiTef

Campo	Valor
Autorizadora	Mastercard [2]
Roteamento	Safra via SiTef [1296]
Valor mínimo de cada parcela	6 reais [600]
Parcelamento máximo com juros	6 parcelas [6]
Parcelamento máximo sem juros	11 parcelas [11]
Código de Filiação Safra	98765432
Número Lógico Terminal TEF	NoLgTe12

...;2|1296|600|6|11|98765432|NoLgTe12

Global Payments via SiTef

Parâmetros necessários para o roteamento Global Payments via SiTef:

• Código de filiação Global Payments

Exemplo Global Payments via SiTef

Campo	Valor
Autorizadora	Mastercard [2]
Roteamento	Safra via SiTef [1206]
Valor mínimo de cada parcela	2 reais [200]
Parcelamento máximo com juros	8 parcelas [8]
Parcelamento máximo sem juros	10 parcelas [10]
Código de Filiação Global Payments	12345678

...;2|1206|200|8|10|12345678

Getnet Lac via SiTef

Parâmetros necessários para o roteamento Getnet Lac via SiTef:

• Código de filiação Getnet Lac
• Terminal Lógico (alfanumérico tamanho 8)

Exemplo Getnet Lac via SiTef

Campo	Valor
Autorizadora	Visa [1]
Roteamento	Safra via SiTef [1181]
Valor mínimo de cada parcela	8 reais [800]
Parcelamento máximo com juros	11 parcelas [11]
Parcelamento máximo sem juros	12 parcelas [12]
Código de Filiação Getnet Lac	87654321
Terminal Lógico	TerLog18

...;1|1181|800|11|12|87654321|TerLog18

Stone WS

Este roteamento se refere à interface e-commerce da adquirente Stone. Parâmetros necessários para o roteamento via Stone WS:

• salesAffiliationKey: alfanumérico.

ATENÇÃO: Os parâmetros específicos para este roteamento devem ser enviados no formato chave:valor.

Exemplo Stone WS

Campo	Valor
Autorizadora	Visa [1]
Roteamento	Stone WS [409]
Valor mínimo de cada parcela	9 reais [900]
Parcelamento máximo com juros	10 parcelas [10]
Parcelamento máximo sem juros	10 parcelas [10]
salesAffiliationKey	chaveDeIdentificacaoDaLojaNaStone

...;1|409|900|10|10|salesAffiliationKey:chaveDeIdentificacaoDaLojaNaSt
one

Cielo EC

Este roteamento se refere à interface e-commerce da adquirente Cielo. Parâmetros necessários para o roteamento via Cielo EC:

• merchantId: alfanumérico (tamanho < 36)
• merchantKey: alfanumérico (tamanho < 40)

ATENÇÃO: Os parâmetros específicos para este roteamento devem ser enviados no formato chave:valor.

Exemplo Cielo EC

Campo	Valor
Autorizadora	Visa [1]
Roteamento	Cielo EC [201]
Valor mínimo de cada parcela	21 reais [2100]
Parcelamento máximo com juros	10 parcelas [10]
Parcelamento máximo sem juros	10 parcelas [10]
merchantId	identificacaoDaLojaNaCieloEC
merchantKey	chaveDaLojaNaCieloEC

...;1|201|2100|10|10|merchantId:identificacaoDaLojaNaCieloEC|merchantKey:chaveDaLojaNaCieloEC

e-Rede

Este roteamento se refere à interface e-commerce da adquirente Rede. Parâmetros necessários para o roteamento via e-Rede:

• filiacao: numérico (tamanho 9)
• senha: alfanumérico (tamanho 32)

ATENÇÃO: Os parâmetros específicos para este roteamento devem ser enviados no formato chave:valor.

Exemplo e-Rede

Campo	Valor
Autorizadora	Visa [1)]
Roteamento	e-Rede [1200]
Valor mínimo de cada parcela	13 reais [1300]
Parcelamento máximo com juros	10 parcelas [10]
Parcelamento máximo sem juros	10 parcelas [10]
filiacao	123456789
senha	aSenhaLojaNaERedeCom32Caracteres

...;1|1200|1300|10|10|filiacao:123456789|senha:aSenhaLojaNaERedeCom32Caracteres

Global Payments WS

Este roteamento se refere à interface e-commerce da adquirente Global Payments. Parâmetros necessários para o roteamento via Global Payments WS:

• merchantCode: numérico (tamanho 15)
• secretKey: alfanumérico (tamanho 20)
• terminal: numérico (tamanho 3)

ATENÇÃO: Os parâmetros específicos para este roteamento devem ser enviados no formato chave:valor.

Exemplo Global Payments WS

Campo	Valor
Autorizadora	Mastercard [2]
Roteamento	Global Payments WS [408]
Valor mínimo de cada parcela	8 reais [800]
Parcelamento máximo com juros	10 parcelas [10]
Parcelamento máximo sem juros	10 parcelas [10]
merchantCode	123456789012345
secretKey	qwertyasdf0123456789
terminal	001

...;2|408|800|10|10| merchantCode:123456789012345|secretKey:qwertyasdf0123456789|terminal:001

Getnet WS

Este roteamento se refere à interface e-commerce da adquirente Getnet. Parâmetros necessários para o roteamento via Global Payments WS:

• username: alfanumérico (tamanho 20)
• password: alfanumérico (tamanho 40)
• merchantID: numérico (tamanho 10)
• terminalID: alfanumérico (tamanho 7)

ATENÇÃO: Os parâmetros específicos para este roteamento devem ser enviados no formato chave:valor.

Exemplo Getnet WS

Campo	Valor
Autorizadora	Mastercard [2]
Roteamento	Getnet WS [407]
Valor mínimo de cada parcela	7 reais [700]
Parcelamento máximo com juros	10 parcelas [10]
Parcelamento máximo sem juros	12 parcelas [12]
username	nomeUsuarioDeAcessoG
password	senhaRelativaAoUsernameAcimaComQuarenta
merchantID	1234567890
terminalID	1234567

...;2|407|700|10|12|username:nomeUsuarioDeAcessoG|password:senhaRelativaAoUsernameAcimaComQuarenta|merchantID:123456790|terminalID:1234567

Exemplo completos de linha de arquivo

Abaixo listaremos alguns exemplos de linhas de arquivo de importação.

Apenas uma autorizadora

Campo	Valor
Código Loja	cod_loja_comp
Nome Fantasia	Loja dos Computadores
Razão Social	Loja dos Computadores LTDA.
CNPJ	11137051003444
Endereço	R. dos Computadores, 3032
Cidade	S Joao do Sul
Estado	SC
CEP	07022000
Telefone	12341234
E-mail	email@email.com
Domínio	https://dominio.com.br
URL de Aviso de status	https://dominio.com.br/avisoStatus.jsp
URL de Autenticidade	https://dominio.com.br/autenticidade.jsp
URL de Armazenamento	https://dominio.com.br/envioHash.jsp
URL de Sucesso	https://dominio.com.br/sucesso.jsp
URL de Fracasso	http://dominio.com.br/fracasso.jsp
URL de Cancelamento	https://dominio.com.br/cancelamento.jsp
AUTORIZADORA
Autorizadora	Visa [1]
Roteamento	Cielo [1125]
Valor mínimo de cada parcela	20 reais [2000]
Parcelamento máximo com juros	5 parcelas [5]
Parcelamento máximo sem juros	5 parcelas [5]
Código de Filiação Cielo	00000001

cod_loja_comp;Loja dos Computadores;Loja dos ComputadoresLTDA.;11137051003444;R. dos Computadores,3032;S Joao doSul;SC;07022000;12341234;email@email.com.br;https://dominio.com.br;https://dominio.com.br/avisoStatus.jsp;https://dominio.com.br/autenticidade.jsp;https://dominio.com.br/envioHash.jsp;https://dominio.com.br/sucesso.jsp;http://dominio.com.br/fracasso.jsp;https://dominio.com.br/cancelamento.jsp;1|1125|2000|5|5|00000001

Duas autorizadoras

Campo	Valor
Código Loja	cod_loja_comp
Nome Fantasia	Loja dos Computadores
Razão Social	Loja dos Computadores LTDA.
CNPJ	11137051003444
Endereço	R. dos Computadores, 3032
Cidade	S Joao do Sul
Estado	SC
CEP	07022000
Telefone	12341234
E-mail	email@email.com
Domínio	https://dominio.com.br
URL de Aviso de status	https://dominio.com.br/avisoStatus.jsp
URL de Autenticidade	https://dominio.com.br/autenticidade.jsp
URL de Armazenamento	https://dominio.com.br/envioHash.jsp
URL de Sucesso	https://dominio.com.br/sucesso.jsp
URL de Fracasso	http://dominio.com.br/fracasso.jsp
URL de Cancelamento	https://dominio.com.br/cancelamento.jsp
AUTORIZADORAS
AUTORIZADORA 1
Autorizadora	Visa [1]
Roteamento	Cielo [1125]
Valor mínimo de cada parcela	20 reais [2000]
Parcelamento máximo com juros	5 parcelas [5]
Parcelamento máximo sem juros	5 parcelas [5]
Código de Filiação Cielo	00000001
AUTORIZADORA 2
Autorizadora	Mastercard [2]
Roteamento	Stone WS [409]
Valor mínimo de cada parcela	10 reais [1000]
Parcelamento máximo com juros	10 parcelas [10]
Parcelamento máximo sem juros	10 parcelas [10]
salesAffiliationKey	chaveDeIdentificacaoDaLojaNaStone

cod_loja_comp;Loja dos Computadores;Loja dos ComputadoresLTDA.;11137051003444;R. dos Computadores,3032;S Joao doSul;SC;07022000;12341234;email@email.com.br;https://dominio.com.br;https://dominio.com.br/avisoStatus.jsp;https://dominio.com.br/autenticidade.jsp;https://dominio.com.br/envioHash.jsp;https://dominio.com.br/sucesso.jsp;http://dominio.com.br/fracasso.jsp;https://dominio.com.br/cancelamento.jsp;1|1125|2000|5|5|00000001;2|405|1000|10|10|salesAffiliationKey :chaveDeIdentificacaoDaLojaNaStone

Exemplos de Autorizadoras

Abaixo estão listadas as autorizadoras que podem ser enviadas na importação:

Autorizadora	Código
Visa	1
Mastercard	2
Amex	3
Hipercard / Hiper	5
Aura	6
Diners	33
Elo	41
JCB	43
Discover	44
Visa Electron	221
Maestro / Mastercard débito	286

Exemplos de Roteamentos

Abaixo estão listados os roteamentos que podem ser enviados na importação:

Autorizadora	Código
Cielo	1125
Rede (Redecard)	1005
Stone WS	409
Cielo EC	201
e-Rede	1200
Global Payments WS	408
Getnet WS	407

Configuração de Roteamento em Lote

Visão Geral

A alteração ou configuração de roteamento em lote pode ser utilizada quando um grupo de lojas deseja mudar o roteamento das bandeiras para as adquirentes em somente parte de suas lojas ou quando o número de lojas torna inviável configurar uma a uma manualmente.

Desta forma, por exemplo, um grupo com 800 lojas onde todas roteiam as bandeiras Visa e Mastercard pela Cielo, deseja fazer com que somente 100 de suas lojas roteiem Visa por Rede.

Pré-requisitos

Como pré-requisito as lojas e autorizadoras (bandeiras) que terão o roteamento alterado já devem estar cadastradas no e-SiTef. Caso não estejam, consulte a documentação Cadastros de Lojas em Lote.

Lembrando que os roteamentos e bandeiras devem estar configurados no SiTef, para isso entre em contato com a nossa equipe de suporte e-SiTef para garantir o funcionamento em produção.

Roteamentos/Rede adquirentes suportadas

Os roteamentos suportados na operação de configuração em lote são:

• Cielo via SiTef
• Rede via SiTef
• GetNet via SiTef
• Stone WS

Formato do Arquivo de Importação

ATENÇÃO: O arquivo de importação deve ser gerado com codificação UTF-8.

O arquivo será composto pelo o código da loja seguido pela bandeira que se deseja alterar e a rede por qual a bandeira será roteada, repetindo uma linha por bandeira, uma ou mais linhas por loja.

Somente serão alterados os roteamentos declarados no arquivo, se a loja possuir outras bandeiras não especificadas sua configuração será mantida.

Formato a ser recebido (formatação por linha):

campo1;campo2;campo3;parametro1|parametro2|...|parametroN

Campo	Descrição	Formato	Obrigatório
campo1	CNPJ (ou código loja, ou merchantId) não formatado (apenas números)	< 15 AN	Sim
campo2	Código da Autorizadora (bandeira). Consulte os códigos na seção Códigos de Autorizadoras/Bandeiras	< 15 N	Sim
campo3	Código da Rede Adquirente (Roteamento/Tipo de Pagamento). Consulte os códigos na seção Códigos de Rede Adquirentes/Roteamentos	< 15 N	Sim
parametro1, parametro2, parametroN	Campos para informações adicionais que variam de acordo com a rede adquirente/roteamento.	-	Não

Códigos de Autorizadoras/Bandeiras

Bandeira/Autorizadora	Código
VISA	1
MASTERCARD	2
AMERICAN EXPRESS (AMEX)	3
HIPERCARD	5
AURA	6
CABAL	12
VALECARD	28
SOROCRED	29
DINERS	33
ELO	41
GOODCARD	42
JCB	43
DISCOVER	44
CHINA UNION PAY	45
CREDZ	46
AGIPLAN	47
VEROCHEQUE	48
PAN	122
AVISTA CREDITO	192

Códigos de Rede Adquirentes/Roteamentos

Roteamento/Tipo de Pagamento	Código
Cielo via SiTef	1125
Rede (antiga Redecard) via SiTef	1005
GetNet via SiTef	1181
e-Rede	1200
Stone WS	409

Parâmetros Adicionais

Alguns roteamentos/tipos de pagamento requerem parâmetros adicionais cadastrados no sistema para realizar transações. Para informá-los preencha o campo 4 em diante de uma linha no seguinte formato:

...;chave1:valor1|chave2:valor2|chave3X:valorX

Os parametros adicionais não são obrigatórios, mas se não for enviado, os parametros serão definidos com um valor padrão .

Stone WS

O roteamento Stone WS se refere à plataforma de e-commerce da adquirente Stone.

São requeridos os seguintes parâmetros adicionais para realizar suas funcionalidades:

Campo	Descrição
salesAffiliationKey	Identificação do estabelecimento comercial (loja) na adquirente Stone.
subAdquirenciaHabilitada	Valores possíveis: true ou false. Este valor deve estar de acordo com as configurações do estabelecimento comercial (loja) na adquirente Stone em relação à subadquirência.

NOTA

Para o uso da subadquirência Stone WS, é necessário que os registros de cadastro do estabelecimento comercial (loja) estejam completos, ou seja, é preciso que os campos País, Cidade, Estado e CEP sejam informados corretamente no cadastro da loja no e-SiTef. Verifique com a equipe de suporte e-SiTef antes de solicitar uma mudança para Stone utilizando a subadquirência com SoftDescriptor. Para mais detalhes acesse a documentação da Stone WS.

Exemplo Stone WS

22222222222222;1;409;salesAffiliationKey:XXXXXXXXXX|subAdquirenciaHabilitada:true

Exemplo

Todas as lojas do grupo XPTO transacionam inicialmente com as bandeiras Visa, Mastercard, Hiper e Amex roteadas pela Rede.

Estado inicial do Grupo XPTO, incluindo lojas 11111111111111, 22222222222222 e 333333333333333:

Bandeira	Adquirente
Visa	Rede (antiga Redecard)
Mastercard	Rede (antiga Redecard)
Hiper	Rede (antiga Redecard)
Amex	Rede (antiga Redecard)

É desejado que apenas duas lojas desse grupo, de código 11111111111111 e 22222222222222 passem a transacionar ambas com Visa via Cielo, e Mastercard via Stone WS, mantendo os roteamentos da Amex e Hiper sem alteração.

Lojas 11111111111111 e 22222222222222 após a mudança:

Bandeira	Adquirente
Visa	Cielo
Mastercard	Stone WS
Hiper	Rede (antiga Redecard) -> Não muda
Amex	Rede (antiga Redecard) -> Não muda

E também é desejado mudar a loja de código 333333333333333 para transacionar Visa via Cielo e Amex via Stone WS, conforme abaixo.

Loja 333333333333333 após a mudança:

Bandeira	Adquirente
Visa	Cielo
Mastercard	Rede (antiga Redecard) -> Não muda
Hiper	Rede (antiga Redecard) -> Não muda
Amex	Stone WS (com subadquirência)

O arquivo final a ser gerado será como o apresentado abaixo:

11111111111111;1;1125;
11111111111111;2;409;salesAffiliationKey:ABC123DEF456|subAdquirenciaHabilitada:false
22222222222222;1;1125;
22222222222222;2;409;salesAffiliationKey:ABC123DEF457|subAdquirenciaHabilitada:false
33333333333333;1;1125;
33333333333333;3;409;salesAffiliationKey:ABC123DEF458|subAdquirenciaHabilitada:true

ATENÇÃO: Caso o campo 4 seja vazio, não esquecer de finalizar a linha com ponto e vírgula ";".

Cadastro de Lojas REST

Visão Geral

Para chamar qualquer serviço do e-SiTef, é necessário antes que o lojista tenha sua loja cadastrada pelas nossas equipes de Suporte e Produção (até mesmo para interagir com a API de cadastro de lojas).

A interface REST de cadastro de lojas do e-SiTef é recomendada quando há uma necessidade frequente de cadastro de novas lojas por parte de um mesmo lojista.

Comunicação

Para realizar uma transação Web Service, toda a comunicação será realizada via HTTPS/SSL. É importante que o servidor do lojista suporte criptografia com no mínimo 128 bits. O servidor da loja deverá realizar chamadas em endereços específicos para transações REST.

Cada serviço deve ser chamado utilizando a URL base concatenada do recurso desejado (veja o capítulo referente ao serviço a ser consumido). O método HTTP (GET, POST ou PUT) indica a ação esperada sobre o recurso escolhido. Abaixo estão as URLs base do e-SiTef:

URL base de Produção:

https://esitef-ec.softwareexpress.com.br/e-sitef/api

URL base de Homologação:

https://esitef-homologacao.softwareexpress.com.br/e-sitef/api

Todas as chamadas realizadas para os serviços serão respondidas de forma síncrona.

Atenção:

Nunca utilize o IP ao invés do domínio esitef-ec.softwareexpress.com.br. O IP pode mudar a qualquer momento e sem aviso prévio, portanto é importante a utilização do domínio para acesso ao e-SiTef.

Importante:

Além dos parâmetros de retorno dos serviços descritos nesta especificação o e-SiTef poderá devolver outros parâmetros sem aviso prévio.

É importante que o aplicativo esteja preparado para receber os parâmetros desconhecidos além dos parâmetros já especificados e simplesmente desprezá-los.

Fluxos

Criação de loja

• 1. A loja inicia o processo requisitando a geração de um token para acesso à API de cadastro de lojas.
  • 1.1. O e-SiTef faz um POST na URL de autenticidade cadastrada da loja contendo o token.
  • 1.2. A loja virtual responde ao POST com código HTTP 200 OK.
  • 1.3. Com o processo de autenticidade bem-sucedido, o e-SiTef retorna uma resposta de sucesso para a loja.
• 2. Então, a loja virtual envia a requisição de criação de loja, contendo o token obtido anteriormente.
  • 2.1. O e-SiTef cadastra a loja e retorna uma resposta de sucesso.

Edição de loja

O fluxo para alteração de uma loja é o mesmo da criação, com a diferença de que o serviço a ser chamado no segundo passo é o de edição de lojas.

Quick start

Este guia mostra o processo de cadastro de loja, utilizando a interface web service REST do e-SiTef.

O que você precisará

• Uma loja cadastrada no e-SiTef com permissão para consumo dessa API
• Uma ferramenta capaz de realizar chamadas HTTP, como Postman, REST Client ou cURL
• Uma aplicação capaz de receber chamadas POST HTTPS, caso seja utilizado o post de autenticidade

POST de autenticidade x assinatura

O e-SiTef possui duas formas de autenticação da loja na interface de criação, edição e consulta de loja REST: POST de autenticidade ou assinatura.

No método de POST de autenticidade, o e-SiTef enviará o token recém-criado para a URL de autenticidade cadastrada da loja.

No método de assinatura, a loja deve ter uma chave pública de criptografia RSA cadastrada no e-SiTef e deverá montar uma assinatura JWT (JSON Web Tokens) a ser enviada no cabeçalho Authorization.Saiba mais.

Criando um token

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/token/merchants

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

cURL

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/token/merchants"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Recebimento do POST de autenticidade:

Java + Spring Framework

@RestController
public class MyAuthenticityController {

    @PostMapping(value = "/myauthenticity", 
        consumes = "application/x-www-form-urlencoded; charset=utf-8")
    public ResponseEntity<String> myAuthenticity(@RequestParam Map<String, String> request) {
        Log.info("token = " + request.get("token"));
        // ...
        // armazena o token
        // ...
        return new ResponseEntity<>("OK", HttpStatus.OK);
    }

}

Resposta:

{
   "response_code":0,
   "response_message":"OK. Transaction successful."
}

Saiba mais sobre esse serviço.

Criando a loja

Tipo de requisição: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/merchants/

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}
• token: {token caso seja utilizada o post de autenticidade}
• Authorization: {assinatura caso seja utilizada a assinatura JWT}

Requisição:

JSON

cURL

cURL

{
   "fantasy_name":"Teste de Loja",
   "corporate_name":"Testes de Loja Ltda.",
   "soft_descriptor":{
      "fantasy_name":"Sub-comércio da Loja",
      "country":"BR",
      "mcc":"1234",
      "id":"123456"
   },
   "subacquirer_group":{
      "create":"true",
      "id":"123456",
      "cnpj":"12345678901234"
   },
   "domain":"www.testeloja.com",
   "cnpj":"123123123123",
   "address":"Rua do Teste, 123",
   "city":"São Teste",
   "state":"SP",
   "zip_code":"12345678",
   "phone_number":"11912341234",
   "email":"testeloja@teste.com",
   "transactional_urls":{
      "status":"https://www.testeloja.com/status",
      "authenticity":"https://www.testeloja.com/autent",
      "hash":"https://www.testeloja.com/hash"
   },
   "return_urls":{
      "success":"https://www.testeloja.com/sucesso",
      "failure":"https://www.testeloja.com/fracasso",
      "cancel":"https://www.testeloja.com/cancel"
   },
   "permissions":{
      "payment":"true",
      "pre_authorization":"false",
      "recharge":"false",
      "risk_analysis":"true",
      "schedule":"true",
      "iata":"false",
      "card_store":"false",
      "payment_link":"true"
   },
   "establishments":[
      {
         "code":"00000000123",
         "routing_id":"1125",
         "subacquirer_group_id":"123456"
      },
      {
         "code":"00000000321",
         "routing_id":"1005"
      }
   ],
   "authorizers":[
      {
         "id":"1",
         "routing_id":"1125",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12",
         "enable_subacquirer_group":"true"
      },
      {
         "id":"2",
         "routing_id":"201",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12",
         "parameters":{
            "merchantId":"8h37e9e23oe",
            "merchantKey":"b9f374t5983t745f873tb45f93b4f2293b485ft34"
         }
      }
   ]
}

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/merchants"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "token: 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--data-binary
{
   "fantasy_name":"Teste de Loja",
   "corporate_name":"Testes de Loja Ltda.",
   "soft_descriptor":{
      "fantasy_name":"Sub-comércio da Loja",
      "country":"BR",
      "mcc":"1234",
      "id":"123456"
   },
   "subacquirer_group":{
      "create":"true",
      "id":"123456",
      "cnpj":"12345678901234"
   },
   "domain":"www.testeloja.com",
   "cnpj":"123123123123",
   "address":"Rua do Teste, 123",
   "city":"São Teste",
   "state":"SP",
   "zip_code":"12345678",
   "phone_number":"11912341234",
   "email":"testeloja@teste.com",
   "transactional_urls":{
      "status":"https://www.testeloja.com/status",
      "authenticity":"https://www.testeloja.com/autent",
      "hash":"https://www.testeloja.com/hash"
   },
   "return_urls":{
      "success":"https://www.testeloja.com/sucesso",
      "failure":"https://www.testeloja.com/fracasso",
      "cancel":"https://www.testeloja.com/cancel"
   },
   "permissions":{
      "payment":"true",
      "pre_authorization":"false",
      "recharge":"false",
      "risk_analysis":"true",
      "schedule":"true",
      "iata":"false",
      "card_store":"false",
      "payment_link":"true"
   },
   "establishments":[
      {
         "code":"00000000123",
         "routing_id":"1125",
         "subacquirer_group_id":"123456"
      },
      {
         "code":"00000000321",
         "routing_id":"1005"
      }
   ],
   "authorizers":[
      {
         "id":"1",
         "routing_id":"1125",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12",
         "enable_subacquirer_group":"true"
      },
      {
         "id":"2",
         "routing_id":"201",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12",
         "parameters":{
            "merchantId":"8h37e9e23oe",
            "merchantKey":"b9f374t5983t745f873tb45f93b4f2293b485ft34"
         }
      }
   ]
}
--verbose

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/merchants"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "Authorization: Bearer YYYYYYYYYYYYYY"
--data-binary
{
   "cnpj":"123123123123",
   "fantasy_name":"Teste de Loja",
   "corporate_name":"Testes de Loja Ltda.",
   "soft_descriptor":{
      "fantasy_name":"Sub-comércio da Loja",
      "country":"BR",
      "mcc":"1234",
      "id":"123456"
   },
   "subacquirer_group":{
      "create":"true",
      "id":"123456",
      "cnpj":"12345678901234"
   },
   "domain":"www.testeloja.com",
   "address":"Rua do Teste, 123",
   "city":"São Teste",
   "state":"SP",
   "zip_code":"12345678",
   "phone_number":"11912341234",
   "email":"testeloja@teste.com",
   "transactional_urls":{
      "status":"https://www.testeloja.com/status",
      "authenticity":"https://www.testeloja.com/autent",
      "hash":"https://www.testeloja.com/hash"
   },
   "return_urls":{
      "success":"https://www.testeloja.com/sucesso",
      "failure":"https://www.testeloja.com/fracasso",
      "cancel":"https://www.testeloja.com/cancel"
   },
   "permissions":{
      "payment":"true",
      "pre_authorization":"false",
      "recharge":"false",
      "risk_analysis":"true",
      "schedule":"true",
      "iata":"false",
      "card_store":"false",
      "payment_link":"true"
   },
   "establishments":[
      {
         "code":"00000000123",
         "routing_id":"1125",
         "subacquirer_group_id":"123456"
      },
      {
         "code":"00000000321",
         "routing_id":"1005"
      }
   ],
   "authorizers":[
      {
         "id":"1",
         "routing_id":"1125",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12",
         "enable_subacquirer_group":"true"
      },
      {
         "id":"2",
         "routing_id":"201",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12",
         "parameters":{
            "merchantId":"8h37e9e23oe",
            "merchantKey":"b9f374t5983t745f873tb45f93b4f2293b485ft34"
         }
      }
   ]
}
--verbose

Resposta:

{
   "id":"qereIoinsd3d",
   "key":"9B71234TB12D938T9384TDB294T923D412T938D1293D4B923D",
   "response_code":"0",
   "response_message":"OK"
}

Saiba mais sobre esse serviço.

Serviço de criação de token

O consumo do serviço de geração de token é obrigatório para criar ou editar uma loja. Como resultado dessa operação, o lojista obterá um token pela sua URL de autenticidade que será necessário para o próximo passo do fluxo.

Detalhes da chamada

• Recurso: /v1/token/merchants
• Método HTTP: POST
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM

Exemplo

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/token/merchants"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

POST de autenticidade:

curl -X POST \
  https://urlDeAutenticidadeDaLoja.com.br \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'cache-control: no-cache' \
  -d 'token=1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr

Resposta:

{
   "response_code":0,
   "response_message":"OK. Transaction successful."
}

Parâmetros do POST de autenticidade

Na tabela abaixo está a descrição dos parâmetros enviados pelo e-SiTef no POST de autenticidade:

Parâmetro	Descrição	Formato
token	Token a ser utilizado na próxima etapa do fluxo.	= 66 AN

O e-SiTef também pode enviar novos parâmetros sem aviso prévio, o que significa que a aplicação do lojista deve estar preparada para receber campos extras e simplesmente ignorá-los.

Atenção: É essencial que o site hospedado na URL de Autenticidade da loja receba o token de autenticidade e responda HTTP 200, pois isto é condição para que o e-SiTef considere o sucesso deste POST.

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de criação de token:

Parâmetro	Descrição	Formato
response_code	Código de resposta do e-SiTef. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 4 N
response_message	Mensagem de resposta do e-SiTef.	< 500 AN

Serviço de criação de loja

Após obter o token ou assinatura na etapa anterior, a loja virtual deve enviar os dados da loja a ser criada no e-SiTef e no SiTef (caso necessário).

Detalhes da chamada

• Recurso: /v1/merchants
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
token	Token obtido na etapa anterior, caso a autenticação seja via post de autenticidade Saiba mais.	= 66 AN	NÃO
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM
Authorization	Deve ser enviada a assinatura de autenticação da loja no formato Bearer {assinatura}. Exemplo: Bearer JHVGytfdgauygdauiw78264284527852897hagdg.	< 2000 AN	NÃO

Exemplo utilizando token

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/merchants"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "token: 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--data-binary
{
   "cnpj":"123123123123",
   "fantasy_name":"Teste de Loja",
   "corporate_name":"Testes de Loja Ltda.",
   "mcc":"1234",
   "soft_descriptor":{
      "fantasy_name":"Sub-comércio da Loja",
      "country":"BR",
      "id":"123456"
   },
   "subacquirer_group":{
      "create":"true",
      "id":"123456",
      "cnpj":"12345678901234"
   },
   "domain":"www.testeloja.com",
   "address":"Rua do Teste, 123",
   "city":"São Teste",
   "state":"SP",
   "zip_code":"12345678",
   "phone_number":"11912341234",
   "email":"testeloja@teste.com",
   "transactional_urls":{
      "status":"https://www.testeloja.com/status",
      "authenticity":"https://www.testeloja.com/autent",
      "hash":"https://www.testeloja.com/hash"
   },
   "return_urls":{
      "success":"https://www.testeloja.com/sucesso",
      "failure":"https://www.testeloja.com/fracasso",
      "cancel":"https://www.testeloja.com/cancel"
   },
   "permissions":{
      "payment":"true",
      "pre_authorization":"false",
      "recharge":"false",
      "risk_analysis":"true",
      "schedule":"true",
      "iata":"false",
      "card_store":"false",
      "payment_link":"true"
   },
   "establishments":[
      {
         "code":"00000000123",
         "routing_id":"1125",
         "subacquirer_group_id":"123456"
      },
      {
         "code":"00000000321",
         "routing_id":"1005"
      }
   ],
   "authorizers":[
      {
         "id":"1",
         "routing_id":"1125",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12",
         "enable_subacquirer_group":"true"
      },
      {
         "id":"2",
         "routing_id":"201",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12",
         "parameters":{
            "merchantId":"8h37e9e23oe",
            "merchantKey":"b9f374t5983t745f873tb45f93b4f2293b485ft34"
         }
      }
   ]
}
--verbose

Exemplo utilizando assinatura

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/merchants"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "Authorization: Bearer YYYYYYY"
--data-binary
{
   "cnpj":"123123123123",
   "fantasy_name":"Teste de Loja",
   "corporate_name":"Testes de Loja Ltda.",
   "mcc":"1234",
   "soft_descriptor":{
      "fantasy_name":"Sub-comércio da Loja",
      "country":"BR",
      "id":"123456"
   },
   "subacquirer_group":{
      "create":"true",
      "id":"123456",
      "cnpj":"12345678901234"
   },
   "domain":"www.testeloja.com",
   "address":"Rua do Teste, 123",
   "city":"São Teste",
   "state":"SP",
   "zip_code":"12345678",
   "phone_number":"11912341234",
   "email":"testeloja@teste.com",
   "transactional_urls":{
      "status":"https://www.testeloja.com/status",
      "authenticity":"https://www.testeloja.com/autent",
      "hash":"https://www.testeloja.com/hash"
   },
   "return_urls":{
      "success":"https://www.testeloja.com/sucesso",
      "failure":"https://www.testeloja.com/fracasso",
      "cancel":"https://www.testeloja.com/cancel"
   },
   "permissions":{
      "payment":"true",
      "pre_authorization":"false",
      "recharge":"false",
      "risk_analysis":"true",
      "schedule":"true",
      "iata":"false",
      "card_store":"false",
      "payment_link":"true"
   },
   "establishments":[
      {
         "code":"00000000123",
         "routing_id":"1125",
         "subacquirer_group_id":"123456"
      },
      {
         "code":"00000000321",
         "routing_id":"1005"
      }
   ],
   "authorizers":[
      {
         "id":"1",
         "routing_id":"1125",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12",
         "enable_subacquirer_group":"true"
      },
      {
         "id":"2",
         "routing_id":"201",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12",
         "parameters":{
            "merchantId":"8h37e9e23oe",
            "merchantKey":"b9f374t5983t745f873tb45f93b4f2293b485ft34"
         }
      }
   ]
}
--verbose

Resposta:

{
   "id":"qereIoinsd3d",
   "key":"9B71234TB12D938T9384TDB294T923D412T938D1293D4B923D",
   "response_code":"0",
   "response_message":"OK",
   "authorizer_response_code":"0", 
   "authorizer_response_message":"OK"
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de criação de loja:

Parâmetro	Descrição	Formato	Obrigatório
cnpj	CNPJ ou CPF da loja. Apenas números.	< 14 N	SIM
fantasy_name	Nome fantasia da loja.	< 250 AN	SIM
corporate_name	Razão social da loja.	< 250 AN	SIM
domain	Domínio (site) da loja.	< 500 AN	NÃO
address	Endereço da loja.	< 200 AN	NÃO
city	Cidade da loja.	< 50 AN	NÃO
state	Estado da loja (sigla).	= 2 AN	NÃO
zip_code	CEP da loja.	< 9 AN	NÃO
phone_number	Telefone da loja.	< 30 AN	NÃO
email	Endereço de e-mail da loja.	< 100 AN	NÃO
mcc	Merchant Category Code - código que indica a categoria do estabelecimento (utilizado no cadastro de antifraude)	= 4 N	NÃO
soft_descriptor	Dados do sub-comércio.
id	ID do sub-comércio.	< 22 AN	NÃO
country	País do sub-comércio. Código numérico ISO 3166-1.	= 3 N	NÃO
fantasy_name	Nome fantasia do sub-comércio	< 22 AN	NÃO
subacquirer_group	Dados de grupo de subadquirência.
create	Flag que indica se devemos criar o grupo de subadquirência	< 5 T/F	NÃO
id	ID do grupo de subadquirência	< 6 AN	NÃO
cnpj	CNPJ do grupo de sub-adquirência	= 14 N	SIM, caso o campo subacquirer_group .create seja true
establishments	Dados dos estabelecimentos a serem cadastrados no SiTef.
code	Código do estabelecimento (número lógico) a ser cadastrado no SiTef	< 32 AN	NÃO
routing_id	ID do roteamento (tipo de pagamento do e-SiTef)	< 4 N	NÃO
subacquirer_group_id	ID do grupo de sub-adquirência. Deve ser enviado caso esse estabelecimento deva ser cadastrado para o grupo ao invés da empresa.	< 6 AN	NÃO
extra_data	Informação adicional do estabelecimento	< 32 AN	NÃO
transactional_urls	URLs utilizadas em fluxos transacionais.
status	URL para recebimento de avisos de status.	< 500 AN	NÃO
authenticity	URL para recebimento de POSTs de autenticidade.	< 500 AN	NÃO
hash	URL para recebimento de hash/token de cartão armazenado.	< 500 AN	NÃO
return_urls	URLs de retorno de pagamento HTML.
success	URL de retorno de sucesso.	< 500 AN	NÃO
failure	URL de retorno de fracasso.	< 500 AN	NÃO
cancel	URL de retorno de cancelamento.	< 500 AN	NÃO
permissions	Permissões transacionais a serem designadas para a loja. Enviar o valor true para habilitar a funcionalidade em questão.
payment	Permissão para pagamento.	< 5 AN	NÃO
pre_authorization	Permissão para pré-autorização.	< 5 AN	NÃO
recharge	Permissão para recarga.	< 5 AN	NÃO
risk_analysis	Permissão para análise de risco.	< 5 AN	NÃO
schedule	Permissão para agendamento.	< 5 AN	NÃO
iata	Permissão para IATA.	< 5 AN	NÃO
card_store	Permissão para armazenamento de cartão.	< 5 AN	NÃO
payment_link	Permissão para pagamento via link.	< 5 AN	NÃO
authorizers[]	Autorizadoras a serem cadastradas para a loja. A presença de um roteamento SiTef indica que deve ser criada uma empresa no SiTef.
id	ID da autorizadora no e-SiTef. Saiba mais.	< 4 N	SIM
routing_id	ID do roteamento/adquirente no e-SiTef. Saiba mais.	< 4 N	SIM
min_installments_amount	Valor mínimo para parcelamento em transações HTML. Valor padrão: 1000	< 12 N	NÃO
max_installments_without_interest	Número máximo de parcelas sem juros em transações HTML. Valor padrão: 3	< 2 N	NÃO
max_installments_with_interest	Número máximo de parcelas com juros em transações HTML. Valor padrão: 12	< 2 N	NÃO
enable_subacquirer_group	Habilitar bandeira para uso de grupo de sub-adquirência. Enviar true para habilitar ou false para desabilitar.	< 5 T/F	NÃO
authorizers[].parameters	Parâmetros específicos do roteamento. Saiba mais.

Códigos de roteamento/adquirente

ID	Roteamento
201	Cielo e-Commerce
407	Getnet WS
408	Global Payments WS
409	Stone WS
1005	Rede via SiTef
1181	Getnet Lac via SiTef
1125	Cielo via SiTef
1200	e-Rede
1206	Global Payments via SiTef
1229	BIN via SiTef
1265	Stone via SiTef
1296	Safra via SiTef

Parâmetros específicos do roteamento

Cielo e-Commerce

Parâmetro	Descrição
authorizers[].parameters	Parâmetros específicos do roteamento.
merchantId	Identificação da loja na Cielo.
merchantKey	Chave da loja na Cielo.

Getnet WS

Parâmetro	Descrição
authorizers[].parameters	Parâmetros específicos do roteamento.
username	Usuário de acesso.
password	Senha de acesso.
merchantID	Código de EC cadastrado na GetnetWS.
terminal	Identificação do Terminal.
subMerchantId	ID do Sub comércio.

Global Payments WS

Parâmetro	Descrição
authorizers[].parameters	Parâmetros específicos do roteamento.
merchantCode	Número do estabelecimento definido pela Global Payments.
secretKey	Chave secreta do lojista na Global Payments.
terminal	Número de terminal que será definido pela Global Payments.

Stone WS

Parâmetro	Descrição
authorizers[].parameters	Parâmetros específicos do roteamento.
salesAffiliationKey	Chave de identificação da loja na Stone.
subAdquirenciaHabilitada	Enviar true para habilitar sub-adquirência ou false caso contrário.

BIN via SiTef

Parâmetro	Descrição	Formato
authorizers[].parameters	Parâmetros específicos do roteamento.
subacquirerMerchantId	Código do sub-comércio.
establishments	Dados dos estabelecimentos a serem cadastrados no SiTef.
extra_data	Código de terminal. Campo obrigatório para integração com a Bin.	= 8 AN

e-Rede

Parâmetro	Descrição
authorizers[].parameters	Parâmetros específicos do roteamento.
filiacao	Código do filiação da loja na e-Rede.
senha	Chave pública da loja na e-Rede.

Cadastro de lojas com antifraude

É possível realizar o cadastro automático de novas lojas com as seguintes soluções de antifraude: Fraud Detect, ClearSale, CyberSource e Konduto. Para isso o lojista deve entrar em contato com a instituição de análise de risco e solicitar as credenciais necessárias. Em seguida, o lojista deve passar um conjunto de MCC's (Merchant Category Code) para cada credencial registrada para a equipe de Produção do e-SiTef, que fará o cadastro desses dados. Será feito um mapeamento desses conjuntos de MCC para cada credencial e esses valores serão utilizados no cadastro de cada loja. Uma vez feito esse pré-cadastro, será possível realizar o cadastro de antifraude de forma automática utilizando a API de criação de lojas.

Atenção:

• É necessário ativar a permissão de anti fraude (risk_analysis) no cadastro da loja.
• Apenas a API de criação de lojas faz o cadastro de antifraude automático.

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 201. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de criação de loja:

Parâmetro	Descrição	Formato
response_code	Código de resposta do e-SiTef. Qualquer código diferente de 0 significa falha.	< 4 N
response_message	Mensagem de resposta do e-SiTef.	< 500 AN
authorizer_response_code	Código de resposta da autorizadora.	< 4 N
authorizer_response_message	Mensagem de resposta da autorizadora.	< 500 AN
id	Código da loja criada. Gerado automaticamente (obs: caracteres maiúsculas e minúsculas são diferenciados no sistema).	< 15 AN
key	Chave da loja criada.	< 80 AN

Serviço de edição de loja

Após obter o token ou assinatura na etapa anterior, a loja virtual pode consumir o serviço de edição de loja. Para isso, apenas os dados a serem alterados devem ser enviados.

Detalhes da chamada

• Recurso: /v1/merchants/{id}
• Método HTTP: PUT
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
token	Token obtido no serviço de criação de token. Saiba mais.	= 66 AN	NÃO
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM
Authorization	Deve ser enviada a assinatura de autenticação da loja no formato Bearer {assinatura}. Exemplo: Bearer JHVGytfdgauygdauiw78264284527852897hagdg.	< 2000 AN	NÃO

Exemplo utilizando token

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/merchants/qereIoinsd3d"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "token: 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--data-binary
{
   "fantasy_name":"Teste de Loja",
   "corporate_name":"Testes de Loja Ltda.",
   "merchant_status":"A",
   "subacquirer_group":{
      "create":"true",
      "id":"123456",
      "cnpj":"12345678901234"
   },
   "domain":"www.testeloja.com",
   "cnpj":"123123123123",
   "address":"Rua do Teste, 123",
   "city":"São Teste",
   "state":"SP",
   "zip_code":"12345678",
   "phone_number":"11912341234",
   "email":"testeloja@teste.com",
   "mcc":"1234",
   "transactional_urls":{
      "status":"https://www.testeloja.com/status",
      "authenticity":"https://www.testeloja.com/autent",
      "hash":"https://www.testeloja.com/hash"
   },
   "return_urls":{
      "success":"https://www.testeloja.com/sucesso",
      "failure":"https://www.testeloja.com/fracasso",
      "cancel":"https://www.testeloja.com/cancel"
   },
   "permissions":{
      "payment":"true",
      "pre_authorization":"false",
      "recharge":"false",
      "risk_analysis":"true",
      "schedule":"true",
      "iata":"false",
      "card_store":"false",
      "payment_link":"true"
   },
   "establishments":[
      {
         "code":"00000000123",
         "routing_id":"1125",
         "subacquirer_group_id":"123456"
      },
      {
         "code":"00000000321",
         "routing_id":"1005"
      }
   ],
   "authorizers":[
      {
         "id":"1",
         "routing_id":"1125",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12",
         "enable_subacquirer_group":"true"
      },
      {
         "id":"2",
         "routing_id":"1005",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12",
         "enable_subacquirer_group":"false"
      }
   ]
}
--verbose

Exemplo utilizando assinatura

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/merchants/qereIoinsd3d"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "Authorization: Bearer YYYYYYY"
--data-binary
{
   "fantasy_name":"Teste de Loja",
   "corporate_name":"Testes de Loja Ltda.",
   "merchant_status":"A",
   "subacquirer_group":{
      "create":"true",
      "id":"123456",
      "cnpj":"12345678901234"
   },
   "domain":"www.testeloja.com",
   "cnpj":"123123123123",
   "address":"Rua do Teste, 123",
   "city":"São Teste",
   "state":"SP",
   "zip_code":"12345678",
   "phone_number":"11912341234",
   "email":"testeloja@teste.com",
   "mcc":"1234",
   "transactional_urls":{
      "status":"https://www.testeloja.com/status",
      "authenticity":"https://www.testeloja.com/autent",
      "hash":"https://www.testeloja.com/hash"
   },
   "return_urls":{
      "success":"https://www.testeloja.com/sucesso",
      "failure":"https://www.testeloja.com/fracasso",
      "cancel":"https://www.testeloja.com/cancel"
   },
   "permissions":{
      "payment":"true",
      "pre_authorization":"false",
      "recharge":"false",
      "risk_analysis":"true",
      "schedule":"true",
      "iata":"false",
      "card_store":"false",
      "payment_link":"true"
   },
   "establishments":[
      {
         "code":"00000000123",
         "routing_id":"1125",
         "subacquirer_group_id":"123456"
      },
      {
         "code":"00000000321",
         "routing_id":"1005"
      }
   ],
   "authorizers":[
      {
         "id":"1",
         "routing_id":"1125",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12",
         "enable_subacquirer_group":"true"
      },
      {
         "id":"2",
         "routing_id":"1005",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12",
         "enable_subacquirer_group":"false"
      }
   ]
}
--verbose

Resposta:

{
   "id":"qereIoinsd3d",
   "key":"9B71234TB12D938T9384TDB294T923D412T938D1293D4B923D",
   "response_code":"0",
   "response_message":"OK", 
   "authorizer_response_code":"0", 
   "authorizer_response_message":"OK"
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de edição de loja:

Parâmetro	Descrição	Formato	Obrigatório
{id}	Código da loja a ser editada. Presente na própria URL.	< 15 AN	SIM
fantasy_name	Nome fantasia da loja.	< 250 AN	NÃO
corporate_name	Razão social da loja.	< 250 AN	NÃO
merchant_status	Status da loja. Pode assumir os seguintes valores: A = Ativa I = Inativa	= 1 AN	NÃO
domain	Domínio (site) da loja.	< 500 AN	NÃO
cnpj	CNPJ ou CPF da loja. Apenas números.	< 14 N	NÃO
address	Endereço da loja.	< 200 AN	NÃO
city	Cidade da loja.	< 50 AN	NÃO
state	Estado da loja (sigla).	= 2 AN	NÃO
zip_code	CEP da loja.	< 9 AN	NÃO
phone_number	Telefone da loja.	< 30 AN	NÃO
email	Endereço de e-mail da loja.	< 100 AN	NÃO
mcc	Merchant Category Code.	= 4 N	NÃO
subacquirer_group	Dados de grupo de subadquirência.
create	Flag que indica se devemos criar o grupo de subadquirência	< 5 T/F	NÃO
id	ID do grupo de subadquirência	< 6 AN	NÃO
cnpj	CNPJ do grupo de sub-adquirência	= 14 N	SIM, caso o campo subacquirer_group.create seja true
establishments	Dados dos estabelecimentos a serem cadastrados no SiTef.
code	Código do estabelecimento (número lógico) a ser cadastrado no SiTef	< 32 AN	NÃO
routing_id	ID do roteamento (tipo de pagamento do e-SiTef)	< 4 N	NÃO
subacquirer_group_id	ID do grupo de sub-adquirência. Deve ser enviado caso esse estabelecimento deva ser cadastrado para o grupo ao invés da empresa.	< 6 AN	NÃO
extra_data	Informação adicional do estabelecimento	< 32 AN	NÃO
transactional_urls	URLs utilizadas em fluxos transacionais.
status	URL para recebimento de avisos de status.	< 500 AN	NÃO
authenticity	URL para recebimento de POSTs de autenticidade.	< 500 AN	NÃO
hash	URL para recebimento de hash/token de cartão armazenado.	< 500 AN	NÃO
return_urls	URLs de retorno de pagamento HTML.
success	URL de retorno de sucesso.	< 500 AN	NÃO
failure	URL de retorno de fracasso.	< 500 AN	NÃO
cancel	URL de retorno de cancelamento.	< 500 AN	NÃO
permissions	Permissões transacionais a serem designadas para a loja. Enviar o valor true para habilitar a funcionalidade em questão.
payment	Permissão para pagamento.	< 5 AN	NÃO
pre_authorization	Permissão para pré-autorização.	< 5 AN	NÃO
recharge	Permissão para recarga.	< 5 AN	NÃO
risk_analysis	Permissão para análise de risco.	< 5 AN	NÃO
schedule	Permissão para agendamento.	< 5 AN	NÃO
iata	Permissão para IATA.	< 5 AN	NÃO
card_store	Permissão para armazenamento de cartão.	< 5 AN	NÃO
payment_link	Permissão para pagamento via link.	< 5 AN	NÃO
authorizers[]	Autorizadoras a serem cadastradas para a loja.
id	ID da autorizadora no e-SiTef. Saiba mais.	< 4 N	SIM
routing_id	ID do roteamento/adquirente no e-SiTef. Saiba mais.	< 4 N	SIM
status	Enviar A para ativar ou I para inativar a autorizadora.	< 1 AN	NÃO
min_installments_amount	Valor mínimo para parcelamento em transações HTML. Valor padrão: 1000	< 12 N	NÃO
max_installments_without_interest	Número máximo de parcelas sem juros em transações HTML. Valor padrão: 3	< 2 N	NÃO
max_installments_with_interest	Número máximo de parcelas com juros em transações HTML. Valor padrão: 12	< 2 N	NÃO
enable_subacquirer_group	Habilitar bandeira para uso de grupo de sub-adquirência. Enviar true para habilitar ou false para desabilitar.	< 5 T/F	NÃO
authorizers[].parameters	Parâmetros específicos do roteamento. Saiba mais.

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de edição de loja:

Parâmetro	Descrição	Formato
response_code	Código de resposta do e-SiTef. Qualquer código diferente de 0 significa falha.	< 4 N
response_message	Mensagem de resposta do e-SiTef.	< 500 AN
authorizer_response_code	Authorizer response code.	< 4 N
authorizer_response_message	Authorizer response message.	< 500 AN
id	Código da loja alterada.	< 15 AN
key	Chave da loja alterada.	< 80 AN

Serviço de consulta de loja

Após obter o token ou assinatura na etapa anterior, a loja virtual pode consumir o serviço de consulta de loja.

Detalhes da chamada

• Recurso: /v1/merchants/{id}
• Método HTTP: GET
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
token	Token obtido no serviço de criação de token. Saiba mais.	= 66 AN	NÃO
Authorization	Deve ser enviada a assinatura de autenticação da loja no formato Bearer {assinatura}. Exemplo: Bearer JHVGytfdgauygdauiw78264284527852897hagdg.	< 2000 AN	NÃO

Exemplo

Resposta:

{
   "response_code":"0", 
   "response_message":"OK", 
   "id":"qereIoinsd3d",
   "key":"9B71234TB12D938T9384TDB294T923D412T938D1293D4B923D",
   "fantasy_name":"Teste de Loja",
   "corporate_name":"Testes de Loja Ltda.",
   "merchant_status":"A",
   "sitef_merchant_id":"00000000",
   "domain":"www.testeloja.com",
   "cnpj":"123123123123",
   "address":"Rua do Teste, 123",
   "city":"São Teste",
   "state":"SP",
   "zip_code":"12345678",
   "phone_number":"11912341234",
   "email":"testeloja@teste.com",
   "mcc": "1234",
   "transactional_urls":{
      "status":"https://www.testeloja.com/status",
      "authenticity":"https://www.testeloja.com/autent",
      "hash":"https://www.testeloja.com/hash"
   },
   "return_urls":{
      "success":"https://www.testeloja.com/sucesso",
      "failure":"https://www.testeloja.com/fracasso",
      "cancel":"https://www.testeloja.com/cancel"
   },
   "permissions":{
      "payment":"true",
      "pre_authorization":"false",
      "recharge":"false",
      "risk_analysis":"true",
      "schedule":"true",
      "iata":"false",
      "card_store":"false",
      "payment_link":"true"
   },
   "authorizers":[
      {
         "id":"1",
         "status":"I",
         "routing_id":"1125",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12"
      },
      {
         "id":"2",
         "status":"A",
         "routing_id":"201",
         "min_installments_amount":"100",
         "max_installments_without_interest":"1",
         "max_installments_with_interest":"12",
         "parameters":{
            "merchantId":"8h37e9e23oe",
            "merchantKey":"b9f374t5983t745f873tb45f93b4f2293b485ft34"
         }
      }
   ]
}

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro.

Parâmetro	Descrição	Formato
response_code	Código de resposta do e-SiTef.	< 4 N
response_message	Mensagem de resposta do e-SiTef.	< 500 AN
id	Código da loja consultada.	< 15 AN
key	Chave da loja consultada.	< 80 AN
fantasy_name	Nome fantasia da loja.	< 250 AN
corporate_name	Razão social da loja.	< 250 AN
merchant_status	Status da loja. Pode assumir os seguintes valores: A = Ativa I = Inativa	= 1 AN
sitef_merchant_id	Código de empresa da loja.	8 N
domain	Domínio (site) da loja.	< 65 AN
cnpj	CNPJ ou CPF da loja. Apenas números.	< 14 N
address	Endereço da loja.	< 30 AN
city	Cidade da loja.	< 13 AN
state	Estado da loja (sigla).	= 2 AN
zip_code	CEP da loja.	< 9 AN
phone_number	Telefone da loja.	< 30 AN
email	Endereço de e-mail da loja.	< 100 AN
transactional_urls	URLs utilizadas em fluxos transacionais.
mcc	Merchant Category Code - código que indica a categoria do estabelecimento	= 4 N
status	URL para recebimento de avisos de status.	< 500 AN
authenticity	URL para recebimento de POSTs de autenticidade.	< 500 AN
hash	URL para recebimento de hash/token de cartão armazenado.	< 500 AN
return_urls	URLs de retorno de pagamento HTML.
success	URL de retorno de sucesso.	< 500 AN
failure	URL de retorno de fracasso.	< 500 AN
cancel	URL de retorno de cancelamento.	< 500 AN
permissions	Permissões transacionais a serem designadas para a loja. Enviar o valor true para habilitar a funcionalidade em questão.
payment	Permissão para pagamento.	< 5 AN
pre_authorization	Permissão para pré-autorização.	< 5 AN
recharge	Permissão para recarga.	< 5 AN
risk_analysis	Permissão para análise de risco.	< 5 AN
schedule	Permissão para agendamento.	< 5 AN
iata	Permissão para IATA.	< 5 AN
card_store	Permissão para armazenamento de cartão.	< 5 AN
payment_link	Permissão para pagamento via link.	< 5 AN
authorizers[]	Autorizadoras a serem cadastradas para a loja.
id	ID da autorizadora no e-SiTef. Saiba mais.	< 4 N
routing_id	ID do roteamento/adquirente no e-SiTef. Saiba mais.	< 4 N
min_installments_amount	Valor mínimo para parcelamento em transações HTML. Valor padrão: 1000	< 12 N
max_installments_without_interest	Número máximo de parcelas sem juros em transações HTML. Valor padrão: 3	< 2 N
max_installments_with_interest	Número máximo de parcelas com juros em transações HTML. Valor padrão: 12	< 2 N
authorizers[].parameters	Parâmetros específicos do roteamento. Saiba mais.

Serviço de consulta de status loja

Após obter o token ou assinatura na etapa anterior, a loja virtual pode consumir o serviço de consulta de status de loja.

Atenção:

A loja a solicitar o status deve ter as devidas permissões e também deve estar presente no mesmo grupo em que a loja requisitada. Para mais informações sobre como habilitar a Consulta de Status de Loja, contate a nossa equipe de suporte.

Detalhes da chamada

• Recurso: /v1/merchants/status/{id}
• Método HTTP: GET
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
token	Token obtido no serviço de criação de token. Saiba mais.	= 66 AN	NÃO
Authorization	Deve ser enviada a assinatura de autenticação da loja no formato Bearer {assinatura}. Exemplo: Bearer JHVGytfdgauygdauiw78264284527852897hagdg.	< 2000 AN	NÃO

Exemplo

Resposta:

{
   "response_code":"0", 
   "response_message":"OK", 
   "merchant_status": "A"
}

Parâmetros de resposta

Parâmetro	Descrição	Formato
response_code	Código de resposta do e-SiTef.	< 4 N
response_message	Mensagem de resposta do e-SiTef.	< 500 AN
merchant_status	Status da loja. Pode assumir os seguintes valores: A = Ativa I = Inativa	= 1 AN

Serviço de listagem de lojas

Após obter o token ou assinatura na etapa anterior, a loja virtual pode consumir o serviço de listagem de lojas.

Detalhes da chamada

• Recurso: /v1/merchants
• Método HTTP: GET
• Formato da requisição: query string
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
token	Token obtido no serviço de criação de token. Saiba mais.	= 66 AN	NÃO
Authorization	Deve ser enviada a assinatura de autenticação da loja no formato Bearer {assinatura}. Exemplo: Bearer JHVGytfdgauygdauiw78264284527852897hagdg. Saiba mais.	< 2000 AN	NÃO

Exemplo

Abaixo estão alguns exemplos da chamada do serviço de listagem de loja utilizando a ferramenta cURL.

Listagem de loja utilizando token

Requisição:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/merchants?cnpj=12345678901234&merchant_status=A&page=1&limit=1"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "token: 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--verbose

Listagem de loja utilizando assinatura

Requisição:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/merchants?cnpj=12345678901234&merchant_status=A&page=1&limit=1"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "Authorization: Bearer YYYYYYY"
--verbose

Resposta:

{
   "response_code":"0",
   "response_message":"OK",
   "current_page":"0",
   "total_pages":"1",
   "count":"1",
   "merchants":[
      {
         "id":"qereIoinsd3d",
         "merchant_status":"A",
         "fantasy_name":"Teste de Loja",
         "corporate_name":"Testes de Loja Ltda.",
         "cnpj":"12345678901234"
      }
   ]
}

Parâmetros de requisição

Parâmetro	Descrição	Formato	Obrigatório
cnpj	CNPJ da loja.	= 14 N	NÃO
merchant_status	Status da loja. Pode assumir os seguintes valores: A = Ativa I = Inativa	= 1 AN	NÃO
page	Página da listagem. A primeira página tem valor 0. Caso não seja enviada, assumiremos o valor 0.	< 4 N	NÃO
limit	Número máximo de registros por página. Caso não seja enviado, assumiremos o valor máximo 100.	< 3 N	NÃO

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro.

Parâmetro	Descrição	Formato
response_code	Código de resposta do e-SiTef.	< 4 N
response_message	Mensagem de resposta do e-SiTef.	< 500 AN
current_page	Página atual dos registros.	< 4 N
total_pages	Número total de páginas.	< 4 N
count	Contagem total de registros.	< 4 N
merchants[]	Lista de lojas retornada na consulta.
id	Código da loja consultada.	< 15 AN
merchant_status	Status da loja. Pode assumir os seguintes valores: A = Ativa I = Inativa	= 1 AN
fantasy_name	Nome fantasia da loja.	< 250 AN
corporate_name	Razão social da loja.	< 250 AN
cnpj	CNPJ ou CPF da loja. Apenas números.	< 14 N

Códigos da API do cadastro de loja REST

Códigos de resposta

Código	Descrição
0	Transação OK
1	Inválido file format
2	Valor nulo sitef_merchantid
3	Valor nulo sitef_ip
4	Valor nulo currency
5	Valor nulo sitef_port
6	Valor nulo version
7	Inválido currency
8	Inválido payment_type for merchant
9	Inválido id
10	Inválido email
11	Valor nulo email
12	Valor nulo id
13	Inválido address
14	Valor nulo fantasy_name
15	Inválido fantasy_name
16	Valor nulo corporate_name
17	Inválido corporate_name
18	Valor nulo domain
19	Inválido domain
20	Valor nulo cnpj
21	Inválido cnpj
22	Inválido state
23	Inválido phone_number
24	Inválido transactional_urls.hash
25	Inválido transactional_urls.authenticity
26	Inválido return_urls.cancel
27	Inválido return_urls.failure
28	Inválido return_urls.success
29	Inválido transactional_urls.status
30	Inválido zip_code
31	Inválido city
32	Valor nulo authorizers.routing_id
33	Inválido authorizers.routing_id
34	Valor nulo authorizers.id
35	Inválido authorizers.id
36	Valor nulo authorizers.parameters.name
37	Inválido authorizers.parameters.name
38	Valor nulo authorizers.parameters
39	Inválido authorizers.parameters
40	Valor nulo request
41	Autorizadora não permitida para NPC
42	Valor nulo cpf
43	Inválido cpf
44	Inválido cpf/cnpj
45	Valor nulo login
45	Inválido login
47	login já existe
48	Valor nulo name
49	Inválido name
50	Valor nulo access_type
51	Inválido access_type
52	Valor nulo profile
53	Inválido profile
54	Valor nulo admin_profile
55	Inválido admin_profile
56	Valor nulo prefix
57	Inválido prefix
58	Valor nulo merchant_id
59	Inválido merchant_id
60	Valor nulo merchant_key
61	Inválido merchant_key
62	Valor nulo group_id
63	Inválido group_id
64	Cadastro de loja não permitido
65	Permissões da loja insuficientes
66	Inválido authorizers.min_installments_amount
67	Inválido authorizers.max_installments_with_interest
68	Inválido authorizers.max_installments_without_interest
69	Inválido authorizers.status
70	Erro de cadastro do grupo de loja
71	Sem permissão para consultar a loja
72	Inválido sitef_merchant_id
75	Erro de cadastro adquirente
76	Erro de cadastro da loja-pai
77	Erro de comunicação client
78	Valor nulo establishments.code
79	Valor nulo establishments.routing_id
80	Inválido establishments.routing_id
81	Valor nulo subacquirer_group.id
82	Valor nulo subacquirer_group.cnpj
83	Sem permissão para consultar situação da loja
85	Inválido merchant_status
86	Inválido page
87	Inválido limit
88	Assinatura ou token não podem ser nulos
188	Token expirado
189	Token já foi utilizado
199	Inválido token
200	Erro de assinatura do token
500	Erro de persistencia de dados
1000	Erro inesperado! Por favor entre em contato com o time de atendimento do e-SiTef
1026	Loja não possui chaves públicas registradas
1027	Erro de validação de assinatura
1028	Erro de validação de assinatura do payload
1029	Assinatura expirada
1032	Resultado não encontrado

3DS Server

Visão Geral

Para fazer transações de autenticação 3DS 2.0, é necessária a integração com uma aplicação 3DS Server, como a fornecida pela Software Express. Essa aplicação se comunica com a bandeira e o emissor para autenticar o portador do cartão, reduzindo incidências de fraude e possibilitando pagamentos com cartões de débito.

O protocolo 3DS 2.0 se difere de sua versão 1.0 na possibilidade de permitir uma autenticação frictionless (sem fricção), ou seja, um processo que não exige interações adicionais por parte do comprador.

Esta documentação é focada nas interações com o 3DS Server. Para mais informações referentes aos outros componentes do fluxo, consulte os documentos oficiais da EMVCo.

Comunicação

Para realizar uma transação Web Service, toda a comunicação será realizada via HTTPS/SSL. É importante que o servidor do lojista suporte criptografia com no mínimo 128 bits. O servidor da loja deverá realizar chamadas em endereços específicos para transações REST.

Cada serviço deve ser chamado utilizando a URL base concatenada do recurso desejado (veja o capítulo referente ao serviço a ser consumido). O método HTTP (GET, POST ou PUT) indica a ação esperada sobre o recurso escolhido. Abaixo estão as URLs base do 3DS Server:

URL base de Produção:

https://3ds.softwareexpress.com.br/

URL base de Homologação:

https://mpi-homolog.softwareexpress.com.br/3ds-server/

Todas as chamadas realizadas para os serviços serão respondidas de forma síncrona.

Atenção:

Nunca utilize o IP ao invés do domínio 3ds.softwareexpress.com.br. O IP pode mudar a qualquer momento e sem aviso prévio, portanto é importante a utilização do domínio para acesso ao 3DS Server.

Importante:

Além dos parâmetros de retorno dos serviços descritos nesta especificação o 3DS Server poderá devolver outros parâmetros sem aviso prévio.

É importante que o aplicativo esteja preparado para receber os parâmetros desconhecidos além dos parâmetros já especificados e simplesmente desprezá-los.

Fluxos

O protocolo 3DS 2.0 conta com 3 principais fluxos:

• Frictionless (sem fricção): toda a autenticação é feita sem a exigência de interações adicionais por parte do comprador.
• Challenge (desafio): as informações coletadas pelo emissor não são suficientes para autenticar o portador do cartão. Logo, o comprador deverá fornecer mais dados, diretamente no site do emissor.
• Decoupled (desacoplado): a autenticação é feita fora do protocolo 3DS.

Glossário:

• 3DS Requestor: loja ou gateway (como o e-SiTef)
• DS: Directory Server; representa a bandeira
• ACS: Access Control Server; representa o emissor
• AReq: Authentication Request, conforme o protocolo 3DS 2.0
• ARes: Authentication Response, conforme o protocolo 3DS 2.0
• CReq: Challenge Request, conforme o protocolo 3DS 2.0
• CRes: Challenge Response, conforme o protocolo 3DS 2.0
• RReq: Results Request, conforme o protocolo 3DS 2.0
• RRes: Results Response, conforme o protocolo 3DS 2.0

Fluxo Frictionless

1. 3DS Requestor cria a transação de autenticação no 3DS Server, passando o número do cartão do comprador e seu ID de bandeira.
2. 3DS Server valida se o cartão recebido pode ser autenticado pela bandeira indicada. Caso positivo, retorna o ID da transação 3DS Server (three_ds_server.trans_id) e o 3DS Method URL (three_ds_method_url) correspondente ao cartão.
3. O 3DS Method URL deve ser exibido no navegador do comprador em um frame "invisível" de 1 pixel.
4. Isso permitirá que o ACS colete diretamente as informações do dispositivo do portador do cartão.
5. 3DS Requestor envia informações para a realização da autenticação.
6. 3DS Server gera um AReq e o envia para o DS, que em seguida propaga ao ACS. O resultado da autenticação volta para o 3DS Server como conteúdo do ARes.
7. Caso a autenticação seja bem-sucedida, será retornado o status (campo three_ds_server.status) com valor Y, o ECI (campo eci) e o CAVV (campo authentication.value), que devem ser então enviados ao adquirente.

Fluxo Challenge

Os passos 1 até 6 são os mesmos do fluxo frictionless.

7. Será retornado o status (campo three_ds_server.status) com valor C e a URL do desafio preenchida (campo acs.url).
8. 3DS Requestor prepara o CReq para ser submetido pelo navegador do comprador para a URL de desafio.
9. ACS exibe sua tela de desafio para que o comprador forneça mais informações. Note que podem ser necessárias múltiplas interações para conclusão desse processo.
10. ACS envia o RReq para o DS, que por sua vez propaga ao 3DS Server. Essa chamada se trata de uma notificação informando o resultado da autenticação.
11. ACS envia o CRes ao 3DS Requestor em sua URL informada no passo 5 (campo notification_url). Este objeto contém o ID da transação 3DS Server.
12. 3DS Requestor consulta a transação do 3DS Server para obter o resultado da autenticação.
13. 3DS Server retorna as informações de sua transação.

Fluxo Decoupled

Os passos 1 até 6 são os mesmos do fluxo frictionless.

7. Será retornado o status (campo three_ds_server.status) com valor D.
8. ACS conduzirá seu próprio processo de autenticação, por fora do protocolo 3DS 2.0.
9. ACS envia o RReq para o DS, que por sua vez propaga ao 3DS Server, informando o resultado da autenticação.
10. 3DS Server informa o resultado ao 3DS Requestor através de sua URL de notificação informada no passo 5 (campo decoupled_notification_url).
11. 3DS Requestor responde a notificação com código HTTP 200.

Quick start

Este guia mostra o processo de uma autenticação frictionless, utilizando a interface web service REST do 3DS Server da Software Express.

O que você precisará

• Cadastro ativo no ambiente de homologação do 3DS Server (obtido com nossa equipe de suporte)
• Uma ferramenta capaz de realizar chamadas HTTP, como Postman, REST Client ou cURL

Criando a transação

Tipo de requisição: POST

URL: https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

JSON

cURL

{
   "cardholder":{
      "acct":{
         "number":"1234123412341234"
      }
   },
   "brand_id":"2"
}

curl
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "cardholder":{
      "acct":{
         "number":"1234123412341234"
      }
   },
   "brand_id":"2"
}
--verbose

Resposta:

{
    "three_ds_method_url": "https://www.example.com",
    "three_ds_server": {
        "trans_id": "12341234-1234-1234-1234-123412341234",
        "status": "NEW"
    },
    "acs": {
        "protocol_version": {
            "start": "2.1.0",
            "end": "2.2.0"
        }
    },
    "device_channel": "02",
    "ds": {
        "protocol_version": {
            "start": "2.1.0",
            "end": "2.2.0"
        }
    }
}

Saiba mais sobre esse serviço.

Fazendo a autenticação

Tipo de requisição: PUT

URL: https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/{ID da transação 3DS Server}

Headers:

• Content-Type: application/json
• merchant_id: {seu código de loja}
• merchant_key: {chave da sua loja}

Requisição:

JSON

cURL

{
   "three_ds_comp_ind":"Y",
   "pay_token_ind":"false",
   "notification_url":"https://www.requestor.com/notification",
   "decoupled_notification_url":"https://www.requestor.com/decoupled_notification",
   "trans_type":"01",
   "three_ds_requestor":{
      "authentication_ind":"01",
      "decoupled_max_time":"10",
      "id":"id",
      "name":"Loja de Testes",
      "url":"https://www.requestor.com"
   },
   "acquirer":{
      "bin":"2",
      "merchant_id":"00000000"
   },
   "browser":{
      "accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "ip":"10.20.30.40",
      "javascript_enabled":true,
      "java_enabled":"false",
      "language":"pt-BR",
      "color_depth":"24",
      "screen_height":"864",
      "screen_width":"1536",
      "tz":"180",
      "user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
   },
   "cardholder":{
      "card_expiry_date":"2212",
      "name":"Joaquim",
      "acct":{
         "type":"02",
         "number":"1234123412341234"
      }
   },
   "merchant":{
      "mcc":"mcc",
      "country_code":"BRA",
      "name":"Loja de Teste",
   },
   "message":{
      "category":"01"
   },
   "purchase":{
      "amount":"10000",
      "currency":"986",
      "exponent":"2",
      "date":"date"
   }
}

curl
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/12341234-1234-1234-1234-123412341234"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "three_ds_comp_ind":"Y",
   "pay_token_ind":"false",
   "notification_url":"https://www.requestor.com/notification",
   "decoupled_notification_url":"https://www.requestor.com/decoupled_notification",
   "trans_type":"01",
   "three_ds_requestor":{
      "authentication_ind":"01",
      "decoupled_max_time":"10",
      "id":"id",
      "name":"Loja de Testes",
      "url":"https://www.requestor.com"
   },
   "acquirer":{
      "bin":"2",
      "merchant_id":"00000000"
   },
   "browser":{
      "accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "ip":"10.20.30.40",
      "javascript_enabled":true,
      "java_enabled":"false",
      "language":"pt-BR",
      "color_depth":"24",
      "screen_height":"864",
      "screen_width":"1536",
      "tz":"180",
      "user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
   },
   "cardholder":{
      "card_expiry_date":"2212",
      "name":"Joaquim",
      "acct":{
         "type":"02",
         "number":"1234123412341234"
      }
   },
   "merchant":{
      "mcc":"mcc",
      "country_code":"BRA",
      "name":"Loja de Teste",
   },
   "message":{
      "category":"01"
   },
   "purchase":{
      "amount":"10000",
      "currency":"986",
      "exponent":"2",
      "date":"date"
   }
}
--verbose

Resposta:

{
    "three_ds_server": {
        "trans_id": "12341234-1234-1234-1234-123412341234",
        "status": "AUY"
    },
    "acs": {
        "operator_id": "acsOperatorID",
        "reference_number": "acsReferenceNumber",
        "trans_id": "43214321-4321-4321-4321-432143214321"
    },
    "eci": "05",
    "device_channel": "02",
    "authentication": {
        "value": "1234567890123456789012345678"
    },
    "broad_info": "broadInfo",
    "ds": {
        "reference_number": "dsReferenceNumber",
        "trans_id": "56785678-5678-5678-5678-567856875678"
    },
    "transaction": {
        "status": "Y"
    }
}

Saiba mais sobre esse serviço.

Serviço de criação de transação

Essa chamada é necessária para obter o 3DS Method URL correspondente ao cartão, além criar uma transação 3DS Server, que será utilizada nos passos seguintes do fluxo.

Detalhes da chamada

• Recurso: /v2/authentication
• Método HTTP: POST
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no 3DS Server. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no 3DS Server. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM
Authorization	Deve ser enviada a assinatura de autenticação da loja no formato Bearer {assinatura}. Exemplo: Bearer JHVGytfdgauygdauiw78264284527852897hagdg.	< 2000 AN	COND.*

* Nota: Por razões de segurança, para que a autenticação da transação seja realizada, é recomendado informar o valor para o campo Authorization.
Caso a loja tenha cadastrado sua chave pública com o e-SiTef, este campo passa a ser obrigatório.

Geração da assinatura

Para gerar o valor a ser enviado no header Authorization, é necessário:

• Gerar as chaves pública e privada
  • Consulte a página de Autenticação com assinatura, seção Criando as chaves pública e privada.
  • Enviar somente a chave pública para a nossa equipe de suporte, que associará internamente essa chave ao cadastro de sua loja.
• Seguir as instruções de geração de assinatura descritas na página Autenticação com assinatura, seção Algoritmo de assinatura, com exceção da subseção Segunda parte (payload), que será diferente neste caso - ver mais detalhes a seguir.

Payload

O payload para esta funcionalidade deverá ter o seguinte formato:

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "cartao": "5555555555555555",
  "timestamp": "1620952402824"
}

Payload Base64:

eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M

Composição do payload

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no e-SiTef.	= 15 AN	SIM
merchant_key	Chave de autenticação da loja no e-SiTef.	< 80 AN	SIM
cartao	Número do cartão do comprador (PAN).	< 19 AN	SIM
timestamp	Representação em milissegundos do momento de geração da assinatura. Enfatizando que o campo timestamp possui um limite de validade de 10 minutos.	< 13 N	SIM

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de criação de transações utilizando a ferramenta cURL.

Requisição:

curl
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M'
--data-binary
{
   "cardholder":{
      "acct":{
         "number":"1234123412341234"
      }
   },
   "brand_id":"2"
}
--verbose

Resposta:

{
    "three_ds_method_url": "https://www.example.com",
    "three_ds_server": {
        "trans_id": "12341234-1234-1234-1234-123412341234",
        "status": "NEW"
    },
    "acs": {
        "protocol_version": {
            "start": "2.1.0",
            "end": "2.2.0"
        }
    },
    "device_channel": "02",
    "ds": {
        "protocol_version": {
            "start": "2.1.0",
            "end": "2.2.0"
        }
    }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de criação de transações:

Parâmetro	Descrição	Formato	Obrigatório
brand_id	ID da bandeira. Saiba mais.	= 4 N	SIM
cardholder.acct
number	Número do cartão do comprador.	< 19 N	SIM
message
version	Versão da mensagem 3DS: 2.1.0 ou 2.2.0.	< 8 AN	NÃO

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 201. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de criação de transações:

Parâmetro	Descrição	Formato
three_ds_method_url	URL do frame invisível a ser exibido no navegador do comprador	< 256 AN
device_channel	Canal do dispositivo. Saiba mais.	< 2 N
three_ds_server
trans_id	ID da transação 3DS Server	< 8 AN
status	Status no 3DS Server. Saiba mais.	= 3 AN
acs.protocol_version
start	Versão mais antiga de protocolo 3DS suportada pelo ACS	< 8 AN
end	Versão mais recente de protocolo 3DS suportada pelo ACS	< 8 AN
ds.protocol_version
start	Versão mais antiga de protocolo 3DS suportada pelo DS	< 8 AN
end	Versão mais recente de protocolo 3DS suportada pelo DS	< 8 AN
error
code	Código do erro. Saiba mais.	< 3 N
component	Indica qual componente identificou o erro. C = 3DS SDK S = 3DS Server D = DS A = ACS	= 1 AN
description	Descrição do erro	< 2048 AN
detail	Detalhamento do erro	< 28 AN

Serviço de autenticação

Após a criação da transação, é necessário chamar o serviço de autenticação para dar continuidade ao fluxo. Caso seja retornado o status AUC, será preciso iniciar um desafio. Para o status AUD, deve ser seguido o fluxo "decoupled". Nos demais casos, não serão necessárias mais chamadas.

Detalhes da chamada

• Recurso: /v2/authentication/{ID da transação 3DS Server}
• Método HTTP: PUT
• Formato da requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no 3DS Server. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no 3DS Server. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de autenticação utilizando a ferramenta cURL.

Fluxo Frictionless

Requisição:

curl
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/12341234-1234-1234-1234-123412341234"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "three_ds_comp_ind":"Y",
   "pay_token_ind":"false",
   "notification_url":"https://www.requestor.com/notification",
   "decoupled_notification_url":"https://www.requestor.com/decoupled_notification",
   "trans_type":"01",
   "three_ds_requestor":{
      "authentication_ind":"01",
      "decoupled_max_time":"10",
      "id":"id",
      "name":"Loja de Testes",
      "url":"https://www.requestor.com"
   },
   "acquirer":{
      "bin":"2",
      "merchant_id":"00000000"
   },
   "browser":{
      "accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "ip":"10.20.30.40",
      "javascript_enabled":true,
      "java_enabled":"false",
      "language":"pt-BR",
      "color_depth":"24",
      "screen_height":"864",
      "screen_width":"1536",
      "tz":"180",
      "user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
   },
   "cardholder":{
      "card_expiry_date":"2212",
      "name":"Joaquim",
      "acct":{
         "type":"02",
         "number":"1234123412341234"
      }
   },
   "merchant":{
      "mcc":"mcc",
      "country_code":"BRA",
      "name":"Loja de Teste",
   },
   "message":{
      "category":"01"
   },
   "purchase":{
      "amount":"10000",
      "currency":"986",
      "exponent":"2",
      "date":"date"
   }
}
--verbose

Resposta:

{
    "three_ds_server": {
        "trans_id": "12341234-1234-1234-1234-123412341234",
        "status": "AUY"
    },
    "acs": {
        "operator_id": "acsOperatorID",
        "reference_number": "acsReferenceNumber",
        "trans_id": "43214321-4321-4321-4321-432143214321"
    },
    "eci": "05",
    "device_channel": "02",
    "authentication": {
        "value": "1234567890123456789012345678"
    },
    "broad_info": "broadInfo",
    "ds": {
        "reference_number": "dsReferenceNumber",
        "trans_id": "56785678-5678-5678-5678-567856875678"
    },
    "transaction": {
        "status": "Y"
    }
}

Fluxo Challenge

Requisição:

curl
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/12341234-1234-1234-1234-123412341234"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "three_ds_comp_ind":"Y",
   "pay_token_ind":"false",
   "notification_url":"https://www.requestor.com/notification",
   "decoupled_notification_url":"https://www.requestor.com/decoupled_notification",
   "trans_type":"01",
   "three_ds_requestor":{
      "authentication_ind":"01",
      "decoupled_max_time":"10",
      "id":"id",
      "name":"Loja de Testes",
      "url":"https://www.requestor.com"
   },
   "acquirer":{
      "bin":"2",
      "merchant_id":"00000000"
   },
   "browser":{
      "accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "ip":"10.20.30.40",
      "javascript_enabled":true,
      "java_enabled":"false",
      "language":"pt-BR",
      "color_depth":"24",
      "screen_height":"864",
      "screen_width":"1536",
      "tz":"180",
      "user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
   },
   "cardholder":{
      "card_expiry_date":"2212",
      "name":"Joaquim",
      "acct":{
         "type":"02",
         "number":"1234123412341234"
      }
   },
   "merchant":{
      "mcc":"mcc",
      "country_code":"BRA",
      "name":"Loja de Teste",
   },
   "message":{
      "category":"01"
   },
   "purchase":{
      "amount":"10004",
      "currency":"986",
      "exponent":"2",
      "date":"date"
   }
}
--verbose

Resposta:

{
    "three_ds_server": {
        "trans_id": "12341234-1234-1234-1234-123412341234",
        "status": "AUC"
    },
    "acs": {
        "challenge_mandated": "Y",
        "operator_id": "acsOperatorID",
        "reference_number": "acsReferenceNumber",
        "trans_id": "43214321-4321-4321-4321-432143214321",
        "url": "https://www.acs.com/challenge"
    },
    "device_channel": "02",
    "authentication": {
        "type": "01"
    },
    "broad_info": "broadInfo",
    "ds": {
        "reference_number": "dsReferenceNumber",
        "trans_id": "56785678-5678-5678-5678-567856875678"
    },
    "transaction": {
        "status": "C"
    }
}

Fluxo Decoupled

Requisição:

curl
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/12341234-1234-1234-1234-123412341234"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "three_ds_comp_ind":"Y",
   "pay_token_ind":"false",
   "notification_url":"https://www.requestor.com/notification",
   "decoupled_notification_url":"https://www.requestor.com/decoupled_notification",
   "trans_type":"01",
   "three_ds_requestor":{
      "authentication_ind":"01",
      "decoupled_max_time":"10",
      "id":"id",
      "name":"Loja de Testes",
      "url":"https://www.requestor.com"
   },
   "acquirer":{
      "bin":"2",
      "merchant_id":"00000000"
   },
   "browser":{
      "accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "ip":"10.20.30.40",
      "javascript_enabled":true,
      "java_enabled":"false",
      "language":"pt-BR",
      "color_depth":"24",
      "screen_height":"864",
      "screen_width":"1536",
      "tz":"180",
      "user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
   },
   "cardholder":{
      "card_expiry_date":"2212",
      "name":"Joaquim",
      "acct":{
         "type":"02",
         "number":"1234123412341234"
      }
   },
   "merchant":{
      "mcc":"mcc",
      "country_code":"BRA",
      "name":"Loja de Teste",
   },
   "message":{
      "category":"01"
   },
   "purchase":{
      "amount":"10006",
      "currency":"986",
      "exponent":"2",
      "date":"date"
   }
}
--verbose

Resposta:

{
    "three_ds_server": {
        "trans_id": "12341234-1234-1234-1234-123412341234",
        "status": "AUD"
    },
    "acs": {
        "challenge_mandated": "Y",
        "operator_id": "acsOperatorID",
        "reference_number": "acsReferenceNumber",
        "trans_id": "43214321-4321-4321-4321-432143214321",
        "decoupled_confirmation_ind": "Y"
    },
    "device_channel": "02",
    "authentication": {
        "type": "04"
    },
    "broad_info": "broadInfo",
    "cardholder": {
        "info": "cardholderInfo"
    },
    "ds": {
        "reference_number": "dsReferenceNumber",
        "trans_id": "56785678-5678-5678-5678-567856875678"
    },
    "transaction": {
        "status": "D"
    }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de autenticação:

Parâmetro	Descrição	Formato	Obrigatório
device_channel	Canal do dispositivo. Valor padrão: 02. Saiba mais.	= 2 N	NÃO
three_ri_ind	Indica o tipo de requisição 3RI. 01 = Transação recorrente 02 = Transação parcelada 03 = Adição de cartão 04 = Manter informações de cartão 05 = Verificação de conta 06 = Entrega atrasada 07 = Recarga 08 = Serviço postal 09 = Serviço telefônico 10 = Verificação de status de lista branca 11 = Outros pagamentos Obrigatório para device_channel = 03.	= 2 N	COND.
three_ds_comp_ind	Indica se o 3DS Method foi executado com sucesso. Y = Realizado com sucesso N = Não executado com sucesso U = Indisponível— não tinha 3DS Method URL associada ao cartão. Obrigatório para device_channel = 02.	= 1 A	COND.
pay_token_ind	O valor true indica que a transação foi "destokenizada" antes do recebimento pelo ACS.	< 5 AN	NÃO
pay_token_source	Indica onde ocorreu a "destokenização". 01 - 3DS Server 02 - DS	= 2 N	NÃO
notification_url	URL completa do 3DS Requestor para receber a mensagem CRes. Campo obrigatório para device_channel = 02.	< 256 AN	COND.
decoupled_notification_url	URL completa do 3DS Requestor para recebimento na notificação "decoupled".	< 300 AN	SIM
trans_type	Identifica o tipo de transação sendo autenticada. 01 = Compra de bens/serviços 03 = Check Acceptance 10 = Financiamento de Conta 11 = Transação Quasi-Cash 28 = Ativação e carga de pré-pago	= 2 N	SIM
broad_info	Informação não-estruturada enviada entre 3DS Server, DS e ACS.	Object	NÃO
three_ds_requestor
authentication_ind	Indica o tipo da requisição de autenticação. 01 = Transação de pagamento 02 = Transação recorrente 03 = Transação parcelada 04 = Adição de cartão 05 = Manter cartão 06 = Verificação do portador como parte de EMV token ID&V	= 2 N	SIM
decoupled_max_time	Indica a quantidade máxima de tempo que o 3DS Requestor vai esperar para que o ACS forneça os resultados de uma autenticação decoupled (em minutos).	< 5 N	NÃO
decoupled_request_ind	Indica se o 3DS Requestor pede para que o ACS use autenticação decoupled e concorda com a sua utilização caso o ACS confirme seu uso. Y = Autenticação decoupled é suportada e preferida se um desafio for necessário N = Não use autenticação decoupled	= 1 AN	NÃO
challenge_ind	Indica se um desafio é requerido para essa transação. 01 = Sem preferência 02 = Desafio não pedido 03 = Desafio pedido (preferência do 3DS Requestor) 04 = Desafio pedido (mandato) 05 = Desafio não pedido (análise de fraude já realizada) 06 = Desafio não pedido (apenas compartilhamento de dados) 07 = Desafio não pedido (forte autenticação de consumidor já é feita) 08 = Desafio não pedido (usar isenção de lista branca caso o desafio não seja requerido) 09 = Desafio pedido (uso de lista branca caso desafio seja requerido)	= 2 N	NÃO
id	Identificador do 3DS Requestor designado pelo DS.	< 35 AN	SIM
name	Nome do 3DS Requestor designado pelo DS.	< 40 AN	SIM
url	URL completa do site do 3DS Requestor ou site de atendimento ao cliente.	< 2048 AN	SIM
three_ds_requestor. authentication_info	Informações sobre como o 3DS Requestor autenticou o portador do cartão antes ou durante a transação.
data	Dado que documenta e auxilia um processo específico de autenticação.	< 20000 AN	NÃO
method	Mecanismo usado pelo portador do cartão para se autenticar no 3DS Requestor. 01 = Nenhuma autenticação do 3DS Requestor ocorreu (ou seja, portador fez "login" como visitante) 02 = Login para a conta do portador no sistema do 3DS Requestor usando as credenciais do próprio 3DS Requestor 03 = Login para a conta do portador no sistema do 3DS Requestor usando ID federado 04 = Login para a conta do portador no sistema do 3DS Requestor usando credenciais do emissor 05 = Login para a conta do portador no sistema do 3DS Requestor usando autenticação terceirizada 06 = Login para a conta do portador no sistema do 3DS Requestor usando FIDO Authenticator 07 = Login para a conta do portador no sistema do 3DS Requestor usando FIDO Authenticator (garantia de dados FIDO assinada) 08 = Seguro de Dados SRC	= 2 N	NÃO
timestamp	Data e hora UTC da autenticação do portador em formato AAAAMMDDHHMM.	= 12 N	NÃO
three_ds_requestor. prior_authentication_info	Informações sobre como o 3DS Requestor autenticou o portador do cartão como parte de uma transação 3DS prévia.
data	Dado que documenta e auxilia um processo específico de autenticação.	< 2048 AN	NÃO
method	Mecanismo usado anteriormente pelo portador para se autenticar no 3DS Requestor. 01 = Autenticação frictionless ocorrida pelo ACS 02 = Desafio do portador ocorrida pelo ACS 03 = AVS verificada 04 = Outras formas do emissor	= 2 N	NÃO
timestamp	Data e hora UTC da autenticação prévia do portador em formato AAAAMMDDHHMM.	= 12 N	NÃO
reference	Este elemento fornece informações adicionais para que o ACS determine a melhor forma de tratar uma requisição.	< 36 AN	NÃO
acquirer
bin	Código da rede adquirente conforme definida pelo DS.	< 11 AN	SIM
merchant_id	Identificador da loja designado pelo adquirente.	< 35 AN	SIM
browser	Estes parâmetros são obrigatórios caso device_channel = 02.
accept_header	Conteúdo exato do cabeçalho HTTP "Accept" conforme enviado para o 3DS Requestor pelo navegador do comprador.	< 2048 AN	COND.
ip	Endereço IP do comprador.	< 45 AN	COND.
java_enabled	Valor booleano que representa a habilidade do navegador do comprador em executar Java. Este valor é retornado pela propriedade navigator.javaEnabled.	< 5 AN	COND.
javascript_enabled	Valor booleano que representa a habilidade do navegador do portador em executar JavaScript.	< 5 AN	COND.
language	Valor que representa a linguagem do navegador conforme definido na IETF BCP47. Retornado pela propriedade navigator.language.	< 8 AN	COND.
color_depth	Valor que representa a quantidade bits de cor para exibição de imagens, em bits por pixel. Valor obtido pela propriedade screen.colorDepth. 1 = 1 bit 4 = 4 bits 8 = 8 bits 15 = 15 bits 16 = 16 bits 24 = 24 bits 32 = 32 bits 48 = 48 bits	< 2 N	COND.
screen_height	Altura da tela do portador. Valor retornado pela propriedade screen.height.	< 6 N	COND.
screen_width	Comprimento da tela do portador. Valor retornado pela propriedade screen.width.	< 6 AN	COND.
tz	Fuso horário em minutos entre UTC e o horário do navegador do comprador. Valor retornado pelo método getTimezoneOffset().	< 5 AN	COND.
user_agent	User agent do comprador.	< 2048 AN	COND.
cardholder
card_expiry_date	Data de validade do cartão no formato AAMM.	= 4 N	SIM
addr_match	Indica se o endereço de entrega e de cobrança do portador são iguais. Y = Endereços são iguais N = Endereços não são iguais	= 1 AN	NÃO
email	Endereço de email do portador.	< 256 AN	SIM
name	Nome do portador.	< 45 AN	SIM
cardholder. home_phone	Número de telefone residencial do portador.
cc	DDI	< 3 N	SIM
subscriber	DDD + Telefone	< 15 N	SIM
cardholder. mobile_phone	Número do celular do portador.
cc	DDI	< 3 N	SIM
subscriber	DDD + Telefone	< 15 N	SIM
cardholder. work_phone	Número de telefone comercial do portador.
cc	DDI	< 3 N	SIM
subscriber	DDD + Telefone	< 15 N	SIM
cardholder. acct
type	Indica o tipo de conta. Por exemplo, para um cartão múltiplo. 01 = N/A 02 = Crédito 03 = Débito	= 2 N	SIM
number	Número do cartão (PAN)	< 19 N	SIM
id	Informações adicionais sobre a conta fornecidas opcionalmente pelo 3DS Requestor.	< 64 AN	NÃO
cardholder. acct. info
ch_acc_age_ind	Período de tempo que o portador teve conta no 3DS Requestor. 01 = Sem conta (visitante) 02 = Criado durante esta transação 03 = Menos de 30 dias 04 = 30−60 dias 05 = Mais de 60 dias	= 2 N	NÃO
ch_acc_change	Data da última alteração da conta do comprador em formato AAAAMMDD.	= 8 N	NÃO
ch_acc_change_ind	Período de tempo desde a última alteração na conta do portador. 01 = Alterada durante esta transação 02 = Menos de 30 dias 03 = 30−60 dias 04 = Mais de 60 dias	= 2 N	NÃO
ch_acc_date	Data em que o portador abriu a conta no 3DS Requestor no formato AAAAMMDD.	= 8 N	NÃO
ch_acc_pw_change	Data em que o comprador alterou sua senha no formato AAAAMMDD.	= 8 N	NÃO
ch_acc_pw_change_ind	Indica o período de tempo desde a última alteração de senha do portador. 01 = Sem alteração 02 = Alterada durante esta transação 03 = Menos de 30 dias 04 = 30−60 dias 05 = Mais de 60 dias	= 2 N	NÃO
nb_purchase_account	Número de compras com esta conta durante os últimos 6 meses.	< 4 N	NÃO
provision_attempts_day	Número de tentativas de adição de cartão nas últimas 24 horas.	< 3 N	NÃO
txn_activity_day	Número de transações (confirmadas e abandonadas) para este portador com o 3DS Requestor nas últimas 24 horas.	< 3 N	NÃO
txn_activity_year	Número de transações (confirmadas e abandonadas) para este portador com o 3DS Requestor no último ano.	< 3 N	NÃO
payment_acc_age	Data em que a conta de pagamento foi registrada na conta do portador com o 3DS Requestor no formato AAAAMMDD.	= 8 N	NÃO
payment_acc_ind	Indica o período de tempo que a conta de pagamento foi registrada no 3DS Requestor. 01 = Sem conta (visitante) 02 = Durante esta transação 03 = Menos de 30 dias 04 = 30−60 dias 05 = Mais de 60 dias	= 2 N	NÃO
ship_address_usage	Data do primeiro uso do endereço de entrega no formato AAAAMMDD.	= 8 N	NÃO
ship_address_usage_ind	Indica quando foi primeiramente utilizado o endereço de entrega. 01 = Nesta transação 02 = Menos de 30 dias 03 = 30−60 dias 04 = Mais de 60 dias	= 2 N	NÃO
ship_name_indicator	Indica se nome do portador do cartão é idêntico ao nome de entrega utilizada para esta transação. 01 = Nome da conta idêntico ao nome de entrega 02 = Nome de conta diferente de nome de entrega	= 2 N	NÃO
suspicious_acc_activity	Indica se o 3DS Requestor teve experiências suspeitas (incluindo fraude prévia) com a conta do comprador. 01 = Nenhuma atividade suspeita foi observada 02 = Atividade suspeita foi observada	= 2 N	NÃO
cardholder. bill_addr	Endereço de cobrança do portador.
city	Cidade.	< 50 AN	SIM
country	Código numérico ISO 3166-1 de três dígitos do país.	= 3 N	SIM
line1	Primeira linha do endereço.	< 50 AN	SIM
line2	Segunda linha do endereço.	< 50 AN	SIM
line3	Terceira linha do endereço.	< 50 AN	SIM
post_code	CEP.	< 16 AN	SIM
state	Sigla do estado.	< 3 AN	SIM
cardholder. ship_addr	Endereço de entrega do portador.
city	Cidade.	< 50 AN	SIM
country	Código numérico ISO 3166-1 de três dígitos do país.	= 3 N	SIM
line1	Primeira linha do endereço.	< 50 AN	SIM
line2	Segunda linha do endereço.	< 50 AN	SIM
line3	Terceira linha do endereço.	< 50 AN	SIM
post_code	CEP.	< 16 AN	SIM
state	Sigla do estado.	< 3 AN	SIM
merchant
mcc	Código específico do DS que descreve o tipo de negócio/produto/serviço da loja.	= 4 AN	SIM
country_code	Código numérico ISO 3166-1 de três dígitos do país da loja.	= 3 N	SIM
name	Nome da loja designado pelo adquirente ou sistema de pagamento.	< 40 AN	SIM
merchant. risk_indicator	Avaliação da loja sobre o nível de risco de fraude para a autenticação específica para o portador e a autenticação sendo conduzida.
delivery_email_address	Para entrega eletrônica, o endereço de e-mail para qual a mercadoria foi entregue.	< 254 AN	NÃO
delivery_timeframe	Indica o período de tempo de entrega da mercadoria. 01 = Entrega eletrônica 02 = Entrega no mesmo dia 03 = Entrega no dia seguinte 04 = Entrega em dois ou mais dias	= 2 N	NÃO
gift_card_amount	Para compra com cartão presente ou pré-pago, o valor total da compra em números inteiros (por exemplo, 123.45 é 123).	< 15 N	NÃO
gift_card_count	Para compra com cartão presente ou pré-pago, contagem de cartões pré-pagos/presentes comprados.	< 2 N	NÃO
gift_card_curr	Para compra com cartão presente ou pré-pago, código de moeda ISO 4217 de três dígitos do cartão presente.	= 3 N	NÃO
pre_order_date	Para uma pré-venda, a data esperada de disponibilidade da mercadoria no formato AAAAMMDD.	= 8 N	NÃO
pre_order_purchase_ind	Indica se o portador está fazendo um pedido para uma mercadoria com disponibilidade futura. 01 = Mercadoria disponível 02 = Disponibilidade futura	= 2 N	NÃO
reorder_items_ind	Indica se o portador está pedindo uma mercadoria comprada anteriormente. 01 = Pedida pela primeira vez 02 = Pedida novamente	= 2 N	NÃO
ship_indicator	Indica a forma de entrega escolhida para a transação. 01 = Entregar no endereço de cobrança 02 = Entregar em outro endereço verificado no arquivo com a loja 03 = Entregar no endereço que é diferente do endereço de cobrança 04 = Entregar na própria loja 05 = Bens digitais 06 = Bilhetes de viagem ou evento, não entregues fisicamente 07 = Outros	= 2 N	NÃO
message
category	Identifica a categoria da mensagem para um caso de uso específico. 01 - Autenticação de pagamento 02 - Autenticação de não-pagamento	= 2 N	SIM
message. extension[]	Dados necessários para auxiliar em requisitos não definidos na mensagem 3DS são carregados numa extensão de mensagem.
criticality_indicator	Um valor booleano que indica se o destinatário deve entender os conteúdos da extensão para interpretar a mensagem inteira.	< 5 AN	NÃO
data	Dados carregados na extensão.	Object	NÃO
id	Identificador único da extensão.	< 64 AN	NÃO
name	Nome da extensão.	< 64 AN	NÃO
purchase
amount	Valor total da compra em centavos.	< 48 N	SIM
currency	Código da moeda ISO 4217 de três dígitos da compra.	= 3 N	SIM
exponent	Número de casas decimais da moeda conforme definido na ISO 4217.	= 1 N	SIM
date	Data e hora UTC da compra no formato AAAAMMDDHHMMSS.	= 12 N	SIM
instal_data	Número máximo de parcelas da compra. O valor deve ser maior que 1.	< 3 N	SIM
recurring	Dados para transações recorrentes.
expiry	Data em que não serão feitas mais autorizações no formato AAAAMMDD. Obrigatório quando three_ds_requestor. authentication_ind = 02 ou 03.	= 8 N	COND.
frequency	Indica o número mínimo de dias entre autorizações. Obrigatório quando three_ds_requestor. authentication_ind = 02 ou 03.	< 4 N	COND.
sdk	Estes campos são obrigatórios para 3DS SDKs (device_channel = 01).
app_id	GUID criado para todas as instalações do aplicativo do 3DS Requestor num dispositivo do consumidor. Este será gerado e armazenado pelo 3DS SDK para cada instalação.	= 36 AN	COND.
enc_data	Objeto JWE (representado como uma string) contendo dados criptografados pelo SDK para que o DS descriptografe.	< 64000 AN	COND.
ephem_pub_key	Chave pública gerada pelo 3DS SDK para comunicação com o ACS.	Object	COND.
max_timeout	Indica o máximo de tempo (em minutos) para cada troca de mensagem.	< 2 N	COND.
reference_number	Identifica o vendedor e a versão para o 3DS SDK.	< 32 AN	COND.
trans_id	GUID da transação do 3DS SDK.	= 36 AN	COND.
iface	Lista todos os tipos de interface SDK suportadas pelo dispositivo para exibição de interfaces específicas de desafio. 01 = Nativa 02 = HTML 03 = Ambas	= 2 N	COND.
ui_type[]	Lista todos os tipos de interface de usuário que o dispositivo suporta para exibição de interfaces específicas de desafio dentro da SDK. 01 = Texto 02 = Select de um valor 03 = Multi Select 04 = OOB 05 = HTML Outros (válido apenas para interface HTML)	= 2 N[]	COND.
white_list
status	Permite a comunicação de status de lista branca entre ACS, DS e 3DS Requestor. Y = 3DS Requestor está na lista branca do portador N = 3DS Requestor não está na lista branca do portador E = Não qualificado, conforme determinado pelo emissor P = Pendente de confirmação pelo portador R = Portador rejeitou U = Status de lista branca desconhecido, indisponível, ou não se aplica	= 1 AN	NÃO
status_source	Este campo será preenchido pelo sistema que configura o status de lista branca. 01 = 3DS Server 02 = DS 03 = ACS	= 2 N	NÃO

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de autenticação:

Parâmetro	Descrição	Formato
eci	Electronic Commerce Indicator	= 2 N
broad_info	Informação não-estruturada enviada entre 3DS Server, DS e ACS.	Object
device_channel	Canal do dispositivo. Saiba mais.	= 2 N
three_ds_server
trans_id	ID da transação 3DS Server	= 36 AN
status	Status no 3DS Server. Saiba mais.	= 3 AN
acs
challenge_mandated	Indicação de caso o desafio é requerido para a transação a ser autorizada. Y = Desafio é necessário N = Desafio não é necessário	= 1 AN
operator_id	Identificador do ACS designado pelo DS.	< 32 AN
reference_number	Identificador único designado pela EMVCo.	< 32 AN
trans_id	ID da transação no ACS.	= 36 AN
url	URL completa de desafio do ACS.	< 2048 AN
decoupled_confirmation_ind	Indica se o ACS confirma a utilização de autenticação decoupled e concorda com o seu uso para autenticar o comprador. Y = Confirma uso de autenticação decoupled N = Autenticação decoupled não será utilizada	= 1 AN
signed_content	Contém o objeto JWS criado pelo ACS para a mensagem ARes.	var. AN
iface	Esta é a interface ACS em que o desafio será apresentado ao portador. 01 = Nativa 02 = HTML	= 2 N
ui_template	Identifica o formato de interface de usuáro que o ACS apresenta primeiramente ao consumidor. 01 = Texto 02 = Select de um valor 03 = Multi Select 04 = OOB 05 = HTML Outros	= 2 N
authentication
type	Indica o tipo de forma de autenticação que o emissor utilizará para desafiar o portador. 01 = Estática 02 = Dinâmica 03 = OOB 04 = Decoupled	= 2 N
value	Valor específico ao sistema de pagamento fornecido pelo ACS ou o DS usando um algoritmo definido pelo sistema de pagamento. Valor de autenticação que será usado para fornecer prova de autenticação (CAVV).	= 28 AN
cardholder
info	Texto fornecido pelo ACS/Emissor para o portador do cartão durante uma transação frictionless ou decoupled.	< 128 AN
ds
reference_number	Identificador único do DS designado pela EMVCo.	< 32 AN
trans_id	ID da transação no DS.	= 36 AN
message. extension[]	Dados necessários para auxiliar em requisitos não definidos na mensagem 3DS são carregados numa extensão de mensagem.
criticality_indicator	Um valor booleano que indica se o destinatário deve entender os conteúdos da extensão para interpretar a mensagem inteira.	< 5 AN
data	Dados carregados na extensão.	Object
id	Identificador único da extensão.	< 64 AN
name	Nome da extensão.	< 64 AN
transaction
status	Status da transação segundo o protocolo 3DS 2.0. Y = Autenticado com sucesso N = Não autenticado; transação negada. U = Autenticação não pôde ser realizada; problemas técnicos ou outros. A = Tentativas de processamento realizadas; não autenticado, mas uma prova de autenticação é fornecida. C = Desafio requerido. D = Autenticação decoupled requerida. R = Autenticação rejeitada pelo emissor.	= 1 AN
status_reason	Fornece informação sobre o motivo do valor do transaction.status. 01 = Autenticação do cartão falhou 02 = Dispositivo desconhecido 03 = Dispositivo não suportado 04 = Excede limite de frequência de autenticação 05 = Cartão expirado 06 = Número de cartão inválido 07 = Transação inválido 08 = Sem registro de card 09 = Falha de segurança 10 = Cartão roubado 11 = Suspeita de fraude 12 = Transação não permitida para o portador 13 = Portador do cartão não registrado no serviço 14 = Timeout de transação no ACS 15 = Confiança baixa 16 = Confiança média 17 = Confiança alta 18 = Confiança muito alta 19 = Excede máximo de desafios do ACS 20 = Transação de não-pagamento não suportada 21 = Transação 3RI não suportada 22 = Problema técnico no ACS 23 = Autenticação Decoupled requerida pelo ACS, mas não pedida pelo 3DS Requestor 24 = Tempo máximo de autenticação decoupled excedido 25 = Autenticação Decoupled teve tempo insuficiente para autenticar o comprador. ACS não fará tentativa. 26 = Autenticação tentada, mas não realizada pelo portador	= 2 N
white_list
status	Permite a comunicação de status de lista branca entre ACS, DS e 3DS Requestor. Y = 3DS Requestor está na lista branca do portador N = 3DS Requestor não está na lista branca do portador E = Não qualificado, conforme determinado pelo emissor P = Pendente de confirmação pelo portador R = Portador rejeitou U = Status de lista branca desconhecido, indisponível, ou não se aplica	= 1 AN
status_source	Este campo será preenchido pelo sistema que configura o status de lista branca. 01 = 3DS Server 02 = DS 03 = ACS	= 2 N
sdk
trans_id	ID da transação 3DS SDK.	= 36 AN
error
code	Código do erro. Saiba mais.	< 3 N
component	Indica qual componente identificou o erro. C = 3DS SDK S = 3DS Server D = DS A = ACS	= 1 AN
description	Descrição do erro	< 2048 AN
detail	Detalhamento do erro	< 28 AN

Serviço de consulta de transação

Essa chamada permite que o 3DS Requestor consulte o status de uma transação. Essa operação deve ser usada pelo 3DS Requestor caso haja problemas no recebimento do CRes. Retornaremos status, ECI e CAVV, ou seja, o que é necessário para prosseguir com uma autorização.

Detalhes da chamada

• Recurso: /v2/transaction/{ID da transação 3DS Server}
• Método HTTP: GET
• Resposta HTTP OK: 200
• Formato da requisição: não há parâmetros de requisição
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
merchant_id	Código da loja no 3DS Server. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no 3DS Server. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de consulta utilizando a ferramenta cURL.

Requisição:

curl
--request GET "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/transaction/123456789-aaaa-bbbb-cccc-ddddddddddd"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
    "three_ds_server": {
        "trans_id": "12345678-1234-1234-1234-123456789012",
        "status": "AUY"
    },
    "brand_id": "2",
    "eci": "05",
    "device_channel": "02",
    "authentication": {
        "value": "1234567890123456789012345678"
    }
}

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de consulta de transações:

Parâmetro	Descrição	Formato
brand_id	ID da bandeira	< 4 N
eci	Indicador de comércio eletrônico	< 2 N
device_channel	Canal do dispositivo. 01 = aplicativo (APP) 02 = navegador (BRW)	< 2 N
three_ds_server
trans_id	ID da transação 3DS Server	= 35 AN
status	Status no 3DS Server. Saiba mais.	= 3 AN
authentication
value	Valor da autenticação (CAVV)	< 28 AN
error
code	Código do erro. Saiba mais.	< 3 N
component	Indica qual componente identificou o erro. C = 3DS SDK S = 3DS Server D = DS A = ACS	= 1 AN
description	Descrição do erro	< 2048 AN
detail	Detalhamento do erro	< 28 AN

Mensagens de desafio

Para iniciar um desafio, não basta apenas redirecionar o comprador para a URL obtida no campo acs.url, é necessário fazer um POST do CReq. Ao fim dos desafios, o 3DS Requestor receberá informações (na URL apontada no campo notification_url) referentes à transação 3DS dentro do objeto CRes.

Envio do CReq

O POST do CReq deve ser feito com o cabeçalho Content-Type = application/x-www-form-urlencoded quando device_channel = 02 ou application/json quando device_channel = 01. Neste formulário, deve ser enviado o parâmetro creq, cujo conteúdo é o CReq (que é um JSON) codificado em Base64.

Exemplos

CReq JSON:

{
    "threeDSServerTransID":"12341234-1234-1234-1234-123412341234",
    "acsTransID":"43214321-4321-4321-4321-432143214321",
    "challengeWindowSize":"05",
    "messageType":"CReq",
    "messageVersion":"2.2.0"
}

CReq Base64:

ewogICAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiMTIzNDEyMzQtMTIzNC0xMjM0LTEyMzQtMTIzNDEyMzQxMjM0IiwKICAgICJhY3NUcmFuc0lEIjoiNDMyMTQzMjEtNDMyMS00MzIxLTQzMjEtNDMyMTQzMjE0MzIxIiwKICAgICJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLAogICAgIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsCiAgICAibWVzc2FnZVZlcnNpb24iOiIyLjIuMCIKfQ==

HTML de redirecionamento para o desafio:

<!DOCTYPE html>

<html>

    <body>
        <form action="https://www.acs.com/challenge" method="POST">
            <input type="text" name="creq"
                value="ewogICAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiMTIzNDEyMzQtMTIzNC0xMjM0LTEyMzQtMTIzNDEyMzQxMjM0IiwKICAgICJhY3NUcmFuc0lEIjoiNDMyMTQzMjEtNDMyMS00MzIxLTQzMjEtNDMyMTQzMjE0MzIxIiwKICAgICJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLAogICAgIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsCiAgICAibWVzc2FnZVZlcnNpb24iOiIyLjIuMCIKfQ=="/>

            <input type="submit"/>

        
        </form>

    </body>

</html>

Parâmetros do CReq

Parâmetro	Descrição	Formato	Obrigatório
threeDSRequestorAppURL	URL do aplicativo do lojista.	< 256 AN	NÃO
threeDSServerTransID	ID da transação 3DS Server	= 36 AN	SIM
acsTransID	ID da transação ACS	= 36 AN	SIM
challengeCancel	Indicador que informa o ACS e o DS que a autenticação foi cancelada. 01 = Portador selecionou "Cancelar" 03 = Timeout de autenticação decoupled 04 = Timeout no ACS 05 = Primeiro CReq não recebido pelo ACS 06 = Erro na transação 07 = Desconhecido 08 = Timeout no 3DS SDK	= 2 N	NÃO
challengeDataEntry	Contém os dados que o portador digitou no campo de texto da interface nativa.	< 45 AN	NÃO
challengeHTMLDataEntry	Contém os dados que o portador digitou no campo de texto da interface HTML.	< 256 AN	NÃO
challengeNoEntry	Indicador que informa que o portador submeteu uma resposta vazia. Y = Sem entrada de dados	= 1 AN	NÃO
challengeWindowSize	Dimensões da janela de desafio exibida ao portador. 01 = 250 x 400 02 = 390 x 400 03 = 500 x 600 04 = 600 x 400 05 = Tela cheia	= 2 N	SIM
messageType	Valor fixo CReq.	= 4 AN	SIM
messageVersion	Versão de mensagem 3DS: 2.1.0 ou 2.2.0.	< 8 AN	SIM
oobContinue	Valor booleano que notifica o ACS que o portador completou a autenticação selecionando o botão "Continuar" numa forma de autenticação OOB.	< 5 AN	NÃO
resendChallenge	Indicador para o ACS para reenviar o código de informação de desafio para o portador. Y = Reenviar N = Não reenviar	= 1 AN	NÃO
sdkTransID	ID de transação 3DS SDK. Obrigatório quando device_channel = 01.	= 36 AN	COND.
sdkCounterStoA	Contador usado como medida de segurança no canal seguro entre 3DS SDK e ACS.	< 3 AN	NÃO
whitelistingDataEntry	Indicador fornecido pelo SDK ao ACS para confirmar se a lista branca foi optada pelo portador. Y = Lista branca confirmada N = Lista branca não confirmada	= 1 AN	NÃO
messageExtension[]	Dados necessários para auxiliar em requisitos não definidos na mensagem 3DS são carregados numa extensão de mensagem.
criticalityIndicator	Um valor booleano que indica se o destinatário deve entender os conteúdos da extensão para interpretar a mensagem inteira.	< 5 AN	NÃO
data	Dados carregados na extensão.	Object	NÃO
id	Identificador único da extensão.	< 64 AN	NÃO
name	Nome da extensão.	< 64 AN	NÃO

Recebimento do CRes

O CRes chegará em formato JSON codificado em Base64 na URL informada no serviço de autenticação (campo notification_url).

Parâmetros do CRes

Parâmetro	Descrição	Formato
threeDSServerTransID	ID de transação 3DS Server	= 36 AN
acsCounterAtoS	Contador usado como medida de segurança no canal seguro entre ACS e 3DS SDK.	< 3 AN
acsTransID	ID de transação no ACS	= 36 AN
challengeCompletionInd	Indicador do estado do desafio. Y = Desafio concluído, e não serão necessárias novas mensagens de desafio N = Desafio não concluído, e serão necessárias novas mensagens de desafio	= 1 AN
messageType	Valor fixo CRes.	= 4 AN
messageVersion	Versão de mensagem 3DS: 2.1.0 ou 2.2.0.	< 8 AN
sdkTransID	ID de transação no 3DS SDK	= 36 AN
transStatus	Status da transação segundo o protocolo 3DS 2.0. Y = Autenticado com sucesso N = Não autenticado; transação negada. U = Autenticação não pôde ser realizada; problemas técnicos ou outros. A = Tentativas de processamento realizadas; não autenticado, mas uma prova de autenticação é fornecida. C = Desafio requerido. D = Autenticação decoupled requerida. R = Autenticação rejeitada pelo emissor.	= 1 AN
messageExtension[]	Dados necessários para auxiliar em requisitos não definidos na mensagem 3DS são carregados numa extensão de mensagem.
criticalityIndicator	Um valor booleano que indica se o destinatário deve entender os conteúdos da extensão para interpretar a mensagem inteira.	< 5 AN
data	Dados carregados na extensão.	Object
id	Identificador único da extensão.	< 64 AN
name	Nome da extensão.	< 64 AN

Notificação decoupled

Durante o processo de uma autenticação decoupled, o 3DS Server fará uma notificação para o 3DS Requestor informando o resultado da autenticação. Essa notificação se dará por meio de um HTTP POST na URL informada no serviço de autenticação (campo decoupled_notification_url), no formato application/x-www-form-urlencoded. O 3DS Requestor deve responder a essa chamada com o código HTTP 200.

Abaixo estão os parâmetros dessa notificação:

Parâmetro	Descrição	Formato
three_ds_server_status	Status no 3DS Server. Saiba mais.	= 3 AN
three_ds_server_trans_id	ID de transação 3DS Server.	= 36 AN
eci	Electronic Commerce Indicator.	= 2 N
authentication_value	Valor específico ao sistema de pagamento fornecido pelo ACS ou o DS usando um algoritmo definido pelo sistema de pagamento. Valor de autenticação que será usado para fornecer prova de autenticação (CAVV).	= 28 AN

Iniciando um 3DS Method

Ao chamar o serviço de criação da transação, pode ser retornado o campo three_ds_method_url. Isso indica que deve ser renderizado um frame invisível na tela do comprador apontando para essa URL. Para isso, é necessário fazer um HTTP POST no formato application/x-www-form-urlencoded passando o campo threeDSMethodData, que se trata de um JSON codificado em Base64.

Parâmetros do objeto threeDSMethodData

Parâmetro	Descrição	Formato	Obrigatório
threeDSMethodNotificationURL	URL que receberá a notificação de conclusão do 3DS Method pelo ACS.	< 256 AN	SIM
threeDSServerTransID	ID da transação 3DS Server.	= 36 AN	SIM

Exemplos

threeDSMethodData JSON:

{
   "threeDSServerTransID":"12341234-1234-1234-1234-123412341234",
   "threeDSMethodNotificationURL":"threeDSMethodNotificationURL"
}

threeDSMethodData Base64:

ewogICAidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxMjM0MTIzNC0xMjM0LTEyMzQtMTIzNC0xMjM0MTIzNDEyMzQiLAogICAidGhyZWVEU01ldGhvZE5vdGlmaWNhdGlvblVSTCI6InRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiCn0=

Formulário HTML:

<form name="frm" method="POST" action="Rendering URL">
    <input type="hidden" name="threeDSMethodData" value="ewogICAidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxMjM0MTIzNC0xMjM0LTEyMzQtMTIzNC0xMjM0MTIzNDEyMzQiLAogICAidGhyZWVEU01ldGhvZE5vdGlmaWNhdGlvblVSTCI6InRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiCn0=">
</form>

Notificação 3DS Method

Essa chamada será feita pelo ACS na URL informada pelo 3DS Requestor (campo threeDSMethodNotificationURL) utilizando o mesmo formato do formulário descrito acima. Essa chamada é importante para o preenchimento do campo three_ds_comp_ind no serviço de autenticação.

Códigos da API

IDs de bandeira

ID	Nome
1	Visa
2	Mastercard
41	Elo

Status de transações do 3DS Server

Código	Nome	Descrição
NEW	Nova	Transação criada recentemente.
INV	Inválida	Loja enviou algum parâmetro inválido.
ERR	Erro de comunicação	Falha na comunicação com o DS.
EXP	Expirada	Transação nova excedeu seu prazo de validade.
ERM	Mensagem de Erro	3DS Server recebeu uma mensagem de erro do DS.
AUY	Status 3DS Y	Autenticação bem-sucedida.
AUN	Status 3DS N	Não autenticada/conta não verificada; transação negada.
AUU	Status 3DS U	Autenticação/Verificação de Conta não pôde ser realizada; problemas técnicos ou outros erros.
AUA	Status 3DS A	Tentativa de processamento realizada; não autenticada/verificada, mas uma prova de tentativa de autenticação/verificação é fornecida.
AUC	Status 3DS C	Será necessário um desafio, seguindo o fluxo "challenge".
AUR	Status 3DS R	Autenticação/verificação de conta rejeitada; emissor está rejeitando.
AUD	Status 3DS D	Será necessário um desafio, seguindo o fluxo "decoupled".

Códigos de erro

Código	Descrição
1	Credenciais (merchant_id e merchant_key) inválidas
2	Transação não encontrada
3	Status inválido da transação
101	Mensagem de tipo desconhecido
201	Parâmetro vazio (ver error.detail para mais detalhes)
202	message.extension não reconhecido
203	Parâmetro inválido (ver error.detail para mais detalhes)
301	ID de transação inválido para o componente recebido
305	Cartão não suportado pelo emissor para autenticações 3DS 2.0
402	Timeout na comunicação com o DS
404	Erro inesperado
405	Erro de comunicação com o DS

Campo device_channel

Código	Descrição
01	Aplicativo
02	Navegador
03	Iniciado pelo 3DS Requestor (3RI)
04-79	Reservado para uso futuro pela EMVCo
80-99	Reservado para uso futuro pelo DS