e.Rede REST · e-SiTef

A loja tem a possibilidade de configurar o roteamento de transações feitas com cartões de crédito e débito no e-SiTef por vários meios de pagamento, um desses meios é o e.Rede REST. Esta é a plataforma e-commerce da adquirente Rede.

Será usada a nomenclatura "e.Rede REST" para referenciar o roteamento no e-SiTef.

Atenção: O e-SiTef possui o roteamento e-Rede, porém esta integração é uma versão anterior com funcionalidades limitadas e não terá mais suporte a atualizações. Logo, a opção e.Rede REST é a recomendada atualmente.

Interfaces e-SiTef suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento e.Rede REST:

Pagamento REST
Pré-Autorização REST
Captura REST
Cancelamento REST
Pagamento HTML
Pré-Autorização HTML
Cancelamento no Portal do Lojista

Credenciais necessárias

A loja deve obter com a e.Rede as credenciais listadas abaixo, e repassá-las à Software Express ou fazer o cadastro no Portal do Lojista do e-SiTef conforme será explicado mais a frente neste mesmo documento.

Campo	Descrição	Formato
`filiation`	Código identificador gerado pela Rede para os estabelecimentos filiados. O PV (ponto de venda) é único para cada estabelecimento.	< 8 AN
`token`	Código de segurança gerado pela Rede utilizado para garantir a integridade da transação. Faz parte, junto com o PV, das credenciais de autenticação da API	< 32 AN
`threeDSecureOnFailure`	Indica se deve prosseguir com a autorização em caso de falha na autenticação 3DS	Não prossegue ou Prossegue
`subacquirerMerchantId`	Código do sub lojista. Utilizável somente quando for usar o MCC Dinâmico	< 32 AN
`independentSalesOrganizationId`	Código da organização de vendas independente. Utilizável somente quando for usar o MCC Dinâmico	< 11 AN
`paymentFacilitatorId`	Código do facilitador. Utilizável somente quando for usar o MCC Dinâmico.	< 11 N

Aviso importante para o Pagamento HTML: No caso de uma autorizadora da loja não ter cadastrado essas credenciais, essa autorizadora não será exibida na tela de seleção de cartão de crédito durante a operação de pagamento.

Cadastro das informações pelo Portal do Lojista e-SiTef

O próprio lojista pode cadastrar as informações obtidas com a e.Rede no Portal do Lojista do e-SiTef. Para essa finalidade, o lojista deve selecionar a autorizadora e entrar na tela de edição como no exemplo exibido abaixo:

Portal e.Rede REST

Saiba mais detalhes sobre o Portal do Lojista.

Fluxos

Nesta seção serão apresentadas as particularidades do fluxo transacional e.Rede REST.

Atualmente, o e.Rede REST não permite parcelamento com juros da administradora do cartão, ou seja, o campo installments_type não pode receber os valores 3 ou 6. O campo installments permite o máximo de 12 parcelas.

Criação de Transação de Pagamento (HTML e REST)

MCC Dinâmico

Campos relevantes na chamada descrita no Serviço de criação de transação HTML e no Serviço de criação de transação REST:

Parâmetro	Descrição	Formato	Obrigatório
`soft_descriptor` (*)	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais	< 13 AN	NÃO
additional_data	Elemento para envio de dados adicionais.
`mcc` (*)	O MCC (Merchant Category Code) é um código que classifica um negócio pelo tipo de bens ou produtos fornecidos.	< 4 N	NÃO
`postpone_confirmation`	Campo que permite que loja mantenha a transação como Pendente de Confirmação, e posteriormente, confirmá-la ou desfazê-la.	< 5 A	NÃO

(*) Aviso sobre SoftDescriptor e MCC: No contexto de marketplace ou facilitador de pagamentos, é permitido o uso de ambos os campos pela requisição ou utilizando dados cadastrados no backoffice do e-SiTef. Os valores enviados via requisição possuem precedência sobre os valores cadastrados. Adicionalmente, para o mesmo contexto, pode ser cadastrado no e-SiTef o id de SubLoja a ser informado no pagamento. Sobre o cadastro destes valores, por favor entre em contato com a equipe de atendimento do e-SiTef.

Autenticação 3DS Rede

Campos relevantes na chamada descrita no Serviço de criação de transação HTML e no Serviço de criação de transação REST:

Parâmetro	Descrição	Formato	Obrigatório
`authorizer_authentication`	Define se o lojista deseja um pagamento com autenticação na autorizadora. Enviar `true` caso positivo.	< 5 AN	SIM para crédito com autenticação
back_url	Elemento para envio das urls de redirecionamento utilizadas na autenticação MPI Rede
`url_success` (*)	URL de redirecionamento do cliente em caso de sucesso. Deve possuir apenas o caminho relativo ao domínio.	< 87 A	NÃO
`url_failure` (*)	URL de redirecionamento do cliente em caso de fracasso. Deve possuir apenas o caminho relativo ao domínio.	< 87 A	NÃO

É possível realizar um pagamento com autenticação 3DS MPI Rede, desde que esta funcionalidade esteja ativa na conta do lojista na e.Rede. Para utilizar esta funcionalidade no e-SiTef, basta enviar o parâmetro authorizer_authentication com valor true na etapa de criação da transação.

Para pagamentos com cartão de débito, a autenticação é obrigatória, a não ser no caso de Auxílio Emergencial.

(*) Importante: Para pagamentos REST com MPI Rede é obrigatório o envio das informações de backurl referentes aos casos de sucesso e fracasso, para o correto redirecionamento do usuário para a loja ao final do processo de autenticação.

Para cada uma delas o tamanho total da URL (domínio da loja cadastrado no e-SiTef + caminho relativo) deve possuir no máximo 87 caracteres.

Exemplo de requisição de criação de transação para Pagamento REST:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "merchant_usn":"123456789",
    "order_id":"pedido001",
    "amount":"2200",
    "authorizer_id":"2",
    "installments":"2",
    "installment_type":"4",
    "authorizer_authentication":"true",
    "back_url":{
        "url_success":"/urlSucesso.html",
        "url_failure":"/urlFracasso.html"
    }
}
{
--verbose

No caso de falha de autenticação, o lojista pode escolher dar prosseguimento no pagamento ou ter o pagamento interrompido(não prosseguir). Este comportamento deve ser cadastrado no backoffice do e-SiTef, sendo que o seu valor padrão é Não prosseguir caso a autenticação falhe. Para esta configuração, por favor consulte a equipe de atendimento do e-SiTef ou isto pode ser feito via Portal do Lojista.

Pagamento REST

Essa interface suporta o envio de dados de autenticação 3DS externa (eci, xid e cavv) na etapa de efetivação do pagamento. Saiba mais.

Esta integração aceita o uso da carteira digital Visa Checkout.

Pagamento HTML

No caso de pagamento com cartão de débito que não seja elegível para o auxílio emergencial, o e-SiTef forçará a autenticação 3DS com MPI Rede, independente do envio do campo authorizer_authentication na etapa de criação da transação.

Esta integração aceita o uso da carteira digital Masterpass.

Confirmação de Pagamento

É possível confirmar um valor inferior ao valor das autorizações criadas via HTML ou via REST utilizando o campo additional_data.postpone_confirmation igual a true.

Para isso, envie na chamada de confirmação REST o valor de amount desejado:

Parâmetro	Descrição	Formato	Obrigatório
`confirm`	Este campo deve ser enviado com o valor `true` caso se deseje confirmar a transação, ou `false`, caso queira desfazer o pagamento.	< 5 T/F	SIM
`amount`	Valor em centavos do valor que será confirmado. Caso não seja enviado, o valor completo da transação será confirmado.	< 12 N	NÃO

No e.Rede REST, a confirmação de pagamento gera um novo "NSU da autorizadora" e "data de efetivação do pagamento".

Pré-Autorização REST

Essa interface suporta o envio o envio de dados de autenticação externa 3DS (eci, xid e cavv). Saiba mais.

Também é possível o envio dos campos soft_descriptor e mcc na etapa de criação de transação, da mesma forma que no Pagamento REST (veja acima).

Esta integração aceita o uso da carteira digital Visa Checkout.

No fluxo de Pré-Autorização/Captura, os dados de parcelamento devem ser enviados somente na pré-autorização.

Pré-Autorização HTML

Esta integração aceita o uso da carteira digital Masterpass.

Também é possível o envio dos campos soft_descriptor e mcc na etapa de criação de transação, da mesma forma que no Pagamento HTML (veja acima).

No fluxo de Pré-Autorização/Captura, os dados de parcelamento devem ser enviados somente na pré-autorização.

Recorrência

O e.Rede REST aceita o parâmetros de sinalização de recorrência de transações. Para isso, envie na chamada de efetivação de pagamento REST o campo acquirer.recurrency com o valor true. Caso não seja a primeira transação da recorrência, envie também o TID da primeira transação da recorrência no campo acquirer.recurrency_tid.

Para mais informações consulte a página sobre o Serviço de Efetivação de Pagamento REST.

Parâmetro	Descrição	Formato	Obrigatório
acquirer	Dados específicos necessários dependendo da adquirente/roteamento.
`recurrency`	Flag que define se o pagamento é ou não recorrente.	< 5 T/F	NÃO
`recurrency_tid`	Id da transação (TID) na bandeira, referente à primeira transação da recorrência. Identificador que diferencia a primeira recorrência das subsequentes. Só é utilizado quando for uma recorrência. Campo utilizado somente para as bandeiras Visa e Mastercard.	< 16 AN	NÃO

Cancelamento

O Cancelamento de uma transação pode ser feito no Portal do Lojista ou via Web Service REST.

As solicitações de cancelamento podem ser realizadas em até 7 dias para transações de débito e para transações de crédito o padrão é de até 90 dias, mas pode variar conforme o ramo de atuação de cada estabelecimento.

Para cancelamentos solicitados no mesmo dia da transação de autorização ou autorização com captura automática, o processamento será realizado imediatamente, caso contrário, o processamento será realizado em D+1.

Cancelamento parcial disponível somente em D+1 e para transações com captura.

Campos de MCC Dinâmico

Inicialização da transação de pagamento ou de pré-autorização REST

Parâmetros de requisição

Adicionalmente aos campos mencionados no Serviço de criação de transação REST, os campos abaixo são usados no cenário específico de MCC dinâmico da integração com o e.Rede REST:

Parâmetro	Descrição	Formato	Obrigatório
`soft_descriptor`	Frase personalizada que será impressa na fatura do portador. Para informação referente ao MCC dinâmico, equivale ao nome do sublojista.	< 18 AN	SIM
additional_data	Elemento para envio de dados adicionais.
`mcc`	MCC do sublojista.	= 4 N	SIM
`subacquirer_merchant_id`	Código do sublojista. Campo legado!!! Dar preferência ao `additional_data.subacquirer_merchant.id`	< 15 N	NÃO
additional_data.subacquirer_merchant	Elemento para envio de dados referentes ao lojista de uma subadquirente.
`id`	Código do sublojista.	< 15 N	SIM
`address`	Endereço do sublojista.	< 48 AN	NÃO
`city`	Cidade do sublojista.	< 13 AN	NÃO
`state`	Estado do sublojista, em formato de sigla de dois dígitos (ex.: SP).	= 2 A	SIM
`country`	País do sublojista. Seguir o padrão ISO 3166-1 alpha-2 (ex.: BR).	= 2 A	SIM
`zip_code`	Código postal do sublojista.	< 9 AN	SIM
`identification_number`	CNPJ do sublojista.	< 18 N	SIM
`payment_facilitator_id`	Código do facilitador.	< 11 N	SIM
`independent_sales_organization_id`	Código da organização de vendas independente.	< 11 N	NÃO

Exemplo

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "merchant_usn": "21042858195",
    "order_id": "21042858195",
    "amount": "102",
    "installments": "1",
    "installment_type": "4",
    "mcc": "1111",
    "soft_descriptor": "LOJADOZE",
    "additional_data": {
         "subacquirer_merchant": {
            "id": "1234567890",
            "address": "Rua Acre",
            "city": "CAPIVARI",
            "state": "SP",
            "country": "BR",
            "zip_code": "07064-010",
            "identification_number": "71.789.371/0001-42",
            "payment_facilitator_id": "22349202212",
            "independent_sales_organization_id": "1234567"
        }
    }
}

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "pre_authorization": {
        "status": "NOV",
        "nit": "c2d2887a2961a218e6e6effa8a39f281d386d581c8c8b4dc23a3af03b5c6b8c4",
        "order_id": "21042858195",
        "merchant_usn": "21042858195",
        "amount": "102"
    }
}

Parâmetros na efetivação do pagamento ou da pré-autorização REST

Adicionalmente aos campos mencionados nos Serviço de efetivação de pagamento REST e Serviço de efetivação de Pré-Autorização REST, os campos abaixo são usados no cenário específico de MCC dinâmico da integração com o e.Rede REST:

Parâmetro	Descrição	Formato	Obrigatório
`soft_descriptor`	Frase personalizada que será impressa na fatura do portador. Para informação referente ao MCC dinâmico, equivale ao nome do sublojista. Obrigatório somente se não foi enviado no `soft_descriptor` da etapa de inicialização da transação.	< 18 AN	COND.
`mcc`	MCC do sublojista. Obrigatório somente se não foi enviado no `additional_data.mcc` da etapa de inicialização da transação.	= 4 N	COND.
`subacquirer_merchant_id`	Código do sublojista. Obrigatório somente se não foi enviado no `additional_data.subacquirer_merchant.id` da etapa de inicialização da transação.	< 15 N	COND.

ATENÇÃO!

É na efetivação que enviamos os dados acumulados de MCC dinâmico. Porém, se o campo mcc não for enviado em nenhum momento nem estiver cadastrado, os outros campos de MCC dinâmico não serão repassados. Este campo é necessário para identificar que o lojista deseja enviar dados de subadquirência.

Exemplo

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "authorizer_id":"2",
    "installments":"1",
    "installment_type":"4",
    "soft_descriptor":"outraloja",
    "mcc": "2234",
    "subacquirer_merchant_id": "223456",
    "card":{
        "number":"5448280000000007",
        "expiry_date":"0121",
        "security_code":"123"
    }
}

Resposta:

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

Tabela de correspondência de campos

Segue abaixo a tabela de correspondência entre os campos de MCC dinâmico definidos pela interface do e.Rede REST e os campos do e-SiTef.

Campo e.Rede REST	Campo e-SiTef	Observações
softDescriptor	soft_descriptor	O campo softDescriptor do e.Rede REST pode ser enviado na etapa de criação da transação, na efetivação do pagamento ou da pré-autorização REST ou cadastrado pela equipe de atendimento do e-SiTef.
PaymentFacilitatorID	additional_data / subacquirer_merchant / payment_facilitator_id ou paymentFacilitatorId	O campo PaymentFacilitatorID do e.Rede REST pode ser enviado na etapa de criação da transação ou ser configurado quando um roteamento de uma autorizadora é feito via e.Rede REST. Neste último caso, o seu valor pode ser alterado pelo Portal do Lojista ("Autorizadoras" > "Configurar Autorizadoras") ou por solicitacão à equipe de atendimento do e-SiTef.
IndependentSalesOrganizationID	additional_data / subacquirer_merchant / independent_sales_organization_id ou independentSalesOrganizationId	O campo IndependentSalesOrganizationID do e.Rede REST pode ser enviado na etapa de criação da transação ou ser configurado quando um roteamento de uma autorizadora é feito via e.Rede REST. Neste último caso, o seu valor pode ser alterado pelo Portal do Lojista ("Autorizadoras" > "Configurar Autorizadoras") ou por solicitacão à equipe de atendimento do e-SiTef.
SubMerchant / MCC	additional_data / mcc ou mcc	O campo SubMerchant / MCC do e.Rede REST pode ser enviado na etapa de criação da transação, na efetivação do pagamento ou da pré-autorização REST ou cadastrado pela equipe de atendimento do e-SiTef.
SubMerchant / SubMerchantID	additional_data / subacquirer_merchant_id ou additional_data / subacquirer_merchant / id ou subacquirer_merchant_id ou subacquirerMerchantId	O campo SubMerchant / SubMerchantID do e.Rede REST pode ser enviado na etapa de criação da transação, na efetivação do pagamento ou da pré-autorização REST ou ser configurado quando um roteamento de uma autorizadora é feito via e.Rede REST. Neste último caso, o seu valor pode ser alterado pelo Portal do Lojista ("Autorizadoras" > "Configurar Autorizadoras") ou por solicitacão à equipe de atendimento do e-SiTef.
SubMerchant / Address	additional_data / subacquirer_merchant / address	O campo SubMerchant / Address do e.Rede REST pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
SubMerchant / City	additional_data / subacquirer_merchant / city	O campo SubMerchant / City do e.Rede REST pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
SubMerchant / State	additional_data / subacquirer_merchant / state	O campo SubMerchant / State do e.Rede REST pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
SubMerchant / Country	additional_data / subacquirer_merchant / country	O campo SubMerchant / Country do e.Rede REST pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
SubMerchant / CEP	additional_data / subacquirer_merchant / zip_code	O campo SubMerchant / CEP do e.Rede REST pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.
SubMerchant / Cnpj	additional_data / subacquirer_merchant / identification_number	O campo SubMerchant / Cnpj do e.Rede REST pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do e-SiTef para cadastrar ou alterar o valor padrão deste campo em sua loja.

ATENÇÃO!

Quando um campo puder ser enviado de mais de uma forma, sempre prevalecerá o valor do campo enviado mais recentemente ou mais específico. Ou seja, a prioridade segue a regra: mais recente > mais específico > cadastral.

Exemplo: Se o campo SubMerchant / SubMerchantID for enviado na efetivação, este terá prioridade sobre o enviado na inicialização, o qual tem prioridade sobre o campo cadastral.