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 Carat possa ser confirmada dentro do Carat.

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

Esta operação se divide em duas etapas:

A criação de uma transação do tipo "Confirmação" que represente a transação real de pagamento criada externamente
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âmetro	Descrição	Formato	Obrigatório
`merchant_id`	Código da loja no Carat. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
`merchant_key`	Chave de autenticação da loja no Carat. 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

Exemplo#

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br

curl --location --request POST 'https://{{url}}/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â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
`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 Carat, é 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 Carat, no SiTef ele será apenas 123456789012).	< 40 AN	NÃO
`transaction_type`	Constante fixa e obrigatória para o tipo de transação de confirmação de pagamento de origem externa. Valor = `confirmation`	< 15 N	SIM
`is_transaction_origin_external`	Constante fixa e obrigatória para o tipo de transação de confirmação de pagamento de origem externa. Valor = `true`	< 5 T/F	SIM

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âmetro	Descrição	Formato
`code`	Código de resposta do Carat. Qualquer código diferente de `0` significa falha. Saiba mais.	< 4 N
`message`	Mensagem de resposta do e-SiTef.	< 500 AN
payment
`status`	Status da transação de pagamento no Carat. Saiba mais.	= 3 AN
`nit`	Identificador da transação de pagamento no Carat.	= 64 AN
`order_id`	Código de pedido enviado pela loja na criação da transação.	< 40 AN
`merchant_usn`	Número sequencial único enviado pela loja na criação da transação.	< 12 N
`amount`	Valor 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âmetro	Descrição	Formato	Obrigatório
`merchant_id`	Código da loja no Carat. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
`merchant_key`	Chave de autenticação da loja no Carat. 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

Exemplo#

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br

curl --location --request PUT 'https://{{url}}/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âmetro	Descrição	Formato	Obrigatório
`confirm`	Este campo deve ser enviado com o valor `true` caso se deseje confirmar o pagamento, ou `false`, caso queira desfazer o pagamento.	< 5 T/F	SIM

Parâmetros da requisição - JSON#

Parâmetro	Descrição	Formato	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. Se não informado, assume o valor informado na criação da transação.	< 12 N	NÃO
`authorizer_id`	Código da autorizadora no Carat. Saiba mais.	< 3 N	SIM
`installments`	Número de parcelas. Envie ‘1’ para transações à vista.	< 2 N	NÃO(*)
`installment_type`	Tipo 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 N	NÃO(*)
`confirmation_data`	Informaçã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 AN	SIM
acquirer
`routing_id`	Informação do roteamento utilizado para o pagamento efetuado fora do Carat. Este parâmetro é fundamental para o sucesso da confirmação. Esta informação é utilizada para identificar o roteamento no SiTef.	< 5 N	SIM
`order_id`	Código de pedido enviado pela loja na criação da transação.	< 40 AN	NÃO(*)
`host_usn`	NSU do host/autorizadora da transação a ser confirmada.	= 9 N	NÃO(*)
`authorization_number`	Número de autorização da transação a ser confirmada.	< 6 N	NÃO(*)
`authorizer_date`	Data de efetivação SiTef do pagamento no formato `DD/MM/AAAA`.	= 10 D	NÃO(*)
`order_id`	Código do pedido usado no pagamento iniciado externamente ao Carat.	< 40 AN	NÃO(*)
`identification_number`	CPF ou CNPJ usado no pagamento iniciada externamente ao Carat.	< 20 AN	NÃO(*)
`terminal`	Terminal SiTef que se deseja usar. Se NÃO for enviado, o Carat gerará um terminal aleatório.	= 8 AN	NÃO(*)
`company_code`	Código de empresa SiTef que se deseja usar. Se não for enviado, o Carat enviará o código de empresa cadastrado na loja.	= 8 N	NÃO(*)

Nota: Os campos assinalados com NÃO(*) são opcionais e, se informados, não terão como ser consistidos pelo Carat, 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âmetro	Descrição	Formato
`code`	Código de resposta do Carat. Qualquer código diferente de `0` significa falha. Saiba mais.	< 4 N
`message`	Mensagem de resposta do e-SiTef.	< 500 AN
payment
`status`	Status da transação de pagamento no Carat. Saiba mais.	= 3 AN
`payment_date`	Data de efetivação do pagamento no Carat no formato `DD/MM/AAAA'T'HH:mm`. Exemplo: 13/07/2017T16:03	= 16 D
`host_usn`	NSU da autorizadora.	< 15 AN

Home

Introdução#

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

Detalhes da Chamada#

Exemplo#

Parâmetros da requisição#

Parâmetros de resposta#

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

Detalhes da chamada#

Exemplo#

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

Parâmetros da requisição - JSON#

Parâmetros de resposta#