Criar transação

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",
    "splits": [
      {
        "splitCode": "550e8400-e29b-41d4-a716-446655440001",
        "type": "PERCENTAGE",
        "value": 20,
        "shareAmount": 1970
      }
    ],
    "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
}

{
  "data": null,
  "message": null,
  "error": {
    "message": "O Valor Mínimo da transacao e R$ 1,00 (100 centavos).",
    "code": "invalid_amount"
  }
}

{
  "data": null,
  "message": null,
  "error": {
    "message": "Token invalido ou expirado.",
    "code": "unauthorized"
  }
}

{
  "data": null,
  "message": null,
  "error": {
    "message": "Erro ao processar a transacao. Tente novamente.",
    "code": "internal_error"
  }
}

POST

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",
    "splits": [
      {
        "splitCode": "550e8400-e29b-41d4-a716-446655440001",
        "type": "PERCENTAGE",
        "value": 20,
        "shareAmount": 1970
      }
    ],
    "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
}

{
  "data": null,
  "message": null,
  "error": {
    "message": "O Valor Mínimo da transacao e R$ 1,00 (100 centavos).",
    "code": "invalid_amount"
  }
}

{
  "data": null,
  "message": null,
  "error": {
    "message": "Token invalido ou expirado.",
    "code": "unauthorized"
  }
}

{
  "data": null,
  "message": null,
  "error": {
    "message": "Erro ao processar a transacao. Tente novamente.",
    "code": "internal_error"
  }
}

Cria uma transação PIX, boleto ou cartão de crédito.

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.
Cartão de Crédito: Requer method=CreditCard, amount e os dados do cartão (cardNumber, cardHolderName, cardExpirationMonth, cardExpirationYear, cardCvv) ou um cardToken obtido via POST /v1/card-tokenize.

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.

Você também pode usar cartão tokenizado como forma de pagamento! Consulte o guia dedicado: Tokenizar cartão.

Split de pagamento via API

Em uma transação PIX, envie splits para destinar partes do valor líquido a outras organizações. Cada destinatário é identificado pelo seu splitCode.

{
  "method": "Pix",
  "amount": 10000,
  "currency": "BRL",
  "splits": [
    {
      "splitCode": "550e8400-e29b-41d4-a716-446655440001",
      "type": "PERCENTAGE",
      "value": 20
    },
    {
      "splitCode": "550e8400-e29b-41d4-a716-446655440002",
      "type": "FIXED",
      "value": 1000
    }
  ]
}

type: use PERCENTAGE ou FIXED.
value em PERCENTAGE: de 1 a 100, com até duas casas decimais.
value em FIXED: valor inteiro em centavos.
O mesmo splitCode não pode aparecer duas vezes e a soma das fatias deve caber no saldo disponível projetado do pagamento.
Split é exclusivo de PIX e depende de estar habilitado para a organização que cria a cobrança.

Quando o PIX for confirmado, cada destinatário recebe seu shareAmount em centavos. A resposta de criação e a consulta da transação retornam os splits aplicados para conciliação.

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}"

splits

object[] | null

Regras de split para PIX. Cada split direciona parte do valor liquido a outra organizacao. Disponivel apenas quando o split estiver habilitado para a organizacao principal.

Show child attributes

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"

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.

Exemplo:

"5511999998888"

boletoDueDate

string<date> | null

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

Exemplo:

"2025-02-15"

boletoInstructions

string | null

Instrucoes do boleto. Opcional.

Exemplo:

"Nao receber apos o vencimento"

cardNumber

string | null

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

Exemplo:

"4111111111111111"

cardHolderName

string | null

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

Exemplo:

"JOAO SILVA"

cardExpirationMonth

string | null

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

Exemplo:

"12"

cardExpirationYear

string | null

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

Exemplo:

"2028"

cardCvv

string | null

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

Exemplo:

"123"

installments

integer | null

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

Exemplo:

1

cardToken

string | null

Token de cartao obtido via /v1/card-tokenize (alternativa ao envio de dados brutos do cartao)

Exemplo:

"ct_abc123def456"

Resposta

Transacao criada com sucesso

data

object

Show child attributes

message

string | null

error

object | null

Show child attributes

Autenticação

Clientes

Transações

Saldo

Disputas

Saques

Split de pagamento via API

Autorizações

Corpo

Resposta

​Split de pagamento via API

Autorizações

Corpo

Resposta

Split de pagamento via API