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
}

Documentation Index

Fetch the complete documentation index at: https://docs.safefypay.com.br/llms.txt

Use this file to discover all available pages before exploring further.

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"

​
customerPhone
string | null

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

Example:

"5511999998888"

​
boletoDueDate
string<date> | null

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

Example:

"2025-02-15"

​
boletoInstructions
string | null

Instrucoes do boleto. Opcional.

Example:

"Nao receber apos o vencimento"

​
cardNumber
string | null

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

Example:

"4111111111111111"

​
cardHolderName
string | null

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

Example:

"JOAO SILVA"

​
cardExpirationMonth
string | null

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

Example:

"12"

​
cardExpirationYear
string | null

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

Example:

"2028"

​
cardCvv
string | null

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

Example:

"123"

​
installments
integer | null

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

Example:

1

Response

Transacao criada com sucesso

​
data
object
​
message
string | null
​
error
object