Sign in

v10

latestOpenAPI 3.1.1raw.githubusercontent.com2026-06-261653109.3 KB
Transacoes

Criar transacao

Cria uma nova transacao PIX ou boleto. Para PIX, apenas method e amount sao obrigatorios. Para boleto, method, amount e um cliente vinculado sao obrigatorios (customerId ou customerName). Se customerId nao for enviado e customerName for informado, a Safefy cria (ou reutiliza) um cliente automaticamente. A imagem do QR Code não é retornada - utilize uma biblioteca de geração de QR Code no seu frontend para exibir o codigo visualmente.

post/v1/transactions

Request body

method'Pix' | 'CreditCard' | 'Boleto' required

Metodo de pagamento

amountinteger required

Valor em centavos (min: 100)

currency'BRL' required

Moeda

descriptionstring nullable

Descricao da transacao (max: 500)

externalIdstring nullable

ID externo para referencia (max: 100)

customerIdstring uuid nullable

ID do cliente cadastrado. Para boleto, informe customerId ou customerName.

callbackUrlstring nullable

URL para receber webhooks

metadatastring nullable

Metadados em JSON

pixExpirationMinutesinteger nullable

Tempo de expiracao do PIX (5-1440 min)

customerNamestring nullable

Nome do cliente/pagador. Se customerId nao for enviado e customerName for informado, a Safefy cria (ou reutiliza) um cliente e vincula a transacao.

customerDocumentstring nullable

CPF/CNPJ do cliente/pagador

customerEmailstring nullable

Email do cliente/pagador (opcional). Se nao for enviado, a Safefy gera um email tecnico apenas para viabilizar o processamento.

customerPhonestring nullable

Telefone do cliente/pagador com codigo do pais. Aceita com ou sem '+' no envio e e normalizado para apenas digitos no processamento.

boletoDueDatestring date nullable

Data de vencimento do boleto (YYYY-MM-DD). Obrigatorio para boleto. Minimo: D+2.

boletoInstructionsstring nullable

Instrucoes do boleto. Opcional.

cardNumberstring nullable

Numero do cartao de credito (obrigatorio para method=CreditCard)

cardHolderNamestring nullable

Nome do titular do cartao (obrigatorio para method=CreditCard)

cardExpirationMonthstring nullable

Mes de expiracao do cartao, dois digitos (obrigatorio para method=CreditCard)

cardExpirationYearstring nullable

Ano de expiracao do cartao, quatro digitos (obrigatorio para method=CreditCard)

cardCvvstring nullable

Codigo de seguranca do cartao CVV (obrigatorio para method=CreditCard)

installmentsinteger nullable

Numero de parcelas, de 1 a 12 (obrigatorio para method=CreditCard)

cardTokenstring nullable

Token de cartao obtido via /v1/card-tokenize (alternativa ao envio de dados brutos do cartao)

Example request

{
  "method": "Pix",
  "amount": 10000,
  "currency": "BRL",
  "description": "Pagamento do pedido #12345",
  "externalId": "pedido_12345",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "callbackUrl": "https://seusite.com.br/webhook",
  "metadata": "{\"orderId\": 12345}",
  "pixExpirationMinutes": 30,
  "customerName": "Joao Silva",
  "customerDocument": "12345678900",
  "customerEmail": "joao@exemplo.com",
  "customerPhone": "5511999998888",
  "boletoDueDate": "2025-02-15",
  "boletoInstructions": "Nao receber apos o vencimento",
  "cardNumber": "4111111111111111",
  "cardHolderName": "JOAO SILVA",
  "cardExpirationMonth": "12",
  "cardExpirationYear": "2028",
  "cardCvv": "123",
  "installments": 1,
  "cardToken": "ct_abc123def456"
}

Response

Transacao criada com sucesso

messagestring nullable

Example response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalId": "pedido_12345",
    "method": "Pix",
    "amount": 10000,
    "fee": 150,
    "netAmount": 9850,
    "currency": "BRL",
    "status": "Pending",
    "description": "Pagamento do pedido #12345",
    "environment": "Sandbox",
    "expiresAt": "2025-01-15T15:30:00Z",
    "createdAt": "2025-01-15T15:00:00Z",
    "customerId": "550e8400-e29b-41d4-a716-446655440000",
    "pix": {
      "txId": "SAFEFY2025011512345678901234",
      "copyAndPaste": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890...",
      "expiresAt": "2025-01-15T15:30:00Z"
    },
    "card": {
      "lastFour": "1234",
      "brand": "Visa",
      "installments": 1,
      "authorizationCode": "ABC123"
    },
    "boleto": {
      "barcode": "23793.38128 60000.000003 00000.000400 1 84340000010000",
      "digitableLine": "23793.38128 60000.000003 00000.000400 1 84340000010000",
      "pdfUrl": "https://api.safefypay.com.br/boleto/123456.pdf",
      "dueDate": "2025-01-20T00:00:00Z"
    }
  },
  "error": {
    "message": "Token invalido ou expirado.",
    "code": "unauthorized"
  }
}