Skip to main content
GET
/
api
/
v2
/
gateway
/
consult-transaction
Verifica o status de um pagamento PIX
curl --request GET \
  --url https://sandbox.ws.relaxpay.site/api/v2/gateway/consult-transaction \
  --header 'Authorization: Bearer <token>'
{
  "idTransaction": "0b935d10-3c90-4af3-8776-dd18622a7941",
  "status": "PAID",
  "amount": 100,
  "paidAt": "2024-12-15T14:30:45.000Z",
  "response": "OK"
}
Acompanhe o status das suas transações PIX em tempo real com este endpoint.

​
Visão Geral

O endpoint de verificação de status permite consultar a situação atual de um pagamento PIX. Esta é uma forma prática de integrar o status dos pagamentos diretamente ao seu sistema.

​
Endpoint

​
Parâmetros

​
idTransaction
string
required
ID da transação PIX a ser consultada

​
Exemplos de Requisição

​
Resposta de Sucesso

​
200 - OK
object
{
  "idTransaction": "0b935d10-3c90-4af3-8776-dd18622a7941",
  "statusTransaction": "PAID",
  "amount": 100.00,
  "paidAt": "2024-12-15T14:30:45Z",
  "response": "OK"
}

​
Status Possíveis

Modo Sandbox: No ambiente de sandbox, se o ID da transação começar com “paid-”, o sistema retornará automaticamente o status “PAID”. Caso contrário, retornará “UNPAID”. Use este recurso para testar diferentes cenários de pagamento.

PENDING

Pagamento aguardando confirmação

EXPIRED

QR Code expirado sem pagamento

CANCELLED

Pagamento cancelado

PAID

Pagamento confirmado

REFUNDED

Pagamento reembolsado

​
Códigos de Erro

O ID da transação fornecido não é válido ou está em formato incorreto.
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "INVALID_TRANSACTION_ID",
  "details": "O ID da transação é inválido"
}
As credenciais fornecidas são inválidas ou não foram enviadas.
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "INVALID_CREDENTIALS",
  "details": "As credenciais fornecidas são inválidas"
}
A transação com o ID fornecido não foi encontrada.
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "TRANSACTION_NOT_FOUND",
  "details": "A transação informada não foi encontrada"
}

​
Boas Práticas

1

Implementar polling com intervalo

Consulte periodicamente o status de transações pendentes, mas respeite os limites de requisições.
2

Utilizar webhooks

Implemente webhooks para receber atualizações automáticas e reduzir a necessidade de consultas.
3

Armazenar status

Armazene o status em seu sistema para histórico e evite consultas desnecessárias.
4

Implementar retry com backoff

Em caso de falhas temporárias, implemente um mecanismo de retry com tempos crescentes.
Respeite o limite de 100 consultas por minuto para evitar bloqueios temporários.

​
Exemplo de Implementação

Authorizations

​
Authorization
string
header
required

Token de autenticação Bearer usando o Client Secret para a versão v2 da API

Query Parameters

​
idTransaction
string<uuid>
required

ID da transação PIX

Response

Status do pagamento

​
idTransaction
string<uuid>

ID da transação PIX

Example:

"0b935d10-3c90-4af3-8776-dd18622a7941"

​
status
enum<string>

Status do pagamento

Available options:
PENDING,
PAID,
EXPIRED,
CANCELLED,
REFUNDED
Example:

"PAID"

​
amount
number

Valor do pagamento

Example:

100

​
paidAt
string<date-time>

Data e hora do pagamento

Example:

"2024-12-15T14:30:45.000Z"

​
response
string

Status da resposta

Example:

"OK"