Pular para o conteúdo principal
POST
/
v1
/
transactions
curl --request POST \
  --url https://api-payment.safefypay.com.br/v1/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "method": "Pix",
  "amount": 10000,
  "currency": "BRL"
}
'
{
  "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",
    "completedAt": null,
    "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": null,
    "boleto": null
  },
  "message": "Transacao criada com sucesso.",
  "error": null
}
Cria uma transação PIX ou boleto.
  • PIX: Apenas method e amount são obrigatórios. Retorna o código Copia e Cola para pagamento.
  • Boleto: Requer method, amount e um cliente vinculado (customerId ou customerName). Retorna código de barras, linha digitável e URL do PDF.
A imagem do QR Code não é retornada pela API. Você deve gerar a imagem no seu frontend usando uma biblioteca de QR Code a partir do campo copyAndPaste.Veja o guia dedicado: Gerando QR Code do PIX.

Autorizações

​
Authorization
string
header
obrigatório

Token JWT obtido via /v1/auth/token

Corpo

application/json
​
method
enum<string>
obrigatório

Metodo de pagamento

Opções disponíveis:
Pix,
CreditCard,
Boleto
Exemplo:

"Pix"

​
amount
integer<int64>
obrigatório

Valor em centavos (min: 100)

Exemplo:

10000

​
currency
enum<string>
obrigatório

Moeda

Opções disponíveis:
BRL
Exemplo:

"BRL"

​
description
string | null

Descricao da transacao (max: 500)

Exemplo:

"Pagamento do pedido #12345"

​
externalId
string | null

ID externo para referencia (max: 100)

Exemplo:

"pedido_12345"

​
customerId
string<uuid> | null

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

Exemplo:

"550e8400-e29b-41d4-a716-446655440000"

​
callbackUrl
string | null

URL para receber webhooks

Exemplo:

"https://seusite.com.br/webhook"

​
metadata
string | null

Metadados em JSON

Exemplo:

"{\"orderId\": 12345}"

​
pixExpirationMinutes
integer | null

Tempo de expiracao do PIX (5-1440 min)

Exemplo:

30

​
customerName
string | null

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

Exemplo:

"Joao Silva"

​
customerDocument
string | null

CPF/CNPJ do cliente/pagador

Exemplo:

"12345678900"

​
customerEmail
string | null

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

Exemplo:

"joao@exemplo.com"

​
boletoDueDate
string<date> | null

Data de vencimento do boleto (YYYY-MM-DD). Opcional - padrao: 3 dias a partir da data atual.

Exemplo:

"2025-02-15"

​
boletoInstructions
string | null

Instrucoes do boleto. Opcional.

Exemplo:

"Nao receber apos o vencimento"

Resposta

Transacao criada com sucesso

​
data
object
​
message
string | null
​
error
object