PSP FISERV - API Pix 💰

Introdução

Esta documentação detalha as APIs do PSP Fiserv, projetadas para integração com os integradores, possibilitando a gestão de operações relacionadas a 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 detele clientes
• Gestão de Contas: Adicione, atualize, consulte e delete contas.
• Geração de pagamentos e devoluções Pix: Criação de cobranças e devoluções Pix de forma eficiente e segura, permitindo que seus clientes realizem pagamentos via Pix.
• Consulta de Pagamentos Pix: Consulta de status e detalhes de pagamentos realizados via Pix para maior controle e transparência.
• Saques manuais: Solicite saques manuais em vez de aguardar o saque automático.
• Gestão de Webhooks: Registre webhooks para receber notificações automáticas sobre eventos importantes como credenciamento de clientes, confirmações de pagamento ou solicitações de estorno.
• Relatórios: Gere relatórios detalhados das transações Pix, facilitando o acompanhamento das operações e relatório das liquidações relacionadas as contas.

---

Primeiros passos

Credenciais

Para começar consumir a API, serão disponibilizadas os acessos do integrador: client_id e client_secret e app_key e app_secret. O client_id e client_secret devem ser utilizados para obtenção do token e o app_key e app_secret devem ser utilizados para a geração do HMAC. Ambos etapas estão detalhadas nos tópicos a seguir desta documentação. Serão disponibilizadas credenciais diferentes para cada um dos ambientes.

---

/token

POST

Obter o token de autenticação

Parâmetros

Nome	Localização	Descrição	Obrigatório	Type
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string

Responses

Code	Description
200	Retorna o token de acesso e informações de expiração

---

/v1/webhook

Gestão do endereço onde para onde serão enviadas as notificações referentes à conclusão do cadastro de cliente (processo de Know Your Customer) e confirmações das transações de cobrança e devolução realizadas.

PUT

Cadastra o Webhook do integrador.

Parâmetros

Nome	Localização	Descrição	Obrigatório	Tipo
webhookUrl	body	Url a ser chamada no callback	sim	string
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)

Exemplo de requisição

{

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

}

Responses

Response 204: Sucesso - Sem conteúdo a ser devolvido

Response 400: Requisição com formato inválido.

Response 503: Serviço indisponível

* A atualização do webhook se dá por solicitação ao time técnico

GET

Exibir a url cadastrada do webhook do integrador.

Parâmetros

Nome	Localização	Descrição	Obrigatório	Tipo
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
webhookUrl	body	Url a ser chamada no callback	sim	string
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string

Responses

Response 200: Sucesso - Dados do webhook

Response 503: Serviço indisponível

DELETE

Exclusão do webhook do integrador.

Parâmetros

Nome	Localização	Descrição	Obrigatório	Tipo
webhookUrl	body	Url a ser chamada no callback	sim	string
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)

Responses

Response 204: Sucesso - Sem conteúdo a ser devolvido

Response 503: Serviço indisponível

CALLBACKS

POST/client

Após o cadastro do cliente e o processo de KYC ser finalizado, a URL cadastrada para o webhook recebe a notificação no formato 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 e PUT /v1/apm/pix/{endToEndId}/reverse/{txid}

Após a finalização da transação de cobrança ou devolução, 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
Pix.OperationType	string	Tipo da Transação (0 – Cobrança, 1- Devolução Parcial, 2 – Estorno)

POST /v2/apm/pix/cashout and POST /v2/apm/pix/cashout/confirm

Após solicitar uma operação de saque, algumas validações serão realizadas de forma assíncrona, e a solicitação ainda pode ser negada. O resultado dessa validação, juntamente com a chave de confirmação necessária para a solicitação de confirmação, será enviado ao webhook em um payload como no seguinte exemplo:

{

"pix": [

{

"txid": "bec7e05d-484e-4814-a432-dde637f84408",

"endToEndId": null,

"createdAt": "2025-01-16 09:33:01.573Z",

"confirmedAt": null,

"pixKey": "883f75da-1f69-48c4-9444-c32b4bcb3553",

"receiverDocument": "3626416467",

"receiverPixKey": "pix-key-receiver@mail.com",

"amount": 99.99,

"confirmationKey": "4826e6ec-9bd2-4045-b030-f10e519d584a",

"status": 2,

"operationType": 6

}

]

}

Campo	Tipo	Descrição
Pix.txid	string	Identificador único do cash-out
Pix.endToEndId	string	End to nd da transação. Neste momento sempre será nulo.
Pix.createdAt	DateTime (ISO 8601)	Data e hora da solicitação
Pix.confirmedAt	DateTime (ISO 8601)	Data e hora da confirmação
Pix.pixKey	string	Chave Pix da conta Fiserv (origem)
Pix.receiverDocument	string	Documento da conta destino
Pix.receiverPixKey	string	Chave Pix da conta destino
Pix.amount	decimal	Valor do cash-out
Pix.confirmationKey	string	Chave aleatória para a confirmação do saque
Pix.Status	int (enum)	Status da transação
Pix.OperationType	int (enum)	Tipo da transação: Valores possíveis: 6 - PixOrderManual

Status da transação

Código	Status
0	Pendente (Aguardando confirmação)
2	Confirmado (pago)
3	Falhou (Pagamento falhou)

Uma vez que a chave de confirmação é recebida da notificação, a solicitação de confirmação (/cashout/confirm) deve ser chamada para confirmar o saque. 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 (status 1) ou se falhou (status 2). O payload de confirmação tem a mesma estrutura que o payload da solicitação de saque, a única diferença principal será no "status".

---

/v1/client

POST

Adiciona um cliente

Parâmetros

Nome	Localização	Tipo	Descrição	Obrigatório
Authorization	header	string (bearerToken)	Token de autorização	Sim
apikey	header	string	Chave de Api	sim
x-timestamp	header	string	data/hora do request(utilizado para evitar ataque de replay)	sim
x-request-id	header	string	ID aleatório para identificar o request	sim
x-hmac-signature	header	string	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim
address.city	body	string	Cidade do cliente	Sim
address.country	body	string	País do cliente	Sim
address.locality	body	string	Distrito, vila, bairro colônia do cliente	sim
address.number	body	string	Número do endereço	não
address.postalCode	body	string	CEP	sim
address.province	body	string	Estado	sim
address.street	body	string	Rua	sim
address.subNumber	body	string	Complemento	mnão
document.number	body	string	Número do documento	sim
document.type	body	enum	CNPJ	sim
contact.email	body	string	E-mail do cliente	sim
contact.phone	body	string	Telefone do cliente	sim
legalName	body	string	Razão social	sim
tradeName	body	string	Nome Fantasia	sim
averageTicket	body	decimal	Ticket médio	sim

Exemplo de Requisição

{

"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

Response 200:

Nome	Descrição	Tipo
clientId	Id único do cliente	string
protocolId	protocolo da requisição	string

Exemplo de response

{

"clientId": "bb41c1e6-654f-4263-83f4-36e37678f548",

"protocolId": "Request protocol"

}

Response 400: Requisição com formato inválido.

Response 401: Não autorizado

Response 403: Proibido

Response 404: Não localizado

Response 500: Erro

Response 503: Serviço indisponível

/v1/client/{clientId}

GET

Busca a informação sobre o status de "Know Your Customer" do cliente

Parâmetros

Nome	Localização	Descrição	Obrigatório	Tipo
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
clientId	rota	client id	sim	string

Responses

Response 200:

{

"kycStatus": "Approved"

}

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

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

Response 400: Requisição com formato inválido.

Response 401: Não autorizado

Response 403: Proibido

Response 404: Não localizado

Response 500: Erro

Response 503: Serviço indisponível

---

/v1/client/{clientId}/apm/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

---

POST

Adicionar uma conta pix

Parâmetros

Campo	Localização	Tipo	Obrigatório	Descrição
Authorization	header	string (bearerToken)	sim	Bearer token para autenticação
apikey	header	string	sim	Chave de Api
x-timestamp	header	string	sim	data/hora do request(utilizado para evitar ataque de replay)
x-request-id	header	string	sim	ID aleatório para identificar o request
x-hmac-signature	header	string	sim	Assinatura HMAC gerada com combinação dos parâmetros do request.
clientId	rota	string	sim	Client Id
Settlement.pixKey	body	string	sim	Somente a chave domicílio ou os dados1 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”
pixFee.amount	body	decimal	não	Não pode ser menor que 0 se a porcentagem for informada
pixFee.percentage	body	decimal	não	Não pode ser menor que 0 e maior que 100 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	Sempre “CPF”
userTermsAccept.ip	body	string	sim	IP da máquina que deu o termo de aceite
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”
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	Sempre “CPF”
userTermsAccept.ip	body	string	sim	IP da máquina que deu o termo de aceite

Exemplo de requisição

{

"settlement": {

"bankAccount": {

"accountNumber": "12341",

"agency": "00001",

"bankCompeCode": "001",

"document": {

"number": "56011706000103",

"type": "CNPJ"

},

"type": 0

},

"pixKey": null

},

"userTermsAccept": {

"document": {

"number": "372.706.938-46",

"type": "CPF"

},

"ip": "0.0.0.0"

},

"pixFee": {

"amount": null,

"max": null,

"min": 0.12,

"percentage": 0.39

}

}

Responses

Response 200:

Nome	Descrição	Tipo
pixKey	Chave Pix da conta	string

Exemplo de response

{

"pixKey": "495f16cd-b4ba-4ae3-8810-72a23f4ca2c6"

}

Response 400: Requisição com formato inválido.

Response 401: Não autorizado

Response 500: Erro

Possiveis erros:

ErrorCode	Error
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

Name	Located in	Description	Required	Type
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
pixKey	path	Chave PIX da conta	Yes	string
clientId	path	client id	Yes	string

Responses

Response 200:

{

"name": "Store Name",

"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

}

}

Response 400: Requisição com formato inválido.

Response 401: Não autorizado

Response 500: Erro

PUT

Alterar uma conta pix

Description:

Endpoint para alterar uma conta pix

Parâmetros

Name	Located in	Description	Required	Type
authorization	header	Bearer token para autenticação	sim	string (bearerToken)
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
pixKey	path	Chave PIX da conta	sim	string
clientId	path	client id	sim	string

Exemplo de requisição

{

"settlement": {

"pixKey": "string",

"bankAccount": {

"type": 0,

"ispb": "string",

"agency": "string",

"accountNumber": "string",

"document": {

"number": "07.934.103/0001-78",

"type": "CNPJ"

}

}

},

"pixFee": {

"amount": 100,

"percentage": 100

}

}

Responses

Response 204: Sucesso - Sem conteúdo a ser exibido

Response 400: Requisição com formato inválido.

Response 401: Não autorizado

Response 500: Erro

ErrorCode	Error
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

Excluir uma conta pix

Description:

Endpoint para excluir uma conta pix

Parâmetros

Name	Located in	Description	Required	Type
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
pixKey	path	Chave PIX da conta	sim	string
clientId	path	client id	sim	string

Responses

Response 204: Sucesso - Sem conteúdo a ser exibido

Response 400: Requisição com formato inválido.

Response 401: Não autorizado

Response 500: Erro

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

GET

Consultar as contas de um cliente.

Parâmetros

Nome	Localização	Descrição	Obrigatório	Tipo
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
clientId	rota	client id	sim	string
paginaAtual	query	Página a ser consultada	não	int
itensPorPagina	query	Quantidade de itens por página	não	int

Responses

Response 200:

{

"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"

}

],

"totalElements": 10

}

Response 400: Requisição com formato inválido.

Response 401: Não autorizado

Response 500: Erro

/v1/apm/pix/accounts

GET

Consulta contas de um integrador.

Parâmetros

Nome	Localizado em	Descrição	Obrigatório	Tipo
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
pagination.currentPage	query	Página a ser consultada	não	int
pagination.pageSize	query	Quantidade de itens por página	não	int

Responses

Response 200:

{

"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"

},

{

"name": "Store name 2",

"pixFee": {

"amount": 0,

"percentage": 2,

"max": 0,

"min": 0

},

"settlement": {

"bankAccount": {

"accountNumber": "12345-2",

"agency": "1234",

"bankCompeCode": "124",

"document": {

"number": "60.664.745/0001-87",

"type": "CNPJ"

},

"ispb": "00000000",

"type": 1

},

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

},

"status": "string"

}

],

"totalElements": 10

}

Response 400: Requisição com formato inválido.

Response 401: Não autorizado

Response 500: Erro

/v1/apm/pix/charge

POST

Criar cobrança imediata.

Description:

Endpoint para criar uma cobrança imediata.

Parâmetros

Nome	Localizado em	Descrição	Obrigatório	Tipo
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
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)	não	bool
expiration	body	Tempo de expiração do QRcode em segundos	sim	int

Responses

Response 200:

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
amount	decimal	Valor da transação
pixCopyPaste	string	Código copia e cola do pix
pixKey	string	Chave pix utilizada para a transação

Response 400: Requisição com formato inválido.

Response 401: Não autorizado

Response 500: 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
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
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

Response 200:

{

"txid": "string",

"amount": 99.99,

"status": "status",

"location": "string",

"pixCopyAndPaste": "string",

"qrCodeImage": "string"

}

Response 400: Requisição com formato inválido.

Response 404: Não localizado

Response 500: Erro

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

PATCH

Cancelar cobrança imediata.

Parâmetros

Nome	Localização	Descrição	Obrigatório	Tipo
txid	rota	id da transação	sim	string

Responses

Response 204: Sucesso - Sem conteúdo a ser devolvido.

Response 400: Requisição com formato inválido.

Response 404: Não localizado

Response 500: Erro

/v1/apm/pix/charges

GET

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

Parâmetros

Name	Located in	Description	Required	Type
Authorization	header	Bearer token para autenticação	Sim	string (bearerToken)
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
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		Não	string
pagination.currentPage	query		Não	int
pagination.pageSize	query		Não	int

Responses

Response 200: Sucesso - Lista de cobranças imediatas.

Response 500: Erro

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

PUT

Solicitar devolução.

Parâmetros

Name	Located in	Description	Required	Type
Authorization	header	Bearer token para autenticação	Yes	string (bearerToken)
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
endToEndId	path	Código end to end da transação	Yes	string
txid	path	Id da transação	Yes	string

Responses

Response 200:

{

"txid": "DLzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2h",

"endToEndId": "D12345678202009091000abcde123456",

"amount": "231.39",

"confirmedAt": "2025-03-11T12:07:12.395Z",

"status": "PENDING"

}

Response 400: Requisição com formato inválido.

Response 404: Não localizado

Response 500: Erro

GET

Consultar 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
Authorization	header	Bearer token para autenticação	Yes	string (bearerToken)
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
endToEndId	rota	Código End To End do pagamento	Yes	string
txid	rota	Id da transação	Yes	string

Responses

Response 200:

{

"txid": "DLzljVvS6DWp9ubnflS3nnCdeVBg7AxVt2h",

"endToEndId": "D12345678202009091000abcde123456",

"amount": "231.39",

"confirmedAt": "2025-03-11T12:07:12.395Z",

"status": "PENDING"

}

Response 400: Requisição com formato inválido.

Response 404: Não localizado

Response 500: Erro

PATCH /v1/apm/pix/charge/settlement/hold{txid}

Travar a cobrança para que o valor da mesma não seja liquidado na próxima janela de liquidação.

Request parameters

Campo	Tipo	Observações
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
txid	rota	Id da transação a ter a liquidação travada (rota)	sim	string

Responses

Response 204: Sucesso - Sem conteúdo a ser devolvido

Response 400: Requisição com formato inválido.

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

Liberar o valor da cobrança para que seja liquidado na próxima janela de liquidação.

Request parameters

Campo	Tipo	Observações
Authorization	header	Bearer token para autenticação	Yes	string (bearerToken)
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
txid	rota	Id da transação a ter a liquidação liberada (rota)	sim	string

Responses

Response 204: Sucesso - Sem conteúdo a ser devolvido

Response 400: Requisição com formato inválido.

---

Cashouts (saque manual)

/v2/apm/pix/cashout

POST

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

Request parameters

Campo	Localização	Descrição	Obrigatório	Tipo
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
amount	body	Valor do cashout (BRL)	sim	decimal
pixKey	body	Chave pix da conta origem	sim	string
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

Responses

Response 200:

Campo	Tipo	Descrição
txid	string	Indentificador do cashout

Response 400: Requisição com formato inválido.

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 (próximo endpoint), será enviado para o webhook, conforme detalhado na parte de webhooks.

/v2/apm/pix/cashout/confirm

POST

Confirm a pix cashout request with the confirmation key.

Request parameters

Campo	Localização	Descrição	Obrigatório	Tipo
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
txid	body	Indentificador do cashout	sim	string
confirmationKey	body	Chave aleatória para a confirmação do saque	sim	string

Responses

Response 204: Sucesso - Sem conteúdo a ser devolvido

Response 400: Requisição com formato inválido.

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, conforme descrito na parte de webhooks.

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

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.

Request parameters

Campo	Localização	Descrição	Obrigatório	Tipo
Authorization	header	Bearer token para autenticação	sim	string (bearerToken)
apikey	header	Chave de Api	sim	string
x-timestamp	header	data/hora do request(utilizado para evitar ataque de replay)	sim	string
x-request-id	header	ID aleatório para identificar o request	sim	string
x-hmac-signature	header	Assinatura HMAC gerada com combinação dos parâmetros do request.	sim	string
txid	rota	Indentificador do cashout	sim	string

Responses

Response 200:

Campo	Tipo	Descrição
txid	string	Indentificador do cashout
endToEndId	string	End To End da transação, Será sempre nulo até a confirmaçã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 Cash-out

Response 400: Requisição com formato inválido.

/v2/apm/pix/cashouts

GET

Localiza solicitações de saques manuais

Request parameters

Property	Type	Description
pixKey	string	Chave Pix da conta
startDate	DateTime (ISO 8601)	Data Inicial do filtro
endDate	DateTime (ISO 8601)	Data final do filtro
status	int (enum)	Status do Cash-out

Responses

Response 200:

Property	Type	Description
result.txid	string	Unique identifier of the cashout operation
result.endToEndId	string	End To End da transação, Será sempre nulo até a confirmaçã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 Cash-out
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 Cash-out
pagination.currentPage	int	Página atual
pagination.pageSize	int	Tamanho da página
pagination.totalPages	int	Total de páginas
pagination.totalItems	int	Total itens

Status do cash-out

Código	Status
0	Pendente (Aguardando confirmação)
1	Processando (Processando pagamento)
2	Confirmado (pago)
3	Falhou (Pagamento falhou)
4	Expirado (Confirmação expirada)

Response 400: Requisição com formato inválido.

---

/v1/apm/pix/report/transactions

GET

Consultar lista de cobranças

Parametros

Nome	Localizado em	Descrição	Obrigatório	Tipo
Authorization	header	Bearer token para autenticação	Yes	string (bearerToken)
pixKey	query	Chave Pix	No	string
documentNumber	query	client id	No	string
startDate	query	Data e hora de início da cobrança	No	timezone (ISO 8601)
endDate	query	Data e hora de fim da cobrança	No	timezone (ISO 8601)
settlementStartDate	query	Data e hora de início da liquidação	No	timezone (ISO 8601)
settlementEndDate	query	Data e hora de fim da liquidação	No	timezone (ISO 8601)
txid	query	Id da transação	No	string
endToEnd	query	Código End to End da confirmação	No	string
pagination.currentPage	query	Página atual	Yes	integer
pagination.pageSize	query	Quantidade de itens por página	Yes	integer

Responses

Exemplo

{

"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

}

}

Responses

Response 200: Sucesso

Response 400: Requisição com formato inválido.

Response 401: Não autorizado

Response 404: Não localizado

Response 500: Erro

/v1/apm/pix/report/settlements

GET

Consultar lista de liquidações

Parâmetros

Name	Located in	Description	Required	Type
Authorization	header	Bearer token para autenticação	Yes	string (bearerToken)
pixKey	query	Chave Pix da conta	No	string
documentNumber	query	Número do CNPJ	No	string
startDate	query	Data de início para a consulta	No	timezone (ISO 8601)
endDate	query	Data de fim para a consulta	No	timezone (ISO 8601)
status	query		No	Status da liquidação
pagination.currentPage	query	Página atual	Yes	integer
pagination.pageSize	query	Items por página	No	integer

Status da liquidação

Código	Status
0	Pendente
1	Confirmado
2	Falha

Responses

Response 200:

Exemplo

{

"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

}

}

Response 400:

Response 401:

Response 500:

/v2/apm/pix/report/transactions

GET

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

Request parameters

Property	Type	Description
pixKey	string	Chave Pix
documentNumber	string	Documento da conta
startDate	DateTime (ISO 8601)	Data inicial de filtro
endDate	DateTime (ISO 8601)	Data final de filtro
txid	String	Id da transação a ser filtrado
endToEndId	String	End to end da transação a ser filtrado
pagination.currentPage	Integer	Página a ser buscada
pagination.pageSize	Integer	Tamanho de página para a busca

Responses

Response 200:

Property	Type	Description
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
result.accountCnpj	string	CNPJ da conta
result.createdAt	DateTime (ISO 8601)	Data e hora
result.endToEndId	string	End to end
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 Tx Id utilizado
criteria.endToEndId	string	Filtro de end to end utilizado
summary.sumAmountCredits	decimal	Total de créditos
summary.sumAmountDebits	decimal	Total de débitos

Tipo de transação

Código	Status
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)

Response 400: requisição com formato inválido.

---

Informações Adicionais

Header Padrão

Algumas informações são necessárias em todas as requisições, sendo elas:

Header	Detalhes
Authorization	Token de autenticação.
apikey	Disponibilizado pela Fiserv após o credenciamento do integrador
x-timestamp	Timestamp da requisição. Também utilizado para a geração do HMAC signature.
x-hmac-signature	HMAC gerado.
x-request-id	Id aleatório da requisição.

Objeto padrão de erros

Todos os erros tratados são devolvidos em um formato padrão, sendo ele o seguinte:

{

"message": "Mensagem de erro",

"details": [

{

"errorCode": 0,

"error": "Descrição do erro"

}

]

}