Pular para o conteúdo principal
POST
/
v1
/
transactions
Criar transacao
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 transacao PIX e retorna o codigo Copia e Cola para pagamento.
A imagem do QR Code nao e retornada pela API. Voce deve gerar a imagem no seu frontend usando uma biblioteca de QR Code a partir do campo copyAndPaste.

​
Parametros

​
amount
integer
obrigatório
Valor da transacao em centavos. Exemplo: R$ 150,00 = 15000.
​
description
string
Descricao da transacao. Aparece no extrato do pagador.
​
externalId
string
Identificador externo no seu sistema (ex: ID do pedido). Maximo 100 caracteres.
​
customerId
string
ID do cliente associado a transacao (UUID).
​
expiresInMinutes
integer
Tempo de expiracao em minutos. Padrao: 30 minutos.
​
callbackUrl
string
URL para receber o webhook quando o pagamento for confirmado.
​
metadata
string
Dados adicionais em formato JSON string. Maximo 1000 caracteres.

​
Gerando o QR Code

O campo pix.copyAndPaste contem o codigo EMV (BR Code) do PIX. Para exibir o QR Code visualmente, voce precisa gerar a imagem no seu frontend.

​
JavaScript (usando qrcode.js)

<script src="https://cdn.jsdelivr.net/npm/qrcode/build/qrcode.min.js"></script>

<canvas id="qrcode"></canvas>

<script>
  const pixCode = "00020126580014br.gov.bcb.pix0136a1b2c3d4...";
  QRCode.toCanvas(document.getElementById('qrcode'), pixCode);
</script>

​
React (usando react-qr-code)

import QRCode from 'react-qr-code';

function PaymentPage({ transaction }) {
  return (
    <div>
      <QRCode value={transaction.pix.copyAndPaste} size={256} />
      <p>Ou copie o codigo:</p>
      <code>{transaction.pix.copyAndPaste}</code>
    </div>
  );
}

​
Next.js (usando next-qrcode)

import { useQRCode } from 'next-qrcode';

function PaymentPage({ transaction }) {
  const { Canvas } = useQRCode();
  
  return (
    <Canvas
      text={transaction.pix.copyAndPaste}
      options={{ width: 256, margin: 2 }}
    />
  );
}
O codigo copyAndPaste tambem pode ser copiado pelo usuario e colado diretamente no app do banco para efetuar o pagamento.

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

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 pagador (PIX)

Exemplo:

"Joao Silva"

​
customerDocument
string | null

CPF/CNPJ do pagador (PIX)

Exemplo:

"12345678900"

Resposta

Transacao criada com sucesso

​
data
object
​
message
string | null
​
error
object