Pix

Dados da API

API Gateway
Esta API é utilizada para operações do gateway de pagamento:

• Produção: https://api.sopague.com.br/gateway
• Homologação: https://api-hmg.sopague.com.br/gateway
• Arquitetura: Representational State Transfer (REST)

Introdução

Os endpoints de Pix permitem gerar um QR Code para pagamento e consultar o status da transação utilizando o identificador pixTransactionId.

---

Gerar QR Code Pix

Utilize o endpoint abaixo para criar uma cobrança Pix e obter o código para pagamento.

POST /v1/pix

Via request Representational State Transfer (REST) com o body:

Requisição

{
  "amount": 1,
  "referenceCode": "123"
}

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	OBSERVAÇÃO
amount	Valor da cobrança Pix.	integer	body	sim	Informe o valor da transação.
referenceCode	Código de referência do cliente.	string	body	não	Campo opcional para conciliação interna.

🟢 200

QR Code Pix gerado com sucesso

{
  "statusCode": "05",
  "statusDescription": "Aguardando pagamento",
  "pixTransactionId": "bec7361e36341a3bdad466b73e32d856abac0da6880d8aadd15b5f265478542cc",
  "amount": 1,
  "dueDate": "2026-03-20T11:09:57.2758708-03:00",
  "qrCode": "11120101021226810014br.gov.bcb.pix2559api.rendimento.com.br/q/v2/1caeaeebvdfy2159afe08b369e4a405204000053039865802BR5914282492060111794414Santa Catarina61080000000062070503***630476AG"
}

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
statusCode	Código de status da cobrança Pix.	string
statusDescription	Descrição do status atual.	string
pixTransactionId	Identificador da transação Pix.	string
amount	Valor da cobrança.	integer
dueDate	Data limite para pagamento do QR Code.	string
qrCode	Código Pix para cópia e cola.	string

---

Consultar status do pagamento Pix

Utilize o identificador retornado na criação do QR Code para consultar o andamento do pagamento.

GET /v1/pix/{pixTransactionId}

Via request Representational State Transfer (REST) utilizando o parâmetro de rota:

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	OBSERVAÇÃO
pixTransactionId	Identificador da transação Pix.	string	path	sim	Valor retornado no endpoint de geração do QR Code.

🟢 200

Status do pagamento Pix

{
  "statusCode": "05",
  "statusDescription": "Aguardando pagamento",
  "pixTransactionId": "bec7361e36349a3bdad466b73e10d10365ac0da6880d8aadd15b5f2590ff2d9c",
  "authorizationCode": "SE000ES182492Z591CTQOHZEYDNDVAHUVC",
  "amount": 1,
  "releaseAt": "2026-03-20T11:07:00"
}

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
statusCode	Código de status da transação Pix.	string
statusDescription	Descrição do status atual.	string
pixTransactionId	Identificador da transação Pix.	string
authorizationCode	Código de autorização da transação.	string
amount	Valor da transação.	integer
releaseAt	Data de liberação ou atualização da transação.	string

---

Tabela de códigos de status Pix

Os endpoints de Pix retornam o campo statusCode para indicar o estado atual da transação.

CÓDIGO	CONSTANTE	SIGLA	DESCRIÇÃO	CATEGORIA
0	Confirmed	CON	Efetuada / Aprovada	Sucesso
01	New	NOV	Transação recém-criada	Pendência / Estado intermediário
03	PendingConfirmation	PPC	Pendente de confirmação	Pendência / Estado intermediário
05	AwaitingPayment	PEN	Aguardando resposta da instituição financeira	Pendência / Estado intermediário
11	AwaitingUser	AGU	Aguardando ação do usuário	Pendência / Estado intermediário
14	Retry	RET	Agendada para retentativa	Pendência / Estado intermediário
06	Denied	NEG	Negada pela instituição financeira	Negada / Encerrada sem sucesso
04	Undone	PPN	Desfeita (pendente não confirmado)	Negada / Encerrada sem sucesso
09	Expired	EXP	Expirada por prazo do NIT	Negada / Encerrada sem sucesso
12	Abandoned	ABA	Expirada por inatividade do usuário	Negada / Encerrada sem sucesso
13	Cancelled	CAN	Cancelada pelo usuário/comprador	Negada / Encerrada sem sucesso
02	Invalid	INV	Parâmetro incorreto na criação	Erro / Bloqueio
07	Error	ERR	Erro de comunicação com a autorizadora	Erro / Bloqueio
08	Blocked	BLQ	Bloqueada após múltiplas tentativas	Erro / Bloqueio
10	Reversed	EST	Estornada	Pós-pagamento