::: container-section-documentation

## Documentação{#documentacao .menu-nv1}

### Pré-requisitos técnicos {#documentacao-pre-requisitos-tecnicos .menu-nv2}

O mecanismo de integração é simples, de modo que conhecimentos em linguagem de programação para web, requisições HTTPS e manipulação de arquivos JSON sejam necessários para implantar a solução com sucesso.

### Credenciamento {#documentacao-credenciamento .menu-nv2}

Para solicitar o credenciamento do e.Rede e realizar a integração à sua aplicação, entre em contato com a Central de atendimento da Rede:

**4001 4433** (_capitais e regiões metropolitanas_)
**0800 728 4433** (_demais localidades_)

Quando o credenciamento for realizado, o responsável pelo estabelecimento será notificado via e-mail com o número de filiação (PV), orientações para acessar ao portal da Rede e suas credenciais para integração.

### Certificado Digital Rede {#documentacao-certificado-digital-rede .menu-nv2}

**O que é um certificado digital?**
Certificado digital é um arquivo eletrônico que serve como identidade virtual para uma empresa e por ele pode se fazer transações online com garantia de autenticidade. Como uma prática de mercado para garantir toda a proteção das informações trocadas entre sua empresa e a Rede, é realizada a atualização do Certificado Digital Rede anualmente.

**Por que ele deve ser atualizado?**
Para garantir maior segurança em suas vendas realizadas online.

**Como fazer a atualização do Certificado Digital Rede?**
Para que seja feita a atualização do certificado dentro da sua empresa, pedimos que você direcione esta atividade ao seu time de tecnologia ou a quem tenha acesso ao seu servidor e seja responsável pela sua aplicação e-commerce. Caso o seu contato com a Rede seja feito por meio de sua plataforma, gateway ou módulo pedimos que entre em contato com eles para a atualização.

Ela deve ser realizada a partir do servidor que é responsável pela comunicação entre a sua empresa e a Rede e no qual o certificado já esteja instalado. Baixe o certificado digital de acordo com o seu sistema operacional determinado nas caixas sinalizadas abaixo nesta página.

Para efetuar a instalação ou atualização do Certificado Digital Rede utilize o link abaixo e siga as instruções.
[https://www.userede.com.br/n/documentos/certificado-digital-rede](https://www.userede.com.br/n/documentos/certificado-digital-rede)

Caso seu e-commerce não faça uso de certificado digital, essa etapa não é necessária.

### Homologação e certificado SSL {#documentacao-homologacao-certificado-ssl .menu-nv2}

Para transacionar com a API do e.Rede é necessário que o estabelecimento possua instalado na página de pagamento um certificado de segurança SSL com criptografia 2048 bits ou superior, para garantir o sigilo das informações transferidas e certificar ao portador do cartão que está realmente acessando o site desejado, evitando problemas com fraude.

Para garantir que os estabelecimentos tenham o certificado SSL instalado, a Rede faz o processo de homologação automaticamente da loja ou serviço virtual do estabelecimento após a realização da primeira transação.

**IMPORTANTE:** Periodicamente, o processo de homologação é realizado e a Rede se reserva o direito de suspender o uso da plataforma até que a loja ou serviço virtual estejam adequados às normas de segurança solicitadas.

Para identificar se a página possui o certificado SSL, ao acessar o site, a URL deve ser exibida com o protocolo “https” possibilitando a visualização do cadeado de segurança nos navegadores.

### Exemplos:

#### Firefox:

![SSL Firefox](assets/images/e-rede/ssl-firefox.png){#img-ssl-firefox .content-image}

#### Google Chrome:

![SSL Google Chrome](assets/images/e-rede/ssl-google-chrome.jpg){#img-ssl-chrome .content-image}

#### Internet Explorer:

![SSL Internet Explorer](assets/images/e-rede/ssl-internet-explorer.jpg){#img-ssl-internet-explorer .content-image}

Caso o estabelecimento tenha sido suspenso por não estar certificado, acesse o portal da Rede no menu _para vender > e-commerce > homologação_ e clique em “Solicitar homologação” após a regularização do certificado SSL.

### Filiação e Chave de Integração {#documentacao-filiacao-chave-integracao .menu-nv2}

Para que o estabelecimento comece a transacionar com o e.Rede, é necessário configurar a API com suas credenciais: número de filiação (PV) e chave de integração.

A **chave de integração** é uma chave de uso confidencial, gerada no [Portal da Rede](https://www.userede.com.br/){target="_blank"}. Para gerá-la, certifique-se que seu usuário possua perfil de administrador (usuário master). Acesse o menu: \_e.Rede > para vender > e-commerce > chave de integração_ e clique em “Gerar chave de integração”.

Em caso de perda ou esquecimento da chave de integração, uma nova deverá ser gerada e a configuração da API deverá ser alterada, para que as transações continuem sendo enviadas à Rede.

### Métodos HTTP {#documentacao-metodos-http .menu-nv2}

Os métodos HTTP para serviços RESTful serão frequentemente utilizados para requisição das transações.

::: table-scroll
| VERBO HTTP | DESCRIÇÃO |
|----------- | ------------------------------------------------------------------------------------------------------------------------- |
| POST | Utilizado na criação dos recursos ou no envio de informações que serão processadas. Por exemplo, criação de uma transação. |
| GET | Utilizado para consultas de recursos já existentes. Por exemplo, consulta de transações. |
| PUT | Utilizado para atualização de um recurso já existente. Por exemplo, captura de uma transação previamente autorizada. |
{.table-bordered}
:::

As variações serão utilizadas conforme o serviço requisitado: autorização, captura, autorização com captura automática, consulta, cancelamento e consulta de cancelamento.

### Códigos de retorno {#documentacao-codigos-de-retorno .menu-nv2}

Os códigos de retorno HTTP são utilizados para indicar o sucesso ou fracasso de uma solicitação da API. Os códigos iniciados com 2xx indicam sucesso, os códigos iniciados com 4xx indicam um erro devido a alguma informação incorreta fornecida na requisição e os códigos iniciados com 5xx indicam erro nos servidores.

#### Códigos de sucesso

::: table-scroll
| RETORNO | DESCRIÇÃO | MÉTODO |
| ------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| 200 | Indica que o processamento foi realizado corretamente e o retorno será conforme a expectativa. | GET |
| 201 | Indica que o recurso foi criado com sucesso, deverá existir o header location indicando a url do novo recurso. | POST |
| 202 | Indica que o processamento será assíncrono, portanto, além do header location, deverá retornar o conteúdo com um atributo status. | POST E PUT |
| 204 | Indica que o recurso foi alterado ou excluído com sucesso. | PUT |
{.table-bordered}
:::

#### Códigos de erro

::: table-scroll
| RETORNO | DESCRIÇÃO |
|-------- | --------------------------------------------------------------------- |
| 400 | Requisição mal formatada. |
| 401 | Requisição requer autenticação. |
| 403 | Requisição negada. |
| 404 | Recurso não encontrado. |
| 405 | Método não permitido. |
| 408 | Tempo esgotado para requisição. |
| 413 | Requisição excede o tamanho máximo permitido. |
| 415 | Tipo de mídia inválida (verificar o header content-type da requisição)|
| 422 | Exceção de negócio. Verificar return code e return message. |
| 429 | Requisição excede a quantidade máxima de chamadas permitidas à API. |
{.table-bordered}
:::

**OBS:** Caso você receba o erro "HTTP 401: Requisição requer autenticação" ao realizar uma requisição utilizando o protocolo de autenticação oAuth 2.0, significa que o acess_token utilizado está expirado e um novo deve ser gerado.

#### Exceção lançada por erro de servidor(es)

::: table-scroll
| RETORNO | DESCRIÇÃO |
|-------- | ---------------- |
| 500 | Erro de servidor. |
{.table-bordered}
:::

>  **Observação**{.text-rede-orange}
>
> Caso ocorra o erro 500 durante uma transação 3DS ou DATA ONLY, recomenda-se a verificação do status da transação. Essa verificação deve ser realizada na API de Consulta de transação pelo código do pedido campo (Reference):
>
> **GET: [/v2/transactions?reference={codigo_reference}](e-rede#operations-Transação-consultarTransacaoPorReference)**
{.content-info-orange .with-icon}

### Formatação {#documentacao-formatacao .menu-nv2}

#### Encoding

Para utilizar as APIs da Rede será necessário configurar em sua aplicação o uso do encoding UTF-8.

#### JSON

JSON (JavaScript Object Notation) é um padrão para descrição de dados para intercâmbio entre sistemas. Ele é mais simples e mais leve que o XML. Por padrão, toda API trafega JSON, tanto para receber informações (métodos POST e PUT) quanto no retorno (método GET).

Devido esta padronização, para as chamadas POST e PUT é necessário informar no HTTP Header content-type: application/json. Do contrário, você receberá um erro HTTP 415: Unsupported Media Type.

#### Campos do tipo Datetime

Todos os atributos do tipo Datetime, tanto atributos que são retornados em objetos quanto os que são passados como parâmetros nas operações, seguem o padrão ISO-8601, representado abaixo:

Date: YYYY-MM-DDThh:mm:ss.sTZD
Exemplo: 2015-11-28T08:54:00.000-03:00

### Transações {#documentacao-transacoes .menu-nv2}

As transações são divididas de forma com que o lojista possa optar em realizar a captura de forma posterior ou automática.

Na **autorização com captura posterior**, o valor da transação sensibiliza o limite do cartão do portador, porém não gera cobrança na fatura enquanto não houver a confirmação (captura).

Já na **autorização com captura automática**, o valor da transação é confirmado de maneira instantânea, sem a necessidade de realizar a transação de captura.

### Captura {#documentacao-captura .menu-nv2}

Ao realizar uma autorização, é necessária a confirmação desta transação (captura). Nesse momento é gerada a cobrança na fatura do portador do cartão.

A autorização deverá ser capturada no período máximo de acordo com o ramo do estabelecimento.

**IMPORTANTE:** Sempre aguardar a resposta da transação antes de realizar nova tentativa de captura da mesma.

O diagrama abaixo mostra o fluxo da transação de captura:

![Fluxo de Transação de Captura](assets/images/e-rede/fluxo-captura-erede.png){#img-captura .content-image}

> PUT: **[/v2/transactions/{tid}](e-rede#operations-Transação-confirmarAutorizacaoDaTransacaoCaptura)** {.content-info}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|---------------- | ------- | -------- | ----------- | :----------------------------------- |
| amount | Até 10 | Numérico | Não | Valor da captura sem separador de milhar e decimal. |\
| | | | | |\
| | | | | Exemplos: |\
| | | | | - R$10,00 = 1000 |\
| | | | | - R$0,50 = 50 |\
{.table-bordered}
:::

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|------------------------- | ------- | ------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| tid | 20 | Alfanumérico | Número identificador único da transação. |
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| dateTime | | Datetime | Data da transação no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
{.table-bordered}
:::

### Delay Capture{#documentacao-delay-capture .menu-nv2}

**1. Como Funciona**

A funcionalidade de delay capture permitirá que a confirmação de transações pendentes possa ser feita em até 120 horas após a autorização do pagamento.

**1.1 Regras do Delay Capture**

- O produto delay capture Rede, só poderá ser usado na modalidade Crédito (kind = credit). 
- O estabelecimento deverá enviar no request da transação o tempo de expiração da mesma, esse tempo poderá ser de 24, 48, 72, 96 ou 120 horas; 
- Em caso de confirmação não realizada pelo estabelecimento até a data de expiração da transação, a Rede irá ESTORNAR o pagamento em sua totalidade; 
- O valor confirmado, deverá ser sempre igual ao valor autorizado; 
- Bandeiras disponíveis Mastercard e ELO; 
- O produto também está disponível para transações autenticadas com 3DS e Data Only, tanto MPI interno (Rede) quanto MPI externo.

**2. Autorização de Transação**

O corpo da requisição (body) deve estar em formato JSON contendo os campos descritos na tabela abaixo:

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|------|:--------|:-----|:-------------|:-----------|
|capture| | Booleano | Sim | Defina se a transação terá captura automática ou posterior. Para este caso deve ser enviado como “true”|
|kind| | Alfanumérico | Não | Tipo de transação a ser realizada.|\
| | | | | |\
| | | | |- Para transações de crédito, utilizar credit. O não envio desse campo será considerado crédito. |\
| | | | | |\
| | | | | O produto débito não está disponível nesta modalidade de captura. | 
| reference | Até 12 | Alfanumérico | Sim | Código do pedido gerado pelo estabelecimento. |
| amount | Até 10 | Numérico | Sim | Valor total da transação sem separador de milhar e decimal. Exemplos: |\
| | | | | - R$10,00 = 1000 |\
| | | | | - R$0,50 = 50 |
| cardholderName | Até 30 | Alfanumérico | Não | Nome do portador impresso no cartão. \ |\
| | | | | Não enviar caracteres especiais. |
| cardNumber | Até 19 | Alfanumérico | Sim | Número do cartão. |
| expirationMonth | Até 2 | Numérico | Sim | Mês de vencimento do cartão. De 1 a 12. |
| expirationYear | 2 ou 4 | Numérico | Sim | Ano de vencimento do cartão. \ |\
| | | | | Ex .: 2028 ou 28. |
| securityCode | Até 4 | Alfanumérico | Não | Código de segurança do cartão geralmente localizado no verso do cartão. \ |\
| | | | | O envio desse parâmetro garante maior possibilidade de aprovação da transação. |
|captureExpirationHours| Até 3 | Numérico | Sim | Tempo em horas para a expiração da transação. Valores aceitos: 24, 48, 72, 96, 120 |
{.table-bordered table}
:::

**2.1 Resposta da Autorização**

Caso a autorização ocorra com sucesso os seguintes campos serão retornados

::: table-scroll
| Nome | Tamanho | Tipo |  Descrição |
|------|:--------|:-----|:-------------|:-----------|
|reference|Até 12|Alfanumérico|Código do pedido gerado pelo estabelecimento.|
|tid|Até 20|Alfanumérico|Número identificador único da transação|
|nsu|Até 12|Alfanumérico|Número sequencial retornado pela Rede|
|authorizationCode|6|Alfanumérico|Número de autorização da transação retornado pelo emissor|
|brandTid|Até 16|Alfanumérico|Código identificador da transação na respectiva bandeira. Para mais detalhes consulte a seção Recorrência e [Card-on-file](e-rede#documentacao-recorrencia) \ |\
||| |\
| | | | Campo utilizado somente para as bandeiras Visa e Mastercard|
|dateTime|29|Alfanumérico|Data da transação de autorização no formato YYYY-MMDDThh:mm:ss.sTZD|
|captureExpirationHours|Até 3|Numérico|Tempo em horas para a expiração da transação. Valores aceitos: 24, 48, 72, 96, 120|
|captureExpirationDateTime| |Date time|Data de expiração da transação no formato YYYYMM-DDThh:mm:ss.sTZD Contém o dateTime da transação acrescido das horas enviadas no campo captureExpirationHours|
|amount|Até 10|Numérico|Valor total da transação sem separador de milhar e decimal. Exemplos:R$10,00 = 1000|
|cardBin|6|Alfanumérico|6 primeiros dígitos do cartão|
|last4|4|Alfanumérico|4 últimos dígitos do cartão|
|returnCode|Até 3|Alfanumérico|Código de retorno da transação|
|returnMessage|Até 256|Alfanumérico|Mensagem de retorno da transação|
{.table-bordered table}
:::

**3. Consulta de Transação**

**3.1 Consulta com sucesso e transação pendente**

Caso a consulta ocorra com sucesso e a transação esteja pendente os seguintes campos serão retornados

::: table-scroll
| Nome | Tamanho | Tipo |  Descrição |
|------|:--------|:-----|:-------------|:-----------|
|requestDateTime|29|Alfanumérico| Data de requisição no formato YYYY-MM-DDThh:mm:ss STZD|
|authorization| |Objeto|Grupo com informações sobre a autorização|
|dateTime|29|Alfanumérico|Data da transação de autorização no formato YYYY-MM-DDThh:mm:ss STZD|
|returnCode|Até 3|Alfanumérico|Código de retorno da transação|
|returnMessage|Até 256|Alfanumérico|Mensagem de retorno da transação|
|status| |Alfanumérico|Status da transação Approved / Denied / Canceled / Pending|
|reference|Até 12|Alfanumérico|Código do pedido gerado pelo estabelecimento.|
|tid|Até 20|Alfanumérico|Número identificador único da transação|
|brandTid|Até 16|Alfanumérico|Código identificador da transação na respectiva bandeira. Para mais detalhes consulte a seção Recorrência e [Card-on-file](e-rede#documentacao-recorrencia) \ |\
||| |\
| | | | Campo utilizado somente para as bandeiras Visa e Mastercard|
|nsu|Até 12|Alfanumérico|Número sequencial retornado pela Rede|
|authorizationCode|6|Alfanumérico|Número de autorização da transação retornado pelo emissor|
|kind|Até 10|Alfanumérico|Método de pagamento utilizado na transação original|
|amount|Até 10|Numérico|Valor total da transação sem separador de milhar e decimal. Exemplos:R$10,00 = 1000|
|cardBin|6|Alfanumérico|6 primeiros dígitos do cartão|
|last4|4|Alfanumérico|4 últimos dígitos do cartão|
|captureExpirationDateTime| |Date Time|Data de expiração da transação|
{.table-bordered table}
:::

**3.2 Consulta com sucesso e transação aprovada**

Caso a consulta ocorra com sucesso e a transação esteja capturada os seguintes campos serão retornados

::: table-scroll
| Nome | Tamanho | Tipo |  Descrição |
|------|:--------|:-----|:-------------|:-----------|
|requestDateTime|29|Alfanumérico| Data de requisição no formato YYYY-MM-DDThh:mm:ss STZD|
|authorization| |Objeto|Grupo com informações sobre a autorização|
|dateTime|29|Alfanumérico|Data da transação de autorização no formato YYYY-MM-DDThh:mm:ss STZD|
|returnCode|Até 3|Alfanumérico|Código de retorno da transação|
|returnMessage|Até 256|Alfanumérico|Mensagem de retorno da transação|
|status| |Alfanumérico|Status da transação Approved / Denied / Canceled / Pending|
|reference|Até 12|Alfanumérico|Código do pedido gerado pelo estabelecimento.|
|tid|Até 20|Alfanumérico|Número identificador único da transação|
|nsu|Até 12|Alfanumérico|Número sequencial retornado pela Rede|
|authorizationCode|6|Alfanumérico|Número de autorização da transação retornado pelo emissor|
|kind|Até 10|Alfanumérico|Método de pagamento utilizado na transação original|
|amount|Até 10|Numérico|Valor total da transação sem separador de milhar e decimal. Exemplos:R$10,00 = 1000|
|cardBin|6|Alfanumérico|6 primeiros dígitos do cartão|
|last4|4|Alfanumérico|4 últimos dígitos do cartão|
|capture| |Objeto|Grupo com informações da captura|
|brandTid|Até 16|Alfanumérico|Código identificador da transação na respectiva bandeira. Para mais detalhes consulte a seção Recorrência e [Card-on-file](e-rede#documentacao-recorrencia) \ |\
||| |\
| | | | Campo utilizado somente para as bandeiras Visa e Mastercard|
|captureExpirationDateTime| |Date Time|Data de expiração da transação|
{.table-bordered table}
:::

**4. Confirmação de autorização**

Confirma (captura) a transação previamente autorizada.
O corpo da requisição (body) deve estar em formato JSON contendo os campos descritos na tabela abaixo:

::: table-scroll
| Nome | Tamanho | Tipo |  Descrição |
|------|:--------|:-----|:-------------|:-----------|
| amount | Até 10 | Numérico |  Valor total da compra sem separador de milhar e casa decimal Ex: R$10,00 = 1000 / R$ 0,50 = 50  |\
| | | | |\
| | | | Para Delay Capture, o valor capturado deve ser igual ao valor autorizado. |\
| | | | |
{.table-bordered table}
:::

Caso a captura ocorra com sucesso os seguintes campos serão retornados:

::: table-scroll
| Nome | Tamanho | Tipo |  Descrição |
|------|:--------|:-----|:-------------|:-----------|
|reference|Até 12|Alfanumérico|Código do pedido gerado pelo estabelecimento.|
|tid|Até 20|Alfanumérico|Número identificador único da transação|
|nsu|Até 12|Alfanumérico|Número sequencial retornado pela Rede|
|dateTime|29|Alfanumérico|Data da transação de autorização no formato YYYY-MM-DDThh:mm:ss STZD|
|returnCode|Até 3|Alfanumérico|Código de retorno da transação|
|returnMessage|Até 256|Alfanumérico|Mensagem de retorno da transação|
{.table-bordered table}
:::

**5. Caso Especial**

**Zero Dollar**

Se:

amount = 0

Então:

- A transação será processada como Zero Dollar
- A captura será automática
- O fluxo de delay capture não se aplica

**OBS:** Importante lembrar que não é possível utilizar o 3DS em transações Zero Dollar. Portanto se o parâmetro amount for enviado como 0 no bloco de 3DS a autenticação retornará erro.

**6. Códigos de Retorno**

Os retornos de integração são exibidos sempre que houver algo de errado na sua requisição, permitindo assim a correção imediata.

::: table-scroll
| Nome | Descrição | Descrição |
|------|:--------|:-----|
| 173 | Authorization expired | A transação a ser capturada já está expirada |
| 3118 | CaptureExpirationHours: Invalid parameter format | Formato do parâmetro inválido |
| 3119 | Capture: Invalid parameter format | Formato do parâmetro inválido |
| 3120 | CaptureExpirationHours: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 3121 | Invalid amount | O valor enviado é diferente do valor autorizado |
| 3122 | CaptureExpirationHours: Invalid parameter | O valor enviado não é um dos valores permitidos para esse campo |
{.table-bordered table}
:::

### Companhias aéreas {#documentacao-companhias-aereas .menu-nv2}

Companhias aéreas possuem um tipo de transação diferenciada, que permite o envio do valor da taxa de embarque separado do valor da passagem aérea. A transação pode ser “à vista” ou “parcelada”.

As transações de companhias aéreas devem ser do tipo ++crédito++, com ++captura automática (capture = true)++ e devem ser enviadas juntamente com o **BODY** da transação.

**IMPORTANTE:** Cancelamentos de transações do tipo IATA só podem ser realizados à partir de D+1.

> Selecione o tipo "Companhias aéreas" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|------------------ | ------- | -------- | ----------- | :----------------------------------- |
| iata | | iata | | |
| iata/code | Até 9 | Numérico | Sim | Código iata da companhia aérea. |
| iata/departureTax | Até 10 | Numérico | Sim | Valor da taxa de embarque sem separador de milhar e decimal. |\
| | | | | |\
| | | | | Exemplos: |\
| | | | | - R$10,00 = 1000 |\
| | | | | - R$0,50 = 50 |\
{.table-bordered}
:::

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|------------------------- | ------- | ------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | 20 | Alfanumérico | Número identificador único da transação. |
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| dateTime | | Datetime | Data da transação no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| amount | Até 10 | Numérico | Valor total da transação sem separador de milhar e decimal. |
| cardBin | 6 | Alfanumérico | 6 primeiros dígitos do cartão. |
| last4 | 4 | Alfanumérico | 4 últimos dígitos do cartão. |
| brand | - | - | Grupo de informações recebidas da bandeira sobre a transação. |
| brand/name | - | Alfanumérico | Nome da bandeira. Ex: Mastercard. |
| brand/returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| brand/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand/merchantAdviceCode | Até 2 | Alfanumérico | Código de Aviso para Estabelecimento Comercial. É um conjunto de códigos usado para fornecer informações adicionais sobre uma resposta de transação de uso exclusivo da bandeira Mastercard. |
| brand/authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| brand/brandTid | Até 21 | Alfanumérico | Código identificador da transação na respectiva bandeira. Para mais detalhes consulte a seção [Recorrência e Card-on-file](e-rede#documentacao-recorrencia) |
{.table-bordered}
:::

### 3D Secure 2.0 {#documentacao-3d-secure2-0 .menu-nv2}

Transações autenticadas 3D Secure ou 3DS são transações que necessitam de uma autenticação adicional para garantir maior segurança para o portador do cartão nas compras online. A autenticação 3DS é efetuada através da validação de dados que apenas o portador do cartão e o banco possuem, como por exemplo, senha do cartão, data de nascimento, código de segurança, token do banco. **Em caso de sucesso da autenticação, o emissor assume o risco da transação.**

O 3D Secure 2.0 é um novo padrão de autenticação para fornecer segurança adicional às transações e é a primeira solução capaz de autenticar uma transação sem intervenção do cliente (autenticação sem desafio), pois o emissor terá acesso a mais informações da transação e não apenas os dados de valor e cartão. Nos casos que necessitam de autenticação (com desafio) o processo é intuitivo e pode ocorrer via biometria, reconhecimento de voz/facial ou envio de SMS, ajudando a evitar o abandono do carrinho. Quem decide se a transação deverá ser com desafio ou não, é o emissor.

Em termos de mercado, atualmente a Rede proporciona a utilização da versão 2.2 do protocolo 3DS. Estamos trabalhando para disponibilizar a versão 2.3 em breve. Resumidamente, o protocolo 3D Secure 2.0 acelera a autenticação, aumenta a segurança e aumenta as taxas de conversão proporcionando aos compradores uma rápida finalização da compra extremamente fluída, especialmente no celular, e trazendo proteção extra para o lojista. Veja a tabela de funcionalidades abaixo:

::: table-scroll
| Funcionalidades do 3DS 2.0 | Benefícios agregados |
| :------------------------- | :--------------------------- |
| Substitui senhas estáticas por 2 fatores fortes: RBA, OTP, Biometria ou Canal Alternativo (Out of Band). | - Maior segurança |\
| | - Maior conveniência |\
| | - Menor fricção |
| Suporte a diferentes canais de pagamento (in-app, IoT, navegador, etc). | - Melhor UX |\
| | - Maior abrangência |\
| | - Controle melhorado para os estabelecimentos |
| Suporte a compra e casos de uso adicionais (provisionamento de Card on File, Carteiras Digitais, Pagamentos Recorrentes, Tokenização, etc). | - Maior aplicabilidade |\
| | - Maior segurança |
{.table-bordered}
:::

**A autenticação 3DS é obrigatória para todas as transações efetuadas com cartões de débito.** Para os cartões de crédito, sua utilização é opcional.

O MPI (merchant plug-in) é o serviço que provê a integração do estabelecimento com diferentes emissores, alinhado às certificações das bandeiras para processamento da autenticação 3D Secure (3DS).

O e.Rede disponibiliza duas formas de utilização do serviço 3DS, através do MPI Rede ou MPI Cliente. A utilização do MPI estará a critério do estabelecimento.

- MPI Rede: serviço já embarcado na plataforma e.Rede, sem necessidade de contratação adicional. Nesse cenário, a Rede realiza o fluxo de autenticação e autorização da transação.
- MPI Cliente: serviço contratado **adicionalmente** pelo cliente para integração com o e.Rede, sem influência da Rede na autenticação da transação. Portanto, nesse cenário, a Rede realiza apenas o fluxo de autorização.

Para que as transações 3DS possam ser realizadas, os emissores também precisam estar preparados para receber as informações de autenticação do comprador. Os principais emissores do Brasil já disponibilizam esse serviço a seus clientes.

### 3DS 2.0 - MPI Rede {#documentacao-3d-secure2-0-3d-secure2-0-mpi-rede .menu-nv3}

O e.Rede já possui o MPI embarcado em sua plataforma. Portanto, utilize o parâmetro _embedded_ para sinalizar que o MPI contratado é o da Rede, vide tabela de “Parâmetros da requisição”.

As transações que utilizam o serviço 3DS com o MPI Rede podem ser do tipo ++crédito++ ou ++débito++ e devem ser enviadas juntamente com o **BODY** da transação de autorização.

O MPI Rede permite a autenticação do 3DS2.0 em transações das bandeiras Visa, Mastercard e Elo.

Para as ++transações de crédito++, caso a transação ++não++ tenha sido autenticada com sucesso, existe a possibilidade de prosseguir com a transação sem a devida autenticação 3DS, e o risco da transação passa a ser do lojista, voltando ao ciclo transacional “comum”.

Para transações de débito o valor deste parâmetro é automaticamente definido devido à obrigatoriedade da autenticação.

Para habilitar o serviço, acesse o portal “userede.com.br”, _menu vender online > e-commerce > 3DS/Data Only > Contratar_.

Em algumas horas, a Rede retornará informando o status da solicitação de habilitação do serviço.

Os diagramas abaixo mostram o fluxo da transação autenticada (1) e autorizada (2) utilizando o MPI Rede, quando há a solicitação do desafio por parte do emissor:

![Fluxograma 1 de autenticacao com desafio](assets/images/e-rede/fluxograma1-autenticacao-com-desafio.png){#img-fluxograma1 .content-image}

Fluxograma 1 de autenticação (com desafio)

![Fluxograma 2 de autorizacao com desafio](assets/images/e-rede/fluxograma2-autorizacao-com-desafio.png){#img-fluxograma2 .content-image}

Fluxograma 2 de autorização (com desafio)

Já o diagrama abaixo, ilustra o fluxo da transação autenticada e autorizada quando o emissor **não** solicita o desafio ao comprador:

![Fluxograma 3 de autenticacao + autorizacao sem desafio](assets/images/e-rede/fluxograma3-autenticacao-autorizacao-sem-desafio.png){#img-fluxograma3 .content-image}

Fluxograma 3 de autenticação + autorização (sem desafio)

**IMPORTANTE:** Para verificar o status da transação, utilize o endpoint de consulta. [Clique aqui](e-rede#documentacao-consulta-transacao) para obter mais informações.

> Selecione o tipo "3D Secure 2.0: MPI Rede" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|----------------------- | ------- | ------------ | ----------- | :----------------------------------- |
| threeDSecure | | threeDSecure | Sim | |
| threeDSecure /embedded | | Booleano | Não | Informa se o serviço MPI utilizado será da Rede ou terceiro. |\
| | | | | - **true:** utiliza o serviço MPI da Rede |\
| | | | | - **false:** utiliza serviço MPI terceiro |\
| | | | | |\
| | | | | O não envio desse campo será considerado o uso do MPI da Rede. |
| threeDSecure /onFailure | | Alfanumérico | Sim | Define como prosseguir com a transação nos fluxos de autenticação 3DS quando a autenticação não for concluída com sucesso. |\
| | | | | - **continue:** prossegue com a transação financeira mesmo sem sucesso na autenticação 3DS. |\
| | | | | - **decline:** não prossegue com a transação financeira sem sucesso na autenticação 3DS. |\
| | | | | |\
| | | | | Para transações de débito, o valor deste parâmetro é automaticamente definido como **decline**, devido à obrigatoriedade da autenticação via 3DS.|
| threeDSecure /userAgent | Até 255 | Alfanumérico | Sim |Identificador do browser utilizado pelo comprador no momento da compra.|
| threeDSecure /ipAddress | 11 | Alfanumérico | Sim | Suporta informações somente em iPv4. Exemplo: 10.0.0.1 |
| threeDSecure /device | | | | |
| threeDSecure /device/colorDepth | 2 | Numérico | Sim | Campo que representa a estimativa da paleta de cores usada para a exibição de imagens, em bits por pixel. Obtido no navegador do cliente através da propriedade. |
| threeDSecure /device/deviceType3ds | 20 | Alfanumérico | Sim | Campo que indica tipo de dispositivo.|
| threeDSecure /device/javaEnabled | | Booleano | Sim | Campo booleano que representa a capacidade do navegador para executar Java. O valor é aquele retornado pela propriedade navigator.javaEnabled, true ou false.|
| threeDSecure /device/language | 10 | Alfanumérico | Sim | Idioma do navegador no formato IETF BCP47, contendo entre 1 e 8 caracteres. |
| threeDSecure /device/screenHeight | 6 | Numérico | Sim- para browser e Mobile | A altura total da tela do cliente em pixels. O valor é aquele retornado pela propriedade screen.height. |
| threeDSecure /device/screenWidth | 6 | Numérico | Sim- para browser e Mobile | A largura total da tela do cliente em pixels. O valor é aquele retornado pela propriedade screen.width. |
| threeDSecure /device/timeZoneOffset | 10 | Alfanumérico | Sim | Diferença de horário, em horas, entre o UTC e a hora local do navegador do titular do cartão. |
| cardholderName | Até 30 | Alfanumérico | Sim | Nome do portador impresso no cartão. Não enviar caracteres especiais. |
| threeDSecure /billing | | billing | Sim | Dados referentes ao portador do cartão
| threeDSecure /billing /address | Até 128 | Alfanumérico | Sim | Endereço
| threeDSecure /billing /city | Até 64 | Alfanumérico | Sim | Cidade
| threeDSecure /billing /postalcode | 9 | Numérico | Sim | CEP
| threeDSecure /billing /state | Até 64 | Alfanumérico | Sim | Estado
| threeDSecure /billing /country | Até 64 | Alfanumérico | Sim | País
| threeDSecure /billing /emailAddress | Até 128 | Alfanumérico | Sim | E-mail
| threeDSecure /billing /phoneNumber | Até 32 | Numérico | Sim | Telefone
| urls | | urls | | |
| urls/kind | | Alfanumérico | Sim | Campo que identifica qual o tipo da url. |\
| | | | | - threeDSecureSuccess |\
| | | | | - threeDSecureFailure |\
| | | | | - threeDSecureCallback|
| urls/url | Até 87 | Alfanumérico | Sim | Campo para informar a url que o comprador deverá ser redirecionado após a autenticação e ser notificado via postback (application/x-www-form-urlencoded) ou callback com os dados da transação. |\
| | | | | |\
| | | | | Caso o urls/kind seja preenchido com o **threeDSecureSuccess** ou **threeDSecureFailure**, será recebido um postback conforme documentação [Clique aqui](https://developer.userede.com.br/e-rede#documentacao-3d-secure2-0-postback).|\
| | | | | |\
| | | | | Caso seja enviado o **threeDSecureCallback**, será recebido um callback conforme documentação [Clique aqui](https://developer.userede.com.br/e-rede#documentacao-3d-secure2-0-callback).|\
| | | | | |\
| | | | | Os processos podem ser usados de maneira conjunta como estratégia de redundância no reebimento das informações.
{.table-bordered}
:::

**Ponto de atenção:** É possível utilizar o 3DS MPI Interno somente com as seguintes mensagerias e produtos:

- [MCC dinâmico:](https://developer.userede.com.br/e-rede#documentacao-mcc-dinamico) Mensageria específica para os clientes que atuam com mais de um MCC
- [Carteira digital escalonada (SDWO)](https://developer.userede.com.br/e-rede#documentacao-carteiras-digitais-operadoras-carteiras-digital-escalonada-SDWO)
- [Tokenização de bandeira Rede](https://developer.userede.com.br/e-rede#documentacao-tokenizacao-bandeira-rede)
- [Tokenização de bandeira externa (captura)](https://developer.userede.com.br/e-rede#documentacao-tokenizacao-bandeira-externa)
- [Cofre de Cartões](https://developer.userede.com.br/e-rede#documentacao-cofre-cartoes)
- [Recorrência e Card-on-File](https://developer.userede.com.br/e-rede#documentacao-recorrencia) **Importante**: Ao combinar as duas mensagerias, a autenticação é realizada e válida apenas para a **primeira** transação da recorrência. As transações subsequentes não terão autenticação 3DS, nem o benefício do liability shift.

As mensagerias podem ser utilizadas em conjunto ou individualmente.

**Observação:**

1. Não é possível utilizar o 3DS em transações Zero Dollar.
2. Não é possível fazer simulações de Iframe com 3DS em sandbox.

>  **Erro 500 em transações 3DS**{.text-rede-orange}
>
> Caso ocorra o erro 500 durante uma transação 3DS, recomenda-se a verificação do status da transação. Essa verificação deve ser realizada na API de Consulta de transação pelo código do pedido campo (Reference):
>
> **GET: [/v2/transactions?reference={codigo_reference}](e-rede#operations-Transação-consultarTransacaoPorReference)**
{.content-info-orange .with-icon}


Para ver um exemplo de todas as mensagerias juntas na requisição:

> Selecione o tipo "3D Secure 2.0: MPI Rede + Token + MCC Dinâmico + SDWO" no combo box "Examples" da requisição.

> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|----------------------- | ------- | ------------ | ----------------------------------- |
| dateTime | | Datetime | Data de transação no formato YYYY-MM-DDThh:mm:ss.sTZD |
| threeDSecure | | threeDSecure | |
| threeDSecure /embedded | | Booleano | Informa se o serviço MPI utilizado será da Rede ou terceiro. |
| threeDSecure /url | Até 500 | Alfanumérico | Url de autenticação retornada pelo sistema MPI. |
| returnCode | 3 | Alfanumérico | Código de retorno da transação com 3ds (vide tabela [retornos 3DS](e-rede#documentacao-retornos-retornos-3ds)). |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação com 3ds (vide tabela [retornos 3DS](e-rede#documentacao-retornos-retornos-3ds)). |
| installments | Até 2 | Numérico | Número de parcelas em que uma transação será autorizada. De 2 a 12. (vide tabela de [Autorização](e-rede#primeiros-passos-autenticacao-e-autorizacao-fluxo-de-autorizacao)). |
{.table-bordered}
:::

### Postback {#documentacao-3d-secure2-0-postback .menu-nv3}

Notificação via application/x-www-form-urlencoded com os seguintes dados da transação:

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|------------------------ | ------- | ------------ | ----------------------------------- |
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | 20 | Alfanumérico | Número identificador único da transação.|
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| date | | Date | Data da transação no formato yyyyMMdd . |
| time | | Time | Hora da transação no formato HH:mm:ss . |
| returncode | Até 4 | Alfanumérico | Código de retorno da transação. |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| threeDSecure.returnCode | Até 4 | Alfanumérico | Código de retorno do 3DS (vide tabela [retornos 3DS](e-rede#documentacao-retornos-retornos-3ds)). |
| brand | | | Grupo de informações recebidas da bandeira sobre a transação. |
| brand/name | | Alfanumérico | Nome da bandeira. Ex: Mastercard. |
| brand/returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| brand/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
{.table-bordered}
:::

O postback será enviado apenas em cenários de autenticação bem-sucedidas. Em casos de falha na autenticação ou de não interação do cliente em um possível fluxo com desafio, nenhum postback será enviado.

>  **IMPORTANTE**{.text-rede-orange}
>
> No caso de um não recebimento de postback, ou de falha nesse fluxo, recomenda-se a verificação do status da transação. Essa verificação deve ser realizada na API de Consulta de transação pelo código do pedido campo (Reference):
>
> **GET: [/v2/transactions?reference={codigo_reference}](e-rede#operations-Transação-consultarTransacaoPorReference)**
>
> Lembrando que se a transação financeira (pós autenticação) não for realizada, a consulta apresentará o seguinte retorno: “returnCode”: “78”, “returnMessage”: “Transaction does not exist.”
{.content-info-orange .with-icon}

### Callback {#documentacao-3d-secure2-0-callback .menu-nv3}

O Callback é um retorno assíncrono da API, que será enviado no endpoint indicado para receber o método post.

Essa “indicação” é feita na própria requisição da transação, dentro do bloco “urls”, enviando o item preenchido com o: **"kind": "threeDSecureCallback"** e a “url” com o valor correspondente ao seu endpoint que irá receber o callback através de uma requisição HTTP com o método POST.

No callback será indicado o resultado da autenticação da transação.

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|------------------------ | ------- | ------------ | ----------------------------------- |
| reference | Até 16 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | 20 | Alfanumérico | Número identificador único da transação.|
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| expiresAt | | Data e hora | Dados de expiração da pré-autorização no formato YYYY-MM-DDThh:mm:ssTZD. |
| date | | Data | Data da transação no formato YYYY-MM-DD. |
| time | | Hora | Hora da transação no formato HH:mm:ss. |
| returncode | Até 4 | Alfanumérico | Código de retorno da transação. |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| threeDSecure.returnCode | Até 4 | Alfanumérico | Código de retorno do 3DS (vide tabela [retornos 3DS](e-rede#documentacao-retornos-retornos-3ds)). |
| threeDSecure.returnMessage | Até 256 | Alfanumérico | Mensagem de retorno do 3DS. |
| brand | | | Grupo de informações recebidas da bandeira sobre a transação. |
| brand/name | | Alfanumérico | Nome da bandeira. Ex: Mastercard. |
| brand/returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| brand/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
{.table-bordered}
:::

**IMPORTANTE:** O callback é utilizado para informar os status de autenticação da transação, para consultar e validar os status de autorização, é necessário confirmar o status da transação na API de [Autorização](https://developer.userede.com.br/e-rede#primeiros-passos-autenticacao-e-autorizacao-fluxo-de-autorizacao).

### 3DS 2.0 - MPI Cliente {#documentacao-3d-secure2-0-3d-secure2-0-mpi-cliente .menu-nv3}

O MPI Cliente é utilizado quando o estabelecimento já possui um MPI contratado. Portanto, utilize o parâmetro _embedded_ para sinalizar que o MPI já foi contratado de forma externa à Rede, vide tabela de “Parâmetros da requisição”.

Para que as transações com 3DS sejam autenticadas pelo emissor e posteriormente autorizadas via e.Rede, através do MPI Cliente, é necessário que o serviço de MPI seja certificado junto às bandeiras e à Rede. Atualmente, os serviços de MPI certificados são: Lyra, Cardinal e Datacash.

Nesse cenário de autenticação externa, a Rede pode receber transações de todas as bandeiras, entre as que já estão preparadas para o produto, e assim seguir com o fluxo de autorização.

As transações que utilizam o serviço 3DS com o MPI Cliente, podem ser do tipo ++crédito++ ou ++débito++ e devem ser enviadas juntamente com o **BODY** da transação de autorização.

O diagrama abaixo mostra o fluxo de autorização da transação autenticada utilizando o MPI Cliente:

![Fluxograma 4 de autorizacao com ou sem desafio](assets/images/e-rede/fluxograma4-autorizacao-com-sem-desafio.png){#img-fluxograma .content-image}
Fluxograma 4 de autorização (com ou sem desafio)

> Selecione o tipo "3D Secure 2.0: MPI Cliente" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|----------------------- | ------- | ------------ | ----------- | :----------------------------------- |
| threeDSecure | | threeDSecure | Sim | |
| threeDSecure /embedded | | Booleano | Não | Informa se o serviço MPI utilizado será da Rede ou terceiro. |\
| | | | | - **true:** utiliza o serviço MPI da Rede |\
| | | | | - **false:** utiliza serviço MPI terceiro |\
| | | | | |\
| | | | | O não envio desse campo será considerado o uso do MPI da Rede. |
| threeDSecure /[eci](e-rede#documentacao-tabela-ecis) | 2 | Alfanumérico | Sim | Código retornado ao MPI pelas Bandeiras que indica o resultado da autenticação do portador junto ao Emissor. Transações de débito devem ser obrigatoriamente autenticadas. |
| threeDSecure /cavv | Até 32 | Alfanumérico | Sim | Código do criptograma utilizado na autenticação da transação e enviado pelo MPI do estabelecimento (pode conter caracteres especiais). |
| threeDSecure /threeDIndicator | 1 | Alfanumérico | Sim | Versão do 3DS usado no processo de autenticação pelo MPI. |
| threeDSecure /xid | 28 | Alfanumérico | Não | ID da transação de autenticação enviado pelo MPI ao estabelecimento (pode conter caracteres especiais). Deve ser enviado apenas para a utilização do serviço de autenticação 3DS na versão 1.0. Campo utilizado somente para bandeira Visa.
| threeDSecure /directoryServerTransactionId | 36 | Alfanumérico | Sim | ID da transação de autenticação incluída pelo MPI ao estabelecimento (pode conter caracteres especiais). Deve ser enviado apenas para a utilização do serviço de autenticação 3DS 2.0.  Esse campo também pode ser chamado como dsTransId na Visa. |
{.table-bordered}
:::

**Ponto de atenção:** É possível utilizar o 3DS MPI Cliente somente com as seguintes mensagerias e produtos:

- [MCC dinâmico:](https://developer.userede.com.br/e-rede#documentacao-mcc-dinamico) Mensageria específica para os clientes que atuam com mais de um MCC
- [Carteira digital escalonada (SDWO)](https://developer.userede.com.br/e-rede#documentacao-carteiras-digitais-operadoras-carteiras-digital-escalonada-SDWO)
- [Tokenização de bandeira Rede](https://developer.userede.com.br/e-rede#documentacao-tokenizacao-bandeira-rede)
- [Tokenização de bandeira externa (captura)](https://developer.userede.com.br/e-rede#documentacao-tokenizacao-bandeira-externa)
- [Cofre de Cartões](https://developer.userede.com.br/e-rede#documentacao-cofre-cartoes)
- [Recorrência e Card-on-File](https://developer.userede.com.br/e-rede#documentacao-recorrencia)

As mensagerias podem ser utilizadas em conjunto ou individualmente.

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|------------------------- | ------- | ------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | 20 | Alfanumérico | Número identificador único da transação. |
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| dateTime | | Datetime | Data da transação no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| amount | Até 10 | Numérico | Valor total da transação sem separador de milhar e decimal. |\
| | | | |\
| | | | Exemplos: |\
| | | | - R$10,00 = 1000 |\
| | | | - R$0,50 = 50 |
| cardBin | 6 | Alfanumérico | 6 primeiros dígitos do cartão. |
| last4 | 4 | Alfanumérico | 4 últimos dígitos do cartão. |
| brand | - | - | Grupo de informações recebidas da bandeira sobre a transação. |
| brand/name | - | Alfanumérico | Nome da bandeira. Ex: Mastercard. |
| brand/returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| brand/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand/merchantAdviceCode | Até 2 | Alfanumérico | Código de Aviso para Estabelecimento Comercial. É um conjunto de códigos usado para fornecer informações adicionais sobre uma resposta de transação de uso exclusivo da bandeira Mastercard. |
| brand/authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| brand/brandTid | Até 21 | Alfanumérico | Código identificador da transação na respectiva bandeira. Para mais detalhes consulte a seção [Recorrência e Card-on-file](e-rede#documentacao-recorrencia) |
{.table-bordered}
:::

Ponto de atenção: Utilizando o 3DS2.0 MPI Cliente, sua autenticação será realizada fora do ambiente da Rede. Neste cenário, alguns clientes estão tendo autenticações negadas devido a falta ou invalidez do parâmetro [**"MCC dinâmico"**](e-rede#documentacao-mcc-dinamico){target="\_blank"}.

Portanto, garanta que este campo está sendo enviado ao provider que realizará a autenticação da transação, aumentando assim as taxas de sucesso e evitando erros inesperados neste fluxo.

### Data Only {#documentacao-data-only .menu-nv2}

Dataonly é uma modalidade de compartilhamento de dados transacionais. O objetivo do protocolo é diminuir o índice de fraude e aumentar taxas de aprovação em relação a uma transação comum, pois mais dados serão analisados para embasar a tomada de decisão do emissor.

O Dataonly intermediado pela Rede está disponível no momento, para as bandeiras Mastercard e Visa.

As transações DataOnly ocorrem sem interação do portador. Isso garante uma experiência de compra fluída para o usuário, mas em contraponto, não aplica o benefício do liability shift, ou seja, em caso de chargebacks, a responsabilidade de pagamento continua com o comércio, diferentemente da autenticação 3DS, que quando bem-sucedida, transfere essa responsabilidade ao emissor.

Para utilização do Produto, é necessário realizar a contratação no portal “userede.com.br”, para que seja realizada a ativação do Comércio no MPI. Portanto, habilite o serviço através do menu _vender online > e-commerce > 3DS/Data Only > Contratar_.

O MPI (merchant plug-in) é o serviço que provê a integração do estabelecimento com diferentes emissores, alinhado às certificações das bandeiras para processamento da autenticação.

O e.Rede disponibiliza duas formas de utilização do serviço, através do MPI Rede ou MPI Cliente. A utilização do MPI estará a critério do estabelecimento.

- MPI Rede: serviço já embarcado na plataforma e.Rede, sem necessidade de contratação adicional. Nesse cenário, a Rede realiza o fluxo de autenticação e autorização da transação.

- MPI Cliente: serviço contratado adicionalmente pelo cliente para integração com o e.Rede, sem influência da Rede na autenticação da transação. Portanto, nesse cenário, a Rede realiza apenas o fluxo de autorização.

Para que as transações 3DS possam ser realizadas, os emissores também precisam estar preparados para receber as informações de autenticação do comprador. Os principais emissores do Brasil já disponibilizam esse serviço a seus clientes.

**Tabela Comparativa:**

::: table-scroll
| | Experiência sempre sem desafio | Influência na decisão de aprovação do emissor | Sem latência na transação | Liability Shift |
| ------------ | ------------------------------ | --------------------------------------------- | ------------------------- | -------------- |
| **DataOnly** | ✓ | ✓ | ✓ | |
| **3DS** | Pode ser solicitado ou não | ✓ | | ✓ |
{.table-bordered}
:::

Para mais informações, consulte o infográfico da MasterCard [aqui](https://www.mastercard.com/content/dam/public/mastercardcom/globalrisk/pdf/Data-Only-Infographic.pdf){target="\_blank"}.

### Data Only - MPI Rede {#documentacao-data-only-data-only-mpi-rede .menu-nv3}

Para utilizar a modalidade Data Only com o MPI embarcado do e.Rede basta adicionar o parâmetro _challengePreference_ na requisição MPI Rede indicando o uso do Data Only, vide tabela de “Parâmetros da requisição”.

> Selecione o tipo "Data Only - MPI Rede" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|----------------------- | ------- | ------------ | ----------- | :----------------------------------- |
| threeDSecure | | threeDSecure | Sim | |
| threeDSecure /embedded | | Booleano | Não | Informa se o serviço MPI utilizado será da Rede ou terceiro. |\
| | | | | - **true:** utiliza o serviço MPI da Rede |\
| | | | | - **false:** utiliza serviço MPI terceiro |\
| | | | | |\
| | | | | O não envio desse campo será considerado o uso do MPI da Rede. |
| threeDSecure /onFailure | | Alfanumérico | Sim | Define como prosseguir com a transação caso a autenticação 3DS não obtenha sucesso. |\
| | | | | - **continue:** prossegue com a transação financeira mesmo se a autenticação falhar |\
| | | | | - **decline:** não prossegue com a transação financeira caso a autenticação falhar |\
| | | | | |\
| | | | | Para transações de débito, o valor deste parâmetro é automaticamente definido para decline devido à obrigatoriedade da autenticação. |
| threeDSecure /userAgent | Até 255 | Alfanumérico | Não | Identificador do browser utilizado pelo comprador no momento da compra. |
| threeDSecure /ipAddress | 11 | Alfanumérico | Sim | Suporta informações somente em iPv4. Exemplo: 10.0.0.1 |
| threeDSecure /device | | | | |
| threeDSecure /device/colorDepth | 2 | Numérico | Sim | Campo que representa a estimativa da paleta de cores usada para a exibição de imagens, em bits por pixel. Obtido no navegador do cliente através da propriedade. |
| threeDSecure /device/deviceType3ds | 20 | Alfanumérico | Sim | Campo que indica tipo de dispositivo. |
| threeDSecure /device/javaEnabled | | Booleano | Sim | Campo booleano que representa a capacidade do navegador para executar Java. O valor é aquele retornado pela propriedade navigator.javaEnabled, true ou false. |
| threeDSecure /device/language |10 | Alfanumérico| Sim | Idioma do navegador no formato [IETF BCP47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt), contendo entre 1 e 8 caracteres. |
| threeDSecure /device/screenHeight | 6 | Numérico | Sim- para Browser e Mobile | A altura total da tela do cliente em pixels. O valor é aquele retornado pela propriedade screen.height. |
| threeDSecure /device/screenWidth | 6 | Numérico | Sim- para Browser e Mobile | A largura total da tela do cliente em pixels. O valor é aquele retornado pela propriedade screen.width. |
| threeDSecure /device/timeZoneOffset | 10 | Alfanumérico | Sim | Diferença de horário, em horas, entre o UTC e a hora local do navegador do titular do cartão. |
| threeDSecure /billing | | billing | Sim | Dados referentes ao portador do cartão
| threeDSecure /billing /address | Até 128 | Alfanumérico | Sim | Endereço
| threeDSecure /billing /city | Até 64 | Alfanumérico | Sim | Cidade
| threeDSecure /billing /postalcode | 9 | Numérico | Sim | CEP
| threeDSecure /billing /state | Até 64 | Alfanumérico | Sim | Estado
| threeDSecure /billing /country | Até 64 | Alfanumérico | Sim | País
| threeDSecure /billing /emailAddress | Até 128 | Alfanumérico | Sim | E-mail
| threeDSecure /billing /phoneNumber | Até 32 | Numérico | Sim | Telefone
| urls | | urls | | |
| urls/kind | | Alfanumérico | Sim | Campo que identifica qual o tipo da url. |\
| | | | | - threeDSecureSuccess|\
| | | | | - threeDSecureFailure |
| urls/url | Até 87 | Alfanumérico | Sim | Campo para informar a url que o comprador deverá ser redirecionado após a autenticação e ser notificado via postback (application/x-www-form-urlencoded) com os dados da transação. Clique aqui para mais informações.|
| threeDSecure /challengePreference | | Alfanumérico | Não | Campo que indica a preferência de uso do Data Only. |\
| | | | | - DATA_ONLY|
{.table-bordered}
:::

**Ponto de atenção:** É possível utilizar o Data Only - MPI Rede somente com as seguintes mensagerias e produtos:

- [MCC dinâmico:](https://developer.userede.com.br/e-rede#documentacao-mcc-dinamico) Mensageria específica para os clientes que atuam com mais de um MCC
- [Carteira digital escalonada (SDWO)](https://developer.userede.com.br/e-rede#documentacao-carteiras-digitais-operadoras-carteiras-digital-escalonada-SDWO)
- [Tokenização de bandeira Rede](https://developer.userede.com.br/e-rede#documentacao-tokenizacao-bandeira-rede)
- [Tokenização de bandeira externa (captura)](https://developer.userede.com.br/e-rede#documentacao-tokenizacao-bandeira-externa)
- [Cofre de Cartões](https://developer.userede.com.br/e-rede#documentacao-cofre-cartoes)
- [Recorrência e Card-on-File](https://developer.userede.com.br/e-rede#documentacao-recorrencia) **Importante**: Ao combinar as duas mensagerias (recorrência e Data Only), a autenticação 3DS é realizada apenas na primeira transação da recorrência. As transações subsequentes não utilizarão o fluxo Data Only.

As mensagerias podem ser utilizadas em conjunto ou individualmente.

**Observação:** Não é possível utilizar o Data Only em transações Zero Dollar.

Para ver um exemplo de todas as mensagerias juntas na requisição:

> Selecione o tipo "Data Only: MPI Rede + Token + MCC Dinâmico + SDWO" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}


>  **Erro 500 em transações Data_ONLY**{.text-rede-orange}
>
> Caso ocorra o erro 500 durante uma transação DATA ONLY, recomenda-se a verificação do status da transação. Essa verificação deve ser realizada na API de Consulta de transação pelo código do pedido campo (Reference):
>
> **> GET: [/v2/transactions?reference={codigo_reference}](e-rede#operations-Transação-consultarTransacaoPorReference)**
{.content-info-orange .with-icon}


**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|------------------ | ------- | ------------ | :----------------------------------- |
| returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | 20 | Alfanumérico | Número identificador único da transação. |
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| dateTime | | Datetime | Data da transação no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| amount | Até 10 | Numérico | Valor total da transação sem separador de milhar e decimal. |\
| | | | |\
| | | | Exemplos: |\
| | | | - R$10,00 = 1000 |\
| | | | - R$0,50 = 50 |
| installments | Até 2 | Numérico | Número de parcelas em que uma transação será autorizada. De 2 a 12. (vide tabela de [Autorização](e-rede#primeiros-passos-autenticacao-e-autorizacao-fluxo-de-autorizacao)). |
| cardBin | 6 | Alfanumérico | 6 primeiros dígitos do cartão. |
| last4 | 4 | Alfanumérico | 4 últimos dígitos do cartão. |
{.table-bordered}
:::

### Data Only - MPI Cliente {#documentacao-data-only-data-only-mpi-cliente .menu-nv3}

Para utilizar a modalidade Data Only com um MPI externo, a requisição será a mesma do 3DS 2.0, com alterações de valores em alguns campos. Vide tabela de “Parâmetros da requisição”.

> Selecione o tipo "Data Only – MPI Cliente" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|----------------------- | ------- | ------------ | ----------- | :----------------------------------- |
| threeDSecure | | threeDSecure | Sim | |
| threeDSecure /embedded | | Booleano | Não | Informa se o serviço MPI utilizado será da Rede ou terceiro. |\
| | | | | - **true:** utiliza o serviço MPI da Rede |\
| | | | | - **false:** utiliza serviço MPI terceiro |\
| | | | | |\
| | | | | O não envio desse campo será considerado o uso do MPI da Rede. |
| threeDSecure /[eci](e-rede#documentacao-tabela-ecis) | 2 | Alfanumérico | Sim | Código retornado ao MPI pelas Bandeiras que indica o resultado da autenticação do portador junto ao Emissor. Transações de débito devem ser obrigatoriamente autenticadas. |
| threeDSecure /cavv | Até 32 | Alfanumérico | Sim | Código do criptograma utilizado na autenticação da transação e enviado pelo MPI do estabelecimento (pode conter caracteres especiais). |
| threeDSecure /threeDIndicator | 1 | Alfanumérico | Sim | Versão do 3DS usado no processo de autenticação pelo MPI. |
| threeDSecure /xid | 28 | Alfanumérico | Não | ID da transação de autenticação enviado pelo MPI ao estabelecimento (pode conter caracteres especiais). Deve ser enviado apenas para a utilização do serviço de autenticação 3DS na versão 1.0. Campo utilizado somente para bandeira Visa.
| threeDSecure /directoryServerTransactionId | 36 | Alfanumérico | Sim | ID da transação de autenticação incluída pelo MPI ao estabelecimento (pode conter caracteres especiais). Deve ser enviado apenas para a utilização do serviço de autenticação 3DS 2.0.  Esse campo também pode ser chamado como dsTransId na Visa. |
{.table-bordered}
:::

**Ponto de atenção:** É possível utilizar o Data Only - MPI Cliente somente com as seguintes mensagerias e produtos:

- [MCC dinâmico:](https://developer.userede.com.br/e-rede#documentacao-mcc-dinamico) Mensageria específica para os clientes que atuam com mais de um MCC
- [Carteira digital escalonada (SDWO)](https://developer.userede.com.br/e-rede#documentacao-carteiras-digitais-operadoras-carteiras-digital-escalonada-SDWO)
- [Tokenização de bandeira Rede](https://developer.userede.com.br/e-rede#documentacao-tokenizacao-bandeira-rede)
- [Tokenização de bandeira externa (captura)](https://developer.userede.com.br/e-rede#documentacao-tokenizacao-bandeira-externa)
- [Cofre de Cartões](https://developer.userede.com.br/e-rede#documentacao-cofre-cartoes)
- [Recorrência e Card-on-File](https://developer.userede.com.br/e-rede#documentacao-recorrencia) **Importante**: Ao combinar as duas mensagerias (recorrência e Data Only), a autenticação 3DS é realizada apenas na primeira transação da recorrência. As transações subsequentes não utilizarão o fluxo Data Only.

As mensagerias podem ser utilizadas em conjunto ou individualmente.

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|------------------ | ------- | ------------ | :----------------------------------- |
| returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | 20 | Alfanumérico | Número identificador único da transação. |
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| dateTime | | Datetime | Data da transação no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| amount | Até 10 | Numérico | Valor total da transação sem separador de milhar e decimal. |\
| | | | |\
| | | | Exemplos: |\
| | | | - R$10,00 = 1000 |\
| | | | - R$0,50 = 50 |
| cardBin | 6 | Alfanumérico | 6 primeiros dígitos do cartão. |
| last4 | 4 | Alfanumérico | 4 últimos dígitos do cartão. |
{.table-bordered}
:::

### Tabela de ECIs {#documentacao-tabela-ecis .menu-nv2}

O parâmetro ECI (Eletronic Commerce Indicator) se baseia no valor retornado ao MPI pelas Bandeiras que indica o resultado da autenticação do portador junto ao Emissor.

Este, portanto, indica a situação do fluxo de autenticação em uma transação, e se o Risco de chargeback é transferido para o emissor ou permanece com o lojista. Confira abaixo os valores utilizados pelas bandeiras:

::: table-scroll
| Bandeira | ECI | Significado da Transação | Risco Chargeback |
| ---------- | --- | ---------------------------- | ---------------- |
| ELO | 0 | Desconhecido/ Não Especificado/ Loja não participa do programa | Risco de chargeback permanece com o estabelecimento |
| ELO | 4 | Transação com autenticação In App | Usada em transações Wallets. Risco de chargeback passa a ser do emissor |
| ELO | 5 | Portador Autenticado pelo Emissor | Risco de chargeback passa a ser do emissor |
| ELO | 6 | Tentativa de Autenticação do Portador pelo Domínio do Credenciador **(autenticada pela bandeira)** | Risco de chargeback passa a ser do emissor |
| ELO | 7 | Transação de eCommerce Não Autenticada | Risco de chargeback permanece com o estabelecimento |
| MASTERCARD | 0 | Tentativa de autenticação incompleta ou falhou | Risco de chargeback permanece com o estabelecimento |
| MASTERCARD | 1 | Autenticação pelo Stand-In da Mastercard | Risco de chargeback passa a ser do emissor |
| MASTERCARD | 2 | Autenticação bem-sucedida | Risco de chargeback passa a ser do emissor |
| MASTERCARD | 4 | Data Only realizado com sucesso | Risco de chargeback permanece com o estabelecimento |
| MASTERCARD | 7 | Recorrência | Risco de chargeback permanece com o estabelecimento |
| VISA | 5 | Autenticação do Cartão bem-sucedida | Risco de chargeback passa a ser do emissor |
| VISA | 6 | A autenticação foi tentada, mas não foi ou não pôde ser concluída; possíveis razões, sendo que o cartão ou seu Banco Emissor ainda não participa. **(autenticada pela bandeira)** | Risco de chargeback passa a ser do emissor |
| VISA | 7 | A autenticação não foi bem-sucedida ou não foi tentada. | Risco de chargeback permanece com o estabelecimento |
| VISA | 7 | Data Only realizado com sucesso | Risco de chargeback permanece com o estabelecimento |
{.table-bordered}
:::

*Para consultar o **ECI final da transação**, utilize o campo **authorizationEci (ECI de autorização)**, disponível na API de consulta: **GET /v2/transactions/{tid} ou {reference}**

O campo **threeDSecure/eci** refere-se **exclusivamente ao ECI gerado na etapa de autenticação**. Esse campo **não deve ser utilizado para análise de liability shift**, pois não representa o ECI efetivamente considerado na autorização da transação. 

Além disso, a API de Consulta expõe o campo **authorization/downgradeEci**, que indica se houve downgrade entre as etapas de autenticação e autorização. 
O downgrade ocorre quando, no momento da autorização, o ECI retornado é inferior ao obtido na autenticação. 

### Zero Dollar {#documentacao-zero-dollar .menu-nv2}

A transação Zero Dollar, permite uma validação prévia para saber se o cartão do portador e dados enviados antes do processamento da transação são válidos. Esse tipo de transação não gera nenhum tipo de cobrança para o comprador, evitando débitos indevidos em seu saldo.

**O serviço está disponível para as bandeiras Visa, MasterCard, Elo e AMEX no crédito. No débito está disponível para as bandeiras Visa, Mastercard e Elo.** O Zero Dollar é obrigatório quando pretende-se armazenar o cartão, já para outras operações é altamente recomendado a fim de validar o cartão antes de iniciar o fluxo transacional padrão.

**Importante:**

* O parâmetro securityCode será obrigatório para validações Zero Dollar em todas as bandeiras. 
* As transações Zero Dollar deverão ser enviadas como autorização com captura automática **(capture = true), informando o valor 0 no parâmetro amount**. 
* Em caso de transações Zero Dollar com token de bandeira Visa, o envio do parâmetro tokenCryptogram é obrigatório. 
* Esse tipo de transação não pode ser cancelada.
* Esse tipo de transação não deve ser enviada como recorrente (subscription = true). Realize primeiro a validação Zero Dollar seguindo os parâmetros especificados a seguir e depois será possível utilizar o cartão para transações recorrentes ou não.

**Contratação do Produto Zero Dollar.**

A contratação do produto Zero Dollar deve ser realizada através da Central E-commerce. Para isso, entre em contato com a nossa Central de Atendimento, peça para falar com a central E-commerce e informe que deseja habilitar o "Zero Dollar" em seu ponto de venda e-commerce. 

_**Central de Atendimento:**_

_4001-4433 (capitais e regiões metropolitanas)_  
_0800-728-4433 (demais localidades)_  
_Horário de Atendimento: Segunda à sexta, das 08h às 20h._

**Custo Zero Dollar**  

A habilitação do serviço Zero Dollar não possui nenhum custo adicional na Rede.
Mas, a utilização das verificações Zero Dollar tem um custo para validação de cartões Mastercard e Visa. Para mais detalhes sobre a precificação, acesse **[Tarifas de Bandeiras](e-rede#tarifas-bandeira)**: Não uso de Zero Dollar e Uso de Zero Dollar.

> Selecione o tipo "Zero Dollar" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|----------------------- | ------- | ------------ | ----------- | :----------------------------------- |
| capture | | Booleano | Não | Define se a transação terá captura automática ou posterior. O não envio desse campo será considerado a captura automática **(true)**. |\
||||||\
||||| Para transações de débito e Zero Dollar, em caso de envio, o valor do parâmetro deve ser definido como **true**, indicando captura automática.|
| kind | | credit / debit | Não | Tipo de transação a ser realizada. |\
||||| - Para transações de crédito, utilizar **credit** |\
||||| - Para transações de débito, utilizar **debit** |\
||||||\
||||| O não envio desse campo será considerado crédito. |
| reference | Até 50 | Alfanumérico | Sim | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Não| Código do pedido gerado pelo estabelecimento. (Não aceita caracteres especiais) |
| amount | Até 10 | Numérico | Sim | Para transação Zero Dollar enviar o valor 0. |
| cardHolderName | Até 30 | Alfanumérico | Não | Nome do portador do cartão. |\
||||||\
||||| Não enviar caracteres especiais. |
| cardNumber | Até 19 | Alfanumérico | Sim | Número do cartão. |
| expirationMonth | Até 2 | Numérico | Sim | Mês de vencimento do cartão. De 1 a 12. |
| expirationYear | 2 ou 4 | Numérico | Sim | Ano de vencimento do cartão. |\
||||||\
||||| Exemplo: 2028 ou 28. |
| securityCode\* | Até 4 | Alfanumérico | Sim | Código de segurança do cartão geralmente localizado no verso do cartão. O envio desse parâmetro garante maior possibilidade de aprovação da transação. |
{.table-bordered}
:::

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|----------------------------- | ------- | ------------ | :-----------------------------------------------------------------------------------|
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | 20 | Alfanumérico | Número identificador único da transação. |
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| dateTime | | Datetime | Data da transação no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| amount | Até 10 | Numérico | Para transação Zero Dollar o retorno será 0 |
| cardBin | 6 | Alfanumérico | 6 primeiros dígitos do cartão. |
| last4 | 4 | Alfanumérico | 4 últimos dígitos do cartão. |
| returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand | - | - | Grupo de informações recebidas da bandeira sobre a transação. |
| brand/name | - | Alfanumérico | Nome da bandeira. Ex: Mastercard. |
| brand/returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| brand/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand/merchantAdviceCode | Até 2 | Alfanumérico | Código de Aviso para Estabelecimento Comercial. É um conjunto de códigos usado para fornecer informações adicionais sobre uma resposta de transação de uso exclusivo da bandeira Mastercard. |
| brand/authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| brand/brandTid | Até 21 | Alfanumérico | Código identificador da transação na respectiva bandeira. Para mais detalhes consulte a seção [Recorrência e Card-on-file](e-rede#documentacao-recorrencia) |
{.table-bordered}
:::

### Cancelamento {#documentacao-cancelamento .menu-nv2}

O cancelamento pode ser solicitado para todas as transações, conforme instruções abaixo:

- **Autorização:** A operação de cancelamento da autorização (sem captura automática) é permitida apenas para o cancelamento total da transação e deverá ser solicitada dentro do período estipulado para cada ramo após esse prazo, a autorização é cancelada automaticamente.


- **Captura e autorização com captura automática:** A operação de cancelamento da captura e da autorização com captura automática pode ser efetuada de forma parcial ou total, através dos canais disponíveis.


No cancelamento total, a transação terá o status “Canceled”, enquanto no cancelamento parcial, o status será mantido como “Approved”, até que a transação seja cancelada integralmente.

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.


Uma requisição de solicitação de cancelamento D+1 que retornou o código 360, não indica que o cancelamento será efetivado com sucesso. O estabelecimento precisa consultar posteriormente para verificar se o cancelamento foi efetivado ou negado.

Caso um cancelamento D+1 esteja no status "Processando", não deve ser enviado um outro pedido de cancelamento parcial, pois isso pode gerar dois cancelamentos distintos.

### Cancelamento Parcial D0 {#documentacao-cancelamento-parcial .menu-nv3}

O Estorno Parcial D0 é oferecido na Rede apenas para as Bandeiras Master e Elo, permitindo a devolução parcial imediata ao pagador.

Para as demais Bandeiras (Visa, Amex etc.), a solicitação de Estorno Parcial será acatada, porém seguirá o fluxo de cancelamento, tendo a devolução dos valores ao pagador em D+1.

O fluxo de Estorno Parcial considera os recortes de liquidação de cada Bandeira:

- **Master:** Processamento do estorno parcial para transação feita no mesmo dia a qualquer momento.

- **Elo:** Considera 4 horários de cortes de liquidação durante o dia (9h, 15h, 21h e 00h), de modo que:
  - Caso a solicitação de estorno parcial seja feita no mesmo período de recorte da autorização confirmada, o pedido de estorno parcial será realizado com sucesso.
  - Caso a solicitação de estorno seja feita em um recorte diferente da autorização confirmada, a solicitação seguirá o fluxo de cancelamento parcial D+1.

O Estorno Parcial funciona para as modalidades de Débito e Crédito e não tem restrição de número de parcelas.

Não é possível realizar estorno parcial em pré autorização pendente. Para tal, o estabelecimento precisa solicitar o cancelamento total ou capturar um valor menor.


Lembramos que para as transações Maestro (débito), é possível realizar **apenas um** cancelamento parcial. Trata-se de uma regra da bandeira Mastercard, que pode enviar a confirmação/ processamento deste cancelamento em até 5 dias úteis


Confira mais detalhes em[ Retornos de Cancelamento](e-rede#documentacao-retornos-retornos-cancelamento).

Para testar os cenários consulte Tutorial Sandbox > [Simular erros](e-rede#tutorial-sandbox-simular-erros).

> POST: **[/v2/transactions/{tid}/refunds](e-rede#operations-Cancelamento-cancelarTransacao)** {.content-info}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|----------------------- | ------- | ------------ | ----------- | :----------------------------------- |
| amount | Até 10 | Numérico | Sim | Valor do cancelamento sem separador de milhar e casa decimal. |\
| | | | | |\
| | | | | Exemplos: |\
| | | | | - R$ 10,00 = 1000 |\
| | | | |- R$ 0,50 = 50 |
| referenceRefund | Até 50 | Alfanumérico | Não | Código do cancelamento gerado pelo estabelecimento. ||
| urls | | urls | Não | |
| Urls/kind | | Alfanumérico | Não | Campo que identifica qual o tipo da url: callback. |
| urls/url | Até 500 | Alfanumérico | Não | Url que receberá o callback com o status do cancelamento após processado pela Rede. Também é possível cadastrar as url no portal userede. [Clique aqui](e-rede#documentacao-url-notificacoes) para mais informações |
| refundReasonCode | 2 | Alfanumérico | Não | Código do motivo de estorno quando o cancelamento ocorrer após análise antifraude do estabelecimento comercial.|\
| | | | | |\
| | | | |Deve ser 60 |
{.table-bordered}
:::

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|------------------ | ------- | ------------ | :----------------------------------- |
| returnCode | Até 4 | Alfanumérico | Código de retorno da transação (vide tabela [retornos de cancelamento](e-rede#documentacao-retornos-retornos-cancelamento)). |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação (vide tabela [retornos de cancelamento](e-rede#documentacao-retornos-retornos-cancelamento)). |
| refundId | 36 | Alfanumérico | Código de retorno da solicitação de cancelamento gerado pela Rede. |\
| | | | Caso a transação seja cancelada por outro canal que não seja a API, este campo retornará vazio. |
| referenceRefund | Até 50 | Alfanumérico | Código do cancelamento gerado pelo estabelecimento. |
| tid | 20 | Alfanumérico | Número identificador único da transação. |
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| refundDateTime | | Datetime | Data do cancelamento no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| cancelId | Até 15 | Alfanumérico | Código identificador da transação de solicitação cancelamento, retornado somente em solicitações D+1. |
{.table-bordered}
:::

### URL de notificações {#documentacao-url-notificacoes .menu-nv2}

A URL de notificações (callback) permite que os dados de uma transação sejam retornados via POST após o processamento dos cancelamentos realizados em D+1. A URL pode ser informada na própria API ou acessando o portal da Rede em menu para *vender > e-commerce > notificação automátic*a. Ressaltamos que caso a URL seja informada nos 2 canais, a prioridade do envio das notificações será sempre na que foi informada na API.

**IMPORTANTE:** Alinhado as práticas de mercado para garantir maior segurança, atualize seu certificado público compatível com TLS 1.2. A partir de **29 de junho de 2018**, as versões anteriores, como 1.1 e 1.0, deixarão de funcionar.

Após informar a URL que receberá a notificação, as informações serão retornadas no seguinte formato:

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|------------------ | ------- | ------------ | :----------------------------------- |
| type | | Alfanumérico | Tipo de evento utilizado para transação: **refund.** |
| tid | 20 | Alfanumérico | Número identificador único da transação. |
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| date | | Datetime | Data do cancelamento no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| amount | Até 10 | Alfanumérico | Valor do cancelamento. |
| status | Até 10 | Alfanumérico | - **Done** (Cancelamento efetivado) |\
| | | | - **Denied** (Cancelamento negado) |\
| | | | - **Processing** (Cancelamento em processamento) |
| cancellationNotice | Até 15 | Alfanumérico | Código identificador da transação de solicitação cancelamento (**cancelId**). |
| refundId | 36 | Alfanumérico | Código de retorno da solicitação de cancelamento gerado pela Rede. |\
| | | | |\
| | | | Caso a transação seja cancelada por outro canal que não seja a API, este campo retornará vazio. |
{.table-bordered}
:::

### Consulta de transação {#documentacao-consulta-transacao .menu-nv2}

A consulta da transação pode ser realizada de duas maneiras. A primeira é informando o tid gerado na transação de autorização. Já a segunda, é informando o número do pedido criado pelo estabelecimento (reference).

**Obs:** O prazo para consulta de pré autorizações pendentes e transações de zero dollar é de 60 dias. Após esse prazo o status da consulta retornará como: not found.

#### Consulta por tid

> GET: **[ /v2/transactions/{tid}](e-rede#operations-Transação-consultarTransacaoPorTid)** {.content-info}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|------ | ------- | ------------ | ----------- | ----------------------- |
| tid | 20 | Alfanumérico | Sim | Número identificador único da transação. |
{.table-bordered}
:::

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|---------------------------------------------------- | ------- | ------------- | :----------------------------------- |
| requestDateTime | | Datetime | Data da requisição no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| authorization | | authorization | |
| authorization/dateTime | | Datetime | Data da transação de autorização no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| authorization/returnCode | Até 3 | Alfanumérico | Código de retorno da transação. |
| authorization/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| authorization/affiliation | Até 9 | Numérico | Número de filiação do estabelecimento (PV).|
| authorization/status | | Alfanumérico | Status da transação: |\
| | | | - Approved |\
| | | | - Denied |\
| | | | - Canceled |\
| | | | - Pending |
| authorization/reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento.|
| authorization/orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento.|
| authorization/tid | 20 | Alfanumérico | Número identificador único da transação. |
| authorization/nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorization/authorizationCode | 6 | Alfanumérico | Número de Autorização da transação retornada pelo emissor do cartão. |
| authorization/kind | Até 10 | Alfanumérico | Método de pagamento utilizado na transação original (Credit ou Debit). |
| authorization/amount | Até 10 | Numérico | Valor total da compra sem separador de milhar. |\
| | | ||\
| | | | Exemplos:|\
| | | | - 1000 = R$10,00 |\
|                                                     |         |               | - R$ 0,50 = 50 |
| authorization/installments | Até 2 | Numérico | Número de parcelas. |
| authorization/cardHolderName | Até 30 | Alfanumérico | Nome do portador impresso no cartão. |
| authorization/cardBin | 6 | Alfanumérico | 6 primeiros dígitos do cartão. |
| authorization/last4 | 4 | Alfanumérico | 4 últimos digitos do cartão. |
| authorization/softDescriptor | Até 18\* | Alfanumérico | Mensagem que será exibida ao lado no nome do estabelecimento na fatura do portador. |
| authorization/origin | Até 2 | Numérico | Identifica a origem da transação.|\
| | | | - e.Rede - 1|
| authorization/subscription | | Booleano | Informa ao emissor se a transação é proveniente de uma recorrência. Se transação for uma recorrência, enviar **true.** Caso contrário, enviar **false.** |\
| | | ||\
| | | | O não envio desse campo será considerado o valor false. |\
| | | | |\
| | | | A Rede não gerencia os agendamentos de recorrência, apenas permite aos lojistas indicarem se a transação se originou de uma recorrência. |
| authorization/distributorAffiliation | Até 9 | Numérico | Número de filiação do distribuidor (PV). |
| authorization/authorizationEci | Até 2 | Alfanumérico | ECI final da transação, retornado pelo emissor ou bandeira no momento da autorização. Representa o nível de segurança atribuído à transação após o processo de autorização. |
| authorization/downgradeEci |  | Booleano | Indicador de downgrade em transações 3DS e Data Only. Compara o ECI da autenticação com o ECI da autorização e indica se houve perda do nível de autenticação. |\
| | | ||\
| | | |Valores possíveis: **true** (houve downgrade)  **false** (não houve downgrade).|\
| | | ||\
| | | |Disponível para Mastercard, Visa e Elo. |
| capture | | capture | |
| capture/dateTime | | Datetime | Data da transação de captura no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| capture/nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede na transação de captura. |
| capture/amount | Até 10 | Numérico | Valor da captura. |
| threeDSecure | | threeDSecure | |
| threeDSecure/embedded | | Booleano | Informa se o serviço MPI utilizado será da Rede ou terceiro. |
| threeDSecure/[eci](e-rede#documentacao-tabela-ecis) | 2 | Alfanumérico | Código retornado ao MPI pelas Bandeiras que indica o resultado da autenticação do portador junto ao Emissor. Deve ser enviado apenas para a utilização do serviço de autenticação 3DS.Transações de débito devem ser obrigatoriamente autenticadas. |
| threeDSecure/cavv | Até 32 | Alfanumérico | Código do criptograma utilizado na autenticação da transação e enviado pelo MPI do estabelecimento (pode conter caracteres especiais). Deve ser enviado apenas para a utilização do serviço de autenticação 3DS/Data Only. O valor informado no campo threeDSecure/cavv deve ser único por autenticação/transação e não pode ser reutilizado em outra transação. |
| threeDSecure/xid | 28 | Alfanumérico | ID da transação de autenticação enviado pelo MPI ao estabelecimento (pode conter caracteres especiais). Deve ser enviado apenas para a utilização do serviço de autenticação 3DS. Campo utilizado somente para bandeira Visa. |
| threeDSecure/returnCode | 3 | Alfanumérico | Código de retorno da transação com 3ds. |
| threeDSecure/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação com 3ds. |
| refunds | | refunds | |
| refunds/dateTime | | Datetime | Data da transação de cancelamento no formato YYYY-MM-DDThh:mm:ss.sTZD .|
| refunds/refundId | 36 | Alfanumérico | Código de retorno da solicitação de cancelamento gerado pela Rede. |
| refunds/referenceRefund | Até 50 | Alfanumérico | Código do cancelamento gerado pelo estabelecimento. |
| refunds/status | Até 10 | Alfanumérico | Status da solicitação de cancelamento. |\
| | | | - Done (Cancelamento efetivado) |\
| | | | - Denied (Cancelamento negado) |\
| | | | - Processing (Cancelamento em processamento) |
| refunds/amount | Até 10 | Numérico | Valor do cancelamento. |
| brand | - | - | Grupo de informações recebidas da bandeira sobre a transação. |
| brand/name | - | Alfanumérico | Nome da bandeira. Ex: Mastercard. |
| brand/returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| brand/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand/authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| brand/brandTid | Até 21 | Alfanumérico | Código identificador da transação na respectiva bandeira. Para mais detalhes consulte a seção [Recorrência e Card-on-file](e-rede#documentacao-recorrencia) |
{.table-bordered}
:::

**IMPORTANTE:** As consultas transacionais realizadas utilizando o ++parâmetro _tid_++ possuem um prazo máximo de visualização dos dados de até **400 dias**. Após esse período, os dados não estarão mais acessíveis para consulta.

#### Consulta por código do pedido (reference)

> GET: **[/v2/transactions?reference={codigo_reference}](e-rede#operations-Transação-consultarTransacaoPorReference)** {.content-info}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|------ | ------- | ------------ | ----------- | ----------------------- |
| reference | Até 50 | Alfanumérico | Sim | Código da transação gerado pelo estabelecimento.|
{.table-bordered}
:::

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|------------------ | ------- | ------------ | :----------------------------------- |
| requestDateTime | | Datetime | Data da requisição no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| authorization | | authorization | |
| authorization/dateTime | | Datetime | Data da transação de autorização no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| authorization/returnCode | Até 3 | Alfanumérico | Código de retorno da transação. |
| authorization/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| authorization/affiliation | Até 9 | Numérico | Número de filiação do estabelecimento (PV).|
| authorization/status | | Alfanumérico | Status da transação: |\
|||| - Approved |\
|||| - Denied |\
|||| - Canceled |\
|||| - Pending |
| authorization/reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento.|
| authorization/orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento.|
| authorization/tid | 20 | Alfanumérico | Número identificador único da transação. |
| authorization/nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorization/authorizationCode | 6 | Alfanumérico | Número de Autorização da transação retornada pelo emissor do cartão. |
| authorization/kind | Até 10 | Alfanumérico | Método de pagamento utilizado na transação original (Credit ou Debit). |
| authorization/amount | Até 10 | Numérico | Valor total da compra sem separador de milhar. |\
|||||\
|||| Exemplos:|\
|||| - 1000 = R$10,00 |\
|||| - R$ 0,50 = 50 |
| authorization/installments | Até 2 | Numérico | Número de parcelas. |
| authorization/cardHolderName | Até 30 | Alfanumérico | Nome do portador impresso no cartão. |
| authorization/cardBin | 6 | Alfanumérico | 6 primeiros dígitos do cartão. |
| authorization/last4 | 4 | Alfanumérico | 4 últimos digitos do cartão. |
| authorization/softDescriptor | Até 18\* | Alfanumérico | Mensagem que será exibida ao lado no nome do estabelecimento na fatura do portador. |
| authorization/origin | Até 2 | Numérico| Identifica a origem da transação.|\
|||| - e.Rede - 1|
| authorization/subscription | | Booleano | Informa ao emissor se a transação é proveniente de uma recorrência. Se transação for uma recorrência, enviar **true.** Caso contrário, enviar **false.** |\
|||||\
|||| O não envio desse campo será considerado o valor false. |\
|||| |\
|||| A Rede não gerencia os agendamentos de recorrência, apenas permite aos lojistas indicarem se a transação se originou de uma recorrência. |
| authorization/distributorAffiliation | Até 9 | Numérico | Número de filiação do distribuidor (PV). |
| authorization/authorizationEci | Até 2 | Alfanumérico | ECI final da transação, retornado pelo emissor ou bandeira no momento da autorização. Representa o nível de segurança atribuído à transação após o processo de autorização. |
| authorization/downgradeEci |  | Booleano | Indicador de downgrade em transações 3DS e Data Only. Compara o ECI da autenticação com o ECI da autorização e indica se houve perda do nível de autenticação. |\
| | | ||\
| | | |Valores possíveis: **true** (houve downgrade)  **false** (não houve downgrade).|\
| | | ||\
| | | |Disponível para Mastercard, Visa e Elo. |
| capture | | capture | |
| capture/dateTime | | Datetime | Data da transação de captura no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| capture/nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede na transação de captura. |
| capture/amount | Até 10 | Numérico | Valor da captura. |
| threeDSecure | | threeDSecure | |
| threeDSecure/embedded | | Booleano | Informa se o serviço MPI utilizado será da Rede ou terceiro. |
threeDSecure/[eci](e-rede#documentacao-tabela-ecis) | 2 | Alfanumérico | Código retornado ao MPI pelas Bandeiras que indica o resultado da autenticação do portador junto ao Emissor. Deve ser enviado apenas para a utilização do serviço de autenticação 3DS.Transações de débito devem ser obrigatoriamente autenticadas. |
| threeDSecure/cavv | Até 32 | Alfanumérico | Código do criptograma utilizado na autenticação da transação e enviado pelo MPI do estabelecimento (pode conter caracteres especiais). Deve ser enviado apenas para a utilização do serviço de autenticação 3DS/Data Only. O valor informado no campo threeDSecure/cavv deve ser único por autenticação/transação e não pode ser reutilizado em outra transação. |
| threeDSecure/xid | 28 | Alfanumérico | ID da transação de autenticação enviado pelo MPI ao estabelecimento (pode conter caracteres especiais). Deve ser enviado apenas para a utilização do serviço de autenticação 3DS. Campo utilizado somente para bandeira Visa. |
| threeDSecure/returnCode | 3 | Alfanumérico | Código de retorno da transação com 3ds. |
| threeDSecure/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação com 3ds. |
| refunds | | refunds | |
| refunds/dateTime | | Datetime | Data da transação de cancelamento no formato YYYY-MM-DDThh:mm:ss.sTZD .|
| refunds/refundId | 36 | Alfanumérico | Código de retorno da solicitação de cancelamento gerado pela Rede. |
| refunds/referenceRefund | Até 50 | Alfanumérico | Código do cancelamento gerado pelo estabelecimento. |
| refunds/status | Até 10 | Alfanumérico | Status da solicitação de cancelamento. |\
| | | | - Done (Cancelamento efetivado) |\
| | | | - Denied (Cancelamento negado) |\
| | | | - Processing (Cancelamento em processamento) |
| refunds/amount | Até 10 | Numérico | Valor do cancelamento. |
{.table-bordered}
:::

**IMPORTANTE:** As consultas realizadas através do ++parâmetro _reference_++ possuem um prazo máximo de visualização de até **60 dias** para transações quatro partes (Débito e crédito) e de até **90 dias** para transações Pix.

**OBS:** Caso você realize uma consulta fora dos prazos informados, tanto para o _tid_ quanto para a _reference_, nossa API retornará o código de erro **78 (Transaction does not exist)**.

### Consulta de cancelamento {#documentacao-consulta-cancelamento .menu-nv2}

É utilizada para consultar informações de cancelamento a partir de uma solicitação enviada, sendo possível consultar informando o TID, para uma consulta mais detalhada e o refundId para uma consulta de um cancelamento específico.

A consulta do status final do cancelamento poderá ser realizada através da API de consulta de transação, do portal da Rede ou do extrato eletrônico um dia após a requisição de cancelamento ter sido realizada.

**Consulta de cancelamento por tid**

> GET: **[/v2/transactions/{tid}/refunds](e-rede#operations-Cancelamento-consultarCancelamentoPorTid)** {.content-info}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|------ | ------- | ------------ | ----------- | ---------------------------------------- |
| tid | 20 | Alfanumérico | Sim | Número identificador único da transação. |
{.table-bordered}
:::
**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
| ------------------ | ------- | ------------ | :----------------------------------- |
| refundId | 36 | Alfanumérico | Código de retorno do cancelamento gerado pela Rede.|\
|||||\
|||| Caso a transação seja cancelada por outro canal que não seja a API, este campo retornará vazio. |
| refundDateTime | | Datetime | Data do cancelamento no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| cancelId | Até 15 | Alfanumérico | Código identificador da transação de solicitação cancelamento, retornado somente em solicitações D+1. |
| status | Até 10 | Alfanumérico | Status das solicitações de cancelamentos |\
|||| - Done (Cancelamento efetivado)|\
|||| - Denied (Cancelamento negado) |\
|||| - Processing (Cancelamento em processamento) |
| amount | Até 10 | Numérico | Valor do cancelamento sem separador de milhar e casa decimal. |
{.table-bordered}
:::

**Consulta de cancelamento por refundId**
A consulta de cancelamento por refundId lista uma solicitação de cancelamento específica.

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|---------- | ------- | ------------ | ----------- | ---------------------------------------- |
| refundId | 36 | Alfanumérico | Sim | Código de retorno do cancelamento gerado pela Rede. Caso a transação seja cancelada por outro canal que não seja a API, este campo retornará vazio, não sendo possível consultar por refundId. |
{.table-bordered}
:::

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
| ------------------ | ------- | ------------ | :----------------------------------- |
| refundId | 36 | Alfanumérico | Código de retorno do cancelamento gerado pela Rede. Caso a transação seja cancelada por outro canal que não seja a API, este campo retornará vazio, não sendo possível consultar por refundId. |
| tid | 20 | Alfanumérico | Número identificador único da transação |
| refundDateTime | | Datetime | Data do cancelamento no formato YYYY-MM-DDThh:mm:ss.sTZD |
| cancelId | Até 15 | Alfanumérico | Código identificador da transação de solicitação cancelamento, retornado somente em solicitações D+1.|
| amount | Até 10 | Numérico | Valor do cancelamento sem separador de milhar e casa decimal. |
| statusHistory | | statusHistory | |
| statusHistory/status | Até 10 | Alfanumérico | Histórico do status das solicitações de cancelamentos |\
|||| - Done (Cancelamento efetivado) |\
|||| - Denied (Cancelamento negado) |\
|||| - Processing (Cancelamento em processamento) |
| statusHistory/dateTime | | Datetime | Data da solicitação do cancelamento no formato YYYY-MM-DDThh:mm:ss.sTZD |
| returnCode| Até 3 | Alfanumérico | Código de retorno da transação |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação |
{.table-bordered}
:::

### SoftDescriptor {#documentacao-softdescriptor .menu-nv2}

A identificação na fatura (SoftDescriptor ou DBA) é um parâmetro que auxilia o portador a identificar a transação gerada na fatura do cartão.

O parâmetro é composto por 22 caracteres. O SoftDescriptor é dividido em duas partes, no qual a primeira parte é cadastrada no portal da Rede e chamamos de hard descriptor, por ser único por transação daquele PV. A segunda parte é dinâmica, e é enviada a cada requisição de transação via API, essa parte é a que chamamos de SoftDescriptor.

Esses valores são imputados na mensageria de captura para a bandeira, e separados com um \* (asterisco).

O hard descriptor pode ter no máximo 12 caracteres e ele será variável dependendo da quantidade de caracteres de SoftDescriptor que vier na requisição. Ou seja, o **cadastro do hard descriptor** é feito uma **única vez**, e a forma como aparece na fatura **varia de acordo com o tamanho do SoftDescriptor**, abaixo exemplificamos as **regras de API** e.Rede para combinação de ambos os campos:

- Caso seja enviado na requisição entre 1 e 9 posições no SoftDescriptor, a composição na fatura será 12 caracteres do hard + 1 a 9 caracteres do Soft, com o asterisco, totaliza os 22 caracteres abertos para essa informação.

Exemplo: Supondo que seja cadastrado no portal como hard descriptor “REDECOMMERCE” e SoftDescriptor “PRODUTO01”, na fatura do cliente final aparecerá **REDECOMMERCE\*PRODUTO01**

Exemplo com espaços no SoftDescriptor: Supondo que seja cadastrado no portal como hard descriptor “REDECOMMERCE” e SoftDescriptor “PRODU ”, na fatura do cliente final aparecerá **REDECOMMERCE\*PRODU**

- Caso seja enviado na requisição entre 10 e 14 posições no SoftDescriptor, a composição na fatura será 7 caracteres do hard + 10 a 14 caracteres do Soft, com o asterisco, totaliza os 22 caracteres abertos para essa informação.

Exemplo: Supondo que seja cadastrado no portal como hard descriptor “REDECOMMERCE” e SoftDescriptor “PRODUTODIGIT01”, na fatura do cliente final aparecerá **REDECOM\*PRODUTODIGIT01**

Exemplo com espaços no SoftDescriptor: Supondo que seja cadastrado no portal como hard descriptor “REDECOMMERCE” e SoftDescriptor “PRODU ”, na fatura do cliente final aparecerá **REDECOM\*PRODU**

- Caso seja enviado na requisição entre 15 e 18 posições no SoftDescriptor, a composição na fatura será 3 caracteres do hard + 15 a 18 do Soft, com o asterisco, totaliza os 22 caracteres abertos para essa informação.

Exemplo: Supondo que seja cadastrado no portal como hard descriptor “REDECOMMERCE” e SoftDescriptor “PRODUTODIGITAL0001”, na fatura do cliente final aparecerá **RED\*PRODUTODIGITAL0001**

Exemplo com espaços no SoftDescriptor: Supondo que seja cadastrado no portal como hard descriptor “REDECOMMERCE” e SoftDescriptor “PRODU ”, na fatura do cliente final aparecerá **RED\*PRODU**

**Importante:** Caso utilize a MPI Rede, não utilize espaço ou caracteres especiais no SoftDescriptor, pois isso resultará em erros na autenticação da transação.

Para utilizar essa funcionalidade, acesse o portal da Rede no menu *para vender > e-commerce > Identificação na fatur*a ou entre em contato com a Central de atendimento da Rede. Caso o nome não seja cadastrado, o serviço não será habilitado.

Após a habilitação do serviço via portal, a funcionalidade será disponibilizada dentro de um prazo de até 24 horas.

O parâmetro deve ser enviado juntamente à requisição de transações de crédito (autorização ou autorização com captura automática) ou débito.

### MCC dinâmico {#documentacao-mcc-dinamico .menu-nv2}

O código da categoria do estabelecimento, conhecido como MCC, enviado pelo marketplace ou facilitador, pode ser dinâmico conforme as informações do estabelecimento que esteja efetuando a transação.

Para esse cenário, é obrigatório enviar o softdescriptor. [Clique aqui](e-rede#documentacao-softdescriptor) para obter mais informações.

Para informação referente ao MCC dinâmico, o nome cadastrado no portal, menu _para vender > e-commerce > Identificação na fatura_, equivale ao nome do facilitador (subcredenciador).

> Selecione o tipo "MCC dinâmico" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|------------------------------- | ------- | ------------- | ----------- | ------------------------------------------------------------ |
| softDescriptor | Até 18* | Alfanumérico | Sim* | Frase personalizada que será impressa na fatura do portador. |
| paymentFacilitatorID | Até 11 | Numérico | Sim* | Código do facilitador de pagamento na respectiva bandeira. |\
| | | | | |\
| | | | |Quando a transação for originária de um marketplace, o campo marketplaceId deve ser enviado.  |
| marketplaceId  | Até 11 | Alfanumérico | Sim* | Código do marketplace na respectiva bandeira. Obrigatório para marketplaces. |
| independentSalesOrganizationID | Até 11 | Numérico | Não | Código da organização de vendas independente. |
| subMerchant | | SubMerchant | | |
| subMerchant / mcc* | 4 | Numérico | Sim* | MCC do subestabelecimento comercial. |
| subMerchant / subMerchantID | Até 15 | Alfanumérico* | Sim* | Código do subestabelecimento comercial. |
| subMerchant / address | Até 48 | Alfanumérico¹ | Não* | Endereço do subestabelecimento comercial. |
| subMerchant / city | Até 13 | Alfanumérico¹ | Não* | Cidade do subestabelecimento comercial. |
| subMerchant / state | 2 | Alfabético | Sim* | Estado do subestabelecimento comercial. |
| subMerchant / country | Até 3 | Alfanumérico | Sim* | País do subestabelecimento comercial. |
| subMerchant / cep | Até 9 | Alfanumérico | Sim* | Código postal do subestabelecimento comercial. |
| subMerchant / taxIdNumber | Até 14 | Alfanumérico | Sim* | CPF ou CNPJ do subestabelecimento comercial. |
| subMerchant / merchantTaxIdName | Até 27 | Alfanumérico | Sim | Razão social do subestabelecimento comercial. |\
| | | | | |\
| | | | |Somente letras e números. Espaços e caracteres especiais não são aceitos. |
| subMerchant / internationalSellerIndicator | - | Booleano | Não\* | True ou False.|\
| | | | | |\
| | | | | Indica se a transação é enviada por um estabelecimento/marketplace internacional.|
| subMerchant / url  | Até 25 | Alfanumérico | Sim | URL do estabelecimento comercial.|\
| | | | | |\
| | | | | Caso não possua site próprio, pode ser utilizada a URL dentro do marketplace. |\
| | | | | |\
| | | | |Somente letras e números. Espaços e caracteres especiais não são aceitos. |
| subMerchant / telephone   | Até 15 | Alfanumérico  | Não | Telefone do estabelecimento.|\
| | | | | |\
| | | | | Deve conter DDD e número válido.  Opcional quando a URL estiver preenchida|
{.table-bordered}
:::

**_Importante: o não envio do parâmetro internationalSellerIndicator quando a transação for de um marketplace internacional pode resultar em custos adicionais._**

Os campos de cidade, estado e razão devem ser enviados sem caracteres especiais ou acentos.

- Para a bandeira ELO, o campo subMerchantID deve ser enviado como numérico. Caso seja enviado como alfanumérico a transação será negada.

- Devido à LGPD (Lei Geral de proteção de dados), os seguintes campos da chave “subMerchant”: subMerchantID, address, city, state, country, cep e cnpj, mesmo quando enviados na requisição, não são devolvidos nas consultas de transações.

- **Para garantir o devido processamento da transação, não se deve incluir caracteres especiais.**

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
| ------------------ | ------- | ------------ | :----------------------------------- |
| returnCode | Até 3 | Alfanumérico | Código de retorno da transação. |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | 20 | Alfanumérico | Número identificador único da transação.|
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão.|
| dateTime | | Datetime | Data da transação no formato YYYY-MM-DDThh:mm:ss.sTZD. |
| amount | Até 10 | Numérico | Valor total da transação sem separador de milhar e decimal. |
| cardBin | 6 | Alfanumérico | 6 primeiros dígitos do cartão. |
| last4 | 4 | Alfanumérico | 4 últimos dígitos do cartão. |
| brand | - | - | Grupo de informações recebidas da bandeira sobre a transação. |
| brand/name | - | Alfanumérico | Nome da bandeira. Ex: Mastercard. |
| brand/returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| brand/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand/merchantAdviceCode | Até 2 | Alfanumérico | Código de Aviso para Estabelecimento Comercial. É um conjunto de códigos usado para fornecer informações adicionais sobre uma resposta de transação de uso exclusivo da bandeira Mastercard. |
| brand/authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| brand/brandTid | Até 21 | Alfanumérico | Código identificador da transação na respectiva bandeira. Para mais detalhes consulte a seção [Recorrência e Card-on-file](e-rede#documentacao-recorrencia) |
{.table-bordered}
:::

### Subadquirentes e Marketplaces {#documentacao-subadquirentes-marketplaces .menu-nv2}

#### Público

**Subadquirentes**: empresa integrada a um adquirente que habilita outras empresas ou pessoas físicas para a aceitação de pagamentos com cartões mediante intermediação do fluxo financeiro das transações;

**Marketplace**: e-commerce que vende produtos terceiros, operando como um shopping center virtual. Está sob as mesmas regras de um Subadquirente por fazer intermediação do fluxo financeiro para o Seller;

#### Mensageria do transacional

A Circular 3978 determina que os Subadquirentes e Marketplace identifique os beneficiários finais no momento da transação. Para cumprimento desta norma, é obrigatório o envio dos campos identificadores na mensageria da transação, conforme orientações abaixo:

- **Softdescriptor**: É um parâmetro que auxilia o portador a identificar a transação gerada na fatura do cartão.

Esse parâmetro é composto por duas partes, a primeira é o **Hard Descriptor**, que é **único do subadquirente**, e a segunda é dinâmica, a que chamamos de **Softdescriptor**, ela identifica o subestabelecimento da transação.

Este campo é obrigatório e deve ter um tamanho de até **22 caracteres**. O _Hard Descriptor_ pode ter no máximo 12 caracteres e ele será variável dependendo da quantidade de caracteres de _SoftDescriptor_ que vier na requisição.

\*O hard descriptor pode ter no máximo 12 caracteres e ele será variável dependendo da quantidade de caracteres de SoftDescriptor que vier na requisição. Ou seja, **o cadastro do hard descriptor** é feito **uma única vez**, e a forma como aparece na fatura **varia de acordo com o tamanho do SoftDescriptor**. Poderá ser enviado na requisição até 18 posições no SoftDescriptor e neste caso, a composição na fatura será 3 caracteres do hard + 18 do Soft, com o asterisco, totaliza os 22 caracteres abertos para essa informação.

Para maiores detalhes sobre o envio deste campo, clique aqui ou acesse a sessão [Softdescriptor](e-rede#documentacao-softdescriptor);

- **PFID (paymentFacilitatorID)**: Código do Facilitador de Pagamento em cada bandeira
- **marketplaceId**: Código do marketplace em cada bandeira
- **SubmerchantID**: Código do Subestabelecimento (Seller). Este código é gerado pelo facilitador de Pagamento
- **subMerchant / address**: Endereço do Subestabelecimento (Seller)
- **subMerchant / city**: Cidade do Subestabelecimento (Seller)
- **subMerchant / state**: Estado do Subestabelecimento (Seller)
- **subMerchant / country**: País do Subestabelecimento (Seller)
- **subMerchant / cep**: Cep do Subestabelecimento (Seller)
- **subMerchant / mcc**: Código do ramo/MCC do subestabelecimento (Seller) = MCC Dinâmico
- **SubMerchant / url**: Url do Subestabelecimento (Seller) 
- **SubMerchant / telephone**: Telefone do Subestabelecimento (Seller) 

Para classificação correta do MCC do Seller, deve-se seguir a regra determinada pela ABECs descrita abaixo:

**Regra de definição de MCC**

1. CNAE (Código Nacional de Atividade Econômica) primário, atribuído pela Receita Federal para classificar a área de atuação do estabelecimento. A ABECS utiliza uma base de CNPJs enviada pela Serasa, com as informações de DE-PARA de CNAE para CNPJ. Para classificar o cliente em qualquer outro CNAE, ainda que seja o CNAE secundário, é necessário antes demonstrar para as bandeiras a atividade exercida pelo cliente.
2. Avaliação no comitê de BANDEIRAS que sobrepõe a regra 1. É feito a aprovação dos casos de exceção, onde a regra do CNAE/MCC não reflete a atividade do cliente. A avaliação é feita por CNPJ e aplicada após uma defesa à ABECS.

**_Nota: Para maiores detalhes e acesso a base, consulte o site oficial da ABECS: [https://www.abecs.org.br/consulta-mcc-individual](https://www.abecs.org.br/consulta-mcc-individual)_**

- **subMerchant / CPF_cnpj**: CNPJ/CPF do Subestabelecimento (Seller)

**Parâmetros de requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
| ------------------------------------------ | ------- | ------------ | ----------- | :----------------------------------------------------------- |
| softDescriptor | Até 18 | Alfanumérico | Sim | Frase personalizada que será impressa na fatura do portador. |
| paymentFacilitatorID | Até 11 | Numérico | Sim | Código do facilitador de pagamento na respectiva bandeira.|\
| | | | | |\
| | | | | Quando a transação for originária de um marketplace, o campo marketplaceId deve ser enviado.  |
| marketplaceId  | Até 11 | Alfanumérico | Não | Código do marketplace na respectiva bandeira. Obrigatório para marketplaces.  |
| subMerchant | | SubMerchant | Sim | |
| subMerchant / mcc | 4 | Numérico | Sim | MCC do subestabelecimento comercial. |
| subMerchant / subMerchantID | Até 15 | Alfanumérico | Sim | Código do subestabelecimento comercial. |
| subMerchant / address | Até 48 | Alfanumérico | Sim | Endereço do subestabelecimento comercial. |
| subMerchant / city | Até 13 | Alfanumérico | Sim | Cidade do subestabelecimento comercial. |
| subMerchant / state | 2 | Alfabético | Sim | Estado do subestabelecimento comercial. |
| subMerchant / country | Até 3 | Alfanumérico | Sim | País do subestabelecimento comercial. |
| subMerchant / cep | Até 9 | Alfanumérico | Sim | Código postal do subestabelecimento comercial. |
| subMerchant / taxIdNumber | Até 14 | Alfanumérico | Sim | CPF ou CNPJ do subestabelecimento comercial. |
| subMerchant / merchantTaxIdName | Até 27 | Alfanumérico | Sim | Razão social do subestabelecimento comercial. |\
| | | | | |\
| | | | |Somente letras e números. Espaços e caracteres especiais não são aceitos. |
| subMerchant / internationalSellerIndicator | | Booleano | Não | True ou False.|\
| | | | | |\
| | | | | Indica se a transação é enviada por um estabelecimento/marketplace internacional. |
| subMerchant / url  | Até 25 | Alfanumérico | Sim | URL do estabelecimento comercial.|\
| | | | | |\
| | | | | Caso não possua site próprio, pode ser utilizada a URL dentro do marketplace. |\
| | | | | |\
| | | | |Somente letras e números. Espaços e caracteres especiais não são aceitos. |
| subMerchant / telephone   | Até 15 | Alfanumérico | Não | Telefone do estabelecimento.|\
| | | | | |\
| | | | | Deve conter DDD e número válido.  Opcional quando a URL estiver preenchida|
{.table-bordered}
:::

**_Importante: o não envio do parâmetro internationalSellerIndicator quando a transação for de um marketplace internacional pode resultar em custos adicionais._**

Os campos de cidade, estado e razão social devem ser enviados sem caracteres especiais ou acentos..

Selecione o tipo "MCC dinâmico" no combo box "Examples" da requisição.

POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

Note que os parâmetros de requisição dentro do grupo “submerchant” devem sempre começar em letra minúscula.

OBS: Devido à LGPD (Lei Geral de proteção de dados), os seguintes campos da chave “subMerchant”: subMerchantID, address, city, state, country, cep e cnpj, mesmo quando enviados na requisição, não são devolvidos nas consultas de transações.

**Atenção: Para garantir o devido processamento da transação, não se deve incluir caracteres especiais.**

**Parâmetros de resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
| ------------------------ | ------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| returnCode | Até 3 | Alfanumérico | Código de retorno da transação. |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | 20 | Alfanumérico | Número identificador único da transação. |
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| dateTime | | Datetime | Data da transação no formato YYYY-MM-DDThh:mm:ss.sTZD. |
| amount | Até 10 | Numérico | Valor total da transação sem separador de milhar e decimal. |
| cardBin | 6 | Alfanumérico | 6 primeiros dígitos do cartão. |
| last4 | 4 | Alfanumérico | 4 últimos dígitos do cartão. |
| brand | - | - | Grupo de informações recebidas da bandeira sobre a transação. |
| brand/name | - | Alfanumérico | Nome da bandeira. Ex: Mastercard. |
| brand/returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| brand/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand/merchantAdviceCode | Até 2 | Alfanumérico | Código de Aviso para Estabelecimento Comercial. É um conjunto de códigos usado para fornecer informações adicionais sobre uma resposta de transação de uso exclusivo da bandeira Mastercard. |
| brand/authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| brandTid | Até 21 | Alfanumérico | Correlaciona a primeira e demais transações através do envio deste campo. Para mais detalhes consulte a seção [Recorrência e Card-on-file](e-rede#documentacao-recorrencia) |
{.table-bordered}
:::

### Recorrência e Card-on-File {#documentacao-recorrencia .menu-nv2}

**O que é Recorrência?**
A recorrência é uma opção de pagamentos que funciona como uma cobrança periódica, o pagamento é feito por prazo e frequência pré-determinados pelo lojista e acordados com o pagador. A principal vantagem é o não comprometimento do limite do cartão do cliente, efetuando cobranças automaticamente. É uma opção que apoia o lojista a não a se preocupar em cobrar os clientes frequentemente, uma vez que esse ajuste já foi feito no momento da compra.

Lembramos que o e.Rede não possui um motor de recorrência ou gerencia agendamentos recorrentes, caso seu e-commerce possua esse motor, deve enviar as transações recorrentes para a Rede usando os campos corretamente.

**O que é card-on-file?**
Também conhecido como credential-on-file ou credencial armazenada. As transações com cartão armazenado são aquelas em que o portador autorizou o armazenamento dos dados do seu cartão para iniciar compras futuras ou que possam ser utilizadas pelo lojista para recorrências ou cobranças futuras.

Quando temos um cartão armazenado, não é necessário enviar o securityCode nas transações.

**Confira abaixo quais campos usar em cada operação:**

::: table-scroll
| Recorrentes | Card-on-file |
| :---------- | :---------- |
| - storageCard | - storageCard |\
| | |
| - credentialId (para Mastercard) | - credentialId (para Mastercard) |\
| | |
| - subscription | |\
| | |
| - brandTid | |\
| | |
| - transacionLinkId | |\
| | |
{.table-bordered}
:::

**O que cada um deles significa?**

- storageCard: Indica operações que possam ou não estar utilizando COF (Card On File – credencial armazenada)

**0 -** Utilizado para cartão não armazenado (deve ser acompanhado do securityCode)

**1 -** Utilizado para cartão que está sendo armazenado pela primeira vez (deve ser acompanhado do securityCode, caso esta seja a primeira transação em que se pretende armazenar o cartão. Esse passo pode ser substituído por uma transação de Zero Dollar, que também deve ser acompanhado do código de segurança)

**2 -** Utilizado para indicar cartão já armazenado (securityCode não deve ser enviado)

Para a bandeira Elo é obrigatório que antes de indicar cartão armazenado (storageCard=2) tenha sido feito um Zero Dollar ou transação com storageCard = 1.

**\*Importante:** A Rede só irá sinalizar uma transação com credencial armazenada quando o storageCard for igual a “2”, transações sinalizadas como 1, indicam que o estabelecimento está executando uma transação que irá iniciar o armazenamento da credencial, exigindo então validações de transações comuns. EX: uso de código de segurança do cartão (securityCode).\*

- **credentialId:** Campo utilizado atualmente somente pela bandeira Mastercard, para indicar o motivo de armazenamento do cartão e facilitar a análise para aprovação. Para mais detalhes consulte a seção a seguir [Categorização de transações card-on-file](e-rede#documentacao-recorrencia-categorizacao-transacoes-card-on-file).

- **subscription:** Parâmetro utilizado para a sinalização de transações recorrentes.
  Deve ser enviado como true caso a transação seja recorrente, false para transações comuns;

- **brandTid:** Este é um campo único e dinâmico, recebido a cada resposta de transação, e é utilizado para correlacionar planos de recorrência (nos casos das bandeiras Visa e Mastercard) e correlacionar transações iniciadas pelo estabelecimento como incrementais, recorrentes e com cartão armazenado (no caso da bandeira Elo).

- **transactionLinkId:** Este campo é único e dinâmico, recebido a cada resposta de transação, e é utilizado para correlacionar transações iniciadas pelo estabelecimento como incrementais, recorrentes e com cartão armazenado na bandeira Mastercard.Deve ser enviado para a bandeira a partir da segunda transação, e faz uma correlação das transações subsequentes com a primeira.
**Este campo passará a ser retornado em outubro de 2025 e deverá ser armazenado pelos estabelecimentos. Em 2026 esse campo substituirá o brandTid em transações recorrentes ou de card-on-file da bandeira Mastercard, a data será divulgada futuramente.**

Deve ser enviado para a bandeira a partir da segunda transação, e faz uma correlação das transações subsequentes com a primeira.

O estabelecimento é responsável por armazenar o brandTid e o transactionLinkId retornado e enviá-lo em todas as transações subsequentes.

**Para a bandeira Visa:** Quando a transação é identificada como recorrente (subscription=true), a cada transação seguinte que o estabelecimento enviar para aquele plano de recorrência deve enviar também o brandTid fornecido pela bandeira da transação **original.**

**Por exemplo:** Em um plano recorrente mensal, na terceira transação o estabelecimento deve encaminhar o brandTid recebido na transação que deu início ao plano de recorrência.

No caso de transações **tokenizadas Visa, o envio desse parâmetro é obrigatório.** Nos demais tipos de transação, caso seja feito, deve-se garantir o envio do valor correto para evitar negativas por parte da bandeira.

**Para a bandeira Mastercard:** Quando a transação é identificada como recorrente (subscription=true), a cada transação seguinte que o estabelecimento enviar para aquele plano de recorrência deve enviar também o brandTid e o transactionLinkId fornecido pela bandeira da transação **original ou anterior**.

**Para a bandeira Elo**: Sempre que o estabelecimento iniciar uma transação, seja por recorrência, cartão armazenado ou quaisquer outros tipos de transações incrementais, deverá enviar o brandTid fornecido pela bandeira na **transação original**.

Para a Elo, caso tenha sido feita uma validação Zero Dollar antes de utilizar o cartão, deve-se enviar o brandTid recebido no Zero Dollar nas transações financeiras subsequentes.

**Lembre-se:** O estabelecimento continuará recebendo um brandTid diferente da bandeira em cada nova transação, mas na solicitação de autorização de uma transação recorrente ou iniciada pelo estabelecimento, deverá seguir as regras descritas acima. Fique atento aos formatos e garanta sempre o envio correto do parâmetro para evitar negativas por parte do emissor/bandeira.

Caso não possua o valor correspondente, orientamos que seja iniciado um novo processo de armazenamento do cartão (card-on-file) junto ao portador para obter o parâmetro a ser enviado nas transações subsequentes.

**Atente-se aos pontos abaixo de ambas as operações:**

- O não envio do campo storageCard será considerado 0 (credencial não armazenada).
- Caso o cliente queira trocar o cartão, será necessário reiniciar o processo desde o envio da primeira transação, ou seja, storageCard=1 para o novo cartão, então nas demais poderá ser enviado o brandTid e storageCard=2, além da indicação de recorrência (subscription=true).
- Ressaltamos que transações recorrentes **não podem ser processadas como pré-autorização,** para isso o campo **capture** deve ser igual a “true”, indicando uma captura automática. **Caso sejam enviadas como capture “false”, a marcação de recorrência não será considerada.**
- Além disso, qualquer alteração na recorrência (Ex: mudança no valor cobrado mensalmente), será considerada uma nova transação e a antiga deverá ser desconsiderada.
- Ao realizar transações por meio de credencial armazenada (card-on-file), se o estabelecimento já desejar iniciar as cobranças ou apenas salvar o cartão para cobranças futuras, as bandeiras **exigem** que antes seja feito uma validação Zero Dólar.
- A validação **Zero Dollar** pode ser utilizada por estabelecimentos para verificar os dados do cartão para checar se a credencial é válida e pode ser armazenada, além possibilitar as cobranças futuras sem o envio do securityCode em cobranças de recorrentes com credencial armazenada ou apenas de credencial armazenada, além de aumentar a possibilidade de conversão.
- **Uso do “sai” em transações card-on-file (credencial armazenada):** O parâmetro deverá ser utilizado sempre que a transação possuir um ECI específico, que não esteja atrelado a autenticação 3DS (ex: Wallets e Cloud Token Visa), **quando autenticado como 3DS faz-se necessário que o “eci” seja informado dentro do grupo 3D Secure, não sendo necessária a utilização do “sai” neste caso.**
- Ao fazer o envio do grupo threeDSecure em qualquer requisição, o campo “sai” será ignorado e a prioridade será do fluxo de 3DS.

### Categorização de transações card-on-file {#documentacao-recorrencia-categorizacao-transacoes-card-on-file .menu-nv3}

Desde outubro de 2022, devido a mudanças regulatórias de bandeiras, as transações card-on-file da bandeira Mastercard passarão a ser categorizadas em 12 tipos de categorias **CIT (Iniciadas pelo portador do cartão – Card Holder) e MIT (Iniciadas pelo estabelecimento – Merchant).** Desde 1 de junho de 2023, a bandeira passou a monitorar o envio do campo, fique atento pois podem ocorrer ações de compliance.

O crescimento contínuo do comércio eletrônico, juntamente com o aumento dos tipos de transação, exige a necessidade de entender a intenção do consumidor. A introdução do indicador CIT ou MIT fornece transparência permitindo o uso para:

- Lógica de autorização do emissor
- Detecção de fraude
- Gestão de disputas

Por isso, é necessário realizar ajustes em sua integração com o e.Rede para envio do campo chamado "credentialId", que fará parte do grupo “transactionCredentials”. Desse modo, quando storageCard for igual a 1 ou 2, indicando que o cartão está sendo ou já foi armazenado, será **obrigatório** indicar em qual categoria a transação card-on-file (credencial armazenada) está enquadrada.

O envio também deve ser feito em transações Zero Dollar que pretendem armazenar o cartão, ou em transações tokenizadas.

O envio deste campo passou a ser **obrigatório** para a operação Mastercard **desde 01 de junho de 2023,** e a partir de 01 de junho de 2024, a bandeira Mastercard poderá aplicar penalidades em caso de não conformidade dos estabelecimentos, referente ao período fora da norma. Entre os benefícios do envio do campo, está a capacidade de apoiar a bandeira e o emissor na análise de suas transações, o que pode ajudar na conversão. Os outros campos já utilizados atualmente para finalidades semelhantes como storageCard, subscription e installments, precisam continuar a ser populados.

A seguir, a tabela de categorias a ser considerada:

::: table-scroll
| Categorias principais | Indicador a ser enviado (credentialId) | Sub-Categoria correspondente | Definição | Exemplo
| ---------- | --- | ---------------------------- | ---------------- | ----------------------------------------|
| **1. Iniciada pelo Portador (CIT)** Qualquer transação em que o titular do cartão esteja participando ativamente da transação. As transações podem ser realizadas com base nas credenciais fornecidas pelo titular do cartão na hora da transação ou uma credencial armazenada em arquivo de uma interação anterior. As transações podem ocorrer como uma transação de PDV na loja, uma transação de comércio eletrônico, uma transação por correspondência/pedido por telefone ou em um caixa eletrônico. | 01 | Card on File (Credencial armazenada) | O consumidor concorda que seu cartão seja armazenado com o comerciante para futuras transações que possam ocorrer de tempos em tempos. | Transações de aplicativos de carro. |
| ^^ | 02 | Ordem Permanente | O consumidor concorda que seu cartão seja armazenado com o comerciante e inicia uma primeira transação em uma série destinada a um valor variável e uma frequência fixa. | Pagamento mensal de serviços.|
| ^^ | 03 | Assinatura | O consumidor concorda que seu cartão seja armazenado e inicia uma primeira transação em uma série destinada a um valor fixo e uma frequência fixa. | Assinatura mensal de jornal. |
| ^^ | 04 | Parcelado | O consumidor concorda que seu cartão seja armazenado para estabelecer um plano de parcelamento e inicia uma primeira transação em uma série. | A transações parceladas. |
|**2. Iniciadas pelo estabelecimento (MIT), pagamentos recorrentes ou parcelamentos** Uma operação decorrente de um acordo entre o titular do em que o titular do cartão concorda que o comerciante armazene os dados do titular do cartão credencial e usar essa credencial armazenada em arquivo para uma aquisição posterior de bens ou serviços. | 05 | Card on File (Credencial armazenada) – não programada | Transações realizadas por um acordo entre um titular de cartão e um comerciante, pelo qual o consumidor autoriza o comerciante a armazenar e usar os dados da conta do titular do cartão para iniciar uma ou mais transações futuras. | Pedágio Auto recarga||
| ^^ | 06 | Ordem Permanente | Usar os dados da conta do titular do cartão para uma transação que deve ocorrer em intervalos regulares por um valor variável. | Pagamentos mensais de serviços |
| ^^ | 07 | Assinatura| Usar os dados da conta do titular do cartão para uma transação que deve ocorrer em intervalos regulares por um valor fixo. | Assinatura mensal ou pagamento de serviço mensal fixo. |
| ^^ | 08 | Parcelado | Armazenar os dados da conta do titular do cartão para uso do comerciante para iniciar uma ou mais transações futuras por um valor conhecido com uma determinada duração com base em uma única compra. | Comprar uma TV por R$ 1.000, pagando em quatro parcelas iguais de R$ 250 (a primeira transação é CIT, as três transações restantes são MIT). |
|**3. Iniciadas pelo estabelecimento (MIT) práticas da indústria.** Uma transação iniciada pelo comerciante para cumprir uma prática comercial que ocorre com mais frequência após uma interação inicial com o titular do cartão. As transações de prática do setor podem ser realizadas com credenciais armazenadas em arquivo ou credenciais que não são armazenadas em arquivo, mas são temporariamente retidas pelo comerciante conforme acordado pelo consumidor. | 09 | Remessa Parcial | Ocorre quando uma quantidade acordada de mercadorias encomendadas por e-commerce não está disponível para envio no momento da compra. Cada remessa é uma transação separada. | O consumidor encomendou mercadorias que são enviadas em horários diferentes.||
| ^^ | 10 | Cobrança atrasada | Uma cobrança adicional da conta após a prestação dos serviços iniciais e o processamento do pagamento. | Cobrança do frigobar do hotel após o titular do cartão fazer check out do hotel. |
| ^^ | 11 | No show (Multa) | Uma multa cobrada de acordo com a política de cancelamento do comerciante. | O cancelamento de uma reserva pelo titular do cartão sem aviso prévio adequado ao comerciante. |
| ^^ | 12 | Reenvio | A tentativa de obter autorização para uma transação que foi recusada, mas a resposta do emissor não proíbe que o comerciante tente mais tarde. | Fundos insuficientes/ resposta acima do limite de crédito/ retentativa de transações de trânsito. |
{.table-bordered}
:::

### Carteiras Digitais{#documentacao-carteiras-digitais .menu-nv2 .text-rede-orange}

As Carteiras digitais ou Wallets funcionam como dispositivos que armazenam cartões e dados de pagamento para compradores do e-commerce. Permitem que o consumidor cadastre suas credenciais de pagamento e seja capaz de realizar pagamentos de forma rápida e prática pelo celular ou outros dispositivos conectados, por exemplo.

As Wallets que o e.Rede pode receber transações são:

- [Apple Pay](e-rede#documentacao-carteiras-digitais-apple-pay)
- [Google Pay](e-rede#documentacao-carteiras-digitais-google-pay)
- [Samsung Pay](e-rede#documentacao-carteiras-digitais-samsung-pay)

Clicando em cada um dos links acima, é possível acessar o site oficial de cada uma das Wallets com informações para integração do check-out e do fluxo transacional.

Neste momento o e.Rede realiza apenas o processamento dessas transações, isto é, o estabelecimento precisa ser ou possuir um intermediário (como por exemplo, um gateway) que seja PSP (Payment Service Provider). Os PSPs possuem a integração com as Wallets para decriptar os dados das transações e encaminhar ao adquirente (Rede) para processar.

Em breve, a Plataforma de Pagamentos Rede oferecerá também a solução de PSP visando facilitar a integração dos nossos clientes.

Neste momento, a Plataforma de pagamentos Rede processa transações provenientes de Wallets (Apple pay, Google Pay, Samsung Pay) nas bandeiras **Visa, Mastercard e Elo.**

Além dessas opções, as bandeiras Mastercard, Visa, Elo e Amex possuem um programa de Operadoras de carteiras Digitais Escalonadas (SDWO), consulte aqui [Carteiras digitais escalonada (SDWO)](e-rede#documentacao-carteiras-digitais-operadoras-carteiras-digital-escalonada-SDWO)

**Parâmetros da requisição para Apple, Google e Samsung Pay:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|------ | ------- | ------------ | ----------- | :---------------------------------------- |
| capture | - | Booleano | Não |Define se uma transação terá captura automática ou posterior. O não envio desse campo será considerado uma captura automática **(true).** |
| kind | \- | Alfanumérico | Não | Tipo de transação a ser realizada. |\
| | | | | - Para transações de crédito, utilizar **credit** |\
| | | | | - Para transações de débito, utilizar **debit** |\
| | | | | |\
| | | | | O não envio desse campo será considerado crédito. |
| reference | Até 50 | Alfanumérico | Sim | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Não| Código do pedido gerado pelo estabelecimento. (Não aceita caracteres especiais) |
| amount | Até 10 | Numérico | Sim | Valor total da transação sem separador de milhar e casa decimal. |\
| | | | | |\
| | | | | Exemplos: |\
| | | | | - R$10,00 = 1000 |\
| | | | | - R$0,50 = 50 |
| installments | Até 2 | Numérico | Não | Número de parcelas em que uma transação será autorizada. |\
| | | | | |\
| | | | | De 2 a 12 |\
| | | | | |\
| | | | | O não envio desse campo será considerado à vista. |
| cardholderName | Até 30 | Alfanumérico | Não | Nome do portador impresso no cartão. |\
| | | | | |\
| | | | | Não enviar caracteres especiais. |
| cardNumber | Até 19 | Alfanumérico | Sim | Número do cartão.|
| expirationMonth | Até 2 | Numérico | Sim | Mês de vencimento do cartão. De 1 a 12. |
| expirationYear | 2 ou 4 | Numérico | Sim | Ano de vencimento do cartão. |\
| | | | | |\
| | | | | Exemplo: 2028 ou 28 |
| origin | Até 2 | Numérico | Não | Identifica a origem da transação. |\
| | | | | - e.Rede: 1 |\
| | | | | |\
| | | | | O não envio desse campo será considerado uma transação e.Rede (1).|
| securityCode | Até 4 | Alfanumérico | Não | Código de segurança do cartão geralmente localizado no verso do cartão.|\
| | | | | |\
| | | | | O envio desse parâmetro garante maior possibilidade de aprovação da transação.|
| tokenCryptogram | - | Alfanumérico | Obrigatório (Consulte mais detalhes ao final da tabela) | Token informado pela Bandeira. Identificar transações tokenizadas. |
| storageCard | Até 1 | Alfanumérico | Não | Indica operações que possam ou não estar utilizando COF (Card on File): |\
| | | | | |\
| | | | | 0 - Transação com credencial não armazenada.\
| | | | | |\
| | | | | 1 - Transação com credencial armazenada pela primeira vez.|\
| | | | | |\
| | | | | 2 - Transação com credencial já armazenada.|\
| | | | | |\
| | | | | Atenção: O não envio desse campo será considerado 0 (credencial não armazenada). |
| wallet* | - | - | - | Grupo wallet para os parâmetros walletId e walletCode |
| wallet/processingType* | 2 | Alfanumérico | Sim | Identificação de tipo de operação para Apple, Google e SamsungPay: |\
| | | | | - 03 para bandeira ELO|\
| | | | | - 04 para Bandeiras Visa e Mastercard |\
|||| ||\
| | | | | Para checar as informações de SDWO consulte a seção [Operadoras de carteira digital escalonada](e-rede#documentacao-carteiras-digitais-operadoras-carteiras-digital-escalonada-SDWO)|
| wallet/walletId | Até 11 | Numérico | Obrigatório caso processingType=03 (Elo) | Identifica a Wallet originária da transação, são Ids fixos e obrigatórios para uso Elo: |\
| | | | | |\
| | | | | 52810030273 – Apple Pay |\
| | | | | |\
| | | | | 52894351835 – Google Pay|\
| | | | | |\
| | | | | 52815860843 – Samsung Pay|\
| | | | | |
| wallet/walletCode | Até 03 | Alfanumérico | Sim | Identifica a Wallet, uso exclusivo para processingType=03 ou 04 |\
| | | | | |\
| | | | | AEP = Apple Pay |\
| | | | | |\
| | | | | GEP = Google Pay |\
| | | | | |\
| | | | | SGP = Samsung Pay |\
| | | | | |\
| | | | | CTP = Click to Pay
| | | | | Uso exclusivo para processing type 3 ou 4 |
| securityAuthentication | - | - | - | Grupo securityAuthentication |
| sai | Até 02 | Alfanumérico | Obrigatório para as bandeiras Visa e ELO. Opcional em transações card-on-file | Identificador de transação eletrônica (ECI).|\
| | | | | Nas transações que não forem tokenizadas (apenas card-on-file) o envio deste campo não é necessário. |\
| | | | | |\
| | | | | **Para transações Wallets com cartão Elo, sempre envie o valor “04” – indicando uma transação in-app e para Wallets com cartão Visa e Mastercard, siga o que foi enviado pela Wallet.** |\
| | | | | |\
| | | | | Para transações da bandeira Mastercard, esse campo não é enviado. |\
| | | | | |\
| | | | | Para mais detalhes desse campo verifique o tópico “uso do sai”. |
| transactionCredentials | | | | Grupo transactionCredentials |
| transactionCredentials/ credentialId | Até 02 | Alfanumérico | Sim, se storageCard=1 ou =2 e cartão mastercard | Indica a categoria da transação com credencial armazenada. Consulte a seção [“Categorização de transações card-on-file”](e-rede#documentacao-recorrencia-categorizacao-transacoes-card-on-file) para mais detalhes |
{.table-bordered}
:::

**Atenção**: Cartões Visa que forem tokenizados via Wallets após 30 de julho de 2025 não poderão realizar transações parceladas ou recorrentes. Para estes casos os cartões devem ser tokenizados via [card-on-file](e-rede#documentacao-recorrencia), com tokens de uso para o estabelecimento.

Ressaltamos que as Wallets utilizam a tokenização de bandeira em suas transações. Desse modo, quando o comprador salva o cartão, um token de bandeira é criado, alterando assim as informações do cartão físico (número, código de segurança e validade).

Por isso, é **obrigatório** enviar nas transações os campos card number + token cryptogram devolvido por cada wallet. Além disso, em transações MIT (Iniciadas pelo estabelecimento) para a bandeira **Visa**, é permitido enviar o número do cartão tokenizado (campo cardnumber), sem o campo tokenCryptogram, mantendo o valor do campo “sai” indicado pela Wallet. Para as demais bandeiras o tokenCryptogram **obrigatoriamente** deve ser enviado.

**Uso do “sai”:** O parâmetro deverá ser utilizado sempre que a transação possuir um ECI específico, que não esteja atrelado a autenticação 3DS (ex: Wallets e autenticação de tokens de bandeira), quando autenticado através de desafio 3DS faz-se necessário que o “eci” seja informado dentro do grupo 3D Secure, não sendo necessária a utilização do “sai” neste caso. **Para transações Wallets com cartão Elo, sempre envie o valor “04” – indicando uma transação in-app e para Wallets com cartão Visa, siga o que foi enviado pela Wallet.**

**Pontos de atenção:**

- Ao fazer o envio do grupo threeDSecure em qualquer requisição, o campo “sai” será ignorado e a prioridade será do fluxo de 3DS.
- Em caso de envio incorreto dos parâmetros a bandeira poderá fazer o downgrade da transação, isto é, poderá classificá-la como não autenticada, perdendo o liability emissor. Fique atento aos parâmetros solicitados na documentação.
- Transações Wallets também podem ser contestadas caso possuam ECI (enviado no campo “sai”) de transação não segura. Observe os parâmetros enviados pelas Wallets e encaminhe-os em suas requisições do e.Rede para garantir que as bandeiras e emissores recebam as informações em sua totalidade.

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
| ------------------ | ------- | ------------ | :----------------------------------- |
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | 20 | Alfanumérico | Número identificador único da transação. |
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| dateTime| - | Alfanumérico | Data da transação no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| amount | Até 10 | Numérico | Valor total da transação sem separador de milhar e casa decimal. |\
| | | | |\
| | | | Exemplos:|\
| | | | - R$10,00 = 1000 |\
| | | | - R$0,50 = 50 |
| cardbin | 6 | Alfanumérico | 6 primeiros dígitos do cartão.|
| last4 | 4 | Alfanumérico | 4 últimos dígitos do cartão. |
| returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand | - | - | Grupo de informações recebidas da bandeira sobre a transação. |
| brand/name | - | Alfanumérico | Nome da bandeira. Ex: Mastercard. |
| brand/returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| brand/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand/merchantAdviceCode | Até 2 | Alfanumérico | Código de Aviso para Estabelecimento Comercial. É um conjunto de códigos usado para fornecer informações adicionais sobre uma resposta de transação de uso exclusivo da bandeira Mastercard. |
| brand/authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| brandTid | Até 21 | Alfanumérico | Correlaciona a primeira e demais transações através do envio deste campo. Para mais detalhes consulte a seção [Recorrência e Card-on-file](e-rede#documentacao-recorrencia) |
{.table-bordered}
:::

### Apple Pay{#documentacao-carteiras-digitais-apple-pay .menu-nv3}

Apple Pay é a carteira digital da Apple disponível nos aparelhos Apple tais como:

- iPhone (Modelos com Touch ID, Face ID, exceto 5s);
- Apple Watch (Apple Watch Series 1 e posterior);
- Mac (Modelos com Touch ID);
- iPad (iPad Pro, iPad Air, iPad e iPad mini com Touch ID ou Face ID).

O pagamento por meio da Apple Pay substitui os dados do cartão por um token de bandeira, tornando a transação mais segura.

Para oferecer Apple Pay para seus clientes, é preciso fazer a afiliação à Apple e ao Apple Pay ou possuir um parceiro integrado como PSP capaz de decriptar o payload da Wallet e depois enviar seguindo as instruções de integração com o e.Rede. Você encontra as informações detalhadas buscando por “Apple Pay” nas documentações de tecnologia do [Portal do Desenvolvedor Apple](https://developer.apple.com/apple-pay/){target="\_blank"}. Além disso, é imprescindível que seus compradores estejam acessando o site pelo browser Safari ou através do App em um dispositivo iOS compatível com o Apple Pay.

> Selecione o tipo "Carteiras digitais: Apple, Google, Samsung pay e Click to Pay" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

### Google Pay{#documentacao-carteiras-digitais-google-pay .menu-nv3}

O Google Pay é a carteira virtual do Google, disponível em diversos dispositivos Android. Permite que os consumidores realizem pagamentos, de forma prática e segura, com seus cartões de crédito e débito armazenados.

O pagamento por meio da Google Pay substitui os dados do cartão por um token de bandeira, tornando a transação mais segura.

Para realizar a integração é necessário que seu estabelecimento possua o cadastro e integração com a Google Pay ou possua um parceiro integrado como PSP capaz de decriptar o payload da Wallet e depois enviar seguindo as instruções de integração com o e.Rede.

Para o Google Pay, existem dois tipos de credenciais:

- Tokenizadas: Cartões salvos através do app do Emissor para a Carteira do Google, promovem liability shift e são armazenados na carteira.
- Convencionais: Cartões oriundos do processo de onboarding através do Google Autofill ou Google Settings/Account (pay.google.com). Esses cartões são Card on File e o Google Pay reconhece o dispositivo e o apresenta em toda e qualquer compra - não promovem liability shift. Nesse caso, é recomendado utilização de autenticação 3DS ou outros mecanismos de segurança da transação como anti-fraude.

  Para ambos, existem parâmetros na API Google que permitem identificar se a transação é proveniente de uma credencial tokenizada ou não - essa string é chamada na documentação da Google Pay como AssuranceDetails.

Para maiores detalhes da integração com a Google Pay acima consulte o [Portal do Desenvolvedor Google](https://developers.google.com/pay/api/web/overview/){target="\_blank"}.

> Selecione o tipo "Carteiras digitais: Apple, Google e Samsung pay" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

### Samsung Pay{#documentacao-carteiras-digitais-samsung-pay .menu-nv3}

O Samsung Pay é carteira digital da Samsung, disponível em aparelhos mais recentes, permite que você carregue seus cartões de crédito, débito, presente e de associação em seus dispositivos. Com ele é possível fazer pagamentos e autenticar a compra com sua impressão digital, PIN ou leitura de íris.

O pagamento por meio da Samsung Pay substitui os dados do cartão por um token de bandeira, que é um conjunto aleatório exclusivo de números a serem usados em cada nova transação, para que o número real do cartão nunca seja usado, tornando a transação mais segura.

Para realizar a integração é necessário que seu estabelecimento possua o cadastro e integração com a Samsung Pay ou possua um parceiro integrado como PSP capaz de decriptar o payload da Wallet e depois enviar seguindo as instruções de integração com o e.Rede. Para maiores detalhes da integração consulte o site da [Samsung Pay](https://www.samsung.com.br/services/pay/).{target="\_blank"}

> Selecione o tipo "Carteiras digitais: Apple, Google e Samsung pay" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

Os retornos das transações Wallets obedecem os de transações comuns no e.Rede, disponíveis em nosso portal do desenvolvedor. É importante estar atento a todos os possíveis [Retornos de integração](e-rede#documentacao-retornos-retornos-integracao).

Esteja atento também aos [Retornos fornecidos pelas bandeiras](e-rede#documentacao-retornos-retornos-bandeiras), também disponíveis em nosso portal do desenvolvedor e que podem indicar negativas por parte delas.

### Operadoras de carteira digital escalonada (SDWO - Staged Digital Wallet Operators){#documentacao-carteiras-digitais-operadoras-carteiras-digital-escalonada-SDWO .menu-nv3}

Carteira digital é uma solução eletrônica que permite o armazenamento de dados financeiros e de identidade de forma que os mesmos sejam usados com segurança e privacidade durante as operações financeiras.

Existem dois tipos de carteiras digitais escalonadas (Staged Digital Wallets Operators)

- Cash-in
  - A carteira é abastecida com fundos através de uma transação financeira utilizando o cartão cadastrado previamente em sua plataforma, para posterior utilização;
  - Carteiras de pedágio realizam apenas operações de cash-in, e devem utilizar corretamente os parâmetros indicados na tabela de relação de campos de Cash-in por bandeira.

> Selecione o tipo "Cash-in + Carteiras digitais" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

- Purchase
  - A carteira realiza uma transação financeira a um lojista parceiro ou transfere valores entre carteiras, utilizando o cartão cadastrado previamente em sua plataforma.

> Selecione o tipo "Purchase + Carteiras digitais" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

Para o correto funcionamento da integração do serviço de Carteiras digitais, além da integração inicial do fluxo transacional (Autorização) é necessário que algumas outras integrações às nossas API’s já tenham sido realizadas:

- [MCC Dinâmico (Merchant Category Code)](e-rede#documentacao-mcc-dinamico)
- [SoftDescriptor](e-rede#documentacao-softdescriptor)

O serviço de SDWO, pode ser utilizado em conjunto com os demais serviços disponíveis na Rede:

**O Serviço de Pagamento de Contas do Consumidor (CBPS)\***
(\*) Transações CBPS + Carteiras digitais são possíves nas bandeiras Mastercard e Amex.

> Selecione o tipo "CBPS + Carteiras digitais" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

O serviço de Carteiras digitais, pode ser utilizado nas bandeiras Elo, Mastercard, Visa e Amex.

Para a correta identificação de uma transação do tipo Carteiras digitais, há alguns campos que necessitam ser preenchidos no fluxo transacional de acordo com a modalidade, conforme as regras especificadas por bandeiras.

Confira abaixo a lista de campos existentes e seus respectivos formatos nas operações de Carteira Digital Escalonada. Na sequência será apresentado as regras esperadas para cada bandeira:

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
| -------------------------------------------------------- | ------- | ------------ | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| capture | - | Booleano | Não | Define se uma transação terá captura automática ou posterior. O não envio desse campo será considerado uma captura automática **(true)**. |
| kind | - | - | - | Tipo de transação a ser realizada. |\
| | | | | - Para transações de crédito, utilizar **credit** |\
| | | | | - Para transações de débito, utilizar **debit** |\
| | | | | |\
| | | | | O não envio desse campo será considerado crédito. |
| reference | Até 50 | Alfanumérico | Sim | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Não| Código do pedido gerado pelo estabelecimento. (Não aceita caracteres especiais) |
| amount | Até 10 | Numérico | Sim | Valor total da transação sem separador de milhar e casa decimal. |\
| | | | | |\
| | | | | Exemplos: |\
| | | | | - R$10,00 = 1000 |\
| | | | | - R$0,50 = 50 |
| installments | Até 2 | Numérico | Não | Número de parcelas em que uma transação será autorizada. |\
| | | | | |\
| | | | | De 2 a 12 |\
| | | | | |\
| | | | | O não envio desse campo será considerado à vista. |
| cardholderName | Até 30 | Alfanumérico | Não | Nome do portador impresso no cartão. |\
| | | | | |\
| | | | | Não enviar caracteres especiais. |
| cardNumber | Até 19 | Alfanumérico | Sim | Número do cartão. |
| expirationMonth | Até 2 | Numérico | Sim | Mês de vencimento do cartão. De 1 a 12. |
| expirationYear | 2 ou 4 | Numérico | Sim | Ano de vencimento do cartão. |\
| | | | | |\
| | | | | Exemplo: 2028 ou 28 |
| securityCode | Até 4 | Alfanumérico | Não | Código de segurança do cartão geralmente localizado no verso do cartão. |\
| | | | | |\
| | | | | O envio desse parâmetro garante maior possibilidade |
| softDescriptor | Até 18\* | Alfanumérico | Sim | Frase personalizada que será impressa na fatura do portador. Confira o padrão a ser seguido em cada operação com mais detalhes nas especificações na sequência. |
| subMerchant | | subMerchant | | |
| subMerchant/mcc | 4 | Numérico | Sim | MCC do sublojista. |
| wallet | | | | |
| wallet/walletId | Até 11 | Alfanumérico | Consulte regras por bandeira | Código-identificador de carteira, conhecido como WID (Wallet Identificator Number), que é o número de identificação das carteiras junto a cada uma das bandeiras. |
| wallet/processingType | 2 | Alfanumérico | Sim | Identificação de tipo de operação (01 para Purchase e 02 para Cash-in). |
| wallet/paymentDestination | 2 | Alfanumérico | Consulte regras por bandeira | Identifica o destino/finalidade do cash-in: |\
| | | | | - 04: M2M (Mesma titularidade, mesma carteira/arranjo) |\
| | | | | - 05: P2P (Para outra titularidade, mesma carteira/arranjo) |\
| | | | | - 06: Transferência para outro arranjo (mesma titularidade) |\
| | | | | - 07: Transferência para outro arranjo (outra titularidade) |\
| | | | | - 08: Transferência para carteira de armazenamento de valor |
| receiverData | | | | |
| receiverData/firstName | Até 40 | Alfanumérico | Consulte regras por bandeira | Primeiro nome do recebedor do cash-in. Não utilize caracteres especiais. |
| receiverData/lastName | Até 40 | Alfanumérico | Consulte regras por bandeira | Último nome do recebedor do cash-in. Não utilize caracteres especiais. |
| receiverData/taxIdNumber | Até 14 | Alfanumérico | Consulte regras por bandeira | CPF ou CNPJ do recebedor do cash-in. |
| senderData | | | | |
|senderData/taxIdNumber | Até 14| Alfanumérico | Consulte regras por bandeira |CPF ou CNPJ do pagador do cash-in.|
|senderData/firstName | Até 20| Alfanumérico | Consulte regras por bandeira |Primeiro nome do usuário pagador.|
|senderData/lastName | Até 20| Alfanumérico | Consulte regras por bandeira |Último nome do usuário pagador.|
|senderData/address | Até 35| Alfanumérico | Consulte regras por bandeira |Endereço do usuário pagador.|
|senderData/city | Até 25| Alfanumérico | Consulte regras por bandeira |Cidade do usuário pagador.|
|senderData/country | Até 3| Alfanumérico | Consulte regras por bandeira |País do usuário pagador|
| receiverData/walletAccountIdentification | Até 50 | Numérico | Consulte regras por bandeira | Identificador do usuário na carteira. |
| consumerBillPaymentService | | | | |
| consumerBillPaymentService/businessApplicationIdentifier | 2 | Numérico | Sim, se operação de pagamento de contas | Identificador de transações CBPS. Para esse tipo de transação este campo deve ser preenchido com "01". Quando não tivermos este tipo de transação, o campo não deve ser enviado. |
| consumerBillPaymentService/merchantTaxId | Até 14 | Alfanumérico | Não | Identificador do beneficiário final/ cedente do boleto. Deve ser informado CPF/CNPJ. |\
| | | | | |\
| | | | | Para a Mastercard, caso não seja indicado será considerado como boleto não identificado. |
{.table-bordered}
:::

**Parâmetros de resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
| ------------------------ | ------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | 20 | Alfanumérico | Número identificador único da transação. |
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorizationCode | 6 | Alfanumérico | Número de autorização da transação retornada pelo emissor do cartão. |
| dateTime | - | Data e hora | Dados da transação no formato YYYY-MM-DDhh:mm:ss.sTZD. |
| amount | Até 10 | Numérico | Valor total da transação sem separador de milhar e casa decimal. |
| cardbin | 6 | Alfanumérico | 6 primeiros dígitos do cartão. |
| last4 | 4 | Alfanumérico | 4 últimos dígitos do cartão. |
| brand | - | - | Grupo de informações recebidas da bandeira sobre a transação. |
| brand/name | - | Alfanumérico | Nome da bandeira. Ex: Mastercard |
| brand/returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| brand/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand/merchantAdviceCode | Até 2 | Alfanumérico | Código de Aviso para Estabelecimento Comercial. É um conjunto de códigos usados para fornecer informações adicionais sobre uma resposta de transação de uso exclusivo da bandeira Mastercard. |
| brand/authorizationCode | 6 | Alfanumérico | Número de autorização da transação retornada pelo emissor do cartão. |
| brand/brandTid | Até 21 | Alfanumérico | Código identificador da transação na respectiva bandeira. Para mais detalhes consulte a seção [Recorrência e Card-on-file](e-rede#documentacao-recorrencia) |
{.table-bordered}
:::

**Cash-in:**

**Observe abaixo a relação de campos obrigatórios para a operação de acordo com cada bandeira:**

::: table-scroll
| | Elo | Mastercard | Visa | Amex |
| ---------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| softDescriptor | Nome da Carteira\* TRANSFERENCIA | Nome da Carteira*Nome do titular da conta recebedora na Carteira | Nome da Carteira*Nome do titular da conta recebedora na Carteira | Nome da Carteira\*Nome do titular da conta recebedora na Carteira |
| submerchant | | | | Grupo submerchant |
| submerchant/mcc | - 6051 ou 6540: Cash-in de carteiras escalonadas (SDWO) | - 6540: Cash-in de carteiras escalonadas (SDWO) | - 6051: Cash-in de carteiras escalonadas (SDWO) |- 6051: Cash-in de carteiras escalonadas (SDWO) |\
| | - 4784: Cash-in de carteira de armazenamento de valor (SVDW) |- 4784*: Cash-in de carteira de armazenamento de valor (SVDW) | - 4784*: Cash-in de carteira de armazenamento de valor (SVDW) |  |\
||||- 4900: Cash-in para pagamento de boleto ||
| submerchant/address | Endereço da carteira | | | |
| submerchant/country | País da carteira | | | |
| submerchant/cep | CEP da carteira | | | |
| wallet | | | | Grupo wallet |
| wallet/processingType | 02 | 02 | 02 | 02 |
| wallet/walletId | 11 caracteres | 3 caracteres | 10 caracteres, caso o parâmetro tenha menos de 10 caracteres deve-se preencher a quantidade de zeros faltantes à direita. | Enviar os 8 primeiros dígitos do CNPJ da carteira |\
| | | | | |\
| | (Observar ao final das tabelas como obter) | (Observar ao final das tabelas como obter) | Ex: 3900370000 | |\
| | | | | |\
| | | | (Observar ao final das tabelas como obter) | |
| wallet/paymentDestination | - | Destino/finalidade do cash-in |- 08: Transferência para carteira de armazenamento de valor*- |- |\
| | | - 04: M2M (Mesma titularidade, mesma carteira/arranjo) | | |\
| | | - 05: P2P (Para outra titularidade, mesma carteira/arranjo) | | |\
| | | - 06: Transferência para outro arranjo (mesma titularidade) | | |\
| | | - 07: Transferência para outro arranjo (outra titularidade) | | |\
| | | - 08: Transferência para carteira de armazenamento de valor* | | |
| receiverData | | | | Grupo receiverData |
| receiverData/firstName | - | Primeiro nome do recebedor | - | - |
| receiverData/lastName | - | Último nome do recebedor | - | - |
| receiverData/taxIdNumber | Documento identificador do recebedor (CPF/CNPJ) | Documento identificador do recebedor (CPF/CNPJ) | Documento identificador do recebedor (CPF/CNPJ) | - |
| receiverData/walletAccountIdentification | - | Identificador do usuário na carteira | - | - |
| senderData | | | | |
| senderData/taxIdNumber | Documento identificador do pagador (CPF/CNPJ) | - | - | - |
| senderData/firstName | - | - | Primeiro nome do usuário pagador | - |
| senderData/lastName | - | - | Último nome do usuário pagador | - |
| senderData/address | - | - | Endereço do usuário pagador | - |
| senderData/city | - | - | Cidade do usuário pagador | - |
| senderData/country | - | - | País do usuário pagador | - |
{.table-bordered}
:::

**Atenção:**  O MCC 4784 e paymentDestination = 08 são de uso exclusivo para carteiras de pedágio, outras operações de carteiras digitais devem se restringir a usar o MCC 6051 ou 6540, conforme indicado acima.

**Purchase:**

**Observe abaixo a relação de campos obrigatórios para a operação de acordo com cada bandeira:**

::: table-scroll
| | Elo | Mastercard | Visa | Amex |
| --------------------- | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| softDescriptor | Nome Carteira*Nome do estabelecimento recebedor | Nome Carteira*Nome do estabelecimento recebedor | Nome Carteira*Nome do estabelecimento recebedor | Nome Carteira*Nome do estabelecimento recebedor |
| paymentFacilitatorID | Mesmo valor do campo wallet/walletId | | Mesmo valor do campo wallet/walletId | |
| submerchant | | | | Grupo submerchant |
| submerchant/mcc | MCC do estabelecimento | MCC do estabelecimento | MCC do estabelecimento | MCC do estabelecimento |
| submerchant/subMerchantID | Código do estabelecimento na carteira. | |  | |
| submerchant/address | Endereço do estabelecimento | |  | |
| submerchant/country | País do estabelecimento | |   | |
| submerchant/cep | CEP do estabelecimento | |  | |
| submerchant/taxIdNumber | CNPJ do estabelecimento | | CNPJ do estabelecimento | |
| submerchant/merchantTaxId  | Razão social do subestabelecimento	 | | Razão social do subestabelecimento  | |
| wallet | | | | Grupo wallet |
| wallet/processingType | 01 | 01 | 01 | 01 |
| wallet/walletId | 11 caracteres | 3 caracteres | 11 caracteres | Enviar os 8 primeiros números do CNPJ da carteira |\
| | | | | |\
| | (Observar ao final das tabelas como obter) | (Observar ao final das tabelas como obter) | | |\
| | | | | |\
| | | | (Observar ao final das tabelas como obter) | |
{.table-bordered}
:::

**CBPS/Pagamentos de Contas:**

**Observe abaixo a relação de campos obrigatórios para a operação de acordo com cada bandeira:**

::: table-scroll
| | Mastercard | Amex |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| softDescriptor | Nome Carteira*Nome do estabelecimento recebedor | Nome Carteira*Nome do estabelecimento recebedor |
| submerchant | | Grupo submerchant |
| submerchant/mcc | 6540 | Confira a lista de MCCs permitidos [aqui](https://developer.userede.com.br/files/erede/mccs_permitidos_sdwo_pagamento_de_contas.pdf) |
| consumerBillPaymentService | | Grupo consumerBillPaymentService |
| consumerBillPaymentService/businessApplicationIdentifier | 01 | 01 |
| consumerBillPaymentService/merchantTaxId | CNPJ cedente do boleto/beneficiário final. Se não enviado é considerado como Boleto não identificado | CNPJ do cedente do boleto/beneficiário final |
| wallet | | Grupo wallet |
| wallet/processingType | 01 | 01 |
| wallet/walletId | 3 caracteres | Enviar os 8 primeiros números do CNPJ da carteira |\
| | | | |\
| | Ex: 3900370000 | (Observar ao final das tabelas como obter) | |\
| | (Deve ser enviado apenas caso a operação seja CBPS + Carteira) | | |\
| | | | |\
| | (Observar ao final das tabelas como obter) | | |
{.table-bordered}
:::

**Atenção:**

- Para as bandeiras **Master e Visa**: a solicitação para geração do Wallet ID é feito pelo time de facilitadores Rede [facilitadores@userede.com.br](mailto:facilitadores@userede.com.br).
- Para a bandeira **Elo**: o cadastro deve ser feito diretamente pelo cliente através do e-mail [aceitacaofacilitadores@elo.com.br](mailto:aceitacaofacilitadores@elo.com.br).
- Para a bandeira **Amex**: não é feito cadastro de walletId no momento, por isso deve ser enviado os 8 primeiros números do CNPJ no campo walletId para identificação do estabelecimento. No futuro, caso a bandeira crie walletIds específicos, os clientes serão comunicados.

**Uso do “sai” em transações Cash-in:** O parâmetro deverá ser utilizado sempre que a transação possuir um ECI específico, que não esteja atrelado a autenticação 3DS (ex: Wallets e Cloud Token Visa), **quando autenticado como 3DS faz-se necessário que o “eci” seja informado dentro do grupo 3D Secure, não sendo necessária a utilização do “sai” neste caso.**

**Atenção:** Ao fazer o envio do grupo threeDSecure em qualquer requisição, o campo “sai” será ignorado e a prioridade será do fluxo de 3DS.

### Pix {#documentacao-pix .menu-nv2 .text-rede-orange}

É uma opção de pagamento, recebimento e transferência dentro dos aplicativos de carteiras digitais e de bancos - entre pessoas físicas ou jurídicas.

**Atenção: método de pagamento disponível apenas para correntistas Itaú.**

### Cadastro de chave Pix {#documentacao-pix-cadastro-chave-pix .menu-nv3}

Para habilitar sua chave Itaú para transacionar na Rede:

1. Acesse o portal [userede.com.br](https://www.userede.com.br/);
2. Efetue seu login;
3. Acesse a rota: Para vender > PIX > Clique em “quero utilizar o Pix” > Aceite de termos de uso > Selecione agência e conta.

Não esqueça de cadastrar sua URL para notificações!

Esteja atento para não excluir sua chave antes de finalizar operações nas suas transações, como pedir devoluções de QR Code pagos.

Para dúvidas sobre precificação, consulte a central de atendimento ou o valor negociado em sua conta no Itaú.

### Cadastro de URL {#documentacao-pix-cadastro-url .menu-nv3}

O estabelecimento deverá informar uma URL válida e segura para receber as notificações dos eventos. O cadastro dessa URL será por CNPJ, independente de quantos ou quais PV's foram habilitados para aquele estabelecimento.

Para esse cadastro, o estabelecimento deve ligar na central de atendimento nos telefones: Central de atendimento: Capitais e regiões metropolitanas 4001 4433 ou Central de atendimento: Demais localidades 0800 728 4433 e informar o número de CNPJ, PV, email para contato e a URL que deseja utilizar para receber as notificações do Pix. O prazo para ativação é de **2 dias uteis após a abertura do chamado**.

### Solicitação de QR Code Pix {#documentacao-pix-solicitacao-qr-code-pix .menu-nv3}

**Fluxo transacional**

Para detalhar o fluxo transacional, observe abaixo o fluxo de solicitação, pagamento e recepção de notificações de pagamentos de QR Code Pix:

![Fluxo transacional](assets/images/e-rede/fluxo-transacional-pix.png)

> Selecione o tipo "Pix" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|---------- | ------- | ------------ | ----------- | :----------------------------------------------------------------------------------- |
| kind | | Alfanumérico | Sim | Tipo de transação a ser realizada. Para transações de Pix, utilizar **Pix**. |
| reference | Até 50 | Alfanumérico | Sim | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Não | Código do pedido gerado pelo estabelecimento. (Não aceita caracteres especiais) |
| amount | Até 10 | Numérico | Sim | Valor total da transação sem separador de milhar e decimal. |\
||||||\
||||| Exemplos: R$10,00 = 1000 |
| qrCode | | | | Grupo QR Code |
| qrCode/dateTimeExpiration | | Data e hora | Sim | Dados da expiração do QR Code no formato YYYY-MM-DDThh:mm:ss. |\
||||||\
||||| O prazo máximo deve ser de até 15 dias e não deve ser de datas anteriores à atual. |
{.table-bordered}
:::

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|---------- | ------- | ------------ | :----------------------------------------------------------------------------------- |
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | Até 20 | Alfanumérico | Número identificador único da transação. |
| dateTime | | Data e hora | Data da solicitação do QR Code no formato YYYY-MM-DDThh:mm: ss.sTZD. |
| amount | Até 10 | Numérico | Valor total da transação sem separador de milhar e decimal. |\
||||||\
||||| Exemplos: R$10,00 = 1000 |
| qrCodeResponse | | | Grupo QR Code |
| qrCodeResponse/dateTimeExpiration | | Data e hora | Data de expiração do QR Code da transação no formato YYYY-MM-DDhh:mm:ss.sTZD. |
| qrCodeResponse/qrCodeImage | Até 999 | Alfanumérico | Campo com string do QRCode em base64. Para renderizar a imagem do QR Code, basta utilizar de bibliotecas ou scripts compatíveis com a sua linguagem de programação. |
| qrCodeResponse/qrCodeData | Até 999 | Alfanumérico | Campo com string do QRCode em formato emv (copia e cola). |
| returnCode | Até 04 | Alfanumérico | Código de retorno da Solicitação de QR Code. |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da Solicitação de QR Code.
{.table-bordered}
:::

### Notificação de atualização de status via webhook {#documentacao-pix-notificacao-atualizacao-status-via-webhook .menu-nv3}

Após a solicitação de um QR Code Pix, a cada atualização referente ao status do pagamento ou devolução (via canais Itaú), será retornada uma notificação na URL informada pelo estabelecimento.
O Estabelecimento deverá informar uma URL válida e segura, que deverá ser chamado pelo processo de pagamento de Pix para receber a notificação dos eventos (através de um método POST).
O cadastro dessa URL será por CNPJ, independente de quantos ou quais PV's foram habilitados para aquele estabelecimento.
Para solicitar o cadastro de sua URL entre em contato conosco através de nossos canais de atendimento e informe:

- CNPJ;
- PV;
- E-mail para contato;
- URL que deseja receber as notificações da Rede

O Cliente só poderá associar uma URL para cada CNPJ, sendo possível, excluir ou alterar o mesmo.

Os eventos possíveis são:

::: table-scroll
| Evento de notificação | Status correspondente |
|--------------------------- | --------------------------------------------------- |
| PV.UPDATE_TRANSACTION_PIX | Pago |
| PV.REFUND_PIX | Devolvido (parcial ou totalmente via canais Itaú) |
{.table-bordered}
:::

Para devolução solicitada via API, não haverá notificações, pois, a resposta de sucesso ou falha é dada de forma síncrona.

Para devoluções totais ou parciais feitas via outros canais Itaú como o bankline, você receberá uma notificação e poderá visualizar a relação de devoluções parciais nas APIs de consulta de transações e de consulta de cancelamentos do e.Rede.

Com o recebimento da notificação é opcional retornar à API de consulta do e.Rede com o TID para mais detalhes da transação. Recomendamos que aguarde no mínimo 10 min para realizar consultas após receber uma notificação.

**IMPORTANTE**: Caso o “endpoint/ URL” de notificações não seja informada, nenhum evento será notificado durante o processo de pagamento ou devolução das suas transações Pix.

Para validar como simular em ambiente de teste, consulte a seção [Simulação de notificação de status via webhook](e-rede#documentacao-pix-notificacao-atualizacao-status-via-webhook).

**Parâmetros da notificação – Pagamento PIX:**

::: table-scroll
| Nome | Local de envio | Tamanho | Tipo | Descrição |
|---------------- | -------------- | ------- | :----------------- | :----------------------------------------------------------------------------- |
| authorization | header | Até 3 | Alfanumérico | Header para autorização da requisição na url fornecida pelo estabelecimento – em momento de piloto solicitamos que seja enviado via e-mail caso deseje utilizar autenticação para envio das notificações (opcional) |
| request-ID  | header | Até 36 | Alfanumérico | Identificador único da requisição |
| content-Type | header | - | Alfanumérico | Valor fixo definido como 'application/json' |
| id | body | Até 36 | Alfanumérico | Identificador único da notificação |
| merchantId | body | 9 | Alfanumérico | Número de filiação do estabelecimento (PV) |
| events | body |  | Lista alfanumérica | Nome dos eventos que serão informados ao cliente. |\
|||||||\
||||| Exemplo: |\
||||| |\
||||| ["PV.UPDATE_TRANSACTION_PIX"], |
|||||

| data | body |  |  | Grupo de dados do pagamento PIX  |
| data/txId | body | Até 35 | Alfanumérico | ID de identificação do QR Code emitido  |
| data/id | body | Até 20 | Alfanumérico | Identificador da transação (TID)  |
| endToEndId | body | Até 32 | Alfanumérico | Id de identificação do pagamento do Pix |
{.table-bordered}
:::


**Formato do evento:**
::: {.block-code}

```json
{ 
    "id":"f526fd25-da12-4874-a24d-c926186301e9", 
    "merchantId":"90104480", 
    "events":[ 
      "PV.UPDATE_TRANSACTION_PIX" 
    ], 
    "data":{ 
      "txid":"RERO8044890090104480CV94HGTH46B6BD2", 
      "id":"40402508050758050105", 
      "endToEndId":"E0000000020241219172445877200001" 
    } 
}    
```

:::

**Parâmetros da notificação – Devolução PIX:**

::: table-scroll
| Nome | Local de envio | Tamanho | Tipo | Descrição |
|---------------- | -------------- | ------- | :----------------- | :----------------------------------------------------------------------------- |
| authorization | header | Até 3 | Alfanumérico | Header para autorização da requisição na url fornecida pelo estabelecimento – em momento de piloto solicitamos que seja enviado via e-mail caso deseje utilizar autenticação para envio das notificações (opcional) |
| request-ID | header | Até 36 | Alfanumérico | Identificador único da requisição |
| content-Type | header | -- | Alfanumérico | Valor fixo definido como 'application/json' |
| id | body | Até 36 | Alfanumérico | Identificador único da transação (TID) 
| merchantId  | body | 9 | Alfanumérico | Número de filiação do estabelecimento (PV) |
| companyNumber | body | 9 | Alfanumérico | Número de filiação do estabelecimento (PV) |
| events | body |  | Lista alfanumérica | Nome dos eventos que serão informados ao cliente. |\
||||||\
||||| Exemplo: |\
||||| |\
||||| ["PV.UPDATE_TRANSACTION_PIX"], |\
||||| |\
||||| [“PV.REFUND_PIX”] 
{.table-bordered}
:::

**Formato do evento:**
::: {.block-code}

```json
{ 
  "companyNumber": "90104480", 
  "events": ["PV.UPDATE_TRANSACTION_PIX"], 
  "data": { 
    "id": "41412312010933570004" 
  } 
}   
```

:::


### Consulta de transação Pix {#documentacao-pix-consulta-transacao-pix .menu-nv3}

Para transações Pix, a consulta segue o padrão do e.Rede, sendo possível de ser realizada através do TID e Reference (número do pedido).

**Atenção:** Os campos qrCodeData e qrCodeImage só serão retornados na consulta caso o status do QR Code seja **pendente**. Para QR Codes pagos ou devolvidos, estes campos **não serão retornados**.

Para o caso de QR Codes expirados, será devolvido o código 3036 - QrCode Expired.

**Parâmetros da resposta com QR Code Pix Pendente:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|---------------------------------- | ------- | ------------ | :----------------------------------------------------------------------------- |
| requestDateTime | -- | Datetime | Data da requisição no formato YYYY-MM-DDThh:mm:ss.sTZD. |
| qrCodeResponse | -- | -- | Grupo QR Code |
| qrCodeResponse/dateTime | -- | Datetime | Data da criação do QrCode da transação no formato YYYY-MM-DDhh: mm: ss.sTZD. |
| qrCodeResponse/returnCode | Até 04 | Alfanumérico | Código de retorno da Solicitação de QR Code. |
| qrCodeResponse/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da Solicitação de QR Code. |
| qrCodeResponse/affiliation | Até 9 | Numérico | Número de filiação do estabelecimento (PV). |
| qrCodeResponse/kind | Até 10 | Alfanumérico | Método de pagamento utilizado na transação (Pix). |
| qrCodeResponse/reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| qrCodeResponse/amount | Até 10 | Numérico | Valor total da transação sem separador de milhar e decimal. |
| qrCodeResponse/tid | Até 20 | Alfanumérico | Número identificador único da transação. |
| qrCodeResponse/status | -- | Alfanumérico | Status da transação: |\
|||||\
|||| - Approved |\
|||| - Canceled |\
|||| - Pending |
| qrCodeResponse/expirationQrCode | -- | Datetime | Data do pagamento do QR Code no formato YYYY-MM-DDThh:mm:ss.sTZD. |
| qrCodeResponse/qrCodeImage | Até 999 | Alfanumérico | Campo com string do QR Code em base64. Para renderizar a imagem do QR Code, basta utilizar de bibliotecas ou scripts compatíveis com a sua linguagem de programação. |
| qrCodeResponse/qrCodeData | Até 999 | Alfanumérico | Campo com string do QR Code em formato emv (copia e cola) |
{.table-bordered}
:::

**Parâmetros da resposta com QR Code Pix Pago**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|---------------------------------- | ------- | ------------ | :----------------------------------------------------------------------------- |
| requestDateTime | -- | Datetime | Data da requisição no formato YYYY-MM-DDThh:mm:ss.sTZD. |
| authorization/dateTime | -- | Datetime | Data da criação do QrCode da transação no formato YYYY-MM-DDhh: mm: ss.sTZD. |
| authorization/returnCode | Até 04 | Alfanumérico | Código de retorno da Solicitação de QR Code. |
| authorization/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da Solicitação de QR Code. |
| authorization/affiliation | Até 9 | Numérico | Número de filiação do estabelecimento (PV). |
| authorization/status | -- | Alfanumérico | Status da transação: |\
|||||\
|||| - Approved |\
|||| - Canceled |\
|||| - Pending |
| authorization/reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| authorization/orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| authorization/tid | Até 20 | Alfanumérico | Número identificador único da transação. |
| authorization/kind | Até 10 | Alfanumérico | Método de pagamento utilizado na transação (Pix). |
| authorization/amount | Até 10 | Numérico | Valor total da transação sem separador de milhar e decimal. |
| authorization/origin | Até 2 | Numérico | Identifica a origem da transação. |\
|||||\
|||| e.Rede: 1 |
| authorization/txid | Até 35 | Alfanumérico | Identificador único do Pix gerado pelo Itaú |\
|||||\
|||| Exibido apenas em transações com status Pago ou devolvido || authorization/orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| authorization/endToEndId | Até 32 | Alfanumérico | Id de identificação do pagamento do Pix. |
| capture/dateTime | -- | Datetime | Data do pagamento do QR Code no formato YYYY-MM-DDThh:mm:ss.sTZD. |
| capture/amount | Até 10 | Numérico | Valor do pagamento do QR Code. |
| refunds/refundId | 36 | Alfanumérico | Código de retorno da solicitação de cancelamento gerado pela Rede. |
| refunds/refundDateTime | -- | Datetime | Data da devolução no formato YYYY-MM-DDThh:mm:ss.sTZD. |
| refunds/status | Até 10 | Alfanumérico | |\
|||||\
|||| - Done (Devolução efetivada) |\
|||| - Denied (Devolução negada) |
| refunds/amount | Até 10 | Alfanumérico | Valor da devolução. |
{.table-bordered}
:::

**Status possíveis**

Ao consultar uma transação Pix, são possíveis os seguintes status:

::: table-scroll
| Status | Descrição |
| :--------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| Pending | Seu QR Code ainda não recebeu atualizações de pagamento. Confirme se o pagador já realizou o pagamento no banco de sua preferência. |
| Approved | Seu QR Code foi pago. |
| Canceled | Seu QR Code foi devolvido. |
{.table-bordered}
:::

**Nota:** Para transações parcialmente devolvidas, o status permanecerá como “Approved” até que o saldo total seja devolvido.

Para transações expiradas, será exibido o código 3036 – “QrCode: QR Code Expired”.

### Devolução de transação Pix {#documentacao-pix-devolucao-transacao-pix .menu-nv3}

Para transações Pix, a devolução segue a normativa definida pelo Banco Central do Brasil, sendo permitida em até 90 dias da data da venda.

Através do e.Rede será possível solicitar a devolução do **valor total e parcial**. A solicitação de devolução via API é síncrona, por isso fique atento aos códigos de retorno que confirmarão se seu pedido ocorreu com sucesso, eles estão disponíveis na seção [Códigos de Retorno](e-rede#documentacao-codigos-de-retorno).

O pedido de devolução via API pode ser realizado através do TID.

**Nota:** Para solicitações de devolução feitas via canais Itaú, como o bankline você receberá notificações no evento “PV.REFUND_PIX” (caso possua uma URL habilitada) e verá na consulta a lista de devoluções atreladas à sua transação Pix. Para melhor compreensão do fluxo feito via bankline, observe a ilustração abaixo:

![Fluxo Pix via bankline](assets/images/e-rede/fluxo-pix-via-bankline.png)

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|---------- | ------- | ------------ | ----------- | :----------------------------------------------------------------------------------- |
| amount | Até 10 | Numérico | Sim | Valor do cancelamento sem separador de milhar e casa decimal. |\
||||||\
||||| Exemplos: |\
||||| - R$10,00 = 1000 |\
||||| - R$0,50 = 50 |
{.table-bordered}
:::

**Parâmetros de resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|--------------- | ------- | ------------ | :----------------------------------------------------------------------------------- |
| refundDateTime | -- | Datetime | Data do cancelamento no formato YYYY-MM-DDThh:mm:ss.sTZD. |
| returnCode | Até 4 | Alfanumérico | Código de retorno da transação (vide tabela [códigos](e-rede#documentacao-retornos-retornos-cancelamento) de retorno para devolução). |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação (vide tabela [códigos](e-rede#documentacao-retornos-retornos-cancelamento) de retorno para devolução). |
{.table-bordered}
:::

### Consulta de devolução de transações Pix {#documentacao-pix-consulta-devolucao-transacoes-pix .menu-nv3}

Para transações Pix, a consulta de devolução/ cancelamento é possível através do TID ou refundId.

**Consulta de devolução por TID**

**Parâmetros de resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|------------------------- | ------- | ------------ | :----------------------------------------------------------------------------- |
| refunds/refundId | 36 | Alfanumérico | Código de retorno da solicitação de cancelamento gerado pela Rede. |
| refunds/refundDateTime | -- | Datetime | Data da devolução no formato YYYY-MM-DDThh:mm:ss.sTZD. |
| refunds/status | Até 10 | Alfanumérico | |\
|||||\
|||| - Done (Devolução efetivada) |\
|||| - Denied (Devolução negada) |
| refunds/amount | Até 10 | Alfanumérico | Valor da devolução. |
{.table-bordered}
:::

**Consulta de devolução por refundID**

**Parâmetros de resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|--------------- | ------- | ------------ | :----------------------------------------------------------------------------------- |
| refundId | 36 | Alfanumérico | Código de retorno da solicitação de cancelamento gerado pela Rede. |
| Tid | 20 | Alfanumérico | Número identificador único da transação. |
| refundDateTime | -- | Datetime | Data da devolução no formato YYYY-MM-DDThh:mm:ss.sTZD. |
| status | Até 10 | Alfanumérico | |\
|||||\
|||| - Done (Devolução efetivada) |\
|||| - Denied (Devolução negada) |
| amount | Até 10 | Alfanumérico | Valor da devolução. |
{.table-bordered}
:::

### Códigos de retorno {#documentacao-pix-codigos-de-retorno-pix .menu-nv3}

[Os códigos e mensagens de retorno](e-rede#documentacao-retornos-retornos-integracao) podem ocorrer nos cenários de **solicitação, consulta ou devolução de um QR Code Pix**.

Esteja atento às orientações de cada um dos processos para adequar sua integração.

**Solicitação de QR Code Pix:** Momento da requisição de QR Code.

### Voucher {#documentacao-voucher .menu-nv2}

O Voucher é um novo produto que está habilitado para integrar em um só cartão benefícios de refeição, alimentação, cultura, transporte e as demais opções flexíveis como auxílio home office, educação, saúde e bem-estar.

O pagamento com o cartão Voucher será capturado em um trilho exclusivo, dando mais facilidade à operação. Este produto é aderente aos novos termos das regras do Programa de Alimentação ao Trabalhador (PAT).

**Benefícios do Voucher:**

Empresas de arranjo fechado poderão emitir cartões bandeirados, fazendo com que estabelecimentos possam processar o modelo fechado através do ecossistema de bandeira, reduzindo a necessidade de integrações com arranjo fechados, e centralizando os recebíveis.

Transacionar com Voucher

Para garantir que sua transação com o produto Voucher seja processada corretamente, é necessário que seu estabelecimento esteja classificado nos MCCs (Merchant Category Codes) elegíveis.

**Importante:** Caso seu MCC não esteja listado, não será possível processar a transação com o Voucher na atividade principal.

**Credenciamento elegível ao MCC:** Para solicitar o credenciamento do e.Rede e realizar a integração à sua aplicação, entre em contato com a Central de Atendimento da Rede:

- 4001 4433 (capitais e regiões metropolitanas)
- 0800 728 4433 (demais localidades)

Quando o credenciamento for realizado, o responsável pelo estabelecimento será notificado via e-mail com o número de filiação (PV), orientações para acessar o portal da Rede e suas credenciais para integração.

**Ponto de atenção:** Se o ramo do seu estabelecimento não for elegível, é necessário que o estabelecimento inclua no seu CNAE (Classificação Nacional das Atividades Econômicas) a atividade compatível com o programa para comercializar.

::: table-scroll
| **RAMO** | **MCC** |
|-------------------------------------------------------------|-----------------------------------------------------------------|
| Alimentação | 5300, 5411, 5422, 5441, 5451, 5462, 5499, 5811 |
| Refeição | 5812, 5813, 5814 |
| Cultura | 4722, 5311, 5733, 5735, 5815, 5932, 5942, 5943, 5994, 7832, 7841, 9399, 8699, 7998, 7996, 7991, 7929, 7922, 7911 |
{.table-bordered}
:::

Lembrando que o MCC é um código numérico de quatro dígitos utilizado para classificar o tipo de bens ou serviços que o seu estabelecimento oferece.

Em caso de dúvida, consultar o nosso portal : [https://developer.userede.com.br/e-rede#documentacao-mcc-dinamico](https://developer.userede.com.br/e-rede#documentacao-mcc-dinamico)

**Para voucher existem dois tipos de arranjos de pagamentos, são eles:**

**Arranjo aberto:**

Consiste em um conjunto de normas e procedimentos que permitem a utilização de um meio de pagamento em qualquer estabelecimento comercial incluindo e-commerce. No caso dos cartões, a emissão é realizada por um emissor associado a uma bandeira específica, como a Elo, Visa ou Mastercard.

**Arranjo fechado:**

Consiste em um cartão que é emitido por uma empresa (por exemplo, supermercados ou outras grandes lojas de varejo) e o cliente pagador só poderá usá-lo no estabelecimento que emitiu ou em empresas parceiras.

Empresas como Pluxee, Ticket, Alelo, Sodexo, entre outras, fazem parte do arranjo fechado. Conhecido como modelo VAN.

++**Para maiores informações sobre arranjo fechado, procure o atendimento Rede.**++

++Para maiores informações sobre o fluxo transacional verifique na Lista de APIs, conforme indicado a seguir:++

> Selecione o tipo "Voucher" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

### Solicitação de transação voucher {#documentacao-voucher-solicitacao-transacao-voucher .menu-nv3}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|---------------- | -------- | ------------ | ----------- | :----------------------------------------------------------------------------------- |
| capture | -- | Booleano | Sim | Defina se a transação terá captura automática ou posterior. O não envio desse campo será considerado a captura automática (true). Para transações voucher dever ser enviado como TRUE. |
| kind | -- | Alfanumérico | Sim | **voucher** Tipo de transação a ser realizada. |
| reference | Até 50 | Alfanumérico | Sim | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Não| Código do pedido gerado pelo estabelecimento. (Não aceita caracteres especiais) |
| amount | Até 10 | Numérico | Sim | Valor total da transação sem separador de milhar e decimal. |
| cardholderName | Até 30 | Alfanumérico | Não | Nome do portador impresso no cartão. |\
||||| |\
||||| Não enviar caracteres especiais. |
| cardNumber | Até 19 | Alfanumérico | Sim | Número do cartão |
| expirationMonth | Até 02 | Numérico | Sim | Mês de vencimento do cartão. De 1 a 12. |
| expirationYear | 02 ou 04 | Numérico | Sim | expirationYear 2 ou 4 Numerico Sim Ano de vencimento do cartão. |\
||||| |\
||||| Ex .: 2028 ou 28. |
| securityCode | Até 04 | Alfanumérico | Não | Código de segurança do cartão geralmente localizado no verso do cartão. |\
||||| |\
||||| O envio desse parâmetro garante maior possibilidade de aprovação da transação. |
| softDescriptor | Até 18\* | Alfanumérico | Não | Frase personalizada que será impressa na fatura do portador. |
| storageCard | Até 01 | Alfanumérico | Não | indica operações que possam ou não estar utilizando COF (Card on File): |\
||||| |\
||||| 0 - Transação com credencial não armazenada |\
||||| |\
||||| 1 - Transação com credencial armazenada pela primeira vez. |\
||||| |\
||||| 2 - Transação com credencial já armazenada. |\
||||| |\
||||| Atenção: O não envio desse campo será considerado 0 (credencial não armazenada). |
{.table-bordered}
:::

**Parâmetros de resposta:**

**Parâmetro de Resposta Arranjo Aberto**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|-------------------------------------- | ------- | ------------ | :------------------------------------------------------------------------|
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | Até 20 | Alfanumérico | Número identificador único da transação. |
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| dateTime | -- | Data e hora | Dados da solicitação do QR Code no formato YYYY-MM-DDhh:mm:ss.sTZD. |
| amount | Até 10 | Numérico | Valor total da transação sem separador de milhar e decimal. |
| cardBin | 6 | Alfanumérico | 6 primeiros dígitos do cartão. |
| last4 | 4 | Alfanumérico | 4 últimos dígitos do cartão. |
| brand | -- | -- | Grupo de informações recebidas da bandeira sobre a transação |
| brand/name | -- | -- | Nome da bandeira. Ex.: Elo |
| brand/returnCode | Até 04 | Alfanumérico | Código de retorno da transação. |
| brand/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand/authorizationCode | 06 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| brand/brandTid | Até 21 | Alfanumérico | Código identificador da transação na respectiva bandeira. Para mais detalhes consulte a seção Recorrência e Card-on-file |
| brand/voucher | -- | -- | Grupo de informações recebidas da bandeira sobre a transação **voucher**.|
| brand/voucher/voucherRemainingBalance | Até 10 | Numérico | Saldo disponível no voucher, no momento da transação. |
{.table-bordered}
:::

**Parâmetro de Resposta Arranjo Fechado**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|-------------------------------------- | ------- | ------------ | :----------------------------------------------------------------------- |
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | Até 20 | Alfanumérico | Número identificador único da transação. |
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| dateTime | -- | Data e hora | Dados da solicitação do QR Code no formato YYYY-MM-DDhh:mm:ss.sTZD. |
| amount | Até 10 | Numérico | Valor total da transação sem separador de milhar e decimal. |
| cardBin | 06 | Alfanumérico | 6 primeiros dígitos do cartão. |
| last4 | 04 | Alfanumérico | 4 últimos dígitos do cartão. |
| brand | -- | -- | Grupo de informações recebidas da bandeira sobre a transação. |
| brand/name | -- | -- | Nome da bandeira. Ex.: Elo |
| brand/returnCode | Até 04 | Alfanumérico | Código de retorno da transação. |
| brand/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand/authorizationCode | 06 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| brand/brandTid | Até 21 | Alfanumérico | Código identificador da transação na respectiva bandeira. Para mais detalhes consulte a seção Recorrência e Card-on-file |
| brand/voucher | -- | -- | Grupo de informações recebidas da bandeira sobre a transação **voucher**.|
| brand/voucher/voucherIssuer | -- | -- | Nome do emissor. Ex.: Ticket |
| brand/voucher/voucherIssuerTaxId | Até 14 | Alfanumérico | Código CNPJ |
| brand/voucher/voucherRemainingBalance | Até 10 | Numérico | Saldo disponível no voucher, no momento da transação. |
{.table-bordered}
:::

### Códigos de retorno {#documentacao-voucher-codigos-de-retorno-voucher .menu-nv3}

[Os códigos e mensagens de retorno](e-rede#documentacao-retornos-retornos-integracao) podem ocorrer nos cenários de **solicitação, consulta ou devolução de uma Transação Pix**.

Esteja atento às orientações de cada um dos processos para adequar sua integração.

**Solicitação de Transação Pix:** Momento da requisição de Voucher.

### Retornos{#documentacao-retornos .menu-nv2 .text-rede-orange}

Para melhor experiência na visualização da negativa, a Rede possui campos que exibem a justificativa completa do motivo de negativa da bandeira:

- Grupo Brand (padrão ABECS);

**Importante:** A utilização do grupo Brand é obrigatória, pois fornece informações reais sobre o motivo de negativa.

Outro caso possível é a utilização do antigo encapsulado Rede, vide [retornos de emissor](e-rede#documentacao-retornos-retornos-emissor):

- Return code – fora do grupo Brand (encapsulado Rede);
- Return message – fora do grupo Brand (encapsulado Rede);

**Importante:** A utilização do antigo encapsulado Rede não é recomendada pois não fornece informações concretas sobre o motivo de negativa, em breve deixará de ser utilizado.

### Retornos da bandeira{#documentacao-retornos-retornos-bandeiras .menu-nv3}

A partir do dia 15 de julho de 2020 passamos a oferecer aos nossos clientes a opção do recebimento dos códigos da bandeira abertos, enviados pelos bancos, dependendo do motivo de negada da transação.

Junto com essa opção, passamos a atender a normativa 21 da Abecs que padroniza as mensagens em relação as essas transações negadas no processo de autorização.

O objetivo é proporcionar maior transparência e padronização, buscando aumentar a taxa de aprovação.

Além do retorno padronizado para as principais bandeiras (ELO, Visa, Master/Hiper e Amex) será possível, através da tabela abaixo, verificar se aquela recusa é reversível ou irreversível. Muito importante para o processo de retentativas. Por isso, fique atento aos códigos retornados.

Para as demais bandeiras, as mensagens de transação negada permanecem as mesmas atuais, no entanto, com os códigos abertos.

Vale acrescentar que para passar a ter acesso aos códigos de retorno abertos com a padronização da mensagem, é preciso um pequeno ajuste na sua API, segue abaixo procedimento de ativação.

Caso você não realize esse ajuste, os retornos atuais continuam no padrão Rede, sem qualquer mudança ou impacto.

**Ativação:**

Para habilitar mais essa funcionalidade e passar a receber as mensagens padronizadas pela normativa da Abecs e demais retornos da bandeira com os códigos abertos, basta realizar o ajuste no campo custom header, **“Transaction-Response”**, com o valor **“brand-return-opened”** preenchido, isso vale tanto para a transação quanto na consulta.

::: table-scroll
| Header | Valor |
|--------------------- | ------------------- |
| Transaction-Response | brand-return-opened |
{.table-bordered}
:::

Dessa forma, o response em caso de transação aprovada, passa a retornar o objeto **“Brand”** com os campos da bandeira, **"authorizationCode"** e **"brandTid"**, e adicionalmente **"Name"**, **"returnCode"** e **"returnMessage"**. Em caso de transação negada, no objeto **“Brand”** teremos apenas os campos **"Name"**, **"returnCode"** e **"returnMessage"**.

Caso o header **"Transaction-Response"** com o valor **"brand-return-opened"** não seja enviado na transação, pode ser enviado normalmente na consulta e a informação da bandeira (Brand) será retornada.

Os campos returnCode e returnMessage de fora do “Brand”, que são os que conhecemos hoje, passam a ter somente os códigos de retorno de transações negadas na Rede, novamente.

**Tabela de códigos de retorno da bandeira e padronização da mensagem:**{#retornos-bandeiras}

::: table-scroll
| Motivo | ELO | Visa | Master/Hiper | Amex | Mensagem | Mensagem E-commerce |
| ------- | -------------- | -------------- | -------------- | ---------------- | ------------------------------------------------------- | --------------------- |
| Genérica | 5 – reversível | 5 - reversível | 5 - reversível | 100 - reversível | Contate a central do seu cartão Please contact issuer | Please contact issuer |
| Saldo \| Limite insuficiente | 51 – reversível | 51 - reversível | 51 - reversível | 116 - reversível | Não autorizada | Refused |
| Senha inválida | 55 - reversível | 55 - reversível | 55 - reversível | 117 - reversível | Senha inválida | Invalid pin |\
| | | | | | | |\
| | | 86 - reversível | 86 - reversível | | | |
| Transação não permitida para o cartão | 57 - irreversível | 57 - irreversível | 57 - reversível | 200 - irreversível | **Visa e Elo:** Transação não permitida para o cartão - não tente novamente | Visa e Elo: Transaction not permitted to cardholder. Do not retry. Amex: Unauthorized transaction. Do not try again Mastercard: Transaction not permitted to cardholder |\
| | | | | | | |\
| | | | | | **Mastercard:** Não permitida para o cartão | |
| Nº cartão não pertence ao emissor \| Nº cartão inválido | -14 - irreversível | 14- irreversível | 14- irreversível | 122 - irreversível | Verifique os dados do cartão | Format error. Verify card data Visa: Invalid card. Do not retry |\
| | | | | | | |\
| | 56 - irreversível | | 1 - irreversível | | | |
| Violação de segurança \| Inválido ou não presente | 63 - irreversível | N7 - irreversível | 63 - reversível| 122 - irreversível | Verifique os dados do cartão | Format error. Verify card dataVisa:invalid card. Do not retry |
| Suspeita de fraude \| Aviso de viagem | 59 - reversível | 59 - reversível | 63 - reversível | 100 - reversível | Contate a central do seu cartão | Please contact issuer |
| Comerciante inválido | 58 - irreversível | 3 - irreversível | 3 - irreversível | 109 - irreversível | Transação não permitida - não tente novamente | Unauthorized transaction. Do not try again |
| Refazer a transação (emissor solicita retentativa) | 4 - reversível | Sem código correspondente | Sem código correspondente | Sem código correspondente | Refazer a transação | Please, retry this transaction. |
| Consultar credenciador| 6 - reversível | Sem código correspondente | Sem código correspondente | Sem código correspondente | Lojista, contate o adquirente | Contact card issuer |
| Problema no adquirente | 19 - irreversível | 19 - irreversível | 30 - irreversível | Sem código correspondente | Erro no cartão – não tente novamente | Invalid card. Do not retry |
| Erro no cartão | 12 - irreversível | 6 - irreversível | Sem código correspondente | 115 - irreversível | Verifique os dados do cartão | Format error. Verify card dataVisa: invalid card. Do not retryAmex: function not supported. Do not retry |
| Erro de formato (mensageria) | 30 - irreversível | 12 - irreversível | 30 - irreversível | 181 - irreversível | Erro no cartão – não tente novamente | Invalid card. Do not retry |
| Valor da transação inválida | 13 - irreversível | 13 - irreversível | 13 - irreversível | 110 - irreversível | Valor da transação não permitido - não tente novamente | Transaction amount no permited. Do not retry |
| Valor da parcela inválida | 23 - irreversível | Sem código correspondente | 12 - irreversível | 115 - irreversível | Parcelamento inválido - não tente novamente | Function not supported. Do not retry |
| Excedidas tentativas de senha \| Compras | 38 - reversível | 75 - reversível | 75 - reversível | 106 - reversível | Excedidas tentativas de senha.contate a central do seu cartão | Invalid pin. Contact card issuer |
| Cartão perdido | 41 - irreversível | 41 - irreversível | 41 - irreversível | 200 - irreversível | Transação não permitida - não tente novamente | Unauthorized transaction. Do not try again |
| Cartão roubado | 43 - irreversível | 43 - irreversível | 43 - irreversível | 200 - irreversível | Transação não permitida - não tente novamente | Unauthorized transaction. Do not try again |
| Cartão vencido \| Dt expiração inválida | 54 - irreversível | 54 - irreversível | 54 - irreversível | 101 - irreversível | Verifique os dados do cartão | Format error. Verify card dataVisa: invalid card. Do not retry |
| Transação não permitida \| Capacidade do terminal | 57 - irreversível | 58 - irreversível | 58 - irreversível | 116 - irreversível | Transação não permitida para o cartão - não tente novamente | Transaction not permitted to cardholder. Do not retryAmex: refused |
| Valor excesso \| Saque | 61 - reversível | 61 - reversível | 61 - reversível | Sem código correspondente | Valor excedido. Contate a central do seu cartão | Transaction amount no permited. Contact card issuer |\
| | | | | | | |\
| | | n4 - reversível | | | | |
| Bloqueio Temporário (ex: Inadimplência) | 62 - reversível | 62 - reversível | 57 - reversível | Sem código correspondente | Contate a central do seu cartão | Contact card issuer |
| Valor mínimo da transação inválido | 64 - irreversível | Sem código correspondente | 13 - irreversível | Sem código correspondente | Valor da transação não permitido - não tente novamente | Transaction amount no permited. Do not retry |
| Quant. de saques excedido | 65 - reversível | 65 - reversível | 65 - reversível | Sem código correspondente | Quantidade de saques excedida.contate a central do seu cartão| Exceeds withdrawal limit. Contact card issuer |
| Senha vencida \| Erro de criptografia de senha | 83 - irreversível | 74 - irreversível | 88 - irreversível | 180 - irreversível | Senha inválida - não tente novamente | Invalid pin. Contact card issuer |\
| | | | | | | |\
| | | 81 - irreversível | | | | |
| Excedidas tentativas de senha \| Saque | 75 - reversível | 75 - reversível | 75 - reversível | 106 - reversível | Excedidas tentativas de senha.contate a central do seu cartão | Invalid pin. Contact card issuer |
| Conta destino inválida ou inexistente | 76 - irreversível | Sem código correspondente | Sem código correspondente | Sem código correspondente | Conta destino inválida - não tente novamente | Format error. Do not try again (invalid account) |
| Conta origem inválida ou inexistente | 77 - irreversível | Sem código correspondente | Sem código correspondente | Sem código correspondente | Conta origem inválida - não tente novamente | Format error. Do not try again (invalid account) |
| Cartão novo sem desbloqueio \| Inclui cartão bloqueado pelo cliente no aplicativo (ecom, nfc) | 78 - reversível | 78 - reversível | 57 - reversível | Sem código correspondente | Desbloqueie o cartão | Card not initialized |
| Cartão inválido (criptograma) | 82 - irreversível | 82 - irreversível | 88 - irreversível | 180 - irreversível | Erro no cartão – não tente novamente | Invalid card. Do not retryMaster/Hiper: invalid pin. Contact card issuerAmex: invalid pin. Contact card issuer |
| Emissor fora do ar | 91 - reversível | 91 - reversível | 91 - reversível | 912 - reversível | Falha de comunicação - tente mais tarde | Error. Retry transaction |
| Falha do sistema | 96 - reversível | 96 - reversível | 96 - reversível | 911 - reversível | Falha de comunicação - tente mais tarde | Error. Retry transaction |
| Diferença - pré autorização | Sem código correspondente | N8 - irreversível | Sem código correspondente | Sem código correspondente | Valor diferente da pré autorização - não tente novamente | Format error. Do not retry (authorization amount differs |
| Função incorreta (débito) | Ab - Reversível | 52 - Reversível | Sem código correspondent | Sem código correspondent | Utilize função crédito | Not supported. Submit transaction as credit |\
| | | | | | | |\
| | | 53 - Reversível | | | | |
| Função incorreta (crédito) | Ac - Reversível | 39 - Reversível | Sem código correspondente | Sem código correspondente | Utilize função débito | Not supported. Submit transaction as debit |
| Função incorreta (voucher) | AV - reversível | Sem código correspondente | Sem código correspondente | Sem código correspondente | Utilize função voucher | Not supported. Submit transaction as voucher. |
| Troca de senha \| Desbloqueio | P5 - irreversível | Sem código correspondente | Sem código correspondente | Sem código correspondente | Senha inválida - não tente novamente | Invalid pin. Contact card issuer |
| Nova senha não aceita | P6 - reversível | Sem código correspondente | 55 - Reversível | Sem código correspondente | Senha inválida utilize a nova senha | Invalid pin. Contact card issuer |
| Recolher cartão | Sem código correspondente | 4 - irreversível | 4 - irreversível | Sem código correspondente | Contate a central do seu cartão - não tente novamente | Contact card issuer. Do not retry |
| Erro por mudança de chave dinâmica | Sem código correspondente | N7 - irreversível | Sem código correspondente | Sem código correspondente | Erro no cartão – não tente novamente | Invalid card. Do not retry |
| Fraude confirmada | 57 - irreversível | 7 - irreversível | 4 - irreversível | 200 - irreversível | Transação não permitida para o cartão - não tente novamente | Transaction not permitted to cardholder. Do not retryAmex:unauthorized transaction. Do not try again |
| Emissor não localizado - bin incorreto (negativa do adquirente) | Sem código correspondente | 15 - irreversível | 15 - irreversível | Sem código correspondente | Dados do cartão inválido - não tente novamente | Invalid card number. Do not retry |
| Não cumprimento pelas leis de ante lavagem de dinheiro | Sem código correspondente | 64 - irreversível | Sem código correspondente | Sem código correspondente | Contate a central do seu cartão - não tente novamente | Contact card issuer. Do not retry |
| Reversão inválida | Sem código correspondente | 76 - irreversível | Sem código correspondente | Sem código correspondente | Contate a central do seu cartão - não tente novamente | Contact card issuer. Do not retry |
| Não localizado pelo roteador | Sem código correspondente | 92 - irreversível| 92 - irreversível | Sem código correspondente | Contate a central do seu cartão - não tente novamente | Contact card issuer. Do not retry |
| Transação negada por infração de lei | 57 - irreversível | 93 - irreversível | 62 - irreversível | Sem código correspondente | Transação não permitida para o cartão - não tente novamente | Transaction not permitted to cardholder. Do not retry |
| Valor do tracing data duplicado | Sem código correspondente | 94 - irreversível | 94 - irreversível | Sem código correspondente | Contate a central do seu cartão -não tente novamente | Contact card issuer. Do not retry |
| Surcharge não suportado | Sem código correspondente | B1 - reversível | Sem código correspondente | Sem código correspondente | Contate a central do seu cartão | Please contact issuer |
| Surcharge não suportado pela rede de débito | Sem código correspondente | B2 - reversível | Sem código correspondente | Sem código correspondente | Contate a central do seu cartão | Please contact issuer |
| Forçar stip | Sem código correspondente | N0 - reversível | Sem código correspondente | Sem código correspondente | Contate a central do seu cartão | Please contact issuer |
| Saque não disponível | Sem código correspondente | N3 - irreversível | Sem código correspondente | Sem código correspondente | Saque não disponível - não tente novamente | Withdrawal not permited. Do no retry |
| Suspensão de pagamento recorrente para um serviço | Sem código correspondente | R0 - irreversível | Sem código correspondente | Sem código correspondente | Suspensão de pagamento recorrente para serviço - não tente novamente | Recurring payment not permited. Do not retry |
| Suspensão de pagamento recorrente para todos serviço | Sem código correspondente | R1 - irreversível | Sem código correspondente | Sem código correspondente | Suspensão de pagamento recorrente para serviço - não tente novamente | Recurring payment not permited. Do not retry |
| Transação não qualificada para visa pin | Sem código correspondente | R2 - irreversível | Sem código correspondente | Sem código correspondente | Transação não permitida para o cartão - não tente novamente | Transaction not permitted to cardholder. Do not retry |
| Suspensão de todas as ordens de autorização | Sem código correspondente | R3 - irreversível | Sem código correspondente | Sem código correspondente | Suspensão de pagamento recorrente para serviço - não tente novamente | Recurring payment not permited. Do not retry |
| Conta encerrada | 46- Irreversível | 46- Irreversível | 62-irreversível | Sem código correspondente | Transação não permitida para o cartão - não tente novamente | Transaction not permitted to cardholder. Do not retry |
| Falha validação de id | Sem código correspondente | 6P- Irreversível | Sem código correspondente | Sem código correspondente | Falha na verificação do id | Id validation failure |
| Utilizar o chip | FM- irreversível | Sem código correspondente | Sem código correspondente | Sem código correspondente | Utilize o chip | Use the chip |
| Segurança \| Fraude | 79 - Irreversível (consultar MAC) | Sem código correspondente | Sem código correspondente | Sem código correspondente | Transação não autorizada | Unauthorized transaction |
{.table-bordered}
:::

**Outros Retornos**

Os retornos abaixo são de uso exclusivo das bandeiras e não estão na dentro da Normativa 21 ABECS, mas podem ocorrer em casos que o emissor/bandeira aplicar.

::: table-scroll
| Bandeira | Código | Mensagem | Mensagem e-commerce |
|----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| Mastercard | 1 | Consultar o emissor do cartão | Please contact issuer |
| Mastercard | 70 | Entrar em contato com o emissor | Please contact issuer |
| Mastercard | 72 | Conta não ativada | Unauthorized. Please try again |
| Mastercard | 76 | “Para Conta” especificado Inválido/inexistente | Invalid account. Do not try again |
| Mastercard | 77 | “Da Conta” especificado Inválido/inexistente | Invalid account. Do not try again |
| Mastercard | 78 | Conta especificada inválida/ inexistente (geral) | Invalid account. Do not try again |
| Mastercard | 84 | Ciclo de Vida da Autorização Inválida | Invalid Authorization Lifecycle |
| Mastercard | 89 | Senha Inaceitável — Transação Recusada — Tente Novamente | Invalid PIN. Try again |
| Visa | 1 | Consulte emissor do cartão | Please contact issuer |
| Visa | 2 | Consulte emissor do cartão - condição especial | Please contact issuer |
| Visa | 60 | Falha na verificação [a identificação do titular do cartão não corresponde aos registros do emissor]" | Please contact issuer |
| Visa | 62 | Função não suportada. Não tente novamente. | Function not supported. Do not retry (domestic transaction only) |
| Visa | 70 | Senha requerida | PIN data required |
| Visa | 80 | Sem impacto financeiro | No financial impact |
| Visa | 83 | Fraude ou restrição de segurança identificada  | Fraud/Security |
| Visa | 85 | Não há motivo para recusar uma solicitação de verificação de endereço, verificação de CVV2 ou comprovante de crédito ou devolução de mercadoria | Please contact issuer |
| Visa | 1A | Autenticação adicional do cliente necessária | Unauthorized transaction, try again |
| Visa | P5 | Desbloqueio de PIN negado - alteração de PIN ou solicitação de desbloqueio recusada pelo emissor | Invalid PIN. Do not retry |
| Visa | P6 | Alteração de PIN negada - PIN solicitado inseguro | Invalid PIN. Do not retry |
| Visa | 5C | Transação não suportada/bloqueada pelo emissor | Unauthorized transaction, try again |
| Visa | 9G | Bloqueado pelo portador/entre em contato com o portador | Unauthorized transaction, try again |
| Elo | 15  | EntreEmissor não localizado - BIN incorreto | Unauthorized transaction. Do not try again  |
| Elo | 66  | Não cumprimento pelas leis de anti lavagem de dinheiro | Unauthorized transaction. Do not try again  |
| Elo | 73  | Saque não disponível | Unauthorized transaction. Do not try again  |
| Elo | 80  | Reversão inválida | Unauthorized transaction. Do not try again  |
| Elo | 81 | Bloqueio de função - portador | Unauthorized. Please contact the Card Issuer. |
| Elo | 93 | Transação negada por infração de lei  | Unauthorized transaction. Do not try again |
| Amex | 107 | Entre em contato com o emissor | Please contact issuer |
| Amex | 111 | Conta Inválida | Invalid Account |
| Amex | 121 | Limite excedido | Limit exceed |
| Amex | 122 | Código de segurança do cartão impresso com chave inválido (PCSC) | Format error. Verify card data |
| Amex | 130 | Autenticação forte necessária | Unauthorized transaction, try again |
| Amex | 190 | Incompatibilidade de Identificação Nacional | Unauthorized transaction. Do not try again |
| Amex | 191 | Referência de Voz | Please contact issuer |
| Amex | 900 | Conselho aceito | Please contact issuer |
{.table-bordered}
:::

**Em caso de infração nas diretrizes do programa de retentativas de bandeiras, a Rede apresentará um código de retorno de integração conforme a classificação da retentativa**

**1. Códigos de negativa – dentro do grupo brand (ABECS)**

::: table-scroll
| Código | Mensagem | Descrição | Como atuar |
|------- | ----------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| N01 | Declined by Rede: Issuer will never approve | Recusado pela Rede: Emissor nunca aprovará | Analise os códigos de retorno das negativas, barre retentativas excessivas seja do portador ou de processos de cobrança automática e revisite sua base de cartões armazenados |
| N02 | Declined by Rede: Excessive Reattempts | Recusado pela Rede: Retentativas excessivas |^^ |
| N03 | Declined by Rede: Attention – verify your Data | Recusado pela Rede: Atenção – verifique seus dados |^^ |
| N04 | Declined by Rede: Subseller is not allowed to operate | Recusado pela Rede: Subseller não é autorizado para operar | Consulte a central de atendimento para avaliar a situação cadastral do subestabelecimento |
| N05 | Declined by Rede: Policy. Merchant not allowed to operate. | Recusado pela Rede: Política Subseller não é autorizado para operar | ^^ |
| N06 | Declined by Rede: High risk MCC not allowed to operate. | Recusado pela Rede: MCC de alto risco não é autorizado para operar. | Contate a Rede para obter mais informações sobre o programa de monitoramento de MCCs de alto risco. |
| N08 | Declined by Rede: Excessive transactions denied | Recusado pela Rede: Excesso de Transações Negadas. | Analise as informações da mensageria e boas práticas conforme documentação. |
| N09 | Declined by Rede: credit risk | A venda não foi aprovada nesta tentativa por critérios automáticos de risco de crédito. | Revise os valores e método de pagamento. |
| N99 | Declined by Rede: Contact us | Recusado pela Rede: Contate-nos | Contate a Rede pois algo na operação precisa ser revisado e avalie nossas [Dicas de segurança](e-rede#dicas-de-seguranca) |
{.table-bordered}
:::

**2. Retornos de emissor – fora do grupo brand (não ABECS)**

::: table-scroll
| Código | Mensagem | Descrição |
|------- | -------------------------- | -------------------------------- |
| 124 | Unauthorized. Contact Rede | Não autorizado, consulte a Rede. |
{.table-bordered}
:::

Importante: Para perfeita visualização dos motivos de negativas da ferramenta Rede a utilização do código ABECS é necessária. Clique aqui para instruções de uso [Retornos da Bandeira](e-rede#documentacao-retornos-retornos-bandeiras).

Caso não seja feito o ajuste no campo custom header para habilitar os retornos no padrão ABECS, as transações serão respondidas apenas com o código de Retorno do emissor (124).

Para saber mais sobre o programa de retentativas e suas regras clique aqui [Tarifas de Bandeira](e-rede#tarifas-bandeira).

### Retornos da central do cartão{#documentacao-retornos-retornos-emissor .menu-nv3}

Os retornos da central do cartão são exibidos quando é obtida uma resposta de uma requisição de transação de crédito ou débito.

::: table-scroll
| returnCode | returnMessage | Descrição |
|----------- | ------------------------------------------------------------------------ |----------------------------------------------------------------------------|
| 00 | Success | Sucesso |
| 101 | Unauthorized. Problems on the card, contact the issuer. | Problemas no cartão, contate a central do cartão |
| 102 | Unauthorized. Check the situation of the store with the issuer. | Confirme a situação da loja com a central do cartão |
| 103 | Unauthorized. Please try again. | Não autorizado. Por favor, tente novamente. |
| 104 | Unauthorized. Please try again. | Não autorizado. Por favor, tente novamente. |
| 105 | Unauthorized. Restricted card. | Cartão restrito |
| 106 | Error in issuer processing. Please try again. | Erro no processamento. Tente novamente |
| 107 | Unauthorized. Please try again. | Por favor, tente novamente. |
| 108 | Unauthorized. Value not allowed for this type of card. | Valor não permitido para este tipo de cartão. |
| 109 | Unauthorized. Nonexistent card. | Cartão inexistente |
| 110 | Unauthorized. Transaction type not allowed for this card. | Tipo de transação não permitida para este cartão |
| 111 | Unauthorized. Insufficient funds. | Saldo insuficiente |
| 112 | Unauthorized. Expiry date expired. | Cartão expirado. |
| 113 | Unauthorized. Identified moderate risk by the issuer. | Emissor identificou risco moderado |
| 114 | Unauthorized. The card does not belong to the payment network. | O cartão não pertence a rede de pagamento |
| 115 | Unauthorized. Exceeded the limit of transactions allowed in the period. | Limite de transações permitidas no período foi excedido. |
| 116 | Unauthorized. Please contact the Card Issuer. | Por favor, contate a central do cartão. |
| 117 | Transaction not found. | Transação não encontrada. |
| 118 | Unauthorized. Card locked. | Cartão bloqueado. |
| 119 | Unauthorized. Invalid security code | Código de segurança inválido. |
| 121 | Error processing. Please try again. | Erro no processamento. Por favor, tente novamente. |
| 122 | Transaction previously sent | Transação enviada previamente. |
| 123 | Unauthorized. Bearer requested the end of the recurrences in the issuer. | Portador solicitou encerramento da recorrência na central do cartão. |
| 124 | Unauthorized. Contact Rede | Não autorizado. Contate a Rede. |
| 170 | Zero dollar transaction not allowed for this card. | Transação Zero Dollar não permitida para este cartão. |
| 172 | CVC2 required for Zero Dollar Transaction. | CVC2 exigido para transação Zero Dollar. |
| 174 | Zero dollar transaction success. | Transação Zero Dollar aprovada. |
| 175 | Zero dollar transaction denied. | Transação Zero Dollar negada. |

{.table-bordered}
:::

### Retornos de integração{#documentacao-retornos-retornos-integracao .menu-nv3}

Os retornos de integração são exibidos sempre que houver algo de errado na sua requisição, permitindo assim a correção imediata.

::: table-scroll
| returnCode | returnMessage | Descrição |
|----------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| 1 | expirationYear: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 2 | expirationYear: Invalid parameter format | Formato do parâmetro inválido |
| 3 | expirationYear: Required parameter missing | Parâmetro obrigatório não está presente |
| 4 | cavv: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 5 | cavv: Invalid parameter format | Formato do parâmetro inválido |
| 6 | postalCode: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 7 | postalCode: Invalid parameter format | Formato do parâmetro inválido |
| 8 | postalCode: Required parameter missing | Parâmetro obrigatório não está presente |
| 9 | complement: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 10 | complement: Invalid parameter format | Formato do parâmetro inválido |
| 11 | departureTax: Invalid parameter format | Formato do parâmetro inválido |
| 12 | documentNumber: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 13 | documentNumber: Invalid parameter format | Formato do parâmetro inválido |
| 14 | documentNumber: Required parameter missing | Parâmetro obrigatório não está presente |
| 15 | securityCode: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 16 | securityCode: Invalid parameter format | Formato do parâmetro inválido |
| 17 | distributorAffiliation: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 18 | distributorAffiliation: Invalid parameter format | Formato do parâmetro inválido |
| 19 | xid: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 20 | eci: Invalid parameter format | Formato do parâmetro inválido |
| 21 | xid: Required parameter for Visa card is missing | Parâmetro obrigatório para Visa não está presente |
| 22 | street: Required parameter missing | Parâmetro obrigatório não está presente |
| 23 | street: Invalid parameter format | Formato do parâmetro inválido |
| 24 | affiliation: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 25 | affiliation: Invalid parameter format | Formato do parâmetro inválido |
| 26 | affiliation: Required parameter missing | Parâmetro obrigatório não está presente |
| 27 | Parameter cavv or eci missing | Parâmetro cavv ou eci não está presente |
| 28 | code: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 29 | code: Invalid parameter format | Formato do parâmetro inválido |
| 30 | code: Required parameter missing | Parâmetro obrigatório não está presente |
| 31 | softdescriptor: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 32 | softdescriptor: Invalid parameter format | Formato do parâmetro inválido |
| 33 | expirationMonth: Invalid parameter format | Formato do parâmetro inválido |
| 34 | code: Invalid parameter format | Formato do parâmetro inválido |
| 35 | expirationMonth: Required parameter missing | Parâmetro obrigatório não está presente |
| 36 | cardNumber: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 37 | cardNumber: Invalid parameter format | Formato do parâmetro inválido |
| 38 | cardNumber: Required parameter missing | Parâmetro obrigatório não está presente |
| 39 | reference: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 40 | reference: Invalid parameter format | Formato do parâmetro inválido |
| 41 | reference: Required parameter missing | Parâmetro obrigatório não está presente |
| 43 | number: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 44 | number: Invalid parameter format | Formato do parâmetro inválido |
| 45 | number: Required parameter missing | Parâmetro obrigatório não está presente |
| 46 | installments: Not correspond to authorization transaction | Quantidade de parcelas não corresponde com a transação autorizada |
| 47 | origin: Invalid parameter format | Formato do parâmetro inválido |
| 48 | brandTid: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 49 | The value of the transaction exceeds the authorized | O valor da transação excede o valor autorizado |
| 50 | installments: Invalid parameter format | Formato do parâmetro inválido |
| 51 | Product or service disabled for this merchant. Contact Rede | Produto ou serviço desabilitado para esse lojista. Contate a Rede |
| 53 | Transaction not allowed for the issuer. Contact Rede. | Transação não permitida para este emissor. Contate a Rede |
| 54 | installments: Parameter not allowed for this transaction | Parâmetro não permitido para esta transação |
| 55 | cardHolderName: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 56 | Error in reported data. Try again. | Erro nos dados reportados. Tente novamente |
| 57 | affiliation: Invalid merchant | Lojista inválido enviado no parâmetro |
| 58 | Unauthorized. Contact issuer. | Não autorizado. Contate a central do cartão |
| 59 | cardHolderName: Invalid parameter format | Formato do parâmetro inválido |
| 60 | street: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 61 | subscription: Invalid parameter format | Formato do parâmetro inválido |
| 63 | softdescriptor: Not enabled for this merchant | Produto não habilitado |
| 64 | Transaction not processed. Try again | Transação não processada. Tente novamente |
| 65 | token: Invalid token | Chave de integração não está presente |
| 66 | departureTax: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 67 | departureTax: Invalid parameter format | Formato do parâmetro inválido |
| 68 | departureTax: Required parameter missing | Parâmetro obrigatório não está presente |
| 69 | Transaction not allowed for this product or service. | Transação não permitida para este produto ou serviço |
| 70 | amount: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 71 | amount: Invalid parameter format | Formato do parâmetro inválido |
| 72 | Contact issuer. | Contate a central do cartão |
| 73 | amount: Required parameter missing | Parâmetro obrigatório não está presente |
| 74 | Communication failure. Try again | Falha na comunicação, tente novamente |
| 75 | departureTax: Parameter should not be sent for this type of transaction | Parâmetro não deve ser enviado para este tipo de transação |
| 76 | kind: Invalid parameter format | Formato do parâmetro inválido |
| 78 | Transaction does not exist | Transação não existe |
| 79 | Expired card. Transaction cannot be resubmitted. Contact issuer. | Cartão vencido. Não tente novamente e contate a central do cartão |
| 80 | Unauthorized. Contact issuer. (Insufficient funds) | Saldo insuficiente. Contate a central do cartão |
| 82 | Unauthorized transaction for debit card. | Transação não autorizada para cartão de débito |
| 83 | Unauthorized. Contact issuer. | Não autorizado. Contate a central do cartão |
| 84 | Unauthorized. Transaction cannot be resubmitted. Contact issuer. | Não autorizado. Não tente novamente e contate a central do cartão |
| 85 | complement: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 86 | Expired card | Cartão vencido |
| 87 | At least one of the following fields must be filled: tid or reference | Campo tid ou reference não está preenchido. |
| 88 | Merchant not approved. Regulate your website and contact the Rede to return to transact. | Lojista não aprovado. Regularize seu site e contate a Rede para voltar a transacionar. |
| 89 | token: Invalid token | Chave de integração inválida |
| 97 | tid: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 98 | tid: Invalid parameter format | Formato do parâmetro inválido |
| 99 | BusinessApplicationIdentifier: Invalid parameter format. | Formato do parâmetro inválido. |
| 100 | WalletId: Invalid parameter format. | Formato do parâmetro inválido. |
| 132 | DirectoryServerTransactionId: Invalid parameter size. | Parâmetro enviado com tamanho inválido |
| 133 | ThreedIndicator: Invalid parameter value. | Valor do parâmetro inválido |
| 150 | Timeout. Try again | Tempo esgotado. Tente novamente |
| 151 | installments: Greater than allowed | Valor do parâmetro maior do que o permitido |
| 153 | documentNumber: Invalid number | Valor do parâmetro inválido |
| 154 | embedded: Invalid parameter format | Formato do parâmetro inválido |
| 155 | eci: Required parameter missing | Parâmetro obrigatório não está presente |
| 156 | eci: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 157 | cavv: Required parameter missing | Parâmetro obrigatório não está presente |
| 158 | capture: Type not allowed for this transaction | Valor não permitido para esta transação |
| 159 | userAgent: Invalid parameter size | Parâmetro enviado com tamanho inválido |
| 160 | urls: Required parameter missing (kind) | Parâmetro obrigatório não está presente |
| 161 | urls: Invalid parameter format | Formato do parâmetro inválido |
| 167 | Invalid request JSON | Pedido JSON inválido |
| 169 | Invalid Content-Type | Content-Type inválido |
| 171 | Operation not allowed for this transaction | Operação não permitida para essa transação |
| 173 | Authorization expired | Autorização expirou |
| 176 | urls: Required parameter missing (url) | Parâmetro obrigatório não está presente |
| 370 | Request failed. Contact Rede | Pedido falhou. Contate a Rede |
| 898 | PV with invalid ip origin | PV com ip de origem inválido |
| 899 | Unsuccessful. Please contact Rede. | Sem sucesso. Por favor, contate a Rede |
| 1002 | Wallet Id: Invalid Parameter Size. | Parâmetro enviado com tamanho inválido |
| 1003 | Wallet Id: Required parameter missing. | Parâmetro obrigatório não está presente. |
| 1018 | MCC Invalid Size. | Parâmetro enviado com tamanho inválido |
| 1019 | MCC Parameter Required. | Parâmetro obrigatório não está presente |
| 1020 | MCC Invalid Format. | Formato do parâmetro inválido |
| 1021 | PaymentFacilitatorID Invalid Size. | Parâmetro enviado com tamanho inválido |
| 1023 | PaymentFacilitatorID Invalid Format. | Formato do parâmetro inválido |
| 1027 | SubMerchant: SubMerchantID Invalid Size. | Parâmetro enviado com tamanho inválido |
| 1030 | CitySubMerchant Invalid Size. | Parâmetro enviado com tamanho inválido |
| 1032 | SubMerchant: Estate Invalid Size. | Parâmetro enviado com tamanho inválido |
| 1034 | CountrySubMerchant Invalid Size. | Parâmetro enviado com tamanho inválido |
| 1036 | CepSubMerchant Invalid Size | Parâmetro enviado com tamanho inválido |
| 1038 | CnpjSubMerchant Invalid Size | Parâmetro enviado com tamanho inválido |
| 3020 | Cryptogram: Invalid parameter size. | Parâmetro enviado com tamanho inválido |
| 3021 | Cryptogram: Invalid parameter format. | Criptograma: Parâmetro no formato inválido |
| 3028 | Wallet Processing Type: Invalid Parameter Missing | Parâmetro obrigatório não está presente |
| 3029 | Wallet Processing Type: Invalid Parameter Size | Parâmetro enviado com tamanho inválido |
| 3030 | Wallet Processing Type: Invalid Parameter Format | Formato do parâmetro inválido |
| 3031 | Wallet Sender Tax Identification: Invalid Parameter Missing | Parâmetro obrigatório não está presente |
| 3032 | Wallet Sender Tax Identification: Invalid Parameter Size | Parâmetro enviado com tamanho inválido |
| 3033 | Wallet Sender Tax Identification: Invalid Parameter Format | Parâmetro enviado com tamanho inválido |
| 3034 | SubMerchant: Tax Identification Number Invalid Size. | Parâmetro enviado com tamanho inválido |
| 3035 | DSubMerchant: Tax Identification Number Invalid Format. | Formato do parâmetro inválido |
| 3036 | QrCode Expired. | QrCode expirado.|
| 3052 | Wallet Code: Required parameter missing. | Parâmetro obrigatório não está presente |
| 3053 | Wallet Code: Invalid Parameter format. | Formato do parâmetro inválido |
| 3054 | Wallet Code: Invalid Parameter size. | Parâmetro enviado com tamanho inválido |
| 3055 | Wallet Code: Parameter not allowed. | Parâmetro não permitido para esta transação |
| 3056 | Wallet Id: Parameter not allowed. | Parâmetro não permitido para esta transação |
| 3064 | Sai: Invalid parameter size. | Parâmetro enviado com tamanho inválido |
| 3065 | Sai: Invalid parameter format. | Formato do parâmetro inválido. |
| 3066 | Sai: Required parameter missing. | Parâmetro obrigatório não está presente. |
| 3067 | Cryptogram: Required parameter missing. | Parâmetro obrigatório não está presente. |
| 3068 | Credential Id: Required parameter missing. | Parâmetro obrigatório não está presente. |
| 3069 | Credential Id: Invalid parameter format. | Formato do parâmetro inválido |
| 3070 | Credential Id: Invalid parameter size. | Parâmetro enviado com tamanho inválido |
| 3076 | QrCode: Expiration Date parameter missing. | QrCode: Campo Expiration Date não foi informado. |
| 3077 | QrCode: Expiration Date Invalid parameter value. | QrCode: Campo Expiration Date enviado com valor inválido. |
| 3078 | QrCode: Expiration Date invalid format. | QrCode: Campo Expiration Date enviado em formato inválido. |
| 3079 | QrCode not processed. Try again. | QrCode não processado. Tente novamente. |
| 3081 | QrCode: Expiration Date invalid size. | QrCode: Campo Expiration Date enviado em tamanho inválido. |
| 3084 | Error generating QrCode Image. Please use the GET Transaction for this operation. | Erro na geração do campo qrCodeImage. Use a API de Consulta para obter essa informação, caso seja necessário. |
| 3085 | Error generating QrCode Image. Please try again | Erro na geração do campo qrCodeImage. Tente novamente. |
| 3086 | OrderId: Invalid parameter size. | Tamanho do parâmetro inválido. |
| 3087 | OrderId: Invalid parameter format | Formato do parâmetro inválido |
| 3089 | QRCode not generated, please contact Rede | Qr Code não gerado, contate a Rede. |
| 3090 | Invalid Pix Key | Chave Pix Inválida na geração de qrCode. |
| 3091 | Error, not generated. Try again | Erro na devolução, tente novamente. |
| 3092 | Fail QrCode generate, please try again; | Falha na geração de qrCode, tente novamente. |
| 3094 | Unsucessful. Please contact Rede. | Sem sucesso. Contate a Rede. |
| 3095 | Unknown Pix Key. | Chave Pix não cadastrada. |
| 3096 | Unsucessful. Try again later. | Sem sucesso. Tente novamente mais tarde. |
| 3097 | Unavailable. Please try again later. | Não disponível. Tente novamente mais tarde. |
| 3098 | Service not authorized | Serviço não autorizado. |
| 3099 | Comunication failure. Try again later. | Falha na comunicação. Tente novamente mais tarde. |
| 3100 | Receiver Data Last Name: Invalid parameter format. | Formato do parâmetro inválido. |
| 3101 |  Receiver Data Tax Id Number: Invalid parameter size. | Parâmetro enviado com tamanho inválido. |
| 3102 |  Receiver Data Tax Id Number: Invalid parameter format. | Formato do parâmetro inválido. |
| 3103 | Receiver Data Wallet Account Identification: Invalid parameter size. | Parâmetro enviado com tamanho inválido |
| 3104 | Receiver Data Wallet Account Identification: Invalid parameter format. | Formato do parâmetro inválido. |
| 3105 |  Payment Destination: Invalid parameter format. | Formato do parâmetro inválido. |
| 3106 | Payment Destination: Invalid parameter size. | Parâmetro enviado com tamanho inválido. |
| 3107 | Receiver Data: Required parameter missing. | Parâmetro obrigatório não está presente. |
| 3108 | Receiver Data First Name: Required parameter missing. | Parâmetro obrigatório não está presente. |
| 3109 |  Receiver Data Last Name: Required parameter missing. | Parâmetro obrigatório não está presente. |
| 3110 | Receiver Data Tax Id Number: Required parameter missing. | Parâmetro obrigatório não está presente. |
| 3111 | Receiver Data Account Identification: Required parameter missing. | Parâmetro obrigatório não está presente. |
| 3112 | Payment Destination: Parameter not allowed. | Parâmetro não permitido para esta transação. |
| 3113 |  MerchantTaxIdInvalidSize: Invalid parameter size. | Parâmetro enviado com tamanho inválido. |
| 3114 |  MerchantTaxIdInvalidFormat: Invalid parameter format. | Formato do parâmetro inválido. |
| 3115 | Receiver Data First Name: Invalid parameter size. | Parâmetro enviado com tamanho inválido. |
| 3116 | Receiver Data First Name: Invalid parameter format. | OFormato do parâmetro inválido. |
| 3117 | Receiver Data Last Name: Invalid parameter size. | Parâmetro enviado com tamanho inválido. |
| 3118 | CaptureExpirationHours: Invalid parameter format. | Formato do parâmetro inválido. |
| 3119 |  Capture: Invalid parameter format. | Formato do parâmetro inválido |
| 3120 | CaptureExpirationHours: Invalid parameter size. | Parâmetro enviado com tamanho inválido. |
| 3121 |  Invalid Amount. | |
| 3122 |  Invalid Amount. | |
| 3123 | Devolution not confirmed. | O processo de devolução não foi concluído com sucesso. Por favor, repita a solicitação. |
| 3134 | marketplaceId: Invalid parameter format. | Formato do parâmetro inválido. |
| 3135 | marketplaceId: Invalid parameter size. | Tamanho do parâmetro inválido. |
| 3137 | gatewayId: Invalid parameter format. | Formato do parâmetro inválido. |
| 3136 | gatewayId:Invalid parameter size. | Tamanho do parâmetro inválido. |
| 3125 | Incorrect devolution data | Devolução negada por dados incorretos Revise os dados da transação e tente novamente. |
| 3128 | Devolution blocked | Devolução negada por bloqueio em conta junto a emissor, tente novamente. |
| 3130 | Sender Data: Invalid parameter format. | Formato do parâmetro inválido. |
| 3131 | Sender Data: Invalid parameter size. | Tamanho do parâmetro inválido. |
| 3132 | SubMerchant : Merchant Tax Id Name Invalid Size. | Tamanho do parâmetro inválido. |
| 3133 | SubMerchant: Merchant Tax Id Name Invalid Format. | Formato do parâmetro inválido. |
| 3134 | Sender firstName: invalid parameter format  | Formato do parâmetro inválido. |
| 3135 | Sender firstName: invalid parameter size | Tamanho do parâmetro inválido. |
| 3136 | Sender lastName: invalid parameter format | Formato do parâmetro inválido. |
| 3137 | Sender lastName: invalid parameter size | Tamanho do parâmetro inválido. |
| 3138 | Sender address: invalid parameter format  | Formato do parâmetro inválido. |
| 3139 | Sender address: invalid parameter size  | Tamanho do parâmetro inválido. |
| 3140 | Sender city: invalid parameter format | Formato do parâmetro inválido. |
| 3141 | Sender city: invalid parameter size | Tamanho do parâmetro inválido. |
| 3142 | Sender country: invalid parameter format | Formato do parâmetro inválido. |
| 3143 | Sender country: invalid parameter size | Tamanho do parâmetro inválido. |
| 3301 | PV with invalid ip origin | IP de origem inválido para o PV |
| 3302 | TransactionLinkId: Invalid parameter size | Parâmetro enviado com tamanho inválido. |
| 4005 | submerchant/url: invalid parameter size | Tamanho do parâmetro inválido. |
| 4006 | submerchant/url: invalid parameter format | Formato do parâmetro inválido. |
| 4007 | submerchant/telephone: invalid parameter format | Tamanho do parâmetro inválido. |
| 4008 | submerchant/telephone: invalid parameter format | Formato do parâmetro inválido. |
| 4009 | partnerCode: invalid parameter format | Formato do parâmetro inválido. |
| 4010 | partnerCode: invalid parameter size | Tamanho do parâmetro inválido. |
| 4011 | refundReasonCode: invalid parameter format | Formato do parâmetro inválido. |
| 4012 | refundReasonCode: invalid parameter size | Tamanho do parâmetro inválido. |
| 4030 | token is expired or invalid | Token expirado ou inválido |
{.table-bordered}
:::

Caso receba o retorno 370 em uma requisição de venda (captura automática ou pré), realize uma consulta por Reference para verificar a situação da sua transação.
Caso ocorra o retorno 78 “Transaction does not exist”, a transação deverá ser reenviada.

### Retornos 3DS{#documentacao-retornos-retornos-3ds .menu-nv3}

As transações autenticadas possuem retornos e mensagens específicas.

::: table-scroll
| returnCode | returnMessage | Descrição |
|----------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| 200 | Cardholder successfully authenticated | Autenticação realizada com sucesso |
| 201 | Authentication not required | Autenticação não exigida. |
| 203 | Authentication service not registered for the merchant. Please contact Rede | Serviço não habilitado. Por favor, contate a Rede |
| 202 | Unauthenticated cardholder | Portador não autenticado. |
| 204 | Cardholder not registered in the issuer's authentication program | Portador não registrado no programa de autenticação da central do cartão |
| 220 | Transaction request with authentication received. Redirect URL sent | Pedido de transação com autenticação recebida. URL de redirecionamento enviada. |
| 250 | onFailure: Required parameter missing | Parâmetro obrigatório não está presente. |
| 251 | onFailure: Invalid parameter format | Formato do parâmetro inválido |
| 252 | urls: Required parameter missing (url/threeDSecureFailure) | Parâmetro obrigatório não está presente. |
| 253 | urls: Invalid parameter size (url/threeDSecureFailure) | Parâmetro enviado com tamanho inválido |
| 254 | urls: Invalid parameter format (url/threeDSecureFailure) | Formato do parâmetro inválido |
| 255 | urls: Required parameter missing (url/threeDSecureSuccess) | Parâmetro obrigatório não está presente. |
| 256 | urls: Invalid parameter size (url/threeDSecureSuccess) | Parâmetro enviado com tamanho inválido |
| 257 | urls: Invalid parameter format (url/threeDSecureSuccess) | Formato do parâmetro inválido |
| 258 | userAgent: Required parameter missing | Parâmetro obrigatório não está presente. |
| 259 | urls: Required parameter missing | Parâmetro obrigatório não está presente. |
| 260 | urls: Required parameter missing (kind/threeDSecureFailure) | Parâmetro obrigatório não está presente. |
| 261 | urls: Required parameter missing (kind/threeDSecureSuccess) | Parâmetro obrigatório não está presente. |
| 269 | ChallengePreference: Invalid parameter format | ChallengePreference: Formato do parâmetro inválido |
| 3000 | ColorDepth: Required parameter missing | ColorDepth: Parâmetro obrigatório não está presente |
| 3001 | DeviceType3ds: Required parameter missing | DeviceType3ds: Parâmetro obrigatório não está presente |
| 3002 | JavaEnabled: Required parameter missing | JavaEnabled: Parâmetro obrigatório não está presente |
| 3003 | Language: Required parameter missing | Language: Parâmetro obrigatório não está presente |
| 3004 | TimeZoneOffset: Required parameter missing | TimeZoneOffset: Parâmetro obrigatório não está presente |
| 3005 | ScreenHeight: Required parameter missing | ScreenHeight: Parâmetro obrigatório não está presente |
| 3006 | ScreenWidth: Required parameter missing | ScreenWidth: Parâmetro obrigatório não está presente |
| 3007 | ColorDepth: Invalid parameter size | ColorDepth: Tamanho do parâmetro inválido |
| 3008 | DeviceType3ds: Invalid parameter size | DeviceType3ds: Tamanho do parâmetro inválido |
| 3009 | Language: Invalid parameter size | Language: Tamanho do parâmetro inválido |
| 3010 | TimeZoneOffset: Invalid parameter size | TimeZoneOffset: Tamanho do parâmetro inválido |
| 3011 | ScreenHeight: Invalid parameter size | ScreenHeight: Tamanho do parâmetro inválido |
| 3012 | ScreenWidth: Invalid parameter size | ScreenWidth: Formato do parâmetro inválido |
| 3013 | ColorDepth: Invalid parameter format | ColorDepth: Formato do parâmetro inválido |
| 3014 | DeviceType3ds: Invalid parameter format | DeviceType3ds: Formato do parâmetro inválido |
| 3015 | JavaEnabled: Invalid parameter format | JavaEnabled: Formato do parâmetro inválido |
| 3016 | Language: Invalid parameter format | Language: Formato do parâmetro inválido |
| 3017 | TimeZoneOffset: Invalid parameter format | TimeZoneOffset: Formato do parâmetro inválido |
| 3018 | ScreenHeight: Invalid parameter format | ScreenHeight: Formato do parâmetro inválido |
| 3019 | ScreenWidth: Invalid parameter format | ScreenWidth: Formato do parâmetro inválido |
{.table-bordered}
:::

### Retornos de cancelamento{#documentacao-retornos-retornos-cancelamento .menu-nv3}

As transações canceladas possuem retornos e mensagens específicas.

::: table-scroll
| returnCode | returnMessage | Mensagem |
|----------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| 351 | Forbidden | Cancelamento não permitido |
| 353 | Transaction not found | Transação não encontrada |
| 354 | Transaction with period expired for refund | Período de estorno expirado |
| 355 | Transaction already canceled. | Transação já cancelada |
| 357 | Sum of amount refunds greater than the transaction amount | Soma dos valores de estorno supera o valor da transação |
| 358 | Sum of amount refunds greater than the value processed available for refund | Soma dos valores de estorno supera o valor processado disponível para estorno |
| 359 | Refund successful | Estorno realizado com sucesso. |
| 360 | Refund request has been successful | Pedido de estorno realizado com sucesso. |
| 362 | RefundId not found | RefundID não encontrado |
| 363 | Callback Url characters exceeded 500 | Limite de caracteres da URL de Callback foi excedido |
| 365 | Partial refund not available. | Estorno parcial não disponível |
| 368 | Unsuccessful. Please try again | Sem sucesso. Por favor, tente novamente. |
| 369 | Refund not found | Estorno não encontrado |
| 370 | Request failed. Contact Rede | Pedido falhou. Contate a Rede |
| 371 | Transaction not available for refund. Try again in a few hours | Transação não disponível para estorno. Tente novamente em algumas horas |
| 373 | No further Refund allowed | Sem mais estornos permitidos |
| 374 | Refund not allowed. Chargeback requested | Estorno não permitido. Chargeback foi solicitado. |
{.table-bordered}
:::

**Atenção:** Para o Código 360, lembre-se que a Rede recebeu seu cancelamento, mas é preciso consultá-lo novamente posteriormente para confirmar se ocorreu com sucesso.

### Soluções de Tokenização{#documentacao-solucoes-tokenizacao .menu-nv2 .text-rede-orange}

As soluções de tokenização de cartões permitem o armazenamento e tráfego seguro de dados sensíveis de cartão de crédito e débito, relacionando essas informações com um token.

### Tipos de Tokenização{#documentacao-solucoes-tokenizacao-tipos-tokenizacao .menu-nv3}

O e.Rede oferece os seguintes tipos de tokenização para o seu E-commerce:

::: table-scroll
| Tipo de tokenização | Como funciona | Características | Bandeiras |
| ------------------ | ------- | ------------ | :----------------------------------- |
| [Cofre de Cartões](https://developer.userede.com.br/e-rede#documentacao-cofre-cartoes) | Rede cria um token para o cartão (tokenizationId) através da integração do Estabelecimento Comercial na API de Cofre de Cartões da Rede. Esse campo pode ser usado para transacionar ao invés do uso do cartão. | É ideal para estabelecimentos que desejam uma integração mais simplificada. Os dados do cartão são criptografados no ambiente da Rede e não trafegam pelo servidor da loja no fluxo transacional, pois toda a comunicação é feita pelo tokenizationId gerado. | Todas as bandeiras de crédito e débito aceitas pelo e.Rede |
| [Tokenização de Bandeira Rede](https://developer.userede.com.br/e-rede#documentacao-tokenizacao-bandeira-rede) | A loja integra com a tokenização convencional da Rede, que adicionalmente irá criar o token diretamente na bandeira. | A loja poderá armazenar tanto o token gerado pela Rede, quanto o token gerado pelas bandeiras. Nesse cenário, a geração de [criptogramas](https://developer.userede.com.br/e-rede#documentacao-tokenizacao-bandeira-rede-criptograma) será responsabilidade do estabelecimento. | Visa e Mastercard |
| [Tokenização de Bandeira externa (captura)](https://developer.userede.com.br/e-rede#documentacao-tokenizacao-bandeira-externa) | A loja realiza a tokenização de cartões usando uma solução do mercado externa à Rede. | A loja é responsável por gerenciar o token do cartão, e a Rede será capaz de aceitar o token do cartão durante as transações. | Visa, Mastercard e Elo. |
{.table-bordered}
:::

### Cofre de Cartões{#documentacao-cofre-cartoes .menu-nv2}

O Cofre de Cartões oferece mais segurança ao comprador e permite que o estabelecimento comercial armazene o cartão para compras futuras.

Com essa solução, os dados de pagamento, como número do cartão e validade, são enviados de forma segura diretamente para o sistema da Rede, sem trafegar pelo ambiente do e-commerce. Esses dados são armazenados de forma criptografada como um token. Assim, o Estabelecimento pode usar o token em compras futuras, sem precisar que o comprador insira novamente as informações de pagamento, proporcionando a experiência de "Card on File".

**Benefícios**

- O uso da solução Cofre de Cartões traz mais agilidade e segurança no processo de compra, possibilitando a compra com um clique;
- Possibilita que o Estabelecimento Comercial tenha a experiência Card on File;
- **Funcionalidade 2 em 1:** benefícios de token PCI e token de bandeira na mesma solução;
- Possibilita a geração de tokens de bandeira, com as vantagens abaixo:

  - Credenciais sempre atualizadas;
  - Aumento de conversão;
  - Aumento de segurança;
  - Flexibilidade na autorização.

**Pontos importantes**

- A solução Cofre de Cartões tem por padrão executar uma transação Zero Dollar, para validar se o cartão é válido, antes de armazená-lo. Essa é uma recomendação de todas as bandeiras e impacta positivamente na taxa de autorização do estabelecimento.  
Para entender o processo de ativação do produto Zero Dollar no seu Ponto de Venda e seus custos relacionados, acesse a seção [Zero Dollar](e-rede#documentacao-zero-dollar).  
**Observação**: Caso o Estabelecimento tente utilizar o Cofre de Cartões como canal para o Zero Dollar sem ter essa funcionalidade habilitada, o Zero Dollar não será efetuado. Isso poderá afetar negativamente a taxa de sucesso de tokenização; por isso, é imprescindível que a habilitação do Zero Dollar seja solicitada ao utilizar o Cofre de Cartões e a Tokenização de Bandeira da Rede.

- Caso seja de interesse do estabelecimento à não execução do Zero Dollar, basta enviar o parâmetro embeddedZeroDollar = false. Essa prática não é recomendada e pode afetar negativamente a taxa de aprovação das transações.

- Não armazene cartões sem o consentimento do portador.

- Não mantenha o armazenamento de cartões que estejam vinculados a qualquer tipo de fraude confirmada: ao receber uma notificação de suspeita de fraude, exclua o cartão relacionado à fraude da base de cartões.

### Como contratar?{#documentacao-cofre-cartoes-como-contratar .menu-nv3}

Antes de iniciar a integração com o produto, é necessário fazer a habilitação no portal logado da Rede “userede.com.br”. Basta acessar o menu vender online > e-Commerce > tokenização de bandeira e selecionar o PV de interesse. A contratação será efetivada em alguns instantes.

A contratação e utilização do produto Cofre de Cartões não gera custos adicionais para os clientes do e.Rede.

### Primeiros passos{#documentacao-cofre-cartoes-primeiros-passos .menu-nv3}

O processo de solicitação de Tokenização do cartão realizado na Rede é feito em algumas etapas:

**1.** Primeiro, o usuário manda os dados do cartão para o Estabelecimento;

**2.** O Estabelecimento Comercial manda os dados do cartão que serão criptografados e salvos na base da Rede;

**3.** Após realizar a criptografia, o Estabelecimento Comercial recebe da Rede um identificador único daquele cartão (tokenizationID);

**4.** O Estabelecimento Comercial armazena o tokenizationID recebido da Rede, após isso, todos os pedidos transacionais serão feitos em cima desse tokenizationID.

### Autenticação da Rede via APIs{#documentacao-cofre-cartoes-autenticacao-rede-via-apis .menu-nv3 .text-rede-green}

>  **Atenção**{.text-rede-orange}
>
> Caso você seja um cliente que utiliza a API de Tokenização com a Rede e ainda utiliza o protocolo BASIC, entenda as mudanças.
>Antes, a autenticação era feita seguindo o protocolo BASIC e usando apenas PV e chave de integração gerada no [Portal Use Rede](https://www.userede.com.br/).
>
> ![Fluxo de Tokenização](assets/images/e-rede/basic-tkn.png){#img-fluxo-tokenizcao .content-image}
>
> Agora, adotamos o modelo **OAuth 2.0**, que proporciona mais segurança para suas chamadas com a Rede. Por isso, precisamos adicionar mais uma etapa no processo de autenticação. Assim que as credenciais forem atualizadas, deve ser feito um novo chamado de endpoint
para gerar o **access_token**, necessário para transacionar com o e.Rede.
{.content-info-orange .with-icon}

As APIs da Rede utilizam o protocolo de autenticação **OAuth 2.0**, um padrão da indústria para autorização e autenticação de aplicações.
Esse protocolo foi projetado para simplificar o desenvolvimento de fluxos de autorização para aplicações web, desktop, smartphones e outros.

### Passo a passo para integração OAuth 2.0


**1.** Obtenha as credenciais de acesso PV e Chave de Integração no [Portal Use Rede](https://www.userede.com.br/).

Com a utilização do protocolo **OAuth 2.0**, essas credenciais foram renomeadas para o novo padrão, conforme a tabela. Confira todas credenciais usadas em ambiente de desenvolvimento:

::: table-scroll
|Portal Use Rede|Credencial para OAuth 2.0|
|---------------|-------------------------|
|PV|clientId|
|Chave de Integração|clientSecret|
|Token de acesso dinâmico |access_token|
{.table-bordered table}
:::

**2.** Com essas credenciais, faça uma chamada ao endpoint de autenticação: https://api.userede.com.br/redelabs/oauth2/token

**3.** Essa chamada gera uma **access_token**, que será usado para tokenizar com a Rede

**4.** O **access_token** deve ser armazenado de forma segura, evitando exposição ou uso indevido

**5.** O **access_token** tem validade de 24 minutos. Após esse período, é necessário fazer uma nova chamada ao endpoint para gerar um novo token

### OAuth Authorization

![Fluxo de Tokenização](assets/images/e-rede/oauth-tkn.png){#img-fluxo-tokenizacao .content-image}


> **Informações sobre a Chave de Integração(clientSecret).**
>
>  Se você já possui uma Chave de integração, pode continuar usando a mesma.
>
>  Em caso de **perda ou esquecimento** da chave de integração, uma nova deverá ser gerada no [Portal Use Rede](https://www.userede.com.br/).
>
>  Para gerar a Chave, seu usuário precisa ter **perfil de administrador**. Acesse o menu:  _e-commerce_ > _chave de integração_ e clique em **“Gerar chave de integração”**.
>
> Se uma nova chave de integração for gerada, é necessário **atualizar imediatamente** no campo **clientSecret** da API para que o fluxo de  tokenização se mantenha.
{.content-info .with-icon}


## Como realizar autenticação no padrão OAuth 2.0

### Endpoint de Autenticação {#cofre-cartoes-autenticacao-rede-via-apis-endpoint .menu-nv2 .text-rede-black}

::: table-scroll
| Ambiente | URL para gerar Token |
| -------- | ------------------------------------------------------- |
| Sandbox | https://rl7-sandbox-api.useredecloud.com.br/oauth2/token |
| Produção | https://api.userede.com.br/redelabs/oauth2/token |
{.table-bordered table}
:::

## Autenticação

### Gerar access_token

Com o **clientId** e o **clientSecret**, é possível gerar o token de acesso dinâmico utilizando a chamada:

::: {.block-code}
```json
curl --request POST \
--url '{urlToken}' \
--header 'Authorization: Basic Base64(clientId:clientSecret)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials
```
:::

#### Headers:

::: table-scroll
| Parâmetro | Obrigatório | Descrição |
| -------- | ------------------------------------------------------- |
| Authorization | ✅ | Junte o client_id e o client_secret com dois-pontos (:) e converta o resultado para base64 |
| Content-Type | ✅ | application/x-www-form-urlencoded |
{.table-bordered table}
:::

#### Form:

::: table-scroll
| Parâmetro | Obrigatório | Descrição |
| -------- | ------------------------------------------------------- |
| grant_type | ✅ | Tipo de geração do token, com o valor fixo “client_credentials” |
{.table-bordered table}
:::

#### Response:

::: table-scroll
| Parâmetro | Obrigatório | Descrição |
| -------- | ------------------------------------------------------- |
| access_token | ✅ | Token usado para chamar as APIs da Rede, com duração padrão de 24 minutos |
| token_type | ✅ | Tipo do token gerado, padrão é "Bearer" |
| expires_in | ✅ | Tempo de expiração em segundos do access_token |
| scope | ✅ | Lista de escopos separados por espaço, representando os acessos concedidos à aplicação |
{.table-bordered table}
:::

## Tokenização{#cofre-cartoes-autenticacao-rede-via-apis-tokenizacao .menu-nv2 .text-rede-green}

### Utilizar o Token de acesso

Para utilizar a API de Tokenização da Rede, você deve:

**1.** Ter uma access_token gerado, para ser usado nas APIs de negócio

**2.** Atualizar o access_token gerado anteriormente

> **Header**
>
> Authorization: Bearer {access_token}.
{.content-info .with-icon}


>  **Atenção**{.text-rede-orange}
>
>O **access_token** deve ser armazenado com segurança.
>
> Como sua duração é de 24 minutos, uma nova chamada deverá ser feita antes desse período para atualizar a credencial.
>
> O token de acesso tem validade de 24 minutos e pode ser reutilizado durante esse período. Para evitar expiração, recomenda-se renová-lo entre 15 e 23 minutos após a emissão.
>
>A escolha de como realizar o chamado e atualizar os **access_token** gerados ficam sob sua responsabilidade.
{.content-info-orange .with-icon}

## Codificação OAuth

### UTF8

Configure sua aplicação para usar codificação UTF-8.

### Codificação de URL
A codificação URL é usada para codificar informações em URIs e usada também para dados do tipo application/x-www-formurlencoded, como em formulários HTML.

### JSON

JSON é o padrão usado para troca de dados entre sistemas. Para chamadas POST e PUT, é necessário especificar o cabeçalho:

::: {.block-code}
```json
Content-Type: application/json
```
:::

## Boas práticas de segurança
- Armazene o **access_token** em cache seguro e criptografado
- Evite expor o token em logs ou interfaces públicas
- Implemente controle de acesso para uso do token
- Utilize HTTPS em todas as chamadas às APIs da Rede

### Solicitação de tokenização {#documentacao-cofre-cartoes-solicitacao-tokenizacao .menu-nv3 .text-rede-green}

**Endpoint de Tokenização**

Os endpoints são as URLs que serão utilizadas para a chamada de determinados serviços de tokenização. Elas podem variar dependendo do ambiente e método HTTP. 

A composição é realizada da seguinte forma: 

- URL base 
- Versão da API
- Serviço

::: table-scroll
| Ambiente | URL |
| -------- | ------------------------------------------------------- |
| Sandbox | https://rl7-sandbox-api.useredecloud.com.br/token-service/oauth/v2/tokenization/ |
| Produção | https://api.userede.com.br/redelabs/token-service/oauth/v2/tokenization  |
{.table-bordered table}
:::

**Envio de solicitação de tokenização do cartão para a bandeira:**

> POST: **[/token-service/oauth/v2/tokenization](e-rede#operations-Tokenização-solicitarTokenizacao)** {.content-info}

**Parâmetros da requisição:**

O corpo da requisição (body) deve estar em formato JSON contendo os campos descritos na tabela abaixo:

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|----------- | --------- | ------------ | ----------- | :--------- |
| email | Até 200 | Alfanumérico | Sim | E-mail do portador do cartão, cliente ou estabelecimento comercial |
| cardNumber | Até 19 | Alfanumérico | Sim | Número do cartão |
| expirationMonth | 2 | Alfanumérico | Sim | Mês de vencimento do cartão (entre "01" e "12") |
| expirationYear | 4 | Alfanumérico | Sim | Ano de vencimento do cartão |
| cardholderName | Até 200 | Alfanumérico | Não | Nome do portador impresso no cartão |
| securityCode | Até 4 | Alfanumérico | Não | Código de segurança localizado no verso do cartão |
| storageCard | Até 2 | Numérico | Sim | Indica operações que possam ou não estar utilizando COF (Card on File): |\
| | | | | |\
| | | | | 0 - Transação com credencial não armazenada. |\
| | | | | |\
| | | | | 2 - Transação com credencial já armazenada. |\
| | | | | |\
| | | | | **Para transações tokenizadas este parâmetro deve ter o valor “2”.** |
| kind | \- | Alfanumérico | Não |Tipo de transação a ser realizada: |\
| | | | | |\
| | | | | - Para transações de crédito, utilizar **credit** |\
| | | | | |\
| | | | | - Para transações de débito, utilizar **debit** |\
| | | | | |\
| | | | | O não envio desse campo será considerado crédito. |
| embeddedZeroDollar | \- | Booleano | Não | Ao armazenar um cartão, a realização do zero dollar e obrigatória. Por isso, recomenda-se enviar o campo como true. Caso o cartão já tenha sido armazenado anteriormente e o estabelecimento não possua o CVV, o campo pode ser enviado como false, evitando a execução do zero dollar. Se o campo não for enviado, o zero dollar será realizado automaticamente. |
{.table-bordered}
:::

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|--------------- | ------- | ------------ | ----------------------------------- |
| returnCode | Até 3 | Alfanumérico | Código de retorno da solicitação |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da solicitação|
| tokenizationId | 36 | Alfanumérico | Identificador único da solicitação de tokenização do cartão pela Rede |
{.table-bordered}
:::

### Cadastro da URL para receber as atualizações do token via webhook {#documentacao-cofre-cartoes-cadastro-url-receber-atualizacoes-token-via-webhook .menu-nv3}

Após a contratação do produto de Cofre de Cartões no portal ["userede.com.br"](https://www.userede.com.br/), será possível cadastrar a URL para receber as atualizações do token via webhook. Basta acessar o menu vender online > e-Commerce > tokenização de bandeira > cadastro de url e fazer o cadastro.

**IMPORTANTE:** Caso a url de notificações não seja informada, nenhum evento será entregue durante o processo de tokenização.Além disso, a Rede não se responsabiliza pelo cadastro de URLs inválidas por parte do estabelecimento.

#### URLs Autenticadas e Não Autenticadas

A REDE deve ser informada durante o cadastro se a URL possui autenticação ou não.

- URL Sem Autenticação:

Neste caso a Rede não fará nenhum tipo de verificação de segurança antes de entregar o evento na url informada.

- URL Com Autenticação:

A Rede possibilita a utilização de autenticação basic ou bearer e em ambos os casos o token de acesso deve ser cadastrado no portal, no momento do cadastro da url.

#### Ponto de Atenção:

A URL cadastrada será utilizada para todos os PVs cadastrados no mesmo CNPJ.

### Callback realizado pelo webhook{#documentacao-cofre-cartoes-callback-webhook .menu-nv3}

Após a realização da solicitação de tokenização, assim que a criação do token de bandeira for finalizada, o cliente receberá um evento em uma URL previamente cadastrada no [Portal da Rede](https://www.userede.com.br/).

Além disso, eventos também serão enviados quando houver alguma atualização no token, como por exemplo, se ele for excluído devido ao cancelamento do cartão. Ou então, caso o cartão original seja atualizado, todas essas atualizações serão informadas ao Estabelecimento Comercial através desse webhook.

As tentativas de notificações de evento são de 12 vezes a cada 30 segundos, após isso é tentado de 1 em 1 hora por 14 dias.

Após o recebimento do evento é essencial que o estabelecimento faça uma consulta daquele token, para identificar qual foi a atualização sofrida. Não será informado no evento a atualização.

**Nota:** No ambiente sandbox, esse callback será realizado 2 minutos após o envio da solicitação de tokenização.

**Os parâmetros recebidos no evento serão:**

::: table-scroll
| Nome | Local de envio | Tamanho | Tipo | Descrição |
|-------------------- | -------------- | -------- | ------------------ | ----------------------------------- |
| Authorization | header | Até 3 | Alfanumérico | Header para autorização da requisição na url fornecida pelo estabelecimento através do portal logado. |
| Request-ID | header | Até 36 | Alfanumérico | Identificador único da requisição |
| Content-Type | header | - | Alfanumérico | Valor fixo definido como 'application/json' |
| id | body | 6 | Alfanumérico | Identificador único do callback |
| merchantId | body | 9 | Alfanumérico | Número de filiação do estabelecimento (PV) |
| events | body | \- | Lista Alfanumérica | Nome dos eventos que serão informados ao cliente.|\
||||||\
||||| Exemplo: ["PV.TOKENIZACAO-BANDEIRA"] |
| data/tokenizationId | body | Até 36 | Alfanumérico | Token do cartão|
{.table-bordered}
:::

**Exemplo do evento:**
::: {.block-code}

```json
{
  "id": "123456",
  "merchant_id": "123415678",
  "events": ["PV.TOKENIZACAO-BANDEIRA"],
  "data": {
    "tokenizationId": "0c299dab-2b7a-41a1-8514-e54f9dd18297"
  }
}
```

:::

### Consulta do token{#documentacao-cofre-cartoes-consulta-token .menu-nv3}

A consulta à solicitação de tokenização pode ser feita logo após a obtenção do tokenizationId da Rede (o token de bandeira é gerado de maneira assíncrona, dessa forma, a consulta deve ser feita somente após o recebimento do evento), que será sempre realizada quando o Estabelecimento Comercial receber um evento pelo webhook, permitindo verificar o status da solicitação e demais informações listadas abaixo.

Requisição para a consulta dos dados da solicitação de tokenização:

> GET: **[/token-service/oauth/v2/tokenization/{tokenizationId}](e-rede#operations-Tokenização-consultarTokenizacaoPorTokenizationId)** {.content-info}

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|--------------- | ------- | ------------ | :----------------------------------- |
| returnCode | Até 3 | Alfanumérico | Código de retorno da solicitação |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da solicitação |
| affiliation | Até 9 | Numérico | Número de filiação do estabelecimento (PV) |
| tokenizationId | 36 | Alfanumérico | Token do cartão |
| tokenizationStatus | \- | Alfanumérico | Status da solicitação de tokenização da Rede: |\
| | | | - Pending |\
| | | | - Active |\
| | | | - Inactive |\
| | | | - Suspended |\
| | | | - Failed |\
| | | | - Delete |
| brand/name | - | Alfanumérico | Nome da bandeira do BIN do cartão enviado na solicitação de tokenização |
| brand/message | Até 256 | Alfanumérico | Mensagem de retorno da bandeira em caso de falha na solicitação do token para um determinado cartão. |\
| | | | |\
| | | | O tokenizationStatus nesse cenário será Failed e as informações de token não estarão disponíveis
| brand/tokenStatus | Até 30 | Alfanumérico | Status da solicitação de tokenização da bandeira: |\
| | | | - Pending |\
| | | | - Active |\
| | | | - Inactive |\
| | | | - Suspended |\
| | | | - Failed |\
| | | | - Delete |
| brand/brandTid | Até 21 | Alfanumérico | Correlaciona a primeira e demais transações através do envio deste campo. Para mais detalhes consulte a seção [Recorrência e Card-on-file](e-rede#documentacao-recorrencia)||
| lastModifiedDate | - | Datetime | Data da última atualização do registro no formato YYYY-MM-DDThh:mm:ssTZD |
| bin | Até 9 | Alfanumérico | 2 a 9 primeiros dígitos do cartão |
| last4 | 4 | Alfanumérico | 4 últimos dígitos do cartão |
| token/code | Até 16 | Numérico | Número do token do cartão descriptografado, gerado pela bandeira |
| token/expirationDate | 7 | Alfanumérico | Data de expiração (no formato MM/YYYY) do token gerado pela bandeira para o cartão enviado |
{.table-bordered}
:::

### Gestão do token{#documentacao-cofre-cartoes-gestao-token .menu-nv3}

Após a criação do token é possível gerenciar o status dele. Isto é, o estabelecimento tem autonomia para deletar, suspender e reativar os tokens sob sua responsabilidade.

**Importante:** a gestão e o compartilhamento de tokens é realizada por CNPJ raiz, abrangendo todos os PVs vinculados ao mesmo CNPJ.

> PUT: **[/token-service/oauth/v2/tokenization/{tokenizationId}](e-rede#operations-Tokenização-solicitarTokenizacao)** {.content-info}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|----------- | --------- | ------------ | ----------- | :--------- |
| tokenizationStatus | 100 | Alfanumérico | Sim | Se o status atualizado para qual o do token for **deletar, será o delete**: |\
| | | | | |\
| | | | | Se o status atualizado para qual o do token for **suspender, será o suspend** |\
| | | | | |\
| | | | | Se o status atualizado para qual o do token for **reativar, será o resume** |
| reason | 2 | Numérico | Sim |Motivo da atualização: |\
| | | | | |\
| | | | | 1 - Solicitação do Cliente |\
| | | | | |\
| | | | | 2 - Suspeita de Fraude |
{.table-bordered}
:::

**Parâmetros da Resposta:**

Caso a alteração do token ocorra com sucesso os seguintes campos serão retornados:

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|--------------- | ------- | ------------ | :---------------------------------------------------------- |
| returnCode | Até 3 | Alfanumérico | Código de retorno da solicitação |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da solicitação |
| tokenizationId | 36 | Alfanumérico | Token do cartão, que deve ser armazenado e utilizado em futuras transações |
| Brand/name* | - | Alfanumérico | Nome da bandeira. Ex: Visa |
| Brand/message* | - | Alfanumérico | Mensagem de erro da bandeira. Ex: Card not allowed. \*Esse campo só é retornado em caso de erro na tokenização de bandeira
{.table-bordered}
:::

### Gerando transações com uso de Tokens{#documentacao-cofre-cartoes-gerando-transacoes-uso-token .menu-nv3}

Após a criação do token (tokenizationId), é possível criar transações, onde esse parâmetro irá substituir algumas informações transacionais.

URL de ambientes transacionais:
::: table-scroll
| Ambiente | URL |
|--------- | ----------------------------------------------------------------- |
| Sandbox | https://sandbox-erede.useredecloud.com.br/v2/transactions |
| Produção | https://api.userede.com.br/erede/v2/transactions |
{.table-bordered}
:::

Para acionar o produto de Cofre de Cartões na API transacional do e.Rede, faça a troca dos campos base abaixo:
::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|---------------- | ------- | ------------ | ----------- | ----------------------------------- |
| cardNumber | Até 19 | Alfanumérico | Sim | Número do cartão. |
| expirationMonth | Até 2 | Numérico | Sim | Mês de vencimento do cartão. De 1 a 12. |
| expirationYear | 2 ou 4 | Numérico | Sim | Ano de vencimento do cartão. Ex.: 2028 ou 28|
{.table-bordered}
:::
Pelo novo campo indicativo de uso do nosso produto de Cofre de Cartões:
::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|---------------- | ------- | ------------ | ----------- | ----------------------------------- |
| cardToken | Até 64 | Alfanumérico | Sim | Valor de referência para o cartão tokenizado (tokenizationID) |
{.table-bordered}
:::
**IMPORTANTE:** Ao utilizar o parâmetro “cardToken” não é necessário fazer a solicitação do criptograma antes de solicitar a transação.
Para informações sobre os parâmetros necessários em cada modelo de transação com token, acesse a seção
[Tipos de Tokenização](https://developer.userede.com.br/e-rede#documentacao-solucoes-tokenizacao-tipos-tokenizacao)

**Exemplo de parâmetros de requisição para uma transação com token:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|----------- | --------- | ------------ | ----------- | :--------- |
| capture | - | Booleano | Não | Defina se uma transação terá captura automática ou posterior. O não envio desse campo será considerado uma captura automática **(true)**. |
| kind | \- | Alfanumérico | Não | Tipo de transação a ser realizada. |\
| | | | | - Para transações de crédito, utilizar **credit** |\
| | | | | - Para transações de débito, utilizar **debit** |\
| | | | | |\
| | | | | O não envio desse campo será considerado crédit. |
| reference | Até 50 | Alfanumérico | Sim | Código da transação gerado pelo estabelecimento. |
| amount | Até 10 | Numérico | Sim | Valor total da transação sem separador de milhar e decimal. |\
| | | | | |\
| | | | | Exemplos:|\
| | | | | - R$10,00 = 1000 |\
| | | | | - R$0,50 = 50 |
| installments | Até 2 | Numérico | Não | Número de parcelas em que uma transação será autorizada. |\
| | | | | |\
| | | | | De 2 a 12 |\
| | | | | |\
| | | | | O não envio desse campo será considerado à vista. |
| cardholderName | Até 30 | Alfanumérico | Não | Nome do portador impresso no cartão. |
| cardToken | Até 64 | Alfanumérico | Sim | Valor de referência para o cartão tokenizado (tokenizationID). |
| softDescriptor | Até 13 | Alfanumérico | Não | Frase personalizada que será impressa na fatura do portador. |
| subscription | - | Booleano | Não | Informa ao emissor se a transação é proveniente de uma recorrência. Se transação for uma recorrência, enviar true. Caso contrário, enviar false. O não envio desse campo será considerado o valor false. A Rede não gerencia os agendamentos de recorrência, apenas permite aos lojistas indicarem se a transação originada é de um plano recorrente. |
| storageCard | Até 1 | Alfanumérico | Não | Indica operações que possam ou não estar utilizando COF (Card on File): |\
| | | | | |\
| | | | | 0 - Transação com credencial não armazenada. |\
| | | | | |\
| | | | | 1 - Transação com credencial armazenada pela primeira vez. |\
| | | | | |\
| | | | | 2 - Transação com credencial já armazenada. |\
| | | | | |\
| | | | | **Para transações tokenizadas este parâmetro deve ter o valor “2”.** |\
| | | | | |\
| | | | | Atenção: O não envio desse campo será considerado 0 (credencial não armazenada).|
| transactionCredentials | | | | Grupo transactionCredentials ||
| transactionCredentials/ credentialId | Até 02 | Alfanumérico | Sim, se storageCard=1 ou =2 e cartão mastercard | Indica a categoria da transação com credencial armazenada. Consulte a seção [“Categorização de transações card-on-file”](e-rede#documentacao-recorrencia-categorizacao-transacoes-card-on-file) para mais detalhes |
{.table-bordered}
:::

**IMPORTANTE:** A prioridade da Rede será sempre autorizar com o token de bandeira, ou seja, se a geração do token de bandeira foi feita com sucesso, ele será priorizado na autorização. Os dados do cartão original só serão utilizados, quando o token de bandeira não estiver disponível.

**Notas:**
Para informações sobre autenticação, autorização e configurações na API transacional da Rede acesse a seção [Autenticação e Autorização](e-rede#primeiros-passos-autenticacao-e-autorizacao).

**Ponto de atenção:** É possível utilizar o Cofre de Cartões somente com as seguintes mensagerias e produtos:

- [3DS MPI Rede](https://developer.userede.com.br/e-rede#documentacao-3d-secure2-0-3d-secure2-0-mpi-rede)
- [3DS MPI Cliente](https://developer.userede.com.br/e-rede#documentacao-3d-secure2-0-3d-secure2-0-mpi-cliente)
- [Data Only MPI Rede](https://developer.userede.com.br/e-rede#documentacao-data-only-data-only-mpi-rede)
- [Data Only MPI Cliente](https://developer.userede.com.br/e-rede#documentacao-data-only-data-only-mpi-cliente)
- [Recorrência e Card-on-File](https://developer.userede.com.br/e-rede#documentacao-recorrencia)
- [Mcc dinâmico](https://developer.userede.com.br/e-rede#documentacao-mcc-dinamico)
- [SDWO](https://developer.userede.com.br/e-rede#documentacao-carteiras-digitais-operadoras-carteiras-digital-escalonada-SDWO)
- [Voucher](https://developer.userede.com.br/e-rede#documentacao-voucher)

As mensagerias podem ser utilizadas em conjunto ou individualmente.

### Tokenização de Bandeira Rede {#documentacao-tokenizacao-bandeira-rede .menu-nv2}

O serviço de Tokenização de Bandeira protege as informações do cartão substituindo-as por um token. Cada token é único para o usuário e estabelecimento e não pode ser usado por nenhuma outra loja.

Essa funcionalidade está disponível para crédito e débito, para as bandeiras Visa e Mastercard.

**Benefícios**

- A tokenização do cartão garante a proteção dos dados reais, visto que substitui o número do cartão por um número aleatório, denominado token de bandeira.

- Em caso de vazamento de dados, os cartões de seus clientes permanecem seguros, visto que os tokens só podem ser utilizados dentro do seu estabelecimento.

- Além disso, é uma funcionalidade que garante a conformidade com as normas de regulamentação previstas em lei como a LGPD e PCI DSS (Data Security Standard).

### Como contratar?{#documentacao-tokenizacao-bandeira-rede-como-contratar .menu-nv3}

Antes de iniciar a integração com o produto é necessário fazer a habilitação no portal logado da Rede “userede.com.br”. Basta acessar o menu vender online > e-Commerce > tokenização de bandeira e selecionar o PV de interesse. A contratação será efetivada em alguns instantes.

A contratação e utilização do produto Tokenização de Bandeira não gera custos adicionais para os clientes do e.Rede.

### Primeiros passos{#documentacao-tokenizacao-bandeira-rede-primeiros-passos .menu-nv3}

O processo de solicitação de Tokenização do cartão realizado na Rede é feito em algumas etapas:

**1.** Primeiro o usuário manda os dados do cartão para o Estabelecimento;

**2.** O Estabelecimento Comercial manda os dados enviados para a bandeira e recebe uma resposta com um identificador único daquela solicitação (tokenizationId);

**3.** Em seguida (num processo assíncrono), a bandeira enviará as informações do token que serão atualizadas no registro, possibilitando a consulta delas pelo portador.

![Fluxo token de bandeira](assets/images/e-rede/fluxo-token-bandeira.svg){#img-simulacao-tela .content-image}

![Fluxo de Solicitação do criptograma](assets/images/e-rede/fluxo-solicitacao-criptograma.svg){#img-simulacao-tela .content-image}

### Autenticação da Rede via APIs{#documentacao-tokenizacao-bandeira-rede-autenticacao-rede-via-apis .menu-nv3 .text-rede-green}

>  **Atenção**{.text-rede-orange}
>
> Caso você seja um cliente que utiliza a API de Tokenização com a Rede e ainda utiliza o protocolo BASIC, entenda as mudanças.
>Antes, a autenticação era feita seguindo o protocolo BASIC e usando apenas PV e chave de integração gerada no [Portal Use Rede](https://www.userede.com.br/).
>
> ![Fluxo de Tokenização](assets/images/e-rede/basic-tkn.png){#img-fluxo-tokenizcao .content-image}
>
> Agora, adotamos o modelo **OAuth 2.0**, que proporciona mais segurança para suas chamadas com a Rede. Por isso, precisamos adicionar mais uma etapa no processo de autenticação. Assim que as credenciais forem atualizadas, deve ser feito um novo chamado de endpoint para gerar o **access_token**, necessário para transacionar com o e.Rede.
{.content-info-orange .with-icon}

As APIs da Rede utilizam o protocolo de autenticação **OAuth 2.0**, um padrão da indústria para autorização e autenticação de aplicações.
Esse protocolo foi projetado para simplificar o desenvolvimento de fluxos de autorização para aplicações web, desktop, smartphones e outros.

### Passo a passo para integração OAuth 2.0


**1.** Obtenha as credenciais de acesso PV e Chave de Integração no [Portal Use Rede](https://www.userede.com.br/).

Com a utilização do protocolo **OAuth 2.0**, essas credenciais foram renomeadas para o novo padrão, conforme a tabela. Confira todas credenciais usadas em ambiente de desenvolvimento:

::: table-scroll
|Portal Use Rede|Credencial para OAuth 2.0|
|---------------|-------------------------|
|PV|clientId|
|Chave de Integração|clientSecret|
|Token de acesso dinâmico |access_token|
{.table-bordered table}
:::

**2.** Com essas credenciais, faça uma chamada ao endpoint de autenticação: https://api.userede.com.br/redelabs/oauth2/token

**3.** Essa chamada gera uma **access_token**, que será usado para tokenizar com a Rede

**4.** 0 **access_token** deve ser armazenado de forma segura, evitando exposição ou uso indevido

**5.** 0 **access_token** tem validade de 24 minutos. Após esse período, é necessário fazer uma nova chamada ao endpoint para gerar um novo token

### OAuth Authorization

![Fluxo de Tokenização](assets/images/e-rede/oauth-tkn.png){#img-fluxo-tokenizacao .content-image}


> **Informações sobre a Chave de Integração(clientSecret).**
>
>  Se você já possui uma Chave de integração, pode continuar usando a mesma.
>
>  Em caso de **perda ou esquecimento** da chave de integração, uma nova deverá ser gerada no [Portal Use Rede](https://www.userede.com.br/).
>
>  Para gerar a Chave, seu usuário precisa ter **perfil de administrador**. Acesse o menu:  _e-commerce_ > _chave de integração_ e clique em **“Gerar chave de integração”**.
>
> Se uma nova chave de integração for gerada, é necessário **atualizar imediatamente** no campo **clientSecret** da API para que o fluxo de  tokenização se mantenha.
{.content-info .with-icon}


## Como realizar autenticação no padrão OAuth 2.0

### Endpoint de Autenticação {#tokenizacao-bandeira-rede-autenticacao-rede-via-apis-endpoint .menu-nv2 .text-rede-black}

::: table-scroll
| Ambiente | URL para gerar Token |
| -------- | ------------------------------------------------------- |
| Sandbox | https://rl7-sandbox-api.useredecloud.com.br/oauth2/token |
| Produção | https://api.userede.com.br/redelabs/oauth2/token |
{.table-bordered table}
:::

## Autenticação

### Gerar access_token

Com o **clientId** e o **clientSecret**, é possível gerar o token de acesso dinâmico utilizando a chamada:

::: {.block-code}
```json
curl --request POST \
--url '{urlToken}' \
--header 'Authorization: Basic Base64(clientId:clientSecret)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials
```
:::

#### Headers:

::: table-scroll
| Parâmetro | Obrigatório | Descrição |
| -------- | ------------------------------------------------------- |
| Authorization | ✅ | Junte o client_id e o client_secret com dois-pontos (:) e converta o resultado para base64 |
| Content-Type | ✅ | application/x-www-form-urlencoded |
{.table-bordered table}
:::

#### Form:

::: table-scroll
| Parâmetro | Obrigatório | Descrição |
| -------- | ------------------------------------------------------- |
| grant_type | ✅ | Tipo de geração do token, com o valor fixo “client_credentials” |
{.table-bordered table}
:::

#### Response:

::: table-scroll
| Parâmetro | Obrigatório | Descrição |
| -------- | ------------------------------------------------------- |
| access_token | ✅ | Token usado para chamar as APIs da Rede, com duração padrão de 24 minutos |
| token_type | ✅ | Tipo do token gerado, padrão é "Bearer" |
| expires_in | ✅ | Tempo de expiração em segundos do access_token |
| scope | ✅ | Lista de escopos separados por espaço, representando os acessos concedidos à aplicação |
{.table-bordered table}
:::

## Tokenização{#tokenizacao-bandeira-rede-autenticacao-rede-via-apis-tokenizacao .menu-nv2 .text-rede-green}

### Utilizar o Token de acesso

Para utilizar a API de Tokenização da Rede, você deve:

**1.** Ter uma access_token gerado, para ser usado nas APIs de negócio

**2.** Atualizar o access_token gerado anteriormente

> **Header**
>
> Authorization: Bearer {access_token}.
{.content-info .with-icon}


>  **Atenção**{.text-rede-orange}
>
>O **access_token** deve ser armazenado com segurança.
>
> Como sua duração é de 24 minutos, uma nova chamada deverá ser feita antes desse período para atualizar a credencial.
>
> O token de acesso tem validade de 24 minutos e pode ser reutilizado durante esse período. Para evitar expiração, recomenda-se renová-lo entre 15 e 23 minutos após a emissão.
>
>A escolha de como realizar o chamado e atualizar os **access_token** gerados ficam sob sua responsabilidade.
{.content-info-orange .with-icon}

## Codificação OAuth

### UTF8

Configure sua aplicação para usar codificação UTF-8.

### Codificação de URL
A codificação URL é usada para codificar informações em URIs e usada também para dados do tipo application/x-www-formurlencoded, como em formulários HTML.

### JSON

JSON é o padrão usado para troca de dados entre sistemas. Para chamadas POST e PUT, é necessário especificar o cabeçalho:

::: {.block-code}
```json
Content-Type: application/json
```
:::

## Boas práticas de segurança
- Armazene o **access_token** em cache seguro e criptografado
- Evite expor o token em logs ou interfaces públicas
- Implemente controle de acesso para uso do token
- Utilize HTTPS em todas as chamadas às APIs da Rede

### Solicitação de tokenização {#documentacao-tokenizacao-bandeira-rede-solicitacao-tokenizacao .menu-nv3 .text-rede-green}

**Endpoint de Tokenização**

Os endpoints são as URLs que serão utilizadas para a chamada de determinados serviços de tokenização. Elas podem variar dependendo do ambiente e método HTTP. 

A composição é realizada da seguinte forma: 

- URL base 
- Versão da API
- Serviço

::: table-scroll
| Ambiente | URL |
| -------- | ------------------------------------------------------- |
| Sandbox | https://rl7-sandbox-api.useredecloud.com.br/token-service/oauth/v2/tokenization/ |
| Produção | https://api.userede.com.br/redelabs/token-service/oauth/v2/tokenization  |
{.table-bordered table}
:::

**Envio de solicitação de tokenização do cartão para a bandeira:**

> POST: **[/token-service/oauth/v2/tokenization](e-rede#operations-Tokenização-solicitarTokenizacao)** {.content-info}

**Parâmetros da requisição:**

O corpo da requisição (body) deve estar em formato JSON contendo os campos descritos na tabela abaixo:

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|----------- | --------- | ------------ | ----------- | :--------- |
| email | Até 200 | Alfanumérico | Sim | E-mail do portador do cartão, cliente ou estabelecimento comercial |
| cardNumber | Até 19 | Alfanumérico | Sim | Número do cartão |
| expirationMonth | 2 | Alfanumérico | Sim | Mês de vencimento do cartão (entre "01" e "12") |
| expirationYear | 4 | Alfanumérico | Sim | Ano de vencimento do cartão |
| cardholderName | Até 200 | Alfanumérico | Não | Nome do portador impresso no cartão |
| securityCode | Até 4 | Alfanumérico | Não | Código de segurança localizado no verso do cartão |
| storageCard | Até 2 | Numérico | Sim | Indica operações que possam ou não estar utilizando COF (Card on File): |\
| | | | | |\
| | | | | 0 - Transação com credencial não armazenada. |\
| | | | | |\
| | | | | 2 - Transação com credencial já armazenada. |\
| | | | | |\
| | | | | **Para transações tokenizadas este parâmetro deve ter o valor “2”.** |
| kind | \- | Alfanumérico | Não |Tipo de transação a ser realizada: |\
| | | | | |\
| | | | | - Para transações de crédito, utilizar **credit** |\
| | | | | |\
| | | | | - Para transações de débito, utilizar **debit** |\
| | | | | |\
| | | | | O não envio desse campo será considerado crédito. |
| embeddedZeroDollar | \- | Booleano | Não | Ao armazenar um cartão, a realização do zero dollar e obrigatória. Por isso, recomenda-se enviar o campo como true. Caso o cartão já tenha sido armazenado anteriormente e o estabelecimento não possua o CVV, o campo pode ser enviado como false, evitando a execução do zero dollar. Se o campo não for enviado, o zero dollar será realizado automaticamente. |
{.table-bordered}
:::

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|--------------- | ------- | ------------ | ----------------------------------- |
| returnCode | Até 3 | Alfanumérico | Código de retorno da solicitação |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da solicitação|
| tokenizationId | 36 | Alfanumérico | Identificador único da solicitação de tokenização do cartão pela Rede |
{.table-bordered}
:::

### Cadastro da URL para receber as atualizações do token via webhook{#documentacao-tokenizacao-bandeira-rede-cadastro-url-receber-atualizacoes-token-via-webhook .menu-nv3}

Após a contratação do serviço de tokenização de bandeira no portal [“userede.com.br”](https://www.userede.com.br/), será possível cadastrar a URL para receber as atualizações do token via webhook. Basta acessar o menu vender online > e-Commerce > tokenização de bandeira > cadastro de url e fazer o cadastro.

**IMPORTANTE:** Caso a url de notificações não seja informada, nenhum evento será entregue durante o processo de tokenização. Além disso, a Rede não se responsabiliza pelo cadastro de URls inválidas por parte do estabelecimento.

#### URLs Autenticadas e Não Autenticadas

A REDE deve ser informada durante o cadastro se a URL possui autenticação ou não.

- URL Sem Autenticação:

Neste caso a Rede não fará nenhum tipo de verificação de segurança antes de entregar o evento na url informada.

- URL Com Autenticação:

A Rede possibilita a utilização de autenticação basic ou bearer e em ambos os casos o token de acesso deve ser cadastrado no portal, no momento do cadastro da url.

#### Ponto de Atenção:

A URL cadastrada será utilizada para todos os PVs cadastrados no mesmo CNPJ.

### Callback realizado pelo webhook{#documentacao-tokenizacao-bandeira-rede-callback-webhook .menu-nv3}

Após a solicitação de tokenização do cartão, quando a bandeira finalizar a geração do token, será enviado um evento para a url cadastrada no portal da Rede.

Eventos também serão enviados quando houver alguma atualização no token, como por exemplo, se ele for excluído devido ao cancelamento do cartão. Ou então, caso o cartão original seja atualizado.

As tentativas de notificações de evento são de 12 vezes a cada 30 segundos, após isso é tentado de 1 em 1 hora por 14 dias.

Após o recebimento do evento é essencial que o estabelecimento faça uma consulta daquele token, para identificar qual foi a atualização sofrida. Não será informado no evento a atualização.

**Nota:** No ambiente sandbox, esse callback será realizado 2 minutos após o envio da solicitação de tokenização.

**Os parâmetros recebidos no evento serão:**

::: table-scroll
| Nome | Local de envio | Tamanho | Tipo | Descrição |
|-------------------- | -------------- | -------- | ------------------ | ----------------------------------- |
| authorization | header | Até 3 | Alfanumérico | Header para autorização da requisição na url fornecida pelo estabelecimento através do portal logado. |
| request-ID | header | Até 36 | Alfanumérico | Identificador único da requisição |
| content-Type | header | - | Alfanumérico | Valor fixo definido como 'application/json' |
| id | body | 6 | Alfanumérico | Identificador único do callback |
| merchantId | body | 9 | Alfanumérico | Número de filiação do estabelecimento (PV) |
| events | body | \- | Lista alfanumérica | Nome dos eventos que serão informados ao cliente.|\
||||||\
||||| Exemplo: ["PV.TOKENIZACAO-BANDEIRA"] |
| data/tokenizationId | body | Até 36 | Alfanumérico | Token do cartão|
{.table-bordered}
:::

**Exemplo do evento:**
::: {.block-code}

```json
{
  "id": "123456",
  "merchant_id": "123415678",
  "events": ["PV.TOKENIZACAO-BANDEIRA"],
  "data": {
    "tokenizationId": "0c299dab-2b7a-41a1-8514-e54f9dd18297"
  }
}
```

:::

### Consulta do token{#documentacao-tokenizacao-bandeira-rede-consulta-token .menu-nv3}

A consulta à solicitação de tokenização pode ser feita logo após a obtenção do tokenizationId da Rede será sempre realizada quando o Estabelecimento Comercial receber um evento pelo webhook, onde será possível ver o status da solicitação e demais informações listadas abaixo.

Requisição para a consulta dos dados da solicitação de tokenização:

> GET: **[/token-service/oauth/v2/tokenization/{tokenizationId}](e-rede#operations-Tokenização-consultarTokenizacaoPorTokenizationId)** {.content-info}

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|--------------- | ------- | ------------ | :----------------------------------- |
| returnCode | Até 3 | Alfanumérico | Código de retorno da solicitação |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da solicitação |
| affiliation | Até 9 | Numérico | Número de filiação do estabelecimento (PV) |
| tokenizationId | 36 | Alfanumérico | Token do cartão |
| tokenizationStatus | \- | Alfanumérico | Status da solicitação de tokenização: |\
| | | | - Pending |\
| | | | - Active |\
| | | | - Inactive |\
| | | | - Suspended |\
| | | | - Failed |\
| | | | - Delete |
| brand/name | - | Alfanumérico | Nome da bandeira do BIN do cartão enviado na solicitação de tokenização |
| brand/message | Até 256 | Alfanumérico | Mensagem de retorno da bandeira em caso de falha na solicitação do token para um determinado cartão. |\
| | | | |\
| | | | O tokenizationStatus nesse cenário será Failed e as informações de token não estarão disponíveis
| brand/brandTid | Até 21 | Alfanumérico | Correlaciona a primeira e demais transações através do envio deste campo. Para mais detalhes consulte a seção [Recorrência e Card-on-file](e-rede#documentacao-recorrencia)||
| lastModifiedDate | - | Datetime | Data da última atualização do registro no formato YYYY-MM-DDThh:mm:ssTZD |
| bin | Até 9 | Alfanumérico | 2 a 9 primeiros dígitos do cartão |
| last4 | 4 | Alfanumérico | 4 últimos dígitos do cartão |
| token/code | Até 16 | Numérico | Número do token do cartão decriptografado, gerado pela bandeira |
| token/expirationDate | 7 | Alfanumérico | Data de expiração (no formato MM/YYYY) do token gerado pela bandeira para o cartão enviado |
{.table-bordered}
:::

### Gestão do token{#documentacao-tokenizacao-bandeira-rede-gestao-token .menu-nv3}

Após a criação do token é possível gerenciar o status dele. Isto é, o estabelecimento tem autonomia para deletar, suspender e reativar os tokens sob sua responsabilidade.

**Importante:** a gestão e o compartilhamento de tokens é realizada por CNPJ raiz, abrangendo todos os PVs vinculados ao mesmo CNPJ.

> PUT: **[/token-service/oauth/v2/tokenization/{tokenizationId}](e-rede#operations-Tokenização-solicitarTokenizacao)** {.content-info}

#### Parâmetros de Requisição

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|----------- | --------- | ------------ | ----------- | :--------- |
| tokenizationStatus | 100 | Alfanumérico | Sim | Se o status atualizado para qual o do token for **deletar, será o delete**: |\
| | | | | |\
| | | | | Se o status atualizado para qual o do token for **suspender, será o suspend** |\
| | | | | |\
| | | | | Se o status atualizado para qual o do token for **reativar, será o resume** |
| reason | 2 | Numérico | Sim |Motivo da atualização: |\
| | | | | |\
| | | | | 1 - Solicitação do Cliente |\
| | | | | |\
| | | | | 2 - Suspeita de Fraude |
{.table-bordered}
:::

Caso a alteração do token ocorra com sucesso os seguintes campos serão retornados:

#### Parâmetros de Resposta

Caso a alteração do token ocorra com sucesso os seguintes campos serão retornados:

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|--------------- | ------- | ------------ | :---------------------------------------------------------- |
| returnCode | Até 3 | Alfanumérico | Código de retorno da solicitação |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da solicitação |
| tokenizationId | 36 | Alfanumérico | Token do cartão, que deve ser armazenado e utilizado em futuras transações |
| Brand/name* | - | Alfanumérico | Nome da bandeira. Ex: Visa |
| Brand/message* | - | Alfanumérico | Mensagem de erro da bandeira. Ex: Card not allowed. \*Esse campo só é retornado em caso de erro na tokenização de bandeira
{.table-bordered}
:::

### Criptograma{#documentacao-tokenizacao-bandeira-rede-criptograma .menu-nv3}

Toda transação com token de bandeira precisará de um criptograma, que será enviado no parâmetro tokenCryptogram. Este criptograma é de uso único e não pode ser reutilizado, visto que sua intenção é trazer uma camada adicional de segurança para a transação.

Para um token excluído ou suspenso um criptograma não poderá ser solicitado.

A bandeira Visa permite a solicitação de até 6.000 criptogramas, para um mesmo token, dentro de uma janela de 90 dias.

A geração do criptograma é feita de forma síncrona, basta enviar a seguinte requisição:

> POST: **[/token-service/oauth/v2/cryptogram/{tokenizationId}](e-rede#operations-Tokenização-consultarCriptogramaPorTokenizationId)** {.content-info}

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|--------------- | ------- | ------------ | ------------| ---------------------- |
| subscription | \- | Booleano | Não | Informa ao emissor se uma transação é proveniente de uma recorrência. |\
| | | | | |\
| | | | | Se transação for uma recorrência, enviar **true**. Caso contrário, envie **false**. |\
| | | | | |\
| | | | |O não envio desse campo será considerado o valor **false**. |
{.table-bordered}
:::

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
|-------------------------------- | ------- | ------------ | :----------------------------------- |
| returnCode | Até 3 | Alfanumérico | Código de retorno da solicitação |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da solicitação |
| tokenizationId | 36 | Alfanumérico | Identificador único da solicitação de tokenização do cartão pela Rede |
| cryptogramInfo/tokenCryptogram | 28 | Alfanumérico | Criptograma do token gerado pela bandeira no processo de solicitação de tokenização do cartão. Valor no formato Base64, com quantidade máxima de 28 caracteres |
| cryptogramInfo/eci | 2 | Alfanumérico | Código retornado pelas Bandeiras que indica o resultado da autenticação do portador junto ao Emissor. |
| cryptogramInfo/expirationDate\*\* | 24 | Datetime | Data de expiração (no formato YYYY-MM-DDThh:mm:ss.sssZ) do criptograma do token gerado pela bandeira para o cartão enviado |
{.table-bordered}
:::

**cryptogramInfo/expirationDate\*\*:** A data de expiração do criptograma do token pode não ser retornada por algumas bandeiras.

### Gerando transações com uso de tokens de bandeira{#documentacao-tokenizacao-bandeira-rede-gerando-transacoes-uso-token .menu-nv3}

Após a criação do token (tokenizationId), é possível criar transações, onde esse parâmetro irá substituir os dígitos reais do cartão do portador pelo Token criado na bandeira.

URL de ambientes transacionais:
::: table-scroll
| Ambiente | URL |
|--------- | ----------------------------------------------------------------- |
| Sandbox | https://sandbox-erede.useredecloud.com.br/v2/transactions |
| Produção | https://api.userede.com.br/erede/v2/transactions |
{.table-bordered}
:::

**Exemplo de uma requisição com Token de Bandeira:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|----------- | --------- | ------------ | ----------- | :--------- |
| capture | - | Booleano | Não | Defina se uma transação terá captura automática ou posterior. O não envio desse campo será considerado uma captura automática **(true)**. |
| kind | \- | Alfanumérico | Não | Tipo de transação a ser realizada. |\
| | | | | - Para transações de crédito, utilizar **credit** |\
| | | | | - Para transações de débito, utilizar **debit** |\
| | | | | |\
| | | | | O não envio desse campo será considerado crédito. |
| reference | Até 50 | Alfanumérico | Sim | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Não| Código do pedido gerado pelo estabelecimento. (Não aceita caracteres especiais) |
| amount | Até 10 | Numérico | Sim | Valor total da transação sem separador de milhar e decimal. |\
| | | | | |\
| | | | | Exemplos:|\
| | | | | - R$10,00 = 1000 |\
| | | | | - R$0,50 = 50 |
| installments | Até 2 | Numérico | Não | Número de parcelas em que uma transação será autorizada. |\
| | | | | |\
| | | | | De 2 a 12 |\
| | | | | |\
| | | | | O não envio desse campo será considerado à vista. |
| cardholderName | Até 30 | Alfanumérico | Não | Nome do portador impresso no cartão. |
| cardNumber | Até 19 | Alfanumérico | Sim | Número do token. |
| expirationMonth | Até 2 | Numérico | Sim | Mês de vencimento do token. De 1 a 12. |
| expirationYear | 2 ou 4 | Numérico | Sim | Ano de vencimento do token. |\
| | | | | |\
| | | | | Exemplo: 2028 ou 28 |
| securityCode | Até 4 | Alfanumérico | Não | Código de segurança do cartão geralmente localizado no verso do cartão. |
| tokenCryptogram | \- | Alfanumérico | Obrigatório para CIT e Opcional para MIT | Criptograma do token gerado pela Bandeira no momento de solicitação do criptograma do token criado. Valor no formato Base64, com quantidade máxima de 28 caracteres. |\
| | | | | |\
| | | | | Nas transações iniciadas pelo portador (CIT) este campo é obrigatório, mas em transações iniciadas pelo estabelecimento (MIT) é opcional. |
| storageCard | Até 1 | Alfanumérico | Não | Indica operações que possam ou não estar utilizando COF (Card on File): |\
| | | | | |\
| | | | | 0 - Transação com credencial não armazenada. |\
| | | | | |\
| | | | | 1 - Transação com credencial armazenada pela primeira vez. |\
| | | | | |\
| | | | | 2 - Transação com credencial já armazenada. |\
| | | | | |\
| | | | | Para transações tokenizadas este parâmetro deve ter o valor “2”. |\
| | | | | |\
| | | | | Atenção: O não envio desse campo será considerado 0 (credencial não armazenada).|
| securtityAuthentication | - | - | - | Grupo securityAuthentication |
| sai | Até 02 | Alfanumérico | Obrigatório para as bandeiras Visa e ELO. Opcional em transações card-on-file | Identificador de transação eletrônica (ECI). Para transações da bandeira Mastercard, esse campo não é enviado. Nas transações que não forem tokenizadas (apenas card-on-file) o envio deste campo não é necessário. Para mais detalhes desse campo verifique o tópico “uso do sai”. |
| transactionCredentials | - | - | - | Grupo transactionCredentials |
| transactionCredentials/ credentialId | Até 02 | Alfanumérico | Sim, se storageCard=1 ou =2 e cartão mastercard | Indica a categoria da transação com credencial armazenada. Consulte a seção [“Categorização de transações card-on-file”](e-rede#documentacao-recorrencia-categorizacao-transacoes-card-on-file) para mais detalhes |
{.table-bordered}
:::

**Ponto de atenção:** É possível utilizar a Tokenização de Bandeira Rede somente com as seguintes mensagerias e produtos:

- [3DS MPI Rede](https://developer.userede.com.br/e-rede#documentacao-3d-secure2-0-3d-secure2-0-mpi-rede)
- [3DS MPI Cliente](https://developer.userede.com.br/e-rede#documentacao-3d-secure2-0-3d-secure2-0-mpi-cliente)
- [Data Only MPI Rede](https://developer.userede.com.br/e-rede#documentacao-data-only-data-only-mpi-rede)
- [Data Only MPI Cliente](https://developer.userede.com.br/e-rede#documentacao-data-only-data-only-mpi-cliente)
- [Recorrência e Card-on-File](https://developer.userede.com.br/e-rede#documentacao-recorrencia)
- [Mcc dinâmico](https://developer.userede.com.br/e-rede#documentacao-mcc-dinamico)
- [SDWO](https://developer.userede.com.br/e-rede#documentacao-carteiras-digitais-operadoras-carteiras-digital-escalonada-SDWO)
- [Voucher](https://developer.userede.com.br/e-rede#documentacao-voucher)
- [Zero Dollar](https://developer.userede.com.br/e-rede#documentacao-zero-dollar)

As mensagerias podem ser utilizadas em conjunto ou individualmente.

**Uso do “sai”:** O parâmetro deverá ser utilizado sempre que a transação possuir um ECI específico, que não esteja atrelado a autenticação 3DS (ex: Wallets e Cloud Token Visa), **quando autenticado como 3DS faz-se necessário que o “eci” seja informado dentro do grupo 3D Secure, não sendo necessária a utilização do “sai” neste caso.**

**Atenção:** Ao fazer o envio do grupo threeDSecure em qualquer requisição, o campo “sai” será ignorado e a prioridade será do fluxo de 3DS.

**Envio do securityCode**: Para a bandeira Visa, o envio do código de segurança incorreto fará com que a transação seja negada.

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
| ------------------------ | ------- | ------------ | :-------- |
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | 20 | Alfanumérico | Número identificador único da transação.|
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| dateTime | - | Datetime | Data da transação no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| amount | Até 10 | Numérico | Valor total do pedido sem separador de milhar e decimal. |\
| | | | |\
| | | | Exemplos: |\
| | | | - R$10,00 = 1000 |\
| | | | - R$0,50 = 50 |
| cardBin | 6 | Alfanumérico | 6 primeiros dígitos do cartão. |
| last4 | 4 | Alfanumérico | 4 últimos dígitos do cartão. |
| returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand | - | - | Grupo de informações recebidas da bandeira sobre a transação. |
| brand/name | - | Alfanumérico | Nome da bandeira. Ex: Mastercard. |
| brand/returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| brand/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand/merchantAdviceCode | Até 2 | Alfanumérico | Código de Aviso para Estabelecimento Comercial. É um conjunto de códigos usado para fornecer informações adicionais sobre uma resposta de transação de uso exclusivo da bandeira Mastercard. |
| brand/authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| brand/brandTid | Até 21 | Alfanumérico | Código identificador da transação na respectiva bandeira. Para mais detalhes consulte a seção [Recorrência e Card-on-file](e-rede#documentacao-recorrencia) |
{.table-bordered}
:::

Para maiores informações sobre o fluxo transacional verifique na Lista de APIs, conforme indicado a seguir:

> Selecione o tipo "Tokenização de Bandeiras" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}

**Notas:**
1.Para informações sobre autenticação, autorização e configurações na API transacional da Rede acesse a seção [Autenticação e Autorização](e-rede#primeiros-passos-autenticacao-e-autorizacao).

2.Para mais combinações transacionais confira a seção [Sobre](e-rede#sobre-biblioteca-sobre).

### Tokenização de Bandeira externa (captura) {#documentacao-tokenizacao-bandeira-externa .menu-nv2}

O serviço de Tokenização de Bandeira é prestado por um Token Requestor, sua utilização pode melhorar a conversão junto a bandeira, pois no caso de cartões tokenizados as informações do cartão são protegidas com a devida segurança, substituindo-as por um token. Cada token é único para o usuário e estabelecimento e não pode ser usado por nenhuma outra loja. 

Ao realizar a transação, um criptograma é enviado juntamente com o token, impedindo clonagens de cartão e operações fraudulentas. O emissor identifica o uso do token e confirma a autenticidade do criptograma, autorizando assim a transação, pois sabe que é do portador genuíno. 

Atualmente, a Rede já está preparada para **transacionar** utilizando token das bandeiras Mastercard e Visa. O serviço que promoverá a Tokenização de bandeira provisionada pela Rede já está disponível na bandeira Visa e Mastercard, confira no menu [Tokenização de Bandeira Rede](e-rede#documentacao-tokenizacao-bandeira-rede).

Para transacionar os criptogramas gerados por qualquer Token Requestor no e.Rede, verifique os campos necessários abaixo e na Lista de APIs, conforme indicado a seguir:

Para transações que não sejam de Wallets, o envio do campo tokenCryptogram é obrigatório em todas as transações iniciadas pelo portador (CIT), mas opcional em transações iniciadas pelo estabelecimento (MIT). 

**Parâmetros da requisição:**

::: table-scroll
| Nome | Tamanho | Tipo | Obrigatório | Descrição |
|----------- | --------- | ------------ | ----------- | :--------- |
| capture | - | Booleano | Não | Defina se uma transação terá captura automática ou posterior. O não envio desse campo será considerado uma captura automática **(true)**. |
| kind | \- | Alfanumérico | Não | Tipo de transação a ser realizada. |\
| | | | | - Para transações de crédito, utilizar **credit** |\
| | | | | - Para transações de débito, utilizar **debit** |\
| | | | | |\
| | | | | O não envio desse campo será considerado crédito. |
| reference | Até 50 | Alfanumérico | Sim | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Não | Código do pedido gerado pelo estabelecimento. (Não aceita caracteres especiais) |
| amount | Até 10 | Numérico | Sim | Valor total da transação sem separador de milhar e decimal. |\
| | | | | |\
| | | | | Exemplos:|\
| | | | | - R$10,00 = 1000 |\
| | | | | - R$0,50 = 50 |
| installments | Até 2 | Numérico | Não | Número de parcelas em que uma transação será autorizada. |\
| | | | | |\
| | | | | De 2 a 12 |\
| | | | | |\
| | | | | O não envio desse campo será considerado à vista. |
| cardholderName | Até 30 | Alfanumérico | Não | Nome do portador impresso no cartão. |
| cardNumber | Até 19 | Alfanumérico | Sim | Número do token. |
| expirationMonth | Até 2 | Numérico | Sim | Mês de vencimento do token. De 1 a 12. |
| expirationYear | 2 ou 4 | Numérico | Sim | Ano de vencimento do token. |\
| | | | | |\
| | | | | Exemplo: 2028 ou 28 |
| securityCode | Até 4 | Alfanumérico | Não | Código de segurança do cartão geralmente localizado no verso do cartão. |
| tokenCryptogram | \- | Alfanumérico | Obrigatório para CIT e opcional para MIT | Criptograma do token gerado pela Bandeira no momento de solicitação do criptograma do token criado. Valor no formato Base64, com quantidade máxima de 28 caracteres. |\
| | | | | |\
| | | | | Nas transações iniciadas pelo portador (CIT) este campo é obrigatório, mas em transações iniciadas pelo estabelecimento (MIT) é opcional. |
| storageCard | Até 1 | Alfanumérico | Não | Indica operações que possam ou não estar utilizando COF (Card on File): |\
| | | | | |\
| | | | | 0 - Transação com credencial não armazenada. |\
| | | | | |\
| | | | | 1 - Transação com credencial armazenada pela primeira vez. |\
| | | | | |\
| | | | | 2 - Transação com credencial já armazenada. |\
| | | | | |\
| | | | | Para transações tokenizadas este parâmetro deve ter o valor “2”. |\
| | | | | |\
| | | | | Atenção: O não envio desse campo será considerado 0 (credencial não armazenada).|
| securtityAuthentication | - | - | - | Grupo securityAuthentication |
| sai | Até 02 | Alfanumérico | Obrigatório para as bandeiras Visa e ELO. Opcional em transações card-on-file | Identificador de transação eletrônica (ECI). Para transações da bandeira Mastercard, esse campo não é enviado. Nas transações que não forem tokenizadas (apenas card-on-file) o envio deste campo não é necessário. Para mais detalhes desse campo verifique o tópico “uso do sai”. |
| transactionCredentials | | | | Grupo transactionCredentials |
| transactionCredentials/ credentialId | Até 02 | Alfanumérico | Sim, se storageCard=1 ou =2 e cartão mastercard | Indica a categoria da transação com credencial armazenada. Consulte a seção [“Categorização de transações card-on-file”](e-rede#documentacao-recorrencia-categorizacao-transacoes-card-on-file) para mais detalhes |
{.table-bordered}
:::

**Ponto de atenção:** É possível utilizar a Tokenização de Bandeira Externa (Captura) somente com as seguintes mensagerias e produtos:

- [3DS MPI Rede](https://developer.userede.com.br/e-rede#documentacao-3d-secure2-0-3d-secure2-0-mpi-rede)
- [3DS MPI Cliente](https://developer.userede.com.br/e-rede#documentacao-3d-secure2-0-3d-secure2-0-mpi-cliente)
- [Data Only MPI Rede](https://developer.userede.com.br/e-rede#documentacao-data-only-data-only-mpi-rede)
- [Data Only MPI Cliente](https://developer.userede.com.br/e-rede#documentacao-data-only-data-only-mpi-cliente)
- [Recorrência e Card-on-File](https://developer.userede.com.br/e-rede#documentacao-recorrencia)
- [Mcc dinâmico](https://developer.userede.com.br/e-rede#documentacao-mcc-dinamico)
- [SDWO](https://developer.userede.com.br/e-rede#documentacao-carteiras-digitais-operadoras-carteiras-digital-escalonada-SDWO)
- [Voucher](https://developer.userede.com.br/e-rede#documentacao-voucher)
- [Zero Dollar](https://developer.userede.com.br/e-rede#documentacao-zero-dollar)

As mensagerias podem ser utilizadas em conjunto ou individualmente.

### Uso do sai {#documentacao-tokenizacao-bandeira-externa-uso-sai .menu-nv3}

O parâmetro deverá ser utilizado sempre que a transação possuir um ECI específico, que não esteja atrelado a autenticação 3DS (ex: Wallets e Cloud Token Visa), **quando autenticado como 3DS faz-se necessário que o “eci” seja informado dentro do grupo 3D Secure, não sendo necessária a utilização do “sai” neste caso.**

**Atenção:** Ao fazer o envio do grupo threeDSecure em qualquer requisição, o campo “sai” será ignorado e a prioridade será do fluxo de 3DS.

**Envio do securityCode**: Para a bandeira Visa, o envio do código de segurança incorreto fará com que a transação seja negada.

**Parâmetros da resposta:**

::: table-scroll
| Nome | Tamanho | Tipo | Descrição |
| ------------------------ | ------- | ------------ | :-------- |
| reference | Até 50 | Alfanumérico | Código da transação gerado pelo estabelecimento. |
| orderId | Até 50 | Alfanumérico | Código do pedido gerado pelo estabelecimento. |
| tid | 20 | Alfanumérico | Número identificador único da transação.|
| nsu | Até 12 | Alfanumérico | Número sequencial retornado pela Rede. |
| authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| dateTime | - | Datetime | Data da transação no formato YYYY-MM-DDThh:mm:ss.sTZD . |
| amount | Até 10 | Numérico | Valor total do pedido sem separador de milhar e decimal. |\
| | | | |\
| | | | Exemplos: |\
| | | | - R$10,00 = 1000 |\
| | | | - R$0,50 = 50 |
| cardBin | 6 | Alfanumérico | 6 primeiros dígitos do cartão. |
| last4 | 4 | Alfanumérico | 4 últimos dígitos do cartão. |
| returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand | - | - | Grupo de informações recebidas da bandeira sobre a transação. |
| brand/name | - | Alfanumérico | Nome da bandeira. Ex: Mastercard. |
| brand/returnCode | Até 4 | Alfanumérico | Código de retorno da transação. |
| brand/returnMessage | Até 256 | Alfanumérico | Mensagem de retorno da transação. |
| brand/merchantAdviceCode | Até 2 | Alfanumérico | Código de Aviso para Estabelecimento Comercial. É um conjunto de códigos usado para fornecer informações adicionais sobre uma resposta de transação de uso exclusivo da bandeira Mastercard. |
| brand/authorizationCode | 6 | Alfanumérico | Número da autorização da transação retornada pelo emissor do cartão. |
| brand/brandTid | Até 21 | Alfanumérico | Código identificador da transação na respectiva bandeira. Para mais detalhes consulte a seção [Recorrência e Card-on-file](e-rede#documentacao-recorrencia) |
{.table-bordered}
:::

Para maiores informações sobre o fluxo transacional verifique na Lista de APIs, conforme indicado a seguir:

> Selecione o tipo "Tokenização de Bandeiras" no combo box "Examples" da requisição.
>
> POST: **[/v2/transactions](e-rede#operations-Transação-realizarTransacao)** {.content-info .with-icon}
> :::