Serviço de confirmação de pagamento de origem externa

Introdução#

A funcionalidade de confirmação de pagamento de origem externa permite que uma transação de pagamento criada fora do e-SiTef possa ser confirmada dentro do e-SiTef.

Atualmente esta funcionalidade permite somente a confirmação de transações de pagamento realizadas no SiTef.

Esta operação se divide em duas etapas:

  1. A criação de uma transação do tipo "Confirmação" que represente a transação real de pagamento criada externamente
  2. A confirmação propriamente dita do pagamento dessa transação

Caso de sucesso

O fluxo abaixo ilustra o caminho feliz, onde a transação é iniciada e, em seguida, a confirmação já é enviada.

Criação da confirmação de pagamento de origem externa#

Detalhes da Chamada#

  • Recurso: /v1/transactions
  • Método HTTP: POST
  • Formato da requisição: JSON
  • Formato da resposta: JSON
  • Parâmetros de cabeçalho:
ParâmetroDescriçãoFormatoObrigatório
merchant_idCódigo da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.< 15 ANSIM
merchant_keyChave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.< 80 ANSIM
Content-TypeDeve ser enviado com o valor application/json.= 15 ANSIM

Exemplo#

Requisição:

curl --location --request POST 'https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions'
--header 'merchant_id: xxxxxxxxxxxxxxxxxx'
--header 'merchant_key: xxxxxxxxxxxxxxxxxx'
--header 'Content-Type: application/json'
--data-raw '{
"merchant_usn": "21042858195",
"order_id": "1621949459257",
"amount": "300",
"transaction_type": "confirmation",
"is_transaction_origin_external": "true"
}'
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"confirmation": {
"status": "PPC",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "1621949459257",
"merchant_usn": "21042858195",
"amount": "300"
}
}

Parâmetros da requisição#

A tabela abaixo mostra os campos para a criação transação de confirmação de pagamento de origem externa.

Nome do ParâmetroDescriçãoTamanhoObrigatório
amountValor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto< 12NSIM
merchant_usnNú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 NNÃO
order_idCó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 ANNÃO
transaction_typeConstante fixa e obrigatória para o tipo de transação de confirmação de pagamento de origem externa. Valor = confirmation< 15 NSIM
is_transaction_origin_externalConstante fixa e obrigatória para o tipo de transação de confirmação de pagamento de origem externa. Valor = true< 5 T/FSIM

Parâmetros de resposta#

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

ParâmetroDescriçãoFormato
codeCódigo de resposta do e-SiTef. Qualquer código diferente de 0 significa falha. Saiba mais.< 4 N
messageMensagem de resposta do e-SiTef.< 500 AN
payment
statusStatus da transação de pagamento no e-SiTef. Saiba mais.= 3 AN
nitIdentificador da transação de pagamento no e-SiTef.= 64 AN
order_idCódigo de pedido enviado pela loja na criação da transação.< 40 AN
merchant_usnNúmero sequencial único enviado pela loja na criação da transação.< 12 N
amountValor da compra especificado pela loja (em centavos) na criação da transação.< 12 N

Efetivação da confirmação de pagamento de origem externa#

Detalhes da chamada#

  • Recurso: /v1/payments/{nit}
  • Método HTTP: PUT
  • Formato da requisição: JSON e query string
  • Formato da resposta: JSON
  • Parâmetros de cabeçalho:
ParâmetroDescriçãoFormatoObrigatório
merchant_idCódigo da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.< 15 ANSIM
merchant_keyChave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.< 80 ANSIM
Content-TypeDeve ser enviado com o valor application/json.= 15 ANSIM

Exemplo#

Requisição:

curl --location --request PUT 'https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/bacd62eb62c27f4bf2eae9cef74c93a02e831985eccb6de371628fd272ee5474?confirm=true'
--header 'merchant_id: xxxxxxxxxxxxxx'
--header 'merchant_key: xxxxxxxxxxxxx'
--header 'Content-Type: application/json'
--data-raw '{
"authorizer_id": "1",
"installments": "1",
"installment_type": "4",
"confirmation_data": "123456789012",
"acquirer": {
"routing_id": "5",
"authorization_number": "212991",
"identification_number": "11111111111",
"order_id": "1621949459257",
"authorizer_date": "21/05/2021",
"host_usn": "000212991 ",
"terminal": "HA000006",
"company_code": "00000000"
}
}'
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "130",
"status": "CON",
"acquirer_id": "5",
"host_usn": "000212991 "
}
}

Parâmetros na requisição - query string#

ParâmetroDescriçãoFormatoObrigatório
confirmEste campo deve ser enviado com o valor true caso se deseje confirmar o pagamento, ou false, caso queira desfazer o pagamento.< 5 T/FSIM

Parâmetros da requisição - JSON#

ParâmetroDescriçãoFormatoObrigatório
amountValor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto. Se não informado, assume o valor informado na criação da transação.< 12 NNÃO
authorizer_idCódigo da autorizadora no e-SiTef. Saiba mais.< 3 NSIM
installmentsNúmero de parcelas. Envie ‘1’ para transações à vista.< 2 NNÃO(*)
installment_typeTipo de financiamento do parcelamento:
valor 3 = parcelamento com juros da administradora do cartão.
valor 4 = parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista).
Valor 6 = parcelamento com juros da administradora (IATA).
valor 7 = parcelamento realizado pela loja e sem juros (IATA).
O parcelamento IATA é utilizado somente por empresas do seguimento de transporte aéreo.
< 2 NNÃO(*)
confirmation_dataInformação de pagamento devolvida pelo SiTef ao se efetivar um pagamento. Este parâmetro é fundamental para o sucesso da confirmação. Ele é usada pelo SiTef para identificar o pagamento.< 128 ANSIM
acquirer
routing_idInformação do roteamento utilizado para o pagamento efetuado fora do e-SiTef. Este parâmetro é fundamental para o sucesso da confirmação. Esta informação é utilizada para identificar o roteamento no SiTef.< 5 NSIM
order_idCódigo de pedido enviado pela loja na criação da transação.< 40 ANNÃO(*)
host_usnNSU do host/autorizadora da transação a ser confirmada.= 9 NNÃO(*)
authorization_numberNúmero de autorização da transação a ser confirmada.< 6 NNÃO(*)
authorizer_dateData de efetivação SiTef do pagamento no formato DD/MM/AAAA.= 10 DNÃO(*)
order_idCódigo do pedido usado no pagamento iniciado externamente ao e-SiTef.< 40 ANNÃO(*)
identification_numberCPF ou CNPJ usado no pagamento iniciada externamente ao e-SiTef.< 20 ANNÃO(*)
terminalTerminal SiTef que se deseja usar. Se NÃO for enviado, o e-SiTef gerará um terminal aleatório.= 8 ANNÃO(*)
company_codeCó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 NNÃO(*)

Nota: Os campos assinalados com NÃO(*) são opcionais e, se informados, não terão como ser consistidos pelo e-SiTef, pois, na operação de confirmação eles não são enviados para o SiTef. Estes campos, se informados, serão gravados na transação para fins de registro apenas.

Parâmetros de resposta#

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

ParâmetroDescriçãoFormato
codeCódigo de resposta do e-SiTef. Qualquer código diferente de 0 significa falha. Saiba mais.< 4 N
messageMensagem de resposta do e-SiTef.< 500 AN
payment
statusStatus da transação de pagamento no e-SiTef. Saiba mais.= 3 AN
payment_dateData de efetivação do pagamento no e-SiTef no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03= 16 D
host_usnNSU da autorizadora.< 15 AN