Skip to main content
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
}
Creates a new payment transaction. Supports PIX and Boleto payment methods.
QR Code images are not returned by the API. You should generate the image in your frontend using the pix.copyAndPaste value.See the dedicated guide: Generating PIX QR Code.

Authorizations

​
Authorization
string
header
required

Token JWT obtido via /v1/auth/token

Body

application/json
​
method
enum<string>
required

Metodo de pagamento

Available options:
Pix,
CreditCard,
Boleto
Example:

"Pix"

​
amount
integer<int64>
required

Valor em centavos (min: 100)

Example:

10000

​
currency
enum<string>
required

Moeda

Available options:
BRL
Example:

"BRL"

​
description
string | null

Descricao da transacao (max: 500)

Example:

"Pagamento do pedido #12345"

​
externalId
string | null

ID externo para referencia (max: 100)

Example:

"pedido_12345"

​
customerId
string<uuid> | null

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

Example:

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

​
callbackUrl
string | null

URL para receber webhooks

Example:

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

​
metadata
string | null

Metadados em JSON

Example:

"{\"orderId\": 12345}"

​
pixExpirationMinutes
integer | null

Tempo de expiracao do PIX (5-1440 min)

Example:

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.

Example:

"Joao Silva"

​
customerDocument
string | null

CPF/CNPJ do cliente/pagador

Example:

"12345678900"

​
customerEmail
string | null

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

Example:

"joao@exemplo.com"

​
boletoDueDate
string<date> | null

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

Example:

"2025-02-15"

​
boletoInstructions
string | null

Instrucoes do boleto. Opcional.

Example:

"Nao receber apos o vencimento"

Response

Transacao criada com sucesso

​
data
object
​
message
string | null
​
error
object