Serviço de Consulta de Transações de Pagamento
Consulta a transação de pagamento perante a API Omnichannel. Este serviço deverá ser chamado em seguida a uma requisição do Serviço de Pagamento para verificar o status da aprovação ou status de retorno deste pedido de pagamento.
Como a captura da transação ocorre no POS de forma presencial, o serviço de Consulta Status da transação deve ser chamado pela Automação até que o retorno do campo status seja status=PPC (Pagamento Pendente de confirmação) ou status=ERR (Erro ao Efetuar Pagamento). Caso o status da transação seja PPC, este serviço retornará os dados de resposta do pagamento.
A Consulta de transação de pagamento também pode ser chamada em casos de erro de comunicação para verificar o status atual da transação, que pode ter sido efetuada ou não recebida pela API Omnichannel.
Atenção: A consulta de transação na API Omnichannel 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 da API Omnichannel.
Exemplo: Caso uma transação de pagamento seja confirmada na API Omnichannel, mas seja estornada via telefone diretamente no adquirente / autorizador, este estorno não será necessariamente refletido no serviço de consulta de transação da API Omnichannel.
Detalhes da chamada#
Recurso: /v1/sales/{sale_id}/payments/{nit}
Método HTTP: GET
Parâmetro de URL:
| Parâmetro | Descrição | Tipo | Tamanho | Obrigatório |
|---|---|---|---|---|
| nit | Identificador da transação de pagamento na API Omnichannel, valor retornado do POST | AN | 64 | SIM |
| sale_id | Identificador da venda na API Omnichannel, valor retornado do POST |
- Parâmetros de cabeçalho:
| Parâmetro | Descrição | Tipo | Tamanho | Obrigatório |
|---|---|---|---|---|
| client_id | Identificação do Cliente | AN | N/A | SIM |
| site_id | Identificação da Loja | AN | N/A | SIM |
| Authorization | Bearer valor do access_token | AN | N/A | SIM |
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.
- Parâmetros de cabeçalho:
| Parâmetro | Descrição | Tipo | Tamanho | Obrigatório |
|---|---|---|---|---|
| Content-Type | application/json; charset=utf-8 | AN | 16 | SIM |
- Corpo: JSON
| Parâmetro | Descrição | Tipo | Tamanho | Obrigatório |
|---|---|---|---|---|
| code | Código de resposta do Gateway de Pagamento. Qualquer código diferente de ‘0’ significa falha. Em caso de falha, considerar que o estado da transação permanecerá como Pendente. | N | < 4 | SIM |
| message | Mensagem de resposta opcional que serve de apoio de diagnóstico para o desenvolvedor (sempre em inglês) | AN | < 500 | SIM |
| status | status da requisição de pagamento Se POS ainda não iniciou a captura da transação, status é “1 – Aguardando POS” Se POS já iniciou a captura da transação, status é = “2 – Transação já iniciada (pagamento em andamento)” Se a API Omnichannel já recebeu a resposta da transação (aprovada ou negada, status = “3 – Transação processada” Se a captura da transação foi abortada no POS, status = “4 – Transação cancelada” Somente quando status = 3 (Transação processada) retornarão os dados do pagamento no conjunto de dados do payment. | AN | SIM | |
| payment | Objeto contendo dados do pagamento (veja especificação abaixo) | Objeto | Condicional Obrigatório se houve sucesso na realização do pagamento e o campo status for igual a 3-(Transação processada) |
| Objeto payment | |||||
|---|---|---|---|---|---|
| Parâmetro | Descrição | Tipo | Tamanho | Obrigatório | |
| status | Status da transação de pagamento na API Omnichannel. Para mais informações, consulte a seção de Tabelas Compartilhadas. | AN | =3 | SIM | |
| nit | Identificador da transação de pagamento na API Omnichannel. Este campo será apresentado no Payment apenas em chamadas de múltiplos | NA | =64 | ||
| authorizer_code | Código de resposta do autorizador. | AN | < 10 | SIM | |
| authorizer_message | Mensagem de resposta do autorizador. | AN | < 500 | NÃO | |
| order_id | Código de pedido enviado pela loja na criação da transação. | AN | < 20 | SIM | |
| merchant_usn | Número sequencial único enviado pela loja na criação da transação. | N | < 12 | SIM | |
| amount | Valor da compra especificado pela loja (em centavos) na criação da transação. | N | < 12 | SIM | |
| payment_method | Método de Pagamento previamente informado ou selecionado durante o fluxo de captura da transação. | N | 3 | SIM | |
| gateway_usn | Número sequencial único da transação de pagamento no Gateway de Pagamento. | N | = 6 | SIM (TODO: CONFIRMAR SE POS BIN ESTÁ RETORNANDO) | |
| Lista de objetos contendo os comprovantes da transação. Veja a seção Parâmetros complexos para maiores detalhes. | Lista | SIM | |||
| authorizer_id | Código da autorizadora utilizada na transação. | N | < 4 | NÃO | |
| acquirer_id | Código do adquirente utilizado na transação. | N | < 4 | NÃO | |
| acquirer_name | Nome do adquirente utilizado na transação. | AN | < 100 | NÃO | |
| authorizer_date | Data de efetivação do pagamento retornada pelo autorizador no formato DD-MM-AAAATHH:mm. Exemplo: 13-07-2017T16:03 | D | = 16 | SIM | |
| authorization_code | Código de Autorização. | AN | < 6 | SIM | |
| txidpix | Código de Autorização estendido, presente apenas em transações PIX. | AN | < 99 | CONDICIONAL Obrigatório se o payment_method for igual a 3=(PIX) | |
| host_usn | NSU da autorizadora. | AN | < 15 | NÃO | |
| payment_date | Data de efetivação do pagamento no formato DD-MM-AAAATHH:mm. Exemplo: 13-07-2017T16:03 | D | =16 | TODO: CONFIRMAR SE RECEBEMOS DA BIN. | |
| issuer | Código da bandeira retornado pelo autorizador. | AN | < 5 | TODO: CONFIRMAR SE RECEBEMOS DA BIN. | |
| authorizer_merchant_id | Código de afiliação do lojista na autorizadora. Identificador do Host/adquirente no Gateway de Pagamento. | AN | < 100 | TODO: CONFIRMAR SE RECEBEMOS DA BIN. | |
| terminal_merchant_id | Dados da empresa configurados no terminal que processou a transação | TODO: CONFIRMAR SE RECEBEMOS DA BIN. | |||
| terminal_id | Identificação do terminal que processou a transação | TODO: CONFIRMAR SE RECEBEMOS DA BIN. | |||
| card | Objeto contendo dados do cartão (veja especificação abaixo). | Objeto | NÃO | ||
| endtoendpix | Código endtoend enviado em transações pix | AN | >50 | CONDICIONAL Obrigatório se o payment_method for igual a 3=(PIX) | |
| invoice_data | Objeto com os campos de nota fiscal para a automação realizar a emissão com os órgãos ou entidades competentes (veja especificação abaixo) | Objeto | SIM |
| Objeto card (dentro de payment) | ||||
|---|---|---|---|---|
| Parâmetro | Descrição | Tipo | Tamanho | Obrigatório |
| masked_pan | Pan do cartão, 4 primeiros dígitos e últimos dígitos | a definir | NÃO | |
| expiry_date | Data de vencimento do cartão no formato MMAA. | a definir | NÃO | |
| entry_mode | Modo de entrada do cartão (a definir valores) | a definir | NÃO |
| Objeto invoice_data (dentro de payment) | ||||
|---|---|---|---|---|
| Parâmetro | Descrição | Tipo | Tamanho | Obrigatório |
| host_cnpj | CNPJ da rede credenciadora do cartão de débito/crédito. Usado para NFC-e | String | 0 ou 14 | SIM |
| sat_host_id | Código da rede credenciadora do cartão de débito/crédito para o SAT | String | 0 ou 3 | SIM |
| nfce_issuer_id | Bandeira do cartão de débito/crédito confirme valores definidos pela especificação da NFC-e: ·01 - VISA ·02 - Mastercard ·03 - American Express ·04 - Sorocred ·99 - Outros | String | 0 ou 2 | SIM |
Exemplo#
Requisição e Resposta