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:
- 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).
- 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:
- 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 valortrue
. - 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). - Concluindo, a loja virtual chama o serviço de confirmação do pagamento, passando o NIT novamente e o parâmetro
confirm
com valortrue
, resultando numa transação com statusCON
(confirmada). Também existe a possibilidade do lojista desfazer a transação em vez de confirmar. Para isso, o parâmetroconfirm
deve ser enviado com valorfalse
, o que resultará numa transação com statusPPN
(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:
{
"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:
{
"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
--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
ecompany_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 – AceitaREJ – RejeitadaREV – Em revisãoINV – 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 – AceitaREJ – RejeitadaREV – Em revisãoINV – 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:
- 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).
- 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.
- 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 – AceitaREJ – RejeitadaREV – Em revisãoINV – 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:
- A criação de uma transação do tipo "Confirmação" que represente a transação real de pagamento criada externamente
- 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
equery 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:
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
ecard.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.
- 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
- 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.
{
"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:
@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:
{
"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
--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
ecompany_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 - Visa0080 - MastercardEstes 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
ecompany_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:
- Ao iniciar a operação beginTransaction pela loja virtual, é retornado um
nit
(identificador da transação) e outros parâmetros; - 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 paraCON
(transação confirmada). - 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:
{
"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:
{
"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:
{
"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:
{
"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
--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:
| = 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
ecompany_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
emessage
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:
- 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).
- 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.
- 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
ecompany_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
{
"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
{
"authorizer_id":"2",
"installments":"2",
"installment_type":"4",
"card":{
"number":"xxxxxxxxxxxxxxxx",
"expiry_date":"1222",
"security_code":"yyy"
}
}
c. 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":"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
{
"authorizer_id":"2",
"installments":"2",
"installment_type":"4",
"additional_amount": "200",
"card":{
"number":"xxxxxxxxxxxxxxxx",
"expiry_date":"1222",
"security_code":"yyy"
}
}
b. incremento - resposta
{
"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
{
"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:
| = 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
ecompany_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:
- 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.
- 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 statusATV
(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:
- O lojista cria uma transação no e-SiTef passando os dados do agendamento e o parâmetro
do_payment_now
com valorfalse
. Como resposta, o lojista obterá um SID (identificador de agendamento). - 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:
{
"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:
{
"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
--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.
- 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
- 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
ouINA
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.
{
"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:
@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:
{
"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 – NovoEXP – ExpiradoCON – ConfirmadoINV – 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 de0
);
- 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:
{
"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:
@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
--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
--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:
{
"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:
{
"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:
{
"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
Headers:
- Content-Type: application/json
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"
}
}
}
}
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 | = 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 |
questions.rule
Retorno do campo 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). |
questions.type
Retorno do campo 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 – Sim2 – NãoExemplo de exibição de Menu Livre tipo 0: Sim Não |
Serviço de listagem de dados da filial
normal
Detalhes da chamada para recarga tipo - Recurso:
/v3/rechargebranches
- Método HTTP:
GET
- Formato da requisição:
query string
- Formato da resposta:
JSON
others
Detalhes da chamada para recarga tipo - Recurso:
/v3/rechargebranches/{nit}
- Método HTTP:
PUT
- Formato da requisição:
JSON
- Formato da resposta:
JSON
invoice
Detalhes da chamada para recarga tipo - 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.
normal
Listagem de dados da filial de recarga tipo 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"
]
}
}
}
others
Listagem de dados da filial de recarga tipo 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"
]
}
}
}
invoice
Listagem de dados da filial de recarga tipo 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"
}
}
normal
Parâmetros de requisição para recarga tipo 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 |
others
Parâmetros de requisição para recarga tipo 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. |
invoice
Parâmetros de requisição para recarga tipo 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 |
payment_methods.available
Retorno do campo 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 (tipos02
e03
).
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-71 : digitação da primeira linha do cheque2 : 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 vista01 – Pré-datado02 – Parcelado pelo estabelecimento03 - 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.
normal
com pagamento
Recarga tipo 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"
}
}
}
}
normal
sem pagamento
Recarga tipo 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"
}
]
}
}
}
others
Recarga tipo 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"
}
}
}
invoice
Recarga tipo 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 - PDV02 - TU03 - TAS04 - Internet05 - 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. |
used_payment_methods
Envio do campo 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:
| = 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 campopayment.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:
| = 1A |
authorizer_id | Id da autorizadora no e-SiTef onde o pagamento foi feito | < 5 N |
acquirer | Tipo de pagamento | < 50 AN |