PSP FISERV - API Pix

Este documento tem o intuito de complementar a documentação Swagger das APIs do PSP Fiserv, as quais foram desenvolvidas para facilitar a integração com os parceiros para as operações envolvendo clientes, contas, cobranças e pagamentos via Pix. As principais funcionalidades incluem:

Autenticação: Obtenção de token para todas as operações
Gestão de Clientes: Adicione, atualize, consulte e delete clientes
Gestão de Contas: Adicione, atualize, consulte e delete contas.
Geração de Cobranças Pix: Crie cobranças Pix de forma eficiente e segura, permitindo que seus clientes realizem pagamentos via Pix.
Consulta de Pagamentos Pix: Consulte status e detalhes de pagamentos realizados via Pix para maior controle e transparência.
Devolução: Realize devolução de pagamentos via Pix de maneira eficiente, assegurando a satisfação dos seus clientes.
Liquidação: Saída dos valores obtidos de forma automática ou manual.
Gestão de Webhooks: Registre webhooks para receber notificações automáticas sobre eventos importantes como cadastro de cliente e confirmações de transações.
Relatórios: Gere relatórios detalhados das transações Pix e das liquidações, facilitando a conciliação e acompanhamento das operações

Ambientes#

Produção

https://connect.latam.fiservapis.com/gateway

Testes

https://connect-cert.latam.fiservapis.com/gateway

Conteúdo#

📍Autenticação #

📍Gestão de Webhooks #

🔻Callbacks #

📍Cadastro de clientes #

📍Cadastro de contas #

📍Transações #

📍Cash-out #

📍Relatórios #

📍Informações adicionais #

🔻Objeto padrão de erros #

🔻Header padrão #

🔻Cálculo do HMAC #

🔻Para Testes #

#

Autenticação#

🔒 /token#

POST#

Endpoint de autenticação necessário para todas as chamadas. Obtenha o token de autenticação através de um client_secret e client_id, envie através de application/x-www-form-urlencoded e utilize o token Bearer nas requisições subsequentes.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string

Exemplo de Request#

application/x-www-form-urlencoded

Campo	Valor
client_id	user1234
client_secret	userPassword@123

Responses#

Código	Descrição
200	Retorna o token de acesso e as informações de expiração

Exemplo de Response#

{
  "access_token": "your-access-token",
  "expires_in": 300
}

#

Webhook#

/v1/webhook#

Configura (cria) o webhook do integrador para recebimento de notificações de cadastro de cliente, pagamento e devolução de cobranças.

ATENÇÃO: Para atualizar a URL, é necessário solicitar ao time Fiserv, por ser necessário liberar a URL no proxy.

PUT#

Configurar o Webhook do Integrador.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
webhookUrl	body	URL que será chamada no callback	sim	string
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)

Exemplo de Request#

{
  "webhookUrl": "https://pix.example.com/api/webhook/"
}

Responses#

Código	Descrição
204	Webhook que notificará o integrador
400	Requisição com formato inválido
503	Serviço indisponível

GET#

Exibe a URL de Webhook registrada do integrador.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)

Responses#

Código	Descrição
200	Dados do Webhook
503	Serviço indisponível

Exemplo de Response#

{
  "webhookUrl": "https://pix.example.com/api/webhook/"
}

DELETE#

Exclui o webhook de um integrador.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)

Responses#

Código	Descrição
204	Webhook para notificações do Pix cancelado
503	Serviço indisponível

#

CALLBACKS#

POST /client#

Após o cadastro do cliente e o processo de KYC ser finalizado, a URL cadastrada no para o webhook recebe a notificação abaixo:

{
     "protocolId":"347acdf2-7b01-4191-acff-36bd23639e43",
     "externalProtocolId":"8dd562ee4a7a",
     "omniClientId":"f932d207-573c-439c-b444-6ca26afff066",
     "document":{
        "type":"CNPJ",
        "number":"60664745000187"
         },
    "status":"DONE",
    "errors ":[ {
        "code":"FEP_123",
        "message":"string"
     }
         ]
 }

Quando Status = DONE, indica que o processamento foi finalizado e o status final do KYC e a consulta de cliente pode ser consultada.

POST /v1/apm/pix/charges#

Após a finalização da transação de cobrança, a URL cadastrada no webhook recebe a notificação abaixo:

{
    "Pix": {
        "endToEndId":"D13207930202410252046wrzeq7wrQZ8",
        "txid":"D13207930202410252034KgylGnIt2T3",
        "chave":"ac2ce947-fa51-4dd1-a4f9-52181bcc971f",
        "Status":1,
        "OperationType":2
    }
}

Campo	Tipo	Descrição
Pix.endToEndId	string	End to End da confirmação de pagamento
Pix.txid	string	Id da transação
Pix.chave	string	Chave Pix da conta
Pix.Status	string	Status da Transação Faltou o status: Valores possíveis : 0-PENDENTE;1 - CONFIRMADO; 2 - CANCELADO
Pix.OperationType	string	Tipo da Transação (0 – Cobrança, 1- Devolução Parcial, 2 – Estorno)

Client#

#

/v1/client#

#

POST#

Adiciona um cliente.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)
address.city	body	Cidade do cliente	sim	string
address.country	body	País do cliente	sim	string
address.locality	body	Distrito, colônia, vila ou bairro do cliente	sim	string
address.number	body	Número do endereço do cliente	não	string
address.postalCode	body	CEP do cliente	sim	string
address.province	body	Estado do cliente	sim	string
address.street	body	Logradouro do cliente	sim	string
address.subNumber	body	Complemento do endereço	não	string
document.number	body	Número do Documento	sim	string
document.type	body	Tipo do documento. Valores possíveis: CNPJ	sim	enum
contact.email	body	E-mail do cliente	sim	string
contact.phone	body	Número de Telefone do cliente	sim	string
legalName	body	Razão social do cliente	sim	string
tradeName	body	Nome fantasia	sim	string
averageTicket	body	Ticket médio	sim	int

Exemplo de Request#

{
  "address": {
    "city": "string",
    "country": "str",
    "locality": "string",
    "number": "153",
    "postalCode": "string",
    "province": "string",
    "street": "string",
    "subNumber": "string"
  },
  "document": {
    "number": "60.664.745/0001-87",
    "type": "CNPJ"
  },
  "contact": {
    "email": "user@example.com",
    "phone": "string"
  },
  "legalName": "Fiserv Inc",
  "tradeName": "Fiserv",
  "averageTicket": 100.00
}

Responses#

Nome	Descrição	Tipo
clientId	Identificador único do cliente	string
protocolId	Protocolo da requisição	string

Com o webhook cadastrado, após a conclusão do processo de KYC do cliente, é enviada uma notificação no endereço cadastrado, com o status do processamento e o protocolId.

Exemplo de Response#

{
  "clientId": "bb41c1e6-654f-4263-83f4-36e37678f548",
  "protocolId": "Request protocol"
}

Código	Descrição
200	OK
400	Bad Request
403	Forbidden
404	Not Found
500	Internal Server Error
503	Service Unavailable
504	Gateway Timeout

/v1/client/{clientId}#

#

GET#

Localiza os detalhes do cliente.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)
clientId	path	ClientId do cliente (disponibilizado ao adicionar um novo cliente)	sim	string

Exemplo de response#

{
  "kycStatus": "Approved"
}

O KycSytatus pode ser um dos seguintes:
🔸 APPROVED
🔸 PENDING
🔸 PROCESSING
🔸 REFUSED
🔸 ERROR

Somente o status APPROVED permite a continuação do processo de credenciamento e a criação de uma Conta Pix

Responses#

Código	Descrição
200	OK
400	Bad Request
403	Forbidden
404	Not Found
500	Internal Server Error
503	Service Unavailable
504	Gateway Timeout

Pix Account#

Informações gerais sobre a gestão de contas#

pixFee#

Pix fee, ou taxa do Pix, é a taxa que é cobrada a cada transação realizada. Ela pode ser do tipo valor fixo (amount) ou MDR - Merchant Discount Rate (percentage) quando o modelo comercial for comissionamento. Ou não possui valor nenhum quando o modelo comercial for faturamento.

Exemplo modelo comercial comissionamento com valor fixo#

Taxa cadastrada para conta: R$ 0,85

Cobrança realizada: R$ 30,00

Taxa na cobranca: R$ 0,85

Valor líquido: R$ 29,15

Exemplo modelo comercial comissionamento com valor MDR#

Taxa cadastrada para conta: 1%

Cobrança realizada: R$ 22,00

Taxa na cobranca: R$ 0,22

Valor líquido: R$ 21,78

/v1/client/{clientId}/apm/pix/account#

#

POST#

Adiciona uma conta Pix.

Parâmetros#

Campo	Localizado em	Tipo	Obrigatório	Descrição
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	string (bearerToken)	sim	Bearer Token usado para autenticação
clientId	path	string	sim	Client Id
Settlement.pixKey	body	string	sim	Somente a chave domicílio ou os dados da conta devem ser informados, nunca ambos
Settlement.bankAccount.type	body	integer	sim	(enum) 0. Conta Corrente, 1. Conta Depósito 2. Conta de Pagamento 3. Poupança
Settlement.bankAccount.BankCompeCode	body	string	sim	Código COMPE (Sistema de Compensação de Cheques e Outros Papéis)
Settlement.bankAccount.agency	body	string	sim	Número da agência
Settlement.bankAccount.accountNumber	body	string	sim	Número da Conta
Settlement.bankAccount.document.number	body	string	sim	CNPJ da conta. Deve ter a mesma raiz do CNPJ cadastrado
Settlement.bankAccount.document.type	body	string	sim	Informar sempre “CNPJ”
Settlement.holdSettlement	body	bool	não	Indicador para manter dinheiro da cobrança na conta sem liquidar, ou liquidar.(Para alterar por transação verificar endpoint holdSettlement)
pixFee.amount	body	decimal	não	Não pode ser maior que 0 se a porcentagem for informada
pixFee.percentage	body	decimal	não	Não pode ser maior que 0 se o valor for informado
pixFee.min	body	decimal	não	Pode ser zero; Não pode ser negativo
pixFee.max	body	decimal	não	Só pode ser enviado caso exista o min; Não pode ser zero; Não pode ser negativo Nunca poderá ser menor ou igual ao min
userTermsAccept.number.number	body	string	sim	CPF da pessoa que está realizando o aceite
userTermsAccept.document.type	body	string	sim	Tipo do documento. Sempre “CPF”
userTermsAccept.ip	body	string	sim	IP da máquina que deu o termo de aceite
hasAutomaticSettlement	body	boolean	sim	Indicador que realiza liquidação dos valores automaticamente

Exemplo de Request#

{
  "settlement": {
    "pixKey": "26770318000145",
    "bankAccount": {
      "accountNumber": "12345-1",
      "agency": "1234",
      "bankCompeCode": "341",
      "document": {
        "number": "60.664.745/0001-87",
        "type": "CNPJ"
      },
      "type": 1
    },
    "holdSettlement": true
  },
  "pixFee": {
    "amount": 0,
    "percentage": 2,
    "max": 0,
    "min": 0
  },
  "userTermsAccept": {
    "document": {
      "number": "60.664.745/0001-87",
      "type": "CNPJ"
    },
    "ip": "198.51.100.42"
  },
  "hasAutomaticSettlement": true
}

Exemplo de Response#

{
  "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd"
}

Responses#

Código	Descrição
200	OK
400	Bad Request
401	Unauthorized
422	Client Error
500	Server Error

Possíveis erros:#

Código de erro	Erro
148	O nome da account é inválido
149	O CNPJ da account é inválido
154	A taxa deve ter um único valor
158	Conta não encontrada.
161	A conta não está ativa
162	A chave PixKey deve ser diferente da chave AddressPixKey
169	A conta domicílio informada é inválida
170	A conta domicílio é obrigatória
171	Não é possível informar duas contas domicílio
174	O CNPJ da conta de liquidação é inválido
176	Não é possível alterar as informações para liquidação desta conta
177	Não é possível alterar a taxa desta conta
178	O código ISPB ou o código COMPE deve ser preenchido.
187	A taxa máxima deve ser maior que a taxa mínima.
188	A taxa mínima deve ser informada devido à taxa máxima ter sido informada.
189	A taxa mínima deve ser maior ou igual a zero.
190	A taxa máxima deve ser maior que zero.
191	A taxa mínima e máxima só devem ser informadas em caso de taxa MDR.

/v1/client/{clientId}/apm/pix/account/{pixKey}#

GET#

Consulta uma conta com base na chave PIX.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)
pixKey	path	Chave PIX da conta	sim	string
clientId	path	Identificador do cliente	sim	string

Exemplo de Response#

{
  "name": "Store Nome",
  "documentNumber": "14821268000107",
  "status": 1,
  "settlement": {
    "pixKey": "26770318000145",
    "bankAccount": {
      "accountNumber": "12345-1",
      "agency": "1234",
      "bankCompeCode": "341",
      "document": {
        "number": "60.664.745/0001-87",
        "type": "CNPJ"
      },
      "type": 1
    },
    "holdSettlement": true
  },
  "pixFee": {
    "amount": 0,
    "percentage": 2,
    "max": 0,
    "min": 0
  },
  "hasAutomaticSettlement": true
}

Responses#

Código	Descrição
200	Success
400	Bad Request
401	Unauthorized
422	Client Erro
500	Server Erro

PUT#

Altera uma conta Pix.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)
clientId	path	Identificador do cliente	sim	string
pixKey	path	Chave Pix da conta a ser atualizada	sim	string
settlement.pixKey	body	Chave Pix da conta domicílio. Somente a chave ou os dados da conta domicilio devem ser informados, nunca ambos	sim	string
settlement.holdSettlement	body	Indicador para manter dinheiro da cobrança na conta sem liquidar, ou liquidar.(Para alterar por transação verificar endpoint holdSettlement)	sim	boolean
settlement.bankAccount.type	body	0.Conta Corrente; 1.Conta Depósito; 2.Conta de Pagamento; 3.Poupança	sim	int (enum)
settlement.bankAccount.BankCompeCode	body	Código COMPE (Sistema de Compensação de Cheques e Outros Papéis)	sim	string
settlement.bankAccount.agency	body	Agência bancária	sim	string
settlement.bankAccount.accountNumber	body	Número da conta	sim	string
settlement.bankAccount.cnpj	body	Deve ter a mesma raíz do cnpj cadastrado	sim	int
pixFee.amount	body	Não pode ser maior que 0 se a porcentagem for informada	sim	int
pixFee.percentage	body	Não pode ser maior que 0 se o valor for informado	sim	int
pixFee.min	body	Pode ser zero, mas não pode ser negativo.	sim	int
pixFee.max	body	Só pode ser enviado caso exista o min; não pode ser zero; não pode ser negativo; nunca poderá ser menor ou igual ao min	sim	int
hasAutomaticSettlement	body	Indicador se realiza liquidação dos valores automaticamente	sim	boolean

Exemplo de Request#

{
  "name": "Store name",
  "settlement": {
    "pixKey": "26770318000145",
    "bankAccount": {
      "accountNumber": "12345-1",
      "agency": "1234",
      "bankCompeCode": "341",
      "document": {
        "number": "60.664.745/0001-87",
        "type": "CNPJ"
      },
      "type": 1
    },
    "holdSettlement": true
  },
  "pixFee": {
    "amount": 0,
    "percentage": 2,
    "max": 0,
    "min": 0
  },
  "hasAutomaticSettlement": true
}

Responses#

Código	Descrição
204	No Content
400	Bad Request
401	Unauthorized
422	Client Erro
500	Server Erro

Possíveis erros#

Código de erro	Erro
154	A taxa deve ter um único valor
158	Conta não encontrada.
161	A conta não está ativa
162	A chave PixKey deve ser diferente da chave AddressPixKey
169	A conta domicílio informada é inválida
170	A conta domicílio é obrigatória
171	Não é possível informar duas contas domicílio
174	O CNPJ da conta de liquidação é inválido
176	Não é possível alterar as informações para liquidação desta conta
177	Não é possível alterar a taxa desta conta
178	O código ISPB ou o código COMPE deve ser preenchido.
187	A taxa máxima deve ser maior que a taxa mínima.
188	A taxa mínima deve ser informada devido à taxa máxima ter sido informada.
189	A taxa mínima deve ser maior ou igual a zero.
190	A taxa máxima deve ser maior que zero.
191	A taxa mínima e máxima só devem ser informadas em caso de taxa MDR.

DELETE#

Deleta uma conta pix.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)
pixKey	path	Chave Pix da conta	sim	string
clientId	path	Identificador do cliente	sim	string

Responses#

Código	Descrição
204	No Content
400	Bad Request
401	Unauthorized
422	Client Error
500	Server Error

/v2/client/{clientId}/apm/pix/account/balance/{pixKey} `#

GET#

Consulta o saldo da conta por chave pix.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)
clientId	path	Identificador do cliente	sim	string
pixKey	path	Chave Pix da conta	sim	string

Exemplo de Response#

{
  "availableBalance": 2500000.42,
  "blockedBalance": 500000.18,
  "totalBalance": 3000000.6
}

Responses#

Campo	Tipo	Observações
availableBalance	decimal	Saldo disponível na conta
blockedBalance	decimal	Saldo bloqueado na conta
totalBalance	decimal	Saldo total da conta

/v1/client/{clientId}/apm/pix/accounts#

GET#

Consulta contas de um cliente.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)
clientId	path	Identificador do cliente	sim	string
pagination.currentPage	query	Página a ser consultada	não	int
pagination.pageSize	query	Número de ítens por página	não	int

Exemplo de Response#

{
  "content": [
    {
      "name": "Store name",
      "pixFee": {
        "amount": 0,
        "percentage": 2,
        "max": 0,
        "min": 0
      },
      "settlement": {
        "bankAccount": {
          "accountNumber": "12345-1",
          "agency": "1234",
          "bankCompeCode": "123",
          "document": {
            "number": "60.664.745/0001-87",
            "type": "CNPJ"
          },
          "ispb": "00000000",
          "type": 1
        },
        "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd"
      },
      "status": "string",
      "hasAutomaticSettlement": true
    }
  ],
  "totalElements": 10
}

Responses#

Código	Descrição
200	OK
400	Bad Request
401	Unauthorized
422	Client Erro
500	Server Erro

/v1/apm/pix/accounts#

GET#

Consulta contas de um integrador.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)
pagination.currentPage	query	Página que será consultada	não	int
pagination.pageSize	query	Número de ítens por página	não	int

Exemplo de Response#

{
  "content": [
    {
      "name": "Store name",
      "pixFee": {
        "amount": 0,
        "percentage": 2,
        "max": 0,
        "min": 0
      },
      "settlement": {
        "bankAccount": {
          "accountNumber": "12345-1",
          "agency": "1234",
          "bankCompeCode": "123",
          "document": {
            "number": "60.664.745/0001-87",
            "type": "CNPJ"
          },
          "ispb": "00000000",
          "type": 1
        },
        "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd"
      },
      "status": "string",
      "hasAutomaticSettlement": true
    }
  ],
  "totalElements": 10
}

Responses#

Código	Descrição
200	OK
400	Bad Request
401	Unauthorized
422	Client Error
500	Server Error

#

Pix Transaction#

/v1/apm/pix/charge#

#

POST#

Cria uma cobrança imediata.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)
amount	body	Valor da cobrança	sim	decimal
pixKey	body	Chave pix da conta	sim	string
returnQrCodeImage	body	Indicador para retornar a imagem do qrCode ou não (false default)	sim	bool
expiration	body	Tempo de expiração do QRcode em segundos	sim	int

Exemplo de Request#

{
  "expiration": 3600,
  "amount": "18.92",
  "returnQrCodeImage": false,
  "additionalInfo": [
    {
      "name": "Title of information",
      "value": "Content of information"
    }
  ],
  "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd",
  "payerDocument": "36264164615"
}

Responses#

Campo	Tipo	Observações
txid	string	Id da transação gerada
location	string	Localização do QRCode gerado
qrCodeImage	bool	Imagem em base64 do QRcode (Apenas quando informado returnQrCodeImage= true)
status	string	Status da transação. Valores possíveis: 0- PENDING;1 - CONFIRMED; 2 - CANCELLED
amount	decimal	Valor da transação
pixCopyPaste	string	Código copia e cola do pix
pixKey	string	Chave pix utilizada para a transação

Código	Descrição
200	Immediate charge created
400	Request with invalid format
404	The requested content was not found
503	This service is currently unavailable

Exemplo de Response#

{
  "txid": "ALzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2p",
  "location": "pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002",
  "qrCodeImage": null,
  "status": "PENDING",
  "amount": "18.92",
  "additionalInfo": [
    {
      "name": "Title of information",
      "value": "Content of information"
    }
  ],
  "pixCopyPaste": "00020101021226830014BR.GOV.BCB.PIX2561api-h.rendimento.com.br/q/v2/aeafe31da3ef48c295e6353d703415da5204000053039865802BR5915Teste-automacao6009SAO PAULO61081125553262070503***6304BE8A",
  "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd"
}

Possíveis códigos de erro#

Erro	Descrição
157	Essa cobrança não possui um valor de taxa
96	A data de agendamento da liquidação é menor que a data atual.
153	A conta para essa chave pix não está ativa
157	Essa cobrança não possui um valor de taxa
158	Conta não encontrada.
167	Conta suspensa para processamento de cobranças.
193	A cobrança não pode ser nula ou negativa.

/v1/apm/pix/charge/{txid} '#

GET#

Consultar cobrança imediata através de um determinado txid.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
txid	path	Id da transação	sim	string
returnQrCodeImage	query	Indicador se deve ser gerado QrCode em base64 ou não	não	boolean

Responses#

{
    "txid": "string",
    "amount": 99.99,
    "status": "status",
    "location": "string",
    "pixCopyAndPaste": "string",
    "qrCodeImage": "string"
}

Código	Descrição
200	Dados da cobrança imediata
404	Requisição não encontrada
503	Serviço indisponível

Exemplo de Response#

{
  "expiration": 3600,
  "amount": "18.92",
  "returnQrCodeImage": false,
  "additionalInfo": [
    {
      "name": "Title of information",
      "value": "Content of information"
    }
  ],
  "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd",
  "txid": "ALzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2p",
  "location": "pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002",
  "qrCodeImage": null,
  "status": "PENDING",
  "pixCopyPaste": "00020101021226830014BR.GOV.BCB.PIX2561api-h.rendimento.com.br/q/v2/aeafe31da3ef48c295e6353d703415da5204000053039865802BR5915Teste-automacao6009SAO PAULO61081125553262070503***6304BE8A",
  "createdAt": "2025-06-06T04:32:06.055Z",
  "pix": [
    {
      "endToEndId": "EDARFlxoxT0zBhFBqEIC6c2QQCo2d54U",
      "amount": "231.39",
      "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd",
      "confirmedAt": "2025-06-06T04:32:06.055Z",
      "fraudReproval": null,
      "reverses": [
        {
          "txid": "DLzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2h",
          "endToEndId": "D12345678202009091000abcde123456",
          "amount": "231.39",
          "confirmedAt": "2025-06-06T04:32:06.055Z",
          "status": "PENDING"
        }
      ]
    }
  ]
}

/v1/apm/pix/charge/cancel/{txid} '#

PATCH#

Cancela cobrança imediata.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
txid	path	Id da transação a ser consultada	sim	string

Responses#

Código	Descrição
204	No Content
400	Request with invalid format
404	The requested content was not found
503	Service Unavailable

/v1/apm/pix/charges#

GET#

Consulta lista de cobranças imediatas através de parâmetros como início, fim, cpf, cnpj e status.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
startDate	query	Data de início para filtrar a consulta	sim	timezone (ISO 8601)
endDate	query	Data de fim para filtrar a consulta	sim	timezone (ISO 8601)
pixKey	query	Chave Pix da conta	não	string
documentNumber	query	Número do CNPJ	não	string
status	query	Status da cobrança. Valores possíveis : 0-PENDENTE;1 - CONFIRMADO; 2 - CANCELADO	não	string
pagination.currentPage	query	Página que será consultada	não	int
pagination.pageSize	query	Número de ítens por página	não	int

Responses#

Código	Descrição
200	Lista de cobranças imediatas
503	Serviço indisponível

Exemplo de response#

{
  "criteria": {
    "startDate": "2020-04-01T00:00:00Z",
    "endDate": "2020-04-01T17:00:00Z",
    "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd",
    "documentNumber": "27574383000168",
    "status": 1
  },
  "results": [
    {
      "expiration": 3600,
      "amount": "18.92",
      "returnQrCodeImage": false,
      "additionalInfo": [
        {
          "name": "Title of information",
          "value": "Content of information"
        }
      ],
      "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd",
      "txid": "ALzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2p",
      "location": "pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002",
      "qrCodeImage": null,
      "status": "PENDING",
      "pixCopyPaste": "00020101021226830014BR.GOV.BCB.PIX2561api-h.rendimento.com.br/q/v2/aeafe31da3ef48c295e6353d703415da5204000053039865802BR5915Teste-automacao6009SAO PAULO61081125553262070503***6304BE8A",
      "createdAt": "2025-06-06T04:35:23.707Z",
      "pix": [
        {
          "endToEndId": "EDARFlxoxT0zBhFBqEIC6c2QQCo2d54U",
          "amount": "231.39",
          "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd",
          "confirmedAt": "2025-06-06T04:35:23.707Z",
          "fraudReproval": null,
          "reverses": [
            {
              "txid": "DLzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2h",
              "endToEndId": "D12345678202009091000abcde123456",
              "amount": "231.39",
              "confirmedAt": "2025-06-06T04:35:23.707Z",
              "status": "0"
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 1,
    "totalPages": 1,
    "totalItems": 1
  }
}

/v1/apm/pix/{endToEndId}/reverse/{txid}'#

#

PUT#

Solicita uma devolução.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
endToEndId	path	Código end to end da transação	sim	string
txid	path	Id da transação	sim	string

Exemplo de Request#

{
  "amount": "231.39"
}

Responses#

Código	Descrição
200	Dados requisitados
400	Requisição com formato inválido
404	Requisição não encontrada
503	Serviço indisponível

Exemplo de Response#

{
  "txid": "DLzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2h",
  "endToEndId": "D12345678202009091000abcde123456",
  "amount": "231.39",
  "confirmedAt": "2025-06-06T04:37:07.173Z",
  "status": "PENDING"
}

GET#

Consulta devolução através de um End To End ID do Pix e do ID da devolução.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)
endToEndId	path	Código End To End do pagamento	sim	string
txid	path	Identificador da transação	sim	string

Responses#

Código	Descrição
200	Dados da devolução
404	Requisição não encontrada
503	Serviço indisponível

Exemplo de Response#

{
  "txid": "DLzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2h",
  "endToEndId": "D12345678202009091000abcde123456",
  "amount": "231.39",
  "confirmedAt": "2025-06-06T04:40:25.725Z",
  "status": "PENDING"
}

/v1/apm/pix/charge/settlement/hold/{txid}'#

PATCH#

Bloqueia a liquidação da cobrança do Pix até que ela seja desbloqueada.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string
txid	path	Charge unique identifier	sim	string

Responses#

Código	Descrição
204	No Content
400	Request with invalid format
404	Request content not found
503	Service unavailable

/v1/apm/pix/charge/settlement/release/{txid}'#

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string
txid	path	Charge unique identifier	sim	string

Responses#

Código	Descrição
204	No Content
400	Request with invalid format
404	Request content not found
503	Service unavailable

/v1/apm/pix/charge/settlement/release/{txid}#

PATCH#

Permite que a cobrança do pix seja liquidada na próxima janela de liquidação.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
Authorization	header	Bearer Token usado para autenticação	sim	string
txid	path	Charge unique identifier	sim	string

Responses#

Código	Descrição
204	No Content
400	Request with invalid format
404	Request content not found
503	Service unavailable

#

Cashout#

/v2/apm/pix/cashout#

POST#

Cria a solicitação de cash-out (saque manual).

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string
pixKey	query	Chave pix da conta origem	sim	string
amount	body	Valor do cashout (BRL)	sim	decimal
receiverPixKey	body	Chave pix do recebedor	sim	bool
receiverDocument	body	Documento do recebedor. Será validado e deve ser da mesma titularidade da chave pix.	sim	string

Exemplo de Request#

{
  "pixKey": "tec7e05d-484e-4814-a432-dde637f84402",
  "receiverDocument": "36264164615",
  "receiverPixKey": "pix-key-receiver@mail.com",
  "amount": 99.99
}

Responses#

Campo	Tipo	Observações
txid	string	Indentificador do cashout

Exemplo de Response#

{
  "txid": "2a2cc743-3913-48ea-91fe-13256ab3c3d2"
}

Após solicitar com sucesso a operação de saque, algumas validações serão realizadas de forma assíncrona, e o saque ainda pode ser negado. O resultado dessa validação, juntamente com a chave de confirmação necessária para a solicitação de confirmação (cashout/confirm), será enviado para o webhook, conforme detalhado abaixo.

GET#

Localiza solicitações de saques manuais.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string
pixKey	query	Chave Pix da conta	sim	string
startDate	query	Data Inicial do filtro	sim	DateTime (ISO 8601)
endDate	query	Data final do filtro	sim	DateTime (ISO 8601)
status	query	Status do cashout.	sim	Valores possíveis: 0 - Pendente (Aguardando confirmação) 1 – Processando (Processando pagamento) 2 - Confirmado (pago) 3 - Falhou (Pagamento falhou) 4 - Expirado (Confirmação expirada)

Responses#

Campo	Tipo	Observações
result.txid	string	Identificador único da operação de cashout
result.endToEndId	string	End To End da transação, Será sempre nulo até a confirmação da solicitação.
result.createdAt	DateTime (ISO 8601)	Data e hora da solicitação de saque
result.confirmedAt	DateTime (ISO 8601)	Data e hora da confirmação de saque
result.pixKey	string	Chave pix da conta Fiserv (origem)
result.receiverDocument	string	Documento da conta destino
result.receiverPixKey	string	Chave Pix da conta destino
result.amount	decimal	Valor do saque (BRL)
result.status	int (enum)	Status do saque Valores possíveis: 0 - Pendente (Aguardando confirmação) 1 – Processando (Processando pagamento) 2 - Confirmado (pago) 3- Falhou (Pagamento falhou) 4- Expirado (Confirmação expirada) 5 – Solicitado (Solicitado)
result.failReason	Int(enum)	Tipo de falha (Somente quando o status for de falha) 1 - Sem Limite 2 - Sem Saldo 3 - Expirado 4 - Concorrência 5 - Falha de processamento 6 - Suspeita de Fraude
criteria.pixKey	string	Chave Pix da conta utilizada nos filtros
criteria.startDate	DateTime (ISO 8601)	Data inicial utilizada para os filtros
criteria.endDate	DateTime (ISO 8601)	Data final utilizada para os filtros
criteria.status	int (enum)	Status do saque Valores possíveis: 0 - Pendente (Aguardando confirmação) 1 – Processando (Processando pagamento) 2 - Confirmado (pago) 3 - Falhou (Pagamento falhou) 4 - Expirado (Confirmação expirada) 5 – Solicitado (Solicitado)
pagination.currentPage	int	Página atual
pagination.pageSize	int	Tamanho da página
pagination.totalPages	int	Total de páginas
pagination.totalItems	int	Total de itens

Exemplo de Response#

{
  "criteria": {
    "startDate": "2025-01-16 09:33:01.573Z",
    "endDate": "2025-01-16 09:33:01.573Z",
    "pixKey": "b57c7b3c-976b-41f6-a5f6-7cccd86549bd",
    "status": 2
  },
  "result": [
    {
      "txid": "bec7e05d-484e-4814-a432-dde637f84408",
      "endToEndId": "E144654798498498465123",
      "createdAt": "2025-01-16 09:33:01.573Z",
      "confirmedAt": "2025-01-16 09:33:01.573Z",
      "pixKey": "883f75da-1f69-48c4-9444-c32b4bcb3553",
      "receiverDocument": "36264164615",
      "receiverPixKey": "pix-key-receiver@mail.com",
      "amount": 999.99,
      "status": 2,
      "failReason": 1
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 1,
    "totalItems": 1
  }
}

/v2/apm/pix/cashout/confirm#

POST#

Confirma a solicitação de cash-out com o código de confrimação.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string
txid	body	Indentificador do cashout	sim	string
confirmationKey	body	Chave de confirmação fornecida no payload de notificação do webhook	sim	string

Exemplo de Request#

{
  "txid": "bec7e05d-484e-4814-a432-dde637f84408",
  "confirmationKey": "4826e6ec-9bd2-4045-b030-f10e519d584a"
}

Após a confirmação, o saque ainda pode falhar em alguns cenários, portanto, uma nova notificação será enviada para o webhook configurado para informar se o saque foi concluído com sucesso.

Response#

Código	Descrição
204	No Content

/v2/apm/pix/cashout/{txid}#

GET#

Recupera os dados do saque com o txid. Em caso de atraso ou falha na notificação do webhook, este endpoint pode ser utilizado para verificar o status do saque.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string
txid	path	Cashouts unique identifier	sim	string

Responses#

Campo	Tipo	Observações
txid	string	Identificador do cashout
endToEndId	string	End To End da transação, Será sempre nulo até a confirmação da solicitação
createdAt	DateTime (ISO 8601)	Data e hora da solicitação de saque
confirmedAt	DateTime (ISO 8601)	Data e hora da confirmação do saque
pixKey	string	Chave pix da conta Fiserv (origem)
receiverDocument	string	Documento da conta destino
receiverPixKey	string	Chave Pix da conta destino
amount	decimal	Valor do saque (BRL)
status	int (enum)	Status do saque Valores possíveis: 0 - Pendente (Aguardando confirmação) 1 – Processando (Processando pagamento) 2 - Confirmado (pago) 3 - Falhou (Pagamento falhou) 4 - Expirado (Confirmação expirada)
result.failReason	int (enum)	Tipo de falha (Somente quando o status for de falha) 1 - Sem Limite 2 - Sem Saldo 3 - Expirado 4 - Concorrência 5 - Falha de processamento 6 - Suspeita de Fraude

Exemplo de Response#

{
  "txid": "bec7e05d-484e-4814-a432-dde637f84408",
  "endToEndId": "E144654798498498465123",
  "createdAt": "2025-01-16 09:33:01.573Z",
  "confirmedAt": "2025-01-16 09:33:01.573Z",
  "pixKey": "883f75da-1f69-48c4-9444-c32b4bcb3553",
  "receiverDocument": "36264164615",
  "receiverPixKey": "pix-key-receiver@mail.com",
  "amount": 999.99,
  "status": 2,
  "failReason": 1
}

#

## Reports

/v1/apm/pix/report/transactions#

GET#

Consulta relatório de transações.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)
pixKey	query	Chave Pix	não	string
documentNumber	query	Documento do cliente	não	string
startDate	query	Data de início	não	timezone (ISO 8601)
endDate	query	Data de fim	não	timezone (ISO 8601)
settlementStartDate	query	Data de início da liquidação	não	timezone (ISO 8601)
settlementEndDate	query	Data de fim da liquidação	não	timezone (ISO 8601)
txid	query	Identificador da transação	não	string
endToEnd	query	Identificador de ponta a ponta da transação	não	string
pagination.currentPage	query	Página atual	sim	integer
pagination.pageSize	query	Quantidade de itens por página	sim	integer

Responses#

Código	Descrição
200	Success
400	Bad Request
401	Unauthorized
422	Client Error
500	Server Error

Exemplo de Response#

{
  "criteria": {
    "startDate": "2020-04-01T00:00:00Z",
    "endDate": "2020-04-01T17:00:00Z",
    "pixKey": "string",
    "documentNumber": "string",
    "status": "string"
  },
  "results": [
    {
      "expiration": 3600,
      "amount": "2221.39",
      "returnQrCodeImage": true,
      "pixKey": "string",
      "additionalInfo": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "txid": "69xWbpREB9fvZ5oUr7HPNSlm5r6cclBy3Gk0",
      "location": "pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002",
      "qrCodeImage": "string",
      "status": "ATIVA",
      "pixCopyPaste": "string",
      "createdAt": "2024-12-17T19:42:50.414Z",
      "pix": [
        {
          "endToEndId": "jt86OxM1YwTvUuMsZpjGIhZlcodBS8GD",
          "amount": "52.34",
          "pixKey": "string",
          "confirmedAt": "2024-12-17T19:42:50.414Z",
          "reverses": [
            {
              "txid": "kXrK2W2mFxOQ8NEXH",
              "endToEndId": "D12345678202009091000abcde123456",
              "amount": "7163749810.26",
              "confirmedAt": "2024-12-17T19:42:50.414Z",
              "status": "EM_PROCESSAMENTO"
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "currentPage": 0,
    "pageSize": 1,
    "totalPages": 1,
    "totalItems": 0
  }
}

/v2/apm/pix/report/transactions#

GET#

Localiza as operações de entrada e saída.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string
pixKey	query	Chave Pix da conta	não	string
documentNumber	query	Documento da conta	não	string
startDate	query	Data inicial de filtro	sim	DateTime (ISO 8601)
endDate	query	Data final de filtro	sim	DateTime (ISO 8601)
txid	query	Id da transação a ser filtrado	não	string
endToEndId	query	End to end da transação a ser filtrado	não	string
pagination.currentPage	query	Página a ser buscada	sim	int
pagination.pageSize	query	Tamanho de página para a busca	sim	int

Responses#

Campo	Tipo	Observações
result.txid	string	Id da transação
result.amount	decimal	Valor da transação (BRL)
result.movementType	int (enum)	Tipo do movimento Possible values: 0 - Débito 1 - Crédito
result.transactionType	int	Tipo da transação Valores possíveis: 0 - Cobrança 1 – Devolução Parcial 2 - Estorno 3 – Saque Automático 4 – Movimento de Devolução Especial 5 – Estorno de Movimento de Devolução Especial 6 – Saque manual 7 - Taxa 8 – Devolução de Taxa 9 – Saldo bloqueado por MED 10 – Saldo desbloqueado (MED)
result.accountCnpj	string	CNPJ da conta
result.createdAt	DateTime (ISO 8601)	Data e hora
result.endToEndId	string	End to end
result.fraudReproval	enum	Em caso de reprova pelo motor de antifraude, esse campo vem preenchido: Valores disponíveis: 1 - Suspeita de Fraude
result.thirdPartyName	string	Nome da outra parte (externa) envolvida na transação
pagination.currentPage	int	Página atual
pagination.pageSize	int	Tamanho da página
pagination.totalPages	int	Total de páginas
pagination.totalItems	int	Total de itens
criteria.startDate	DateTime (ISO 8601)	Filtro de data inicial utilizado
criteria.endDate	DateTime (ISO 8601)	Filtro de data final utilizado
criteria.pixKey	string	Filtro de chave pix utilizado
criteria.documentNumber	string	Filtro de documento utilizado
criteria.txid	string	Filtro de Txid utilizado
criteria.endToEndId	string	Filtro de end to end utilizado
summary.sumAmountCredits	decimal	Total de créditos
summary.sumAmountDebits	decimal	Total de débitos

Responses#

Código	Descrição
200	Success
400	Bad Request
401	Unauthorized
422	Client Error
500	Server Error

Exemplo de Response#

{
  "criteria": {
    "pixKey": "4d2dd55d-d1ab-492b-868e-6b1a2791dc0b",
    "documentNumber": "14821268000107",
    "startDate": "2025-01-01",
    "endDate": "2029-12-31",
    "txid": "2a2cc743-3913-48ea-91fe-13256ab3c3d2",
    "endToEndId": "E144654798498498465123"
  },
  "result": [
    {
      "createdAt": "2025-06-06T04:57:20.882Z",
      "movementType": 1,
      "transactionType": 1,
      "amount": 99.99,
      "endToEndId": "EDARFlxoxT0zBhFBqEIC6c2QQCo2d54U",
      "txid": "42474ba2-fd99-43b9-b688-52fb7a74106d",
      "accountCnpj": "14821268000107",
      "thirdPartyName": "John Mary",
      "fraudReproval": 1
    }
  ],
  "summary": {
    "sumAmountCredits": 99.99,
    "sumAmountDebits": 0
  },
  "pagination": {
    "currentPage": 1,
    "pageSize": 1,
    "totalPages": 1,
    "totalItems": 1
  }
}

/v1/apm/pix/report/settlements#

GET#

Consulta relatório de liquidações.

Parâmetros#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)
pixKey	query	Chave Pix	não	string
documentNumber	query	Documento do cliente	não	string
startDate	query	Data de início	não	timezone (ISO 8601)
endDate	query	Data de fim	não	timezone (ISO 8601)
status	query	Status da liquidação: 0 – Pendente 1 – Concluída 2 - Falha	não	int
pagination.currentPage	query	Página atual	sim	int
pagination.pageSize	query	Quantidade de itens por página	não	int

#

Status da liquidação que podem ser obtidos#

Código	Status
0	Pendente
1	Confirmado
2	Falhou

Responses#

Código	Descrição
200	Success
400	Bad Request
401	Unauthorized
422	Client Erro
500	Server Erro

Exemplo de Response#

{
  "criteria": {
    "pixKey": "string",
    "documentNumber": "string",
    "startDate": "string",
    "endDate": "string",
    "status": "string"
  },
  "results": [
    {
      "totalAmount": 0,
      "totalGrossAmount": 0,
      "totalFeeAmount": 0,
      "status": 0,
      "errorMessage": "string",
      "createdAt": "2024-12-17T20:17:24.421Z",
      "endToEnd": "string",
      "settlement": {
        "pixKey": "string",
        "bankAccount": {
          "accountNumber": "12345-1",
          "agency": "1234",
          "bankCompeCode": "341",
          "document": {
            "number": "60.664.745/0001-87",
            "type": "CNPJ"
          },
          "type": 1
        }
      }
    }
  ],
  "pagination": {
    "currentPage": 0,
    "pageSize": 1,
    "totalPages": 1,
    "totalItems": 0
  }
}

#

Informações adicionais#

#

Header padrão#

Algumas informações são necessárias em todas as solicitações, incluindo:

Header	Detalhes
Authorization	Token de autenticação. Para mais informações, consulte Token item neste documento
apikey	Fornecido pela Fiserv após acreditação integrada
x-timestamp	Data e hora da solicitação. Também usado para gerar a assinatura HMAC. Para mais informações, consulte HMAC Calculation item neste documento
x-hmac-signature	HMAC gerado. Para mais informações, consulte HMAC Calculation item neste documento
x-request-id	ID aleatório da requisição

#

Calculo HMAC#

O HMAC deve ser calculado usando o algoritmo SHA256 e a chave privada que será fornecida pela Fiserv, contendo os seguintes campos concatenados:

APIKEY + TIMESTAMP + REQUEST_BODY + URL_PATH

Abaixo está o exemplo de um script postman que gera os cabeçalhos indicados de acordo com a especificação:

var CryptoJS = require("crypto-js");

function setHMACAuth(request) {
const currentDate = new Date();
var API_KEY = pm.collectionVariables.get('apikey');
var SECRET = pm.collectionVariables.get('secret');
var requestId = generateUUID();
const timestamp = currentDate.getTime().toString();

rawData=API_KEY+timestamp+request.body.toString()+'/'+pm.request.url.path.toString().replaceAll(',','/');;
 
var signedValue = CryptoJS.algo.HMAC.create(CryptoJS.algo.SHA256, SECRET).update(rawData).finalize();
hashedStringRequest = CryptoJS.enc.Base64.stringify(signedValue);

pm.request.headers.add({key:"x-timestamp",value:timestamp});
pm.request.headers.add({key:"x-hmac-signature",value:hashedStringRequest});
pm.request.headers.add({key:"requestBody",value:requestId});
}

function generateUUID() {
return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
return v.toString(16);
});
}
 
setHMACAuth(pm.request);

#

Objeto de erro padrão#

Todos os erros tratados são retornados em um formato padrão, que é o seguinte:

{
  "message": "Erro Message",
  "details": [
    {
      "errorCode": 0,
      "error": "Erro Descrição"
    }
  ]
}

#

Testes#

PUT /utils/ ordem-pagar#

Efetuar o pagamento de uma transação. Funcional apenas no ambiente de testes.

Parâmetros da requisição#

Nome	Localizado em	Descrição	Obrigatório	Tipo
apikey	header	API Key	sim	string
x-timestamp	header	Data/hora da solicitação (usada para evitar ataques de repetição)	sim	string
x-request-id	header	ID aleatório usado para identificar a solicitação	sim	string
x-hmac-signature	header	Assinatura HMAC gerada pela combinação dos parâmetros da solicitação. Exemplo: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL )`	sim	string
Authorization	header	Bearer Token usado para autenticação	sim	string (bearerToken)
qrCode	body	Código pix copia e cola (QRCode) da cobrnça	Sim	string

Exemplo de requisição#

{
    "qrCode": "00020101021226830014BR.GOV.BCB.PIX2561api-h.rendimento.com.br/q/v2/28d1eeb09673415ea5ad1c3c2793fbc45204000053039865802BR5914QRCOeAccount6009SAO PAULO61081125553262070503***6304AE83",
}

Home

Ambientes#

Conteúdo#

📍Autenticação#

📍Gestão de Webhooks#

🔻Callbacks#

📍Cadastro de clientes#

📍Cadastro de contas#

📍Transações#

📍Cash-out#

📍Relatórios#

📍Informações adicionais#

🔻Objeto padrão de erros#

🔻Header padrão#

🔻Cálculo do HMAC#

🔻Para Testes#

Autenticação#

🔒 /token#

POST#

Parâmetros#

Exemplo de Request#

Responses#

Exemplo de Response#

Webhook#

/v1/webhook#

PUT#

Parâmetros#

Exemplo de Request#

Responses#

GET#

Parâmetros#

Responses#

Exemplo de Response#

DELETE#

Parâmetros#

Responses#

CALLBACKS#

POST /client#

POST /v1/apm/pix/charges#

Client#

/v1/client#

POST#

Parâmetros#

Exemplo de Request#

Responses#

Exemplo de Response#

/v1/client/{clientId}#

GET#

Parâmetros#

Exemplo de response#

Responses#

Pix Account#

Informações gerais sobre a gestão de contas#

pixFee#

Exemplo modelo comercial comissionamento com valor fixo#

Exemplo modelo comercial comissionamento com valor MDR#

/v1/client/{clientId}/apm/pix/account#

POST#

Parâmetros#

Exemplo de Request#

Exemplo de Response#

Responses#

Possíveis erros:#

/v1/client/{clientId}/apm/pix/account/{pixKey}#

GET#

Parâmetros#

Exemplo de Response#

Responses#

PUT#

Parâmetros#

Exemplo de Request#

Responses#

Possíveis erros#

DELETE#

Parâmetros#

Responses#

/v2/client/{clientId}/apm/pix/account/balance/{pixKey} `#

GET#

Parâmetros#

Exemplo de Response#

📍Autenticação #

📍Gestão de Webhooks #

🔻Callbacks #

📍Cadastro de clientes #

📍Cadastro de contas #

📍Transações #

📍Cash-out #

📍Relatórios #

📍Informações adicionais #

🔻Objeto padrão de erros #

🔻Header padrão #

🔻Cálculo do HMAC #

🔻Para Testes #