---
title: "Criar transacao"
method: POST
path: "/v1/transactions"
tags: ["Transacoes"]
---

# Criar transacao

`POST /v1/transactions`

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.

## Request body

- CreateTransactionRequest
  - `method` 'Pix' | 'CreditCard' | 'Boleto', required — Metodo de pagamento
  - `amount` integer, required — Valor em centavos (min: 100)
  - `currency` 'BRL', required — Moeda
  - `description` string, nullable — Descricao da transacao (max: 500)
  - `externalId` string, nullable — ID externo para referencia (max: 100)
  - `customerId` string, uuid, nullable — ID do cliente cadastrado. Para boleto, informe customerId ou customerName.
  - `callbackUrl` string, nullable — URL para receber webhooks
  - `metadata` string, nullable — Metadados em JSON
  - `pixExpirationMinutes` integer, nullable — Tempo de expiracao do PIX (5-1440 min)
  - `customerName` string, 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.
  - `customerDocument` string, nullable — CPF/CNPJ do cliente/pagador
  - `customerEmail` string, nullable — Email do cliente/pagador (opcional). Se nao for enviado, a Safefy gera um email tecnico apenas para viabilizar o processamento.
  - `customerPhone` string, nullable — Telefone do cliente/pagador com codigo do pais. Aceita com ou sem '+' no envio e e normalizado para apenas digitos no processamento.
  - `boletoDueDate` string, date, nullable — Data de vencimento do boleto (YYYY-MM-DD). Obrigatorio para boleto. Minimo: D+2.
  - `boletoInstructions` string, nullable — Instrucoes do boleto. Opcional.
  - `cardNumber` string, nullable — Numero do cartao de credito (obrigatorio para method=CreditCard)
  - `cardHolderName` string, nullable — Nome do titular do cartao (obrigatorio para method=CreditCard)
  - `cardExpirationMonth` string, nullable — Mes de expiracao do cartao, dois digitos (obrigatorio para method=CreditCard)
  - `cardExpirationYear` string, nullable — Ano de expiracao do cartao, quatro digitos (obrigatorio para method=CreditCard)
  - `cardCvv` string, nullable — Codigo de seguranca do cartao CVV (obrigatorio para method=CreditCard)
  - `installments` integer, nullable — Numero de parcelas, de 1 a 12 (obrigatorio para method=CreditCard)
  - `cardToken` string, nullable — Token de cartao obtido via /v1/card-tokenize (alternativa ao envio de dados brutos do cartao)

## Response `201`

Transacao criada com sucesso

- CreateTransactionResponse
  - `data` TransactionData
    - `id` string, uuid — ID unico da transacao
    - `externalId` string, nullable — ID externo informado
    - `method` 'Pix' | 'CreditCard' | 'Boleto' — Metodo de pagamento
    - `amount` integer — Valor em centavos
    - `fee` integer — Taxa cobrada em centavos
    - `netAmount` integer — Valor liquido em centavos
    - `currency` string — Moeda
    - `status` 'Pending' | 'Processing' | 'Completed' | 'Failed' | 'Refunded' | 'Expired' | 'Cancelled' — Status da transacao
    - `description` string, nullable — Descricao
    - `environment` 'Sandbox' | 'Production' — Ambiente
    - `expiresAt` string, date-time, nullable — Data de expiracao
    - `createdAt` string, date-time — Data de criacao
    - `completedAt` string, date-time, nullable — Data de confirmacao
    - `customerId` string, uuid, nullable — ID do cliente
    - `pix` PixTransactionData, nullable — Dados do PIX. A imagem do QR Code não é retornada - use uma biblioteca de QR Code para gerar a imagem a partir do copyAndPaste.
      - `txId` string — ID da transacao PIX (TxId)
      - `copyAndPaste` string — Codigo PIX Copia e Cola (BR Code). Use este codigo para gerar a imagem do QR Code no seu frontend.
      - `expiresAt` string, date-time — Data de expiracao do codigo PIX
    - `card` CardTransactionData, nullable
      - `lastFour` string — Ultimos 4 digitos do cartao
      - `brand` string — Bandeira do cartao
      - `installments` integer — Numero de parcelas
      - `authorizationCode` string — Codigo de autorizacao
    - `boleto` BoletoTransactionData, nullable
      - `barcode` string — Codigo de barras
      - `digitableLine` string — Linha digitavel
      - `pdfUrl` string — URL do PDF do boleto
      - `dueDate` string, date-time — Data de vencimento
  - `message` string, nullable
  - `error` ApiErrorResponse, nullable
    - `message` string — Mensagem de erro
    - `code` string — Codigo do erro

## Other responses

- `400` — Dados invalidos
- `401` — Nao autorizado
- `500` — Erro interno

---

[API](https://skmtc.net/safefy-pay/apis/safefy-pix-gateway.md) · [All operations](https://skmtc.net/safefy-pay/apis/safefy-pix-gateway/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/safefy-pay/safefy-pix-gateway/revisions/57157be53ccc/schema)