Create transaction

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

Creates a new payment transaction. Supports PIX, Boleto, and Credit Card payment methods.

PIX: Only method and amount are required. Returns the Copy and Paste code for payment.
Boleto: Requires method, amount, and a linked customer (customerId or customerName). Returns barcode, digitable line, and PDF URL.
Credit Card: Requires method=CreditCard, amount, and card data (cardNumber, cardHolderName, cardExpirationMonth, cardExpirationYear, cardCvv) or a cardToken obtained via POST /v1/card-tokenize.

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.

You can also use tokenized cards as a payment method! Check out the dedicated guide: Tokenize card.

Payment splitting through the API

For a PIX transaction, send splits to direct portions of the net amount to other organizations. Each recipient is identified by its 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 or FIXED.
value for PERCENTAGE: from 1 to 100, with up to two decimal places.
value for FIXED: a positive whole number in cents.
The same splitCode cannot be included twice, and all shares must fit within the payment’s projected available settlement.
Splitting is PIX-only and must be enabled for the organization creating the charge.

When the PIX is confirmed, each recipient receives its shareAmount in cents. The create response and transaction retrieval include the applied splits for reconciliation.

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

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)

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

cardToken

string | null

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

Example:

"ct_abc123def456"

Response

Transacao criada com sucesso

data

object

Show child attributes

message

string | null

error

object | null

Show child attributes

Authentication

Customers

Transactions

Balance

Disputes

Cashouts

Payment splitting through the API

Authorizations

Body

Response

​Payment splitting through the API

Authorizations

Body

Response

Payment splitting through the API