Split de Pagamento

Visão Geral

O Split de Pagamento PIX permite dividir automaticamente o valor recebido entre múltiplos beneficiários. Ideal para marketplaces, plataformas de serviços e operações que precisam distribuir valores entre diferentes participantes.

O Split é configurado no momento da criação da cobrança e é executado automaticamente após o pagamento.

Como Funciona

Criação: Cobrança criada com regras de split
Pagamento: Cliente paga o valor total
Divisão: Sistema divide automaticamente
Transferência: Cada beneficiário recebe sua parte
Webhook: Notificação de conclusão enviada

Parâmetros de Split

splits

array

required

Array com configuração de cada beneficiário

Mostrar splits

splits[].walletId

string

required

ID da carteira do beneficiário

splits[].amount

number

Valor fixo em reais para o beneficiário

splits[].percentage

number

Percentual do valor total para o beneficiário

Exemplo de Requisição

curl -X POST "https://api-gateway.firebanking.com.br/pix/v2/payment" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "value": 1000.00,
      "description": "Venda marketplace",
      "externalId": "marketplace-001",
      "expirationTime": 300
    },
    "payer": {
      "fullName": "João Silva",
      "document": "12345678901"
    },
    "splits": [
      {
        "walletId": "vendor_123",
        "percentage": 85
      },
      {
        "walletId": "platform_fee",
        "percentage": 10
      },
      {
        "walletId": "shipping_partner",
        "percentage": 5
      }
    ]
  }'

Exemplo de Resposta

{
  "transactionId": "cd722e93-032f-45e1-b638-87a2490dcea7",
  "status": "WAITING_PAYMENT",
  "pixQrCode": "iVBORw0KGgoAAAANSUhEUgAABbQAAAW0CAYAAAAeooXXAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAIABJREFUeJzs2kGu5DqSRNFmI/a/ZfbwVw7+Q2XLM2UWfs4CBKdIKQIXOvfe+z8AAAAAABDuf98eAAAAAAAA...",
  "pixCode": "00020101021226880014br.gov.bcb.pix2566qrcode-h.firebanking.com.br/QR/cob/EEA7B851BBAFFB546073CE80810F56AA0F95204000053039865802BR5925VICTOR NERY TEIXEIRA CONS6009Sao Paulo610905726-10062070503***630498E0",
  "generateTime": "2024-04-14T02:58:04.997Z",
  "expirationDate": "2024-04-15T02:58:04.997Z",
  "paymentLink": "https://pay.firebanking.com.br/cd722e93-032f-45e1-b638-87a2490dcea7"
}

Tipos de Split

Por Percentual

{
  "walletId": "wallet_123",
  "percentage": 15.5  // 15.5% do valor total
}

Vantagem: Proporcional ao valor
Uso: Comissões, marketplaces
Limite: Soma deve ser ≤ 100%

Valor Fixo

{
  "walletId": "wallet_456",
  "amount": 25.00  // R$ 25,00 fixos
}

Vantagem: Valor garantido
Uso: Taxas fixas, serviços
Limite: Soma deve ser ≤ valor total

Split Misto

"splits": [
  {
    "walletId": "wallet_123",
    "amount": 50.00
  },
  {
    "walletId": "wallet_456",
    "percentage": 10
  }
]

Validações de Split

Regras Obrigatórias

Soma percentual: Máximo 100%
Soma valores fixos: Não pode exceder valor total
Mínimo por beneficiário: R$ 0,01
Máximo de beneficiários: 10 por transação

Exemplos de Validação

✅ Válido - 100% Distribuído

// Valor total: R$ 1.000,00
"splits": [
  { "walletId": "wallet_1", "percentage": 80 },  // R$ 800,00
  { "walletId": "wallet_2", "percentage": 20 }   // R$ 200,00
]
// Total: 100% ✅

✅ Válido - Valores Fixos

// Valor total: R$ 500,00
"splits": [
  { "walletId": "wallet_1", "amount": 400 }, // R$ 400,00
  { "walletId": "wallet_2", "amount": 100 }  // R$ 100,00
]
// Total: R$ 500,00 ✅

❌ Inválido - Excede 100%

"splits": [
  { "walletId": "wallet_1", "percentage": 60 },
  { "walletId": "wallet_2", "percentage": 50 }
]
// Total: 110% ❌

❌ Inválido - Valor Fixo Excede Total

// Valor total: R$ 100,00
"splits": [
  { "walletId": "wallet_1", "amount": 80 },
  { "walletId": "wallet_2", "amount": 30 }
]
// Total: R$ 110,00 > R$ 100,00 ❌

Configuração de Beneficiários

Os beneficiários do split são definidos diretamente no payload da cobrança PIX. Cada beneficiário deve incluir:

Dados Obrigatórios do Beneficiário

pixKey: Chave PIX do beneficiário
pixKeyType: Tipo da chave (DOCUMENT, EMAIL, PHONE, RANDOM_KEY)
document: CPF ou CNPJ do beneficiário
percentage ou value: Percentual ou valor fixo do split

Exemplo de Configuração

{
  "splits": [
    {
      "pixKey": "12345678000195",
      "pixKeyType": "DOCUMENT",
      "document": "12345678000195",
      "percentage": 85,
      "description": "Vendedor principal"
    }
  ]
}

Os beneficiários são configurados no momento da criação da cobrança, não existindo endpoint separado para gerenciamento.

Casos de Uso

Marketplace E-commerce

Vendedor: 85% do valor
Plataforma: 10% de comissão
Logística: 5% para entrega

Plataforma de Serviços

Profissional: 80% do valor
Plataforma: 15% de comissão
Seguro: 5% para garantia

Evento/Show

Artista: 60% do valor
Produtora: 25% de produção
Casa de Show: 10% do espaço
Plataforma: 5% de comissão

Códigos de Erro

Código	Descrição
`INVALID_SPLIT_TOTAL`	Soma dos splits excede 100% ou valor total
`INVALID_RECIPIENT`	Beneficiário não encontrado ou inativo
`SPLIT_MINIMUM_AMOUNT`	Valor do split menor que mínimo (R$ 0,01)
`TOO_MANY_RECIPIENTS`	Máximo de 10 beneficiários por split
`RECIPIENT_LIMIT_EXCEEDED`	Limite de transferência do beneficiário

Boas Práticas

Planejamento

Cadastre beneficiários: Antes de usar no split
Teste percentuais: Valide cálculos em sandbox
Documente regras: Mantenha registro das divisões
Monitore limites: Acompanhe limites dos beneficiários

Performance

Cache beneficiários: Evite consultas repetidas
Valide antes: Confirme dados antes de criar split
Use webhooks: Para monitorar execução em tempo real
Log detalhado: Para auditoria e troubleshooting

Próximos Passos

Criar Cobrança PIX

Crie cobranças PIX com split configurado

Webhooks

Configure notificações de split

Relatórios

Acompanhe performance dos splits

Sandbox

Teste splits em ambiente de desenvolvimento

Authorizations

x-api-key

string

header

required

Chave de API para autenticação

Body

application/json

transaction

object

required

Mostrar atributos filhos

transaction.value

number

required

Valor da transação em reais

Intervalo obrigatório: x >= 0.01

Example:

0.15

transaction.description

string

Descrição da transação

Maximum string length: 140

Example:

"Cobrança de teste"

transaction.expirationTime

integer

Tempo de expiração em segundos

Example:

300

transaction.externalId

string

ID externo da transação

Example:

"uuid-123"

transaction.additionalInfo

object

Mostrar atributos filhos

transaction.additionalInfo.sellerId

integer

Example:

123

transaction.additionalInfo.whatsAppPhone

string

Example:

"37988996655"

payer

object

Mostrar atributos filhos

payer.fullName

string

Nome completo do pagador

Example:

"John Marvin"

payer.document

string

CPF/CNPJ do pagador

Example:

"12312312387"

splits

object[]

Divisão de valores entre múltiplos recebedores

Mostrar atributos filhos

splits.walletId

string

Example:

"wallet_123"

splits.amount

number

Example:

50

splits.percentage

number

Example:

33.33

callback_url

string<uri>

URL para receber webhooks específicos desta transação

metadata

object

Dados adicionais da transação

Mostrar atributos filhos

metadata.{key}

string

Response

Cobrança PIX criada com sucesso

transactionId

string

required

ID único da transação PIX no FireBanking

Example:

"cd722e93-032f-45e1-b638-87a2490dcea7"

status

enum<string>

required

Status atual da transação

Opções disponíveis:

WAITING_PAYMENT,

PAID,

EXPIRED,

CANCELLED,

REFUNDED

Example:

"WAITING_PAYMENT"

pixQrCode

string

required

QR Code em formato base64 (PNG) para exibição

Example:

"iVBORw0KGgoAAAANSUhEUgAABbQAAAW0CAYAAAAeooXXAAAABGdBTUEAALGPC/xhBQ..."

pixCode

string

required

Código PIX Copia e Cola para pagamento

Example:

"00020101021226880014br.gov.bcb.pix2566qrcode-h.firebanking.com.br/QR/cob/EEA7B851BBAFFB546073CE80810F56AA0F95204000053039865802BR5925VICTOR NERY TEIXEIRA CONS6009Sao Paulo610905726-10062070503***630498E0"

generateTime

string<date-time>

required

Data/hora de geração da cobrança (ISO 8601)

Example:

"2024-04-14T02:58:04.997Z"

expirationDate

string<date-time>

required

Data/hora de expiração da cobrança (ISO 8601)

Example:

"2024-04-15T02:58:04.997Z"

paymentLink

string<uri>

required

Link direto para pagamento (ideal para WhatsApp/email)

Example:

"https://pay.firebanking.com.br/cd722e93-032f-45e1-b638-87a2490dcea7"

Visão Geral

Fluxo de Integração

PIX Cobrança (Cash In)

PIX Saque (Cash Out)

Operações

Gestão

Webhooks

Visão Geral

Como Funciona

Parâmetros de Split

Exemplo de Requisição

Exemplo de Resposta

Tipos de Split

Por Percentual

Valor Fixo

Split Misto

Validações de Split

Regras Obrigatórias

Exemplos de Validação

Configuração de Beneficiários

Dados Obrigatórios do Beneficiário

Exemplo de Configuração

Casos de Uso

Marketplace E-commerce

Plataforma de Serviços

Evento/Show

Códigos de Erro

Boas Práticas

Planejamento

Performance

Próximos Passos

Criar Cobrança PIX

Webhooks

Relatórios

Sandbox

Authorizations

Body

Response

Visão Geral

Fluxo de Integração

PIX Cobrança (Cash In)

PIX Saque (Cash Out)

Operações

Gestão

Webhooks

​Visão Geral

​Como Funciona

​Parâmetros de Split

​Exemplo de Requisição

​Exemplo de Resposta

​Tipos de Split

​Por Percentual

​Valor Fixo

​Split Misto

​Validações de Split

​Regras Obrigatórias

​Exemplos de Validação

​Configuração de Beneficiários

​Dados Obrigatórios do Beneficiário

​Exemplo de Configuração

​Casos de Uso

​Marketplace E-commerce

​Plataforma de Serviços

​Evento/Show

​Códigos de Erro

​Boas Práticas

​Planejamento

​Performance

​Próximos Passos

Criar Cobrança PIX

Webhooks

Relatórios

Sandbox

Authorizations

Body

Response

Visão Geral

Como Funciona

Parâmetros de Split

Exemplo de Requisição

Exemplo de Resposta

Tipos de Split

Por Percentual

Valor Fixo

Split Misto

Validações de Split

Regras Obrigatórias

Exemplos de Validação

Configuração de Beneficiários

Dados Obrigatórios do Beneficiário

Exemplo de Configuração

Casos de Uso

Marketplace E-commerce

Plataforma de Serviços

Evento/Show

Códigos de Erro

Boas Práticas

Planejamento

Performance

Próximos Passos