Pular para o conteúdo principal
O objeto Transacao representa uma cobranca ou pagamento processado pela Safefy. Atualmente, a API suporta transacoes via PIX, que geram um QR Code para pagamento instantaneo.

​
Estrutura

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "pedido_12345",
  "method": "Pix",
  "amount": 15000,
  "fee": 150,
  "netAmount": 14850,
  "currency": "BRL",
  "status": "Pending",
  "description": "Compra na Loja XYZ",
  "environment": "Production",
  "customerId": "550e8400-e29b-41d4-a716-446655440001",
  "customer": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Maria Silva",
    "email": "[email protected]",
    "document": "12345678901"
  },
  "pix": {
    "txId": "safefy550e8400e29b41d4a716446655440000",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "copyAndPaste": "00020126580014br.gov.bcb.pix...",
    "expiresAt": "2024-01-15T11:00:00Z"
  },
  "expiresAt": "2024-01-15T11:00:00Z",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": null
}

​
Atributos

​
id
string
obrigatório
Identificador unico da transacao no formato UUID v4. Gerado automaticamente pela API.
​
externalId
string
Identificador externo da transacao no seu sistema. Util para vincular a transacao da Safefy com pedidos ou registros do seu banco de dados.
​
method
string
obrigatório
Metodo de pagamento utilizado. Valores possiveis:
  • Pix - Pagamento instantaneo via PIX
​
amount
integer
obrigatório
Valor total da transacao em centavos. Por exemplo, R$ 150,00 = 15000.
​
fee
integer
obrigatório
Taxa cobrada pela Safefy em centavos.
​
netAmount
integer
obrigatório
Valor liquido que sera creditado na sua conta em centavos. Calculado como amount - fee.
​
currency
string
obrigatório
Moeda da transacao. Atualmente apenas BRL (Real Brasileiro) e suportado.
​
status
string
obrigatório
Status atual da transacao. Valores possiveis:
  • Pending - Aguardando pagamento
  • Processing - Pagamento sendo processado
  • Completed - Pagamento confirmado
  • Failed - Falha no pagamento
  • Refunded - Pagamento estornado
  • Expired - Transacao expirada (nao foi paga no prazo)
  • Cancelled - Transacao cancelada
​
description
string
Descricao da transacao. Aparece no extrato do pagador.
​
environment
string
obrigatório
Ambiente da transacao:
  • Sandbox - Ambiente de testes
  • Production - Ambiente de producao
​
customerId
string
ID do cliente associado a transacao.
​
customer
object
Dados resumidos do cliente associado a transacao.
​
pix
object
Dados especificos do pagamento PIX. Presente apenas quando method e Pix.
​
expiresAt
string
Data e hora de expiracao da transacao no formato ISO 8601. Apos esse horario, a transacao muda para status Expired se nao for paga.
​
createdAt
string
obrigatório
Data e hora de criacao da transacao no formato ISO 8601.
​
completedAt
string
Data e hora em que o pagamento foi confirmado no formato ISO 8601. Nulo se ainda nao foi pago.

​
Ciclo de Vida da Transacao

Pending → Processing → Completed
    ↓         ↓
 Expired   Failed
              ↓
          Refunded
  1. Pending: Transacao criada, aguardando pagamento
  2. Processing: Pagamento em processamento
  3. Completed: Pagamento confirmado com sucesso
  4. Expired: Nao foi paga antes do prazo de expiracao
  5. Failed: Falha no processamento do pagamento
  6. Refunded: Pagamento foi estornado

​
Endpoints

MetodoEndpointDescricao
POST/v1/transactionsCriar transacao
GET/v1/transactionsListar transacoes
GET/v1/transactions/{id}Buscar transacao
POST/v1/transactions/simulateSimular pagamento (Sandbox)