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

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

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

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

Criação da captura origem externa

Detalhes da Chamada

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

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

Exemplos

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

Requisição:

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

Resposta:

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

Parâmetros de Requisição

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

Legenda do tipo do campo "Tamanho":

A = alfanumérico

N = numérico

N A = não utilizado

Parâmetros de resposta

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

Efetivação da captura origem externa

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

Parâmetros de Requisição

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

Legenda do tipo do campo "Tamanho":

A = alfanumérico

N = numérico

N A = não utilizado

Nota:

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

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

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

Exemplo

Requisição:

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

Resposta:

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