Pix
API data
API Gateway
This API is used for payment gateway operations:
- Production: https://api.sopague.com.br/gateway
- Sandbox: https://api-hmg.sopague.com.br/gateway
- Architecture: Representational State Transfer (REST)
Introduction
The Pix endpoints let you generate a QR Code for payment and check the transaction status using the pixTransactionId identifier.
Generate Pix QR Code
Use the endpoint below to create a Pix charge and retrieve the payment code.
POST /v1/pix
Via REST request with the following body:
Request
{
"amount": 1,
"referenceCode": "123"
}
Data dictionary - Parameters
| PROPERTY | DESCRIPTION | TYPE | LOCATION | REQUIRED | NOTES |
|---|---|---|---|---|---|
| amount | Pix charge amount. | integer | body | yes | Enter the transaction amount. |
| referenceCode | Customer reference code. | string | body | no | Optional field for internal reconciliation. |
- 🟢 200
Pix QR Code generated successfully
{
"statusCode": "05",
"statusDescription": "Aguardando pagamento",
"pixTransactionId": "bec7361e36341a3bdad466b73e32d856abac0da6880d8aadd15b5f2590ff2ccc",
"amount": 1,
"dueDate": "2026-03-20T11:09:57.2758708-03:00",
"qrCode": "11120101021226810014br.gov.bcb.pix2559api.rendimento.com.br/q/v2/1caeaeebf6c32159afe08b41108e4a405204000053039865802BR5914282492060111794414Santa Catarina61080000000062070503***630476AG"
}
Data dictionary - Response
| PROPERTY | DESCRIPTION | TYPE |
|---|---|---|
| statusCode | Pix charge status code. | string |
| statusDescription | Current status description. | string |
| pixTransactionId | Pix transaction identifier. | string |
| amount | Charge amount. | integer |
| dueDate | Payment due date for the QR Code. | string |
| qrCode | Pix copy-and-paste code. | string |
Check Pix payment status
Use the identifier returned when creating the QR Code to check the payment progress.
GET /v1/pix/{pixTransactionId}
Via REST request using the route parameter:
Data dictionary - Parameters
| PROPERTY | DESCRIPTION | TYPE | LOCATION | REQUIRED | NOTES |
|---|---|---|---|---|---|
| pixTransactionId | Pix transaction identifier. | string | path | yes | Value returned by the QR Code generation endpoint. |
- 🟢 200
Pix payment status
{
"statusCode": "05",
"statusDescription": "Aguardando pagamento",
"pixTransactionId": "bec7361e36349a3bdad466b73e10d856abac0da6880d8aadd15b5f2590ff2d9c",
"authorizationCode": "SE000ES282492Z593CTQOHZEYDNDVAHUVC",
"amount": 1,
"releaseAt": "2026-03-20T11:07:00"
}
Data dictionary - Response
| PROPERTY | DESCRIPTION | TYPE |
|---|---|---|
| statusCode | Pix transaction status code. | string |
| statusDescription | Current status description. | string |
| pixTransactionId | Pix transaction identifier. | string |
| authorizationCode | Transaction authorization code. | string |
| amount | Transaction amount. | integer |
| releaseAt | Transaction release or update date. | string |
Pix status code table
The Pix endpoints return the statusCode field to indicate the current transaction state.
| CODE | CONSTANT | ABBR. | DESCRIPTION | CATEGORY |
|---|---|---|---|---|
| 0 | Confirmed | CON | Completed / Approved | Success |
| 01 | New | NOV | Newly created transaction | Pending / Intermediate state |
| 03 | PendingConfirmation | PPC | Pending confirmation | Pending / Intermediate state |
| 05 | AwaitingPayment | PEN | Awaiting response from the financial institution | Pending / Intermediate state |
| 11 | AwaitingUser | AGU | Awaiting user action | Pending / Intermediate state |
| 14 | Retry | RET | Scheduled for retry | Pending / Intermediate state |
| 06 | Denied | NEG | Denied by the financial institution | Denied / Closed without success |
| 04 | Undone | PPN | Reverted (pending not confirmed) | Denied / Closed without success |
| 09 | Expired | EXP | Expired due to NIT deadline | Denied / Closed without success |
| 12 | Abandoned | ABA | Expired due to user inactivity | Denied / Closed without success |
| 13 | Cancelled | CAN | Cancelled by the user/buyer | Denied / Closed without success |
| 02 | Invalid | INV | Incorrect parameter during creation | Error / Block |
| 07 | Error | ERR | Communication error with the authorizer | Error / Block |
| 08 | Blocked | BLQ | Blocked after multiple attempts | Error / Block |
| 10 | Reversed | EST | Reversed | Post-payment |