Consulta

import ApiDoc from '../../src/components/api-doc/ApiDoc'; import ResponseCodes from './codigos-de-resposta.md';

Estes serviço pode ser chamado para obter os dados da transação de pagamento ou cancelamento. No caso de pagamento com agendamento, as consultas retornarão os dados das duas transações.

Atenção:

A consulta de transação no Carat NÃO efetua uma consulta do status da transação no adquirente / autorizador. Este serviço retorna o status da transação na base de dados do Carat.

Exemplo: Caso uma transação de pagamento seja confirmada no Carat, mas seja estornada diretamente no adquirente / autorizador, este estorno não será necessariamente refletido no serviço de consulta de transação do Carat.

Consulta por NIT

Detalhes da chamada

Recurso: /v2/transactions/{nit}
Método HTTP: GET
Formato da requisição: não há parâmetros de requisição
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

Exemplos

Consulta de pagamento

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor <URLPOSTMAN/>

curl --location --request GET 'https://{{url}}/e-sitef/api/v2/transactions/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********'

Resposta em caso de pedido encontrado:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "Transacao Aprov.",
        "status": "CON",
        "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "1660141068187",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "10/08/2022T11:17",
        "authorization_number": "105668",
        "merchant_usn": "12050620649",
        "esitef_usn": "220810105359590",
        "sitef_usn": "105668",
        "host_usn": "999105668   ",
        "amount": "10000",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000005",
        "terminal_id": "ES000024",
        "payment_date": "10/08/2022T11:17",
        "installments": 10,
        "standin_details": "000001",
        "cvv_result_code": "M"
    }
}

Resposta em caso de pedido não encontrado:

{
    "code": "82",
    "message": "Your transaction was not found on our system. Please, return to the site and try again.
                Please, contact the website administrator if this problem occurs again."
}

Consulta de cancelamento

Ao solicitar o serviço de cancelamento uma nova transação será criada com um NIT diferente da transação original de pagamento. Caso seja bem-sucedida, a transação de pagamento terá seu status mudado para EST (estornada) e a transação de cancelamento ficará com status CON (confirmada). Cada uma dessas operações podem ser consultadas com seus respectivos NITs.

NIT da transação de pagamento

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor <URLPOSTMAN/>

curl --location --request GET 'https://{{url}}/e-sitef/api/v2/transactions/d0eed50e34b37fd230389d618bf7bb023c02050ff9447d93d5b943e2f38117dd' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********'

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "Transacao Aprov.",
        "status": "EST",
        "nit": "d0eed50e34b37fd230389d618bf7bb023c02050ff9447d93d5b943e2f38117dd",
        "order_id": "1665683321507",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "13/10/2022T14:48",
        "authorization_number": "130083",
        "merchant_usn": "12050620649",
        "esitef_usn": "221013109642120",
        "sitef_usn": "130083",
        "host_usn": "999130083   ",
        "amount": "9977",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000005",
        "terminal_id": "ES000001",
        "payment_date": "13/10/2022T14:48",
        "installments": 10,
        "standin_details": "000001",
        "cvv_result_code": "M"
    }
}

NIT da transação de cancelamento

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor <URLPOSTMAN/>

curl --location --request GET 'https://{{url}}/api/v2/transactions/1c1caed9c650b29832d79d4a714b5d7526573ffefc726226b073fe0235006275' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********'

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "cancellation": {
        "authorizer_code": "000",
        "status": "CON",
        "nit": "1c1caed9c650b29832d79d4a714b5d7526573ffefc726226b073fe0235006275",
        "order_id": "1665683321507",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "13/10/2022T14:49",
        "authorization_number": "130083",
        "merchant_usn": "12050620649",
        "esitef_usn": "221013109642141",
        "sitef_usn": "130084",
        "host_usn": "999130084   ",
        "amount": "9977",
        "payment_type": "C",
        "issuer": "2",
        "terminal_id": "ES000001",
        "esitef_date": "13/10/2022T14:49",
        "is_host_cancel": "false"
    }
}

Consulta por order_id

Detalhes da chamada

Recurso: /v2/transactions?order_id={order_id}
Método HTTP: GET
Formato da requisição: 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

Exemplos

Consulta de pagamento

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor <URLPOSTMAN/>

curl --location --request GET 'https://{{url}}/e-sitef/api/v2/transactions?order_id=1663088515049&page=0&limit=7' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********'

Resposta em caso de pedido encontrado:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "transactions": [
        {
            "payment": {
                "authorizer_code": "000",
                "authorizer_message": "Transacao Aprov.",
                "status": "EST",
                "nit": "b916345da34b17d6e4d81f58cbdbf67100227d253aaa26c3a04de4c1734a024e",
                "order_id": "1663088515049",
                "customer_receipt":"====CUPOM COMPRADOR====",
                "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
                "authorizer_id": "2",
                "acquirer_id": "229",
                "acquirer_name": "Bin",
                "authorizer_date": "13/09/2022T14:01",
                "authorization_number": "135983",
                "merchant_usn": "12050620649",
                "esitef_usn": "220913107453280",
                "sitef_usn": "135983",
                "host_usn": "999135983   ",
                "amount": "9977",
                "payment_type": "C",
                "issuer": "2",
                "authorizer_merchant_id": "000000000000005",
                "terminal_id": "ES000042",
                "payment_date": "13/09/2022T14:01",
                "installments": 10,
                "standin_details": "000001",
                "cvv_result_code": "M"
            }
        },
        {
            "cancellation": {
                "authorizer_code": "000",
                "status": "CON",
                "nit": "eac07d8d1fe9b64166f5c4a5fbc2a8d4fe9047be2b9d41581f891a04bb2759b9",
                "order_id": "1663088515049",
                "customer_receipt": "====CUPOM COMPRADOR====",
                "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
                "authorizer_id": "2",
                "acquirer_id": "229",
                "acquirer_name": "Bin",
                "authorizer_date": "13/09/2022T14:02",
                "authorization_number": "135983",
                "merchant_usn": "12050620649",
                "esitef_usn": "220913107453291",
                "sitef_usn": "135984",
                "host_usn": "999135984   ",
                "amount": "9977",
                "payment_type": "C",
                "issuer": "2",
                "terminal_id": "ES000042",
                "esitef_date": "13/09/2022T14:02",
                "is_host_cancel": "false"
            }
        }
    ],
    "current_page": "0",
    "total_pages": "1",
    "count": "2"
}

Resposta em caso de pedido não encontrado:

{
    "code": "82",
    "message": "Your transaction was not found on our system. Please, return to the site and try again.
                Please, contact the website administrator if this problem occurs again."
}

Consulta de cancelamento

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor <URLPOSTMAN/>

curl --location --request GET 'https://{{url}}/e-sitef/api/v2/transactions?order_id=1663088515049&page=0&limit=7' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********'

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "transactions": [
        {
            "payment": {
                "authorizer_code": "000",
                "authorizer_message": "Transacao Aprov.",
                "status": "EST",
                "nit": "b916345da34b17d6e4d81f58cbdbf67100227d253aaa26c3a04de4c1734a024e",
                "order_id": "1663088515049",
                "customer_receipt": "====CUPOM COMPRADOR====",
                "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
                "authorizer_id": "2",
                "acquirer_id": "229",
                "acquirer_name": "Bin",
                "authorizer_date": "13/09/2022T14:01",
                "authorization_number": "135983",
                "merchant_usn": "12050620649",
                "esitef_usn": "220913107453280",
                "sitef_usn": "135983",
                "host_usn": "999135983   ",
                "amount": "9977",
                "payment_type": "C",
                "issuer": "2",
                "authorizer_merchant_id": "000000000000005",
                "terminal_id": "ES000042",
                "payment_date": "13/09/2022T14:01",
                "installments": 10,
                "standin_details": "000001",
                "cvv_result_code": "M"
            }
        },
        {
            "cancellation": {
                "authorizer_code": "000",
                "status": "CON",
                "nit": "eac07d8d1fe9b64166f5c4a5fbc2a8d4fe9047be2b9d41581f891a04bb2759b9",
                "order_id": "1663088515049",
                "customer_receipt": "====CUPOM COMPRADOR====",
                "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
                "authorizer_id": "2",
                "acquirer_id": "229",
                "acquirer_name": "Bin",
                "authorizer_date": "13/09/2022T14:02",
                "authorization_number": "135983",
                "merchant_usn": "12050620649",
                "esitef_usn": "220913107453291",
                "sitef_usn": "135984",
                "host_usn": "999135984   ",
                "amount": "9977",
                "payment_type": "C",
                "issuer": "2",
                "terminal_id": "ES000042",
                "esitef_date": "13/09/2022T14:02",
                "is_host_cancel": "false"
            }
        }
    ],
    "current_page": "0",
    "total_pages": "1",
    "count": "2"
}

Resposta em caso de pedido não encontrado:

{
    "code": "82",
    "message": "Your transaction was not found on our system. Please, return to the site and try again.
                Please, contact the website administrator if this problem occurs again."
}

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 efetivaçã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 Carat.	< 500 AN
`current_page`	Página atual dos registros.	< 4 N
`total_pages`	Número total de páginas.	< 4 N
`count`	Contagem total de registros.	< 4 N
payment
`authorizer_code`	Código de resposta do autorizador.	< 10 AN
`authorizer_message`	Mensagem de resposta do autorizador.	< 500 AN
`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
`sitef_usn`	Número sequencial único da transação de pagamento no SiTef.	= 6 N
`esitef_usn`	Número sequencial único da transação de pagamento no Carat.	= 15 N
`customer_receipt`	Cupom (via cliente).	< 4000 AN
`merchant_receipt`	Cupom (via estabelecimento).	< 4000 AN
`authorizer_id`	Código da autorizadora utilizada na transação.	< 4 N
`acquirer_id`	Código do adquirente utilizado na transação.	< 4 N
`acquirer_name`	Nome do adquirente utilizado na transação.	< 100 AN
`authorizer_date`	Data de efetivação do pagamento retornada pelo autorizador no formato `DD/MM/AAAA'T'HH:mm`. Exemplo: 13/07/2017T16:03	= 16 D
`authorization_number`	Número de autorização.	< 6 AN
`host_usn`	NSU da autorizadora.	< 15 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
`issuer`	Código da bandeira retornado pelo autorizador.	< 5 AN
`authorizer_merchant_id`	Código de afiliação do lojista na autorizadora.	< 100 AN
`terminal_id`	Código do terminal utilizada na transação	< 8 AN
`installments`	Número de parcelas a ser utilizado nos pagamentos agendados.	< 2 N
`is_host_cancel`	Este campo retornará o valor `true` em caso de cancelamento via host.	< 5 T/F
`customer_receipt`	Cupom (via cliente).	< 4000 AN
`merchant_receipt`	Cupom (via estabelecimento).	< 4000 AN
`payment_type`	Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios de pagamentos, W = Boleto NR via Web Service	= 1 AN
`standin_details`	Este campo proporciona información adicional para identificar si una transacción fue realizada por el Suplente en lugar del emisor. Más información	< 6 AN
`cvv_result_code`	Código de resultado CVV (solo presente en transacciones de Mastercard y Visa).<BR/>Valores:<BR/>M = Válido (coincidente)<BR/>N = No válido (no coincide)<BR/>P = Sin procesar (emisor) no disponible temporalmente)<BR/>U = no verificado<BR/>S = CVV2 debe estar en la tarjeta	= 1 N
cancellation
`authorizer_code`	Código de resposta do autorizador.	< 10 AN
`status`	Status da transação de pagamento no Carat. Saiba mais.	= 3 AN
`nit`	Identificador da transação de cancelamento 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
`sitef_usn`	Número sequencial único da transação de pagamento no SiTef.	= 6 N
`esitef_usn`	Número sequencial único da transação de pagamento no Carat.	= 15 N
`customer_receipt`	Cupom (via cliente).	< 4000 AN
`merchant_receipt`	Cupom (via estabelecimento).	< 4000 AN
`authorizer_id`	Código da autorizadora utilizada na transação.	< 4 N
`acquirer_id`	Código do adquirente utilizado na transação.	< 4 N
`acquirer_name`	Nome do adquirente utilizado na transação.	< 100 AN
`authorizer_date`	Data de efetivação do pagamento retornada pelo autorizador no formato `DD/MM/AAAA'T'HH:mm`. Exemplo: 13/07/2017T16:03	= 16 D
`authorization_number`	Número de autorização.	< 6 AN
`host_usn`	NSU da autorizadora.	< 15 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
`issuer`	Código da bandeira retornado pelo autorizador.	< 5 AN
`authorizer_merchant_id`	Código de afiliação do lojista na autorizadora.	< 100 AN
`terminal_id`	Código do terminal utilizada na transação	< 8 AN
`installments`	Número de parcelas a ser utilizado nos pagamentos agendados.	< 2 N
`is_host_cancel`	Este campo retornará o valor `true` em caso de cancelamento via host.	< 5 T/F
`esitef_date`	Data de efetivação do cancelamento no Carat no formato `DD/MM/AAAA'T'HH:mm`. Exemplo: 13/07/2017T16:03	= 16 D
`customer_receipt`	Cupom (via cliente).	< 4000 AN
`merchant_receipt`	Cupom (via estabelecimento).	< 4000 AN
`payment_type`	Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = transferência bancária, G = cartão gift, O = outros meios de pagamentos, W = Boleto NR via Web Service	= 1 AN