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 |