Armazenamento de cartão REST

Visão Geral

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

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

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

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

Detalhes da chamada

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

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

Fluxo

Exemplos

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

Armazenamento de cartão

Requisição:

Cartão

Carteira Digital

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

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

Resposta:

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

Parâmetros de requisição

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

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

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

Parâmetros de resposta

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

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