ManualAPI_Pagamentos_Pix_Itaú_v1

Prévia do material em texto

Corporativo | Interno 
 
Manual de API Pagamentos - Cash Management 
 
Sumário 
Manual de API Pagamentos - Cash Management ................................................................................................................................................................................................ 1 
Sobre a solução ......................................................................................................................................................................................................................................................... 3 
Como começar ........................................................................................................................................................................................................................................................... 3 
Autenticação .......................................................................................................................................................................................................................................................... 3 
Fluxo de autenticação – OAuth 2.0 (Private KeyJWT e Mutual-TLS Client Authentication) ........................................................................................................................ 3 
Como conhecer e testar as APIs .......................................................................................................................................................................................................................... 4 
Um exemplo de como será essa jornada ....................................................................................................................................................................................................... 4 
Intervalo para obtenção de access_tokens ........................................................................................................................................................................................................ 5 
Padrão de Erros ................................................................................................................................................................................................................................................. 5 
End Point Raiz .................................................................................................................................................................................................................................................... 6 
Parâmetros comuns de cabeçalho............................................................................................................................................................................................................................... 6 
APIs de Gestão de Pagamentos Pix ........................................................................................................................................................................................................................ 7 
Gestão Pagamentos ..................................................................................................................................................................................................................................................... 7 
Inclusão de Pagamentos – PIX Transferência .......................................................................................................................................................................................................... 7 
Inclusão Pix – Código de HTTP Status .................................................................................................................................................................................................................. 9 
Saída – Response OK .......................................................................................................................................................................................................................................... 10 
 
 
Corporativo | Interno 
Exemplo saída - OK ............................................................................................................................................................................................................................................ 11 
Objetos ............................................................................................................................................................................................................................................................... 12 
Inclusão de pagamento PIX-QRCODE .................................................................................................................................................................................................................... 14 
Inclusão Pix – Código de HTTP Status ................................................................................................................................................................................................................ 16 
Saída – Response OK .......................................................................................................................................................................................................................................... 17 
Exemplo saída - OK ............................................................................................................................................................................................................................................ 18 
Objetos ............................................................................................................................................................................................................................................................... 20 
Consulta de pagamento ......................................................................................................................................................................................................................................... 23 
Lista de pagamentos .......................................................................................................................................................................................................................................... 23 
Exemplo saída - OK ............................................................................................................................................................................................................................................ 25 
Detalhe do pagamento ...................................................................................................................................................................................................................................... 27 
Exemplo saída - OK ............................................................................................................................................................................................................................................ 28 
 
 
 
 
Corporativo | Interno 
Sobre a solução 
O Pix permitirá a transferências e pagamentos via QR Code Estático e Dinâmico entre diferentes instituições financeiras em até 10 
segundos, 24 horas por dia e todos os dias do ano, incluindo finais de semana e feriados. Para utilizar o Pix através da API é necessário 
que o SISPAG esteja habilitado. 
Como começar 
O objetivo desta documentação é orientar o desenvolvedor sobre como integrar com a solução de APIs para o PIX do Itaú. 
Apresentaremos no decorrer desse documento as informações necessárias para compreender o fluxo dos dados entre as APIs, dicas 
que auxiliarão no momento da implantação e exemplos. 
Autenticação 
Para começar a sua jornada de desenvolvimento é importanteque o ambiente esteja preparado e configurado para realizar os testes e 
suportar o desenvolvimento da aplicação de maneira segura. Nosso modelo de comunicação atual requer a autenticação do parceiro 
através do fluxo OAuth 2.0. 
Fluxo de autenticação – OAuth 2.0 (Private KeyJWT e Mutual-TLS Client Authentication) 
Os fluxos de autenticação do oAuth 2.0 são baseados em obtenção de access_tokens que permitem a autenticação e autorização das 
APIs. O método previsto para as APIS do PIX do Itaú é o Private Key JWT Client Authentication (private_key_jwt) que consiste em 
autenticação no fluxo client_credentials baseada em chaves (privada e pública). 
Ambas as chaves são criadas pelo desenvolvedor que irá integrar com as APIs do Itaú. A chave privada, deve ser criada e armazenada 
de maneira segura dentro do ambiente da aplicação que consumirá as APIs e é utilizada para assinar todas as obtenções de 
access_tokens. A chave pública deve ser exposta em um terminal de configuração descoberta (well-known endpoint) em uma sessão 
 
 
Corporativo | Interno 
específica conhecida como jwks_uri (JSON Web Key Sets – URI). A jwks_uri deve ser informada para o agente comercial Itaú no 
momento da contratação. Saiba mais em https://auth0.com/docs/tokens/json-web-tokens/json-web-key-sets 
Para estabelecer conexão segura com os API Gateways do Itaú é necessário enviar um client certificate. Este certificado é usado para 
estabelecer o mTLS (OAuth 2.0 Mutual Transport Layer Security - https://tools.ietf.org/html/rfc8705): 
1. A partir de um client_id e token temporário para ativação, ambos fornecidos pelo agente comercial após a contratação, o 
desenvolvedor gera um arquivo CSR (Certificate Signing Request) baseado em um template e documentação será fornecida no 
nosso Portal do Desenvolvedor; 
2. O desenvolvedor solicita um certificado assinado pelo Itaú (CRT – Certificate File), através de uma API informando o CSR e token 
temporário de ativação; 
3. O desenvolvedor configura sua aplicação com o arquivo CRT, que será utilizado junto com o private_key_jwt para a obtenção de 
access_tokens e junto com o access_token para todas as chamadas de APIs. 
4. A renovação automática e revogação estão também documentadas no Portal do Desenvolvedor. 
Como conhecer e testar as APIs 
 
Após a contratação, seu agente comercial realizará o cadastro em nossos sistemas internos e enviará três informações importantes: 
uma credencial (client_id) que será cadastrada com suas informações previamente fornecidas (inclusive o jwks_uri, citado 
anteriormente), token temporário de ativação e um código de registro para Portal do Desenvolvedor Itaú, no qual dará acesso à toda a 
documentação detalhada e referências técnicas, além de um ambiente sandbox para testes simulados. Com esse código, você se 
cadastra e pode cadastrar outros desenvolvedores de sua organização. 
 
Um exemplo de como será essa jornada 
1. O primeiro passo é criar um ‘projeto’ dentro do nosso portal, definindo o nome do projeto e quais APIs farão parte dele e, por fim, 
clicando no botão "Criar Projeto" para finalizar a criação; 
 
 
Corporativo | Interno 
2. Acesse a página da API e leia toda a documentação, com fluxos e exemplos. Isso, com certeza, vai ajudar você a diminuir o tempo e a 
dificuldade na construção; 
3. Dentro da documentação, além das informações referentes ao processo, você encontrará as especificações técnicas de cada API, 
métodos, parâmetros de entrada (requests) e de retorno (responses); 
4. Em seguida, você terá a possibilidade de selecionar a aplicação criada para seu projeto (passo 1), simular uma autorização (obtendo 
um access_token) e simulando uma chamada da API, após o preenchimento dos campos obrigatórias e opcionais; 
5. Se houver dúvidas ou problemas de acesso você poderá contar com o time comercial para melhor direcionar os pontos que 
necessitam de atuação ou melhoria em nossa documentação. Contamos sua colaboração nessa jornada! 
 
Para testar as APIs do sandbox diretamente de sua aplicação, basta obter um cliente_id de uma aplicação criada no Portal do 
Desenvolvedor e private_key_jwt global (que estará disponível nas informações adicionais da aplicação) e realizar as chamadas 
diretamente para as URIs de obtenção de access_tokens e de APIs do sandbox. As URIs estarão disponíveis no Portal. 
 
Intervalo para obtenção de access_tokens 
 
O access_token é muito eficiente quando utilizado diversas vezes antes de expirar (tempo padrão de 5 minutos), portanto é importante 
que sua implementação de código preveja obter novo access_token somente quando estiver perto de expiração do access_token 
corrente. Isso evita fluxo desnecessário de autorização e garante mais performance para seu sistema ou aplicativo. 
Padrão de Erros 
Há um padrão de retorno para todos os erros na API. Esse padrão segue uma estrutura específica, podendo apenas variar os valores 
existentes nos campos. 
No exemplo a seguir, o campo id_transferencia não foi enviado no Body da requisição. 
{ 
 "codigo": "400", 
 
 
Corporativo | Interno 
 "mensagem": "Erro na validação", 
 "campos": [ 
 { 
 "campo": "id_transferencia", 
 "mensagem": " Devolução não concluída. A devolução é limitada a transações realizadas nos últimos 90 dias", 
 "valor": " " 
 } 
 ] 
} 
End Point Raiz 
Após realizar a chamada ao autorizador, o parceiro deverá chamar a API de PIX desejada. A URL base da API está definida como 
https://apisp.dev.aws.cloud.ihf/cash_management/v1/nomeAPI, sendo “nomeAPI” a variável conforme a API a ser chamada. Todas 
as requisições devem usar o schema https por questões de segurança. 
Parâmetros comuns de cabeçalho 
Para consumo das APIs do Itaú, alguns parâmetros de cabeçalho são necessários: 
x-itau-apikey 
O x-itau-apikey é um parâmetro que será requerido em todas as chamadas das APIs que contemplam essa solução. A informação que 
deve ser usada nesse campo é o código gerado através da autenticação OAuth 2.0 para o client_id. Para saber como gerar o client_id 
ou como recuperar as informações de códigos já gerados basta acessar a etapa de ‘autenticação’ desse tutorial. 
x-itau-flowID 
A implementação de um flowID permite identificar qual é a funcionalidade de negócio sendo executada na aplicação. Por exemplo, 
dentro de uma mesma aplicação, várias telas ou linhas de negócio diferentes podem acessar a mesma API. Quando é identificado que 
algumas chamadas a uma determinada API estão dando erro, através do flowID, podemos descobrir que as chamadas são de uma tela 
 
 
Corporativo | Interno 
específica e com isso solucionar o problema mais rápido do que se não tivéssemos essa informação no log. Ter o flowID nos logs 
também permite extrair algum tipo de métrica através do log. Recomenda-se mandar um uuid version 4 nesse campo como: 
b47ec51b-b2a7-4a78-933c-f0b67667e7dc. 
x-itau-correlationID 
A implementação de um correlationID permite relacionar uma mesma chamada passando em diversas aplicações/sistemas diferentes, 
conseguindo fornecer um mapeamento de ponta-a-ponta. Por exemplo, uma aplicação client gera uma chamada à API, neste 
momento fornecendo o correlationID gerado pelo consumidor, o qual é repassado em todas as camadas/microserviços que a api 
precisa para realizar determinada funcionalidade. É importante lembrar que o header x-itau-correlationID deve sempre ser diferente a 
cada requisição. Recomenda-se mandar um uuid version 4 nesse campo como: a1e64241-7fdb-4d05-a7f6-c44febcdd8d9. 
Body: 
Campos de entrada descritos nas outras seções. 
APIs de Gestão de Pagamentos Pix 
Os itens a seguir detalham as funcionalidades disponibilizadas nas APIs do Itaú para o Pix. Sua empresa pode desfrutar de todas as 
visões e opções criadas. 
Gestão Pagamentos 
Inclusão de Pagamentos – PIX Transferência 
POST/cash_management-contas_pagar_ext/v1/transferencia/ 
API responsável por inserir um pagamento pix na plataforma SISPAG do Banco Itaú. 
 
 
Corporativo | InternoAbaixo estão expostos os parâmetros exigidos por essa API e a descrição deles. Para obter mais informações de onde conseguir o x-itau-apikey, e o x-itau-
correlationID, acesse o tópico ‘Informações necessárias’. 
Para essa forma de pagamento, é obrigatório o envio de no mínimo: uma chave de identificação do cliente (chave; ou tipo_identificacao_conta , 
agencia_recebedor, conta_recebedor, tipo_de_identificacao_do_recebedor, identificacao_recebedor), valor, data_pagamento e objeto Pagador. 
Caso seja enviado a chave (chave de endereçamento), todas as outras informações do recebedor são opcionais, e caso sejam enviadas, serão validadas com o 
cadastrado para chave na DICT. 
Entrada - Request 
Parâmetro Tipo Parâmetro Tipo Dado Obrigatório Descrição 
valor body string sim Valor a ser pago. 
data_pagamento body string sim Data do pagamento, formato dd/mm/yyyy 
chave body string sim Chave do recebedor. Exemplo: funcionario_itau@itau-unibanco.com.br 
ispb body string sim Ispb do recebedor. 
banco body string sim Banco recebedor. Nome do banco. Exemplo: Itaú Unibanco. 
tipo_identificacao_conta body string sim Tipo de conta do recebedor. Exemplo: “CC” 
agencia_recebedor body string sim Agência do recebedor. 
 
 
Corporativo | Interno 
Inclusão Pix – Código de HTTP Status 
Código de HTTP Motivo 
200 Inclusão realizada com sucesso 
400 Erros de validação ou os campos informados não existem no sistema. 
422 Inclusão não realizada por alguma regra de negócio não atendida. 
conta_recebedor body string sim Conta do recebedor. 
tipo_de_identificacao_do_recebedor body string sim Identificação do recebedor (PF ou PJ). 
identificacao_recebedor body string sim CPF ou CNPJ do recebedor. 
informacoes_entre_usuarios body string não Mensagem a ser enviado ao pagador via PACS008 (140). 
referencia_empresa body string não Texto de referência da empresa enviado no arquivo cnab para consulta. 
identificacao_comprovante body string não Texto de identificação do comprovante. 
txID body string não campo alfa (25 caracteres) / identificador QR-code. 
pagador body object sim Objeto de caso de uso: Detalhe Pagador. 
 
 
Corporativo | Interno 
Inclusão Pix – Código de HTTP Status 
500 Erro inesperado 
 
Saída – Response OK 
Parâmetro Tipo Parâmetro Tipo Dado Obrigatório Descrição 
status_pagamento body string sim Status do pagamento 
cod_pagamento body string sim Identificação do pagamento. 
numero_lote body string sim número de lote SISPAG. 
numero_lancamento body string Sim número do lançamento SISPAG. 
tipo_pagamento body string sim Tipo de produto da transferência. 
forma_pagamento body string Sim Forma que será realizada a transferência. 
data_pagamento body string sim Data em que será realizado o pagamento. Formato “YYYY-MM-
DDTHH:MM:SS”. 
valor_pagamento body string sim Valor do pagamento. 
referencia_empresa body string sim texto livre de referência da empresa sobre o pagamento. 
identificacao_comprovante body string sim texto livre de para identificação do comprovante da empresa sobre o 
pagamento. 
informacoes_entre_usuarios body string sim mensagem a ser enviado ao pagador via PACS008 (140). 
transaction_id body string não Identificador do PIX. (TXID) 
 
 
Corporativo | Interno 
 
Exemplo saída - OK 
{ 
 "data":{ 
 "status_pagamento": "INCLUIDO", 
 "cod_pagamento": "93577df4-6f43-4e49-bdff-eb8b053fb931", 
 "numero_lote": "291000001", 
 "numero_lancamento": "000019", 
 "tipo_pagamento": "FORNECEDORES", 
 "forma_pagamento": "PIX - Itaú", 
 "data_pagamento": "2020-08-28T12:00:00", 
 "valor_pagamento": "100.00", 
 "referencia_empresa": "Prestação de serviços - Empresa A", 
 "identificacao_comprovante": "Pagamentos - Empresa A", 
 "informacoes_entre_usuarios": "Serviço prestado pela Empresa A", 
 "transaction_id": "bqJJjaVAThmtnUeVLNnSXQ", 
 "pagador": { 
 "tipo_conta": "Conta Corrente", 
 "agencia": "1500", 
 "conta": "00052012", 
 "tipo_pessoa": "PJ", 
 "documento": "00000000000191" 
 }, 
 "recebedor": { 
 "banco": "Itaú Unibanco", 
 "ispb": "60701190", 
 "tipo_conta": "Conta Corrente", 
 "agencia": "1500", 
pagador body object sim Objeto: Detalhe Pagador. 
favorecido body object sim Objeto: Detalhe Favorecido. 
 
 
Corporativo | Interno 
 "conta": "00052061", 
 "tipo_pessoa": "PF", 
 "documento": "00000000019", 
 "nome": "Maria PIX", 
 "tipo_chave": "email", 
 "identificacao_chave": "maria_pix@gmail.com" 
 } 
 } 
 
} 
Objetos 
Objeto Detalhe Pagador 
 
 
 
Parâmetro Tipo Parâmetro Tipo Dado Obrigatório Descrição 
tipo_conta body string Sim Tipo de conta do pagador 
agencia body string sim Agência do pagador 
conta body string sim Conta do pagador 
tipo_pessoa body string sim Tipo de pessoa do pagador (PF ou PJ) 
documento body string sim Documento do pagador (CPF ou CNPJ) 
tipo_pagamento body string sim Módulo SISPAG utilizado para o pagamento 
 
 
Corporativo | Interno 
Objeto Detalhe Recebedor 
 
Parâmetro Tipo Parâmetro Tipo Dado Obrigatório Descrição 
banco body string Sim Nome do banco do recebedor 
Ispb Body String Sim ISPB do banco do recebedor 
tipo_conta body string Sim Tipo de conta do recebedor 
agencia body string sim Agência do recebedor 
conta body string sim Conta do recebedor 
tipo_pessoa body string sim Tipo de pessoa do recebedor (PF ou PJ) 
documento body string sim Documento do recebedor (CPF ou CNPJ) 
nome body string sim Nome do favorecido 
tipo_chave body string sim Tipo da chave utilizada pelo favorecido 
identificacao_chave body string sim Identificação da chave utilizada pelo favorecido 
 
 
Corporativo | Interno 
 
Inclusão de pagamento PIX-QRCODE 
POST/cash_management-contas_pagar_ext/v1/transferencia/ 
API responsável por inserir um pagamento pix na plataforma SISPAG do Banco Itaú. 
Abaixo estão expostos os parâmetros exigidos por essa API e a descrição deles. Para obter mais informações de onde conseguir o x-itau-apikey, e o x-itau-
correlationID, acesse o tópico ‘Informações necessárias’. 
Para essa forma de pagamento, é obrigatório o envio de no mínimo: uma identificação do QR-CODE (pix_link, imagem, emv ou url), valor, data_pagamento e 
o objeto Pagador. Todas as outras informações são opcionais, e caso sejam enviadas, será validada com o QR-CODE decodificado. 
Entrada - Request 
Parâmetro Tipo Parâmetro Tipo Dado Obrigatório Descrição 
pix_link body string sim PIX do QR-Code. Essa informação pode ser encontrada na leitura do QR-CODE. 
imagem body byte sim Imagem QR-Code. Essa informação pode ser encontrada na leitura do QR-
CODE. 
emv body string sim EMV do QR-CODE. Essa informação pode ser encontrada na leitura do QR-
CODE. 
url body string sim URL do QR-Code. Essa informação pode ser encontrada na leitura do QR-
CODE. 
 
 
Corporativo | Interno 
transaction_id body string não 
Txid – Transaction ID. Essa informação pode ser encontrada na leitura do QR-
CODE. 
valor body string sim Valor a ser pago. 
data_pagamento body string sim Data do pagamento, formato dd/mm/yyyy 
chave body string não Chave de endereçamento do Sistema DICT - BACEN. Exemplo: 
funcionario_itau@itau-unibanco.com.br 
ispb body string não ISPB do recebedor. 
banco body number não Banco recebedor. 
agencia_recebedor body string não Agência do recebedor. 
conta_recebedor body string não Conta do recebedor. 
tipo_de_identificacao_do_recebedor body string não Identificação do recebedor (PF ou PJ). 
identificacao_recebedor body string não CPF ou CNPJ do recebe 
informacoes_entre_usuarios body string não Mensagem a ser enviado ao pagador via PACS008 (140). 
 
 
Corporativo | Interno 
 
Inclusão Pix – Código de HTTP Status 
Código de HTTP Motivo 
200 Inclusão realizada com sucesso 
400 Erros de validaçãoou os campos informados não existem no sistema. 
422 Inclusão não realizada por alguma regra de negócio não atendida. 
500 erro inesperado 
 
 
 
 
referencia_empresa body string não Texto de referência da empresa enviado no arquivo cnab para consulta. 
identificacao_comprovante body string não Texto de identificação do comprovante. 
devedor body object não Objeto: Detalhe Devedor. 
pagador body object sim Objeto: Detalhe Pagador. 
 
 
Corporativo | Interno 
Saída – Response OK 
Parâmetro Tipo Parâmetro Tipo Dado Obrigatório Descrição 
status_pagamento body string sim Status do pagamento 
cod_pagamento body string sim Identificação do pagamento. 
numero_lote body string sim número de lote SISPAG. 
numero_lancamento body string Sim número do lançamento SISPAG. 
tipo_pagamento body string sim Tipo de produto da transferência. 
forma_pagamento body string Sim Forma que será realizada a transferência. 
data_pagamento body string sim 
Data em que será realizado o pagamento. Formato “YYYY-MM-
DDTHH:MM:SS”. 
valor_pagamento body string sim Valor do pagamento. 
referencia_empresa body string sim texto livre de referência da empresa sobre o pagamento. 
identificacao_comprovante body string sim texto livre de para identificação do comprovante da empresa sobre o 
pagamento. 
 
 
Corporativo | Interno 
 
Exemplo saída - OK 
{ 
 "data":{ 
 "status_pagamento": "INCLUIDO", 
 "cod_pagamento": "93577df4-6f43-4e49-bdff-eb8b053fb931", 
 "numero_lote": "291000001", 
 "numero_lancamento": "000019", 
 "tipo_pagamento": "FORNECEDORES", 
 "forma_pagamento": "PIX - Itaú", 
 "data_pagamento": "2020-08-28T12:00:00", 
 "valor_pagamento": "100.00", 
 "referencia_empresa": "Prestação de serviços - Empresa A", 
 "identificacao_comprovante": "Pagamentos - Empresa A", 
 "informacoes_entre_usuarios": "Serviço prestado pela Empresa A", 
informacoes_entre_usuarios body string sim mensagem a ser enviado ao pagador via PACS008 (140). 
transaction_id body string sim Identificador QR-code. (TXID) 
documento body object não Objeto: Detalhe Documento. 
pagador body object sim Objeto: Detalhe Pagador. 
recebedor body object sim Objeto: Detalhe Recebedor. 
devedor body object não Objeto: Detalhe Devedor. 
 
 
Corporativo | Interno 
 "transaction_id": "bqJJjaVAThmtnUeVLNnSXQ", 
 "documento": { 
 "valor_original": "100.00", 
 "valor_multa": "0.00", 
 "valor_juros": "0.00", 
 "valor_desconto": "0.00", 
 "valor_final": "100.00", 
 "calendario_expiracao": "2020-08-28T12:00:00", 
 "calendario_vencimento": "2020-08-20", 
 "solicitacao_pagador": "", 
 "info_adicionais": [{ 
 "nome": "Detalhes do Pagamento", 
 "valor": "Informação Adicional do PSP do Recebedor" 
 }] 
 }, 
 "devedor": { 
 "tipo_pessoa": "PJ", 
 "documento": "62143255000100", 
 "nome": "Fulano" 
 }, 
 "pagador": { 
 "tipo_conta": "Conta Corrente", 
 "agencia": "1500", 
 "conta": "00052012", 
 "tipo_pessoa": "PJ", 
 "documento": "00000000000191" 
 }, 
 "recebedor": { 
 "banco": "Itaú Unibanco", 
 "ispb": "60701190", 
 "tipo_conta": "Conta Corrente", 
 "agencia": "1500", 
 "conta": "00052061", 
 "tipo_pessoa": "PF", 
 
 
Corporativo | Interno 
 "documento": "00000000019", 
 "nome": "Maria PIX", 
 "tipo_chave": "email", 
 "identificacao_chave": "maria_pix@gmail.com" 
 } 
 } 
 
} 
Objetos 
Objeto Detalhe Documento 
 
 
Parâmetro Tipo Parâmetro Tipo Dado Obrigatório Descrição 
valor_original body string sim Valor original do documento 
valor_multa body string sim Valor multa do documento 
valor_juros body string sim Valor dos juros do documento 
valor_desconto body string sim Valor do desconto do documento 
valor_final body string sim Valor final do documento 
calendario_expiracao body string sim Data de expiração do documento 
calendario_vencimento body string sim Data de vencimento do documento 
informacoes_adicionais body string sim Informações adicionais do documento. 
solicitacao_pagador body string sim Mensagem a ser enviada ao pagador. 
 
 
Corporativo | Interno 
Objeto Detalhe Pagador 
 
 
Objeto Detalhe Recebedor 
Parâmetro Tipo Parâmetro Tipo Dado Obrigatório Descrição 
tipo_conta body string Sim Tipo de conta do pagador 
agencia body string sim Agência do pagador 
conta body string sim Conta do pagador 
tipo_pessoa body string sim Tipo de pessoa do pagador (PF ou PJ) 
documento body string sim Documento do pagador (CPF ou CNPJ) 
tipo_pagamento body string sim Módulo SISPAG utilizado para o pagamento 
Parâmetro Tipo Parâmetro Tipo Dado Obrigatório Descrição 
banco body string Sim Nome do banco do recebedor 
Ispb Body String Sim ISPB do banco do recebedor 
tipo_conta body string Sim Tipo de conta do recebedor 
agencia body string sim Agência do recebedor 
conta body string sim Conta do recebedor 
 
 
Corporativo | Interno 
 
Objeto Detalhe Devedor 
 
 
 
 
 
 
 
 
tipo_pessoa body string sim Tipo de pessoa do recebedor (PF ou PJ) 
documento body string sim Documento do recebedor (CPF ou CNPJ) 
nome body string sim Nome do favorecido 
tipo_chave body string sim Tipo da chave utilizada pelo favorecido 
identificacao_chave body string sim Identificação da chave utilizada pelo favorecido 
Parâmetro Tipo Parâmetro Tipo Dado Obrigatório Descrição 
tipo_pessoa body string sim Tipo de pessoa do devedor (PF ou PJ) 
documento body string sim Documento do devedor (CPF ou CNPJ) 
nome body string sim Nome do devedor 
 
 
Corporativo | Interno 
 
Consulta de pagamento 
Lista de pagamentos 
GET /cash_management_ext/v1/pagamentos_sispag 
API responsável por resgatar pagamentos SISPAG. Trará uma lista de pagamentos que atende aos filtros passados para API. 
 
Entrada 
Parâmetro Tipo Parâmetro Tipo Dado Obrigatório Descrição 
agencia_pagador query parameter string sim Agência do pagador 
conta_pagador query parameter string sim Conta do pagador 
numero_lote query parameter string não Número do lote de pagamento 
nome_beneficiario query parameter string não Nome do recebedor 
status query parameter string não Filtro do código do tipo do status. 
data_inicial query parameter Date-only não Data do pagamento inicial para consulta 
data_final query parameter Date-only não Data do pagamento final para consulta 
modalidade_fornecedores query parameter Boolean não Filtro do tipo de modalidade de pagamento para fornecedores 
modalidade_imposto query parameter Boolean não Filtro do tipo de modalidade de pagamento para impostos e tributos 
 
 
Corporativo | Interno 
 
Consulta de pagamento – Código de HTTP Status 
Código de HTTP Motivo 
200 Consulta realizada com sucesso 
400 Erros de validação ou os campos informados não existem no sistema. 
422 Inclusão não realizada por alguma regra de negócio não atendida. 
500 erro inesperado 
 
Saída 
modalidade_salario query parameter Boolean não Filtro do tipo de modalidade de pagamento para salário 
tipo_pagamento query parameter string não Filtro do tipo da transação bancária 
referencia_empresa query parameter string não Filtro pela referência da empresa 
valor_minimo query parameter string não Valor mínimo do pagamento da consulta 
valor_maximo query parameter string não Valor máximo do pagamento da consulta 
Parâmetro Tipo Parâmetro Tipo Dado Obrigatório Descrição 
nome_favorecido body string sim Nome do Favorecido 
id_pagamento body string sim Identificação do pagamento. 
 
 
Corporativo | Interno 
 
Exemplo saída - OK 
{ 
 "data": { 
 "itens": [ 
 { 
 "nome_favorecido":"Teste nome favorecido 1", 
 "id_pagamento": "3a2a32d3-37c3-4bf9-b526-b8e3a17592b9", 
 "cpf_cnpj": "89057409011", 
 "cod_banco": "123", 
 "numero_agencia": "1500", 
 "numero_conta": "2011500", 
 "numero_lancamento": "123456789", 
Ispb_favorecido body string sim Número do ISPB do favorecido 
numero_agencia body string sim Número da agência do favorecido 
numero_conta body string Sim Número da conta do favorecido 
referencia_empresa body string não texto livre de referência da empresa sobre o pagamento. 
data_pagamento body string sim Data em que será realizado o pagamento. Formato “YYYY-MM-
DDTHH:MM:SS”. 
valor_pagamento body string sim Valor da transferência. 
status body string sim texto livre de referência da empresa sobre o pagamento. 
comprovante body string não Link para comprovante do pagamento 
motivo body string não Motivo de recusa do pagamento (se houver) 
tipo_pagamento body string sim Tipo do pagamento 
 
 
Corporativo | Interno 
 "referencia_empresa": " ", 
 "data_pagamento": "2020-07-01", 
 "valor_pagamento": "100.00", 
 "status": "Efetuados", 
 "comprovante": "link", 
 "motivo": "", 
 "tipo_pagamento": "TED" 
 }, 
 { 
 "nome_favorecido": "Teste nome favorecido 1", 
 "id_pagamento": "3a2a32d3-37c3-4bf9-b526-b8e3a17592b8", 
 "cpf_cnpj": "89057409011", 
 "cod_banco": "123", 
 "numero_agencia": "1500", 
 "numero_conta": "2011500", 
 "numero_lancamento": "123456789", 
 "referencia_empresa": " ", 
 "data_pagamento": "2020-07-01", 
 "valor_pagamento": "100.00", 
 "status": "Efetuados", 
 "comprovante": "link", 
 "motivo": "", 
 "tipo_pagamento": "TED" 
 } 
 ], 
 "total": "200.00" 
 }, 
 "pagination": { 
 "links": { 
 "first": "https://des-apigateway-int.mbi.cloud.ihf/cash_management/v1/lista_detalhada_pagamentos/", 
 "last": "https://des-apigateway-int.mbi.cloud.ihf/cash_management/v1/lista_detalhada_pagamentos/?page=2", 
 "previous": "", 
 "next": "https://des-apigateway-int.mbi.cloud.ihf/cash_management/v1/lista_detalhada_pagamentos/?page=1" 
 }, 
 
 
Corporativo | Interno 
 "page": 0, 
 "total_pages": 3, 
 "total_elements": 6, 
 "page_size": 2 
 } 
} 
 
Detalhe do pagamento 
GET /cash_management_ext/v1/pagamentos_sispag/{id_pagamento} 
API responsável por resgatar o detalhe do pagamento SISPAG. Retorno varia de acordo com a forma do pagamento detalhado. 
Entrada 
 
Saída 
Parâmetro Tipo Parâmetro Tipo Dado Obrigatório Descrição 
id_pagamento Path string sim Código único do pagamento. 
Parâmetro Tipo Parâmetro Tipo Dado Obrigatório Descrição 
dados_debito body object sim Objeto: Dados Debito 
dados_pagamento body object sim Objeto: Dados Pagamento 
 
 
Corporativo | Interno 
 
 
 
Consulta de pagamento – Código de HTTP Status 
Código de HTTP Motivo 
200 Consulta realizada com sucesso 
400 Erros de validação ou os campos informados não existem no sistema. 
422 Inclusão não realizada por alguma regra de negócio não atendida. 
500 erro inesperado 
 
 
Exemplo saída - OK 
"data": { 
 "dados_debito": { 
 "numero_agencia_debito": "1500", 
 "numero_conta_debito": "052020", 
 "nome_empresa_debito": "NOME RDZD", 
 "cnpj_debito": "34727090000139" 
 }, 
 "dados_pagamento": { 
 "id_pagamento": "3a2a32d3-37c3-4bf9-b526-b8e3a17592b9", 
 "cod_tipo_pessoa": "", 
historico_pagamento body object sim Objeto: Histórico Pagamento 
 
 
Corporativo | Interno 
 "cpf_cnpj_favorecido": "01046001019", 
 "cod_banco_favorecido": "341", 
 "nome_banco_favorecido": "BANCO ITAU S/A", 
 "numero_agencia_favorecido": "1500", 
 "numero_conta_favorecido": "2011500", 
 "nome_favorecido": "TESTE", 
 "valor_pagamento": "1000.00", 
 "numero_lote": "123", 
 "numero_lancamento": "456", 
 "referencia_empresa": "0197 256771", 
 "data_pagamento": "2020-06-15", 
 "status": "Efetuado", 
 "descricao_pagamento": "", 
 "identificacao_comprovante": "pix0123", 
 "codigo_isbp": "", 
 "descricao_finalidade": "", 
 "modalidade_pagto": "", 
 "tipo_pagamento": "", 
 "indicador_motivo": "", 
 "dados_ted": null, 
 "dados_doc": null, 
 "dados_darf": null, 
 "dados_cheque": null, 
 "dados_op": null, 
 "dados_gps": null, 
 "dados_iptu_inss": null, 
 "dados_gare_icms_sp": null, 
 "dados_gare_icms_sp_importacao": null, 
 "dados_gnre_icms_sp_importacao": null, 
 "dados_ipva": null, 
 "dados_fgts": null, 
 "dados_dpvat": null, 
 "dados_licenciamento": null, 
 "dados_multa": null, 
 
 
Corporativo | Interno 
 "dados_trib_cod_barras": null, 
 "motivo_rejeicao": [ 
 { 
 "descricao_motivo": "Teste Motivo rejeicao 1" 
 }, 
 { 
 "descricao_motivo": "Teste Motivo rejeicao 2" 
 } 
 ] 
 }, 
 "historico_pagamento": [ 
 { 
 "status": "Efetivação", 
 "data": "2020-01-01", 
 "nome_operador": "Oper Ex", 
 "cod_operador": "999999999", 
 "cpf_operador": "" 
 }, 
 { 
 "status": "Autorização", 
 "data": "2020-01-01", 
 "nome_operador": "Oper Ex", 
 "cod_operador": "999999999", 
 "cpf_operador": "" 
 }, 
 { 
 "status": "Inclusão Online", 
 "data": "2020-01-01", 
 "nome_operador": "Oper Ex", 
 "cod_operador": "999999999", 
 "cpf_operador": "" 
 } 
 ] 
}