PIX

Consultar Transacao

Consulte o status e detalhes de uma transacao PIX existente.

Endpoint

GET/api/v1/transactions/{id}

Retorna os detalhes de uma transacao especifica

Parametros de URL

Parametro	Tipo	Descricao
`id`obrigatorio	`string`	ID unico da transacao (UUID)

Exemplo de Requisicao

cURL

bash

curl -X GET https://rayopay.com.br/api/v1/transactions/f2d96218-6635-4839-81d7-9f2d5aaf4f14 \
  -H "X-Client-Id: e1c98954cc404cbcb2868af9b40c7a33" \
  -H "X-API-Key: sua-api-key-secreta" \
  -H "Accept: application/json"

Resposta de Sucesso

Status Code: 200 OK

response.json

json

{
  "data": {
    "id": "f2d96218-6635-4839-81d7-9f2d5aaf4f14",
    "status": "PAID",
    "paymentMethod": "PIX",
    "amount": 500,
    "externalId": "pedido-123",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "cpfCnpj": "12345678900"
    },
    "pix": {
      "qrCode": "00020126580014br.gov.bcb.pix0136...",
      "qrCodeBase64": "data:image/png;base64,iVBORw0KGgo...",
      "expiresAt": "2024-01-15T15:30:00Z",
      "paidAt": "2024-01-15T15:10:00Z",
      "endToEndId": "E12345678202401151510ABCDEF"
    },
    "createdAt": "2024-01-15T15:00:00Z",
    "updatedAt": "2024-01-15T15:10:00Z"
  },
  "status": 200,
  "message": "Transação encontrada."
}

Campos Adicionais (quando pago)

Parametro	Tipo	Descricao
`pix.paidAt`	`string`	Data/hora do pagamento (ISO 8601)
`pix.endToEndId`	`string`	ID unico da transacao PIX no BACEN (E2E)

Resposta de Erro

Status Code: 404 Not Found

error.json

json

{
  "type": "https://rayopay.com.br/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Transação não encontrada."
}

Exemplos de Codigo

Node.js / JavaScript

node.js

javascript

const transactionId = 'f2d96218-6635-4839-81d7-9f2d5aaf4f14';
 
const response = await fetch(
  `https://rayopay.com.br/api/v1/transactions/${transactionId}`,
  {
    method: 'GET',
    headers: {
      'X-Client-Id': process.env.RAYO_CLIENT_ID,
      'X-API-Key': process.env.RAYO_API_KEY,
      'Accept': 'application/json'
    }
  }
);
 
const data = await response.json();
 
if (data.data.status === 'PAID') {
  console.log('Pagamento confirmado!');
  console.log('E2E ID:', data.data.pix.endToEndId);
}

Polling vs Webhook

Embora voce possa consultar o status periodicamente (polling), recomendamos configurar webhooks para receber notificacoes em tempo real quando o pagamento for confirmado.