Como usar Split de Pagamentos na API

O que é Split?

O Split é a funcionalidade que permite dividir automaticamente o valor de uma venda entre múltiplas contas de produtor no momento da criação do pagamento.

Essa divisão acontece diretamente na API, sem necessidade de repasses manuais posteriores.

O Split pode ser utilizado nas rotas de pagamento:

• Receber PIX

• Receber Cartão

• Receber Boleto

Como funciona o Split na prática

Ao criar um pagamento via API, você pode incluir o campo opcional splits no body da requisição.

Esse campo deve conter um array de objetos indicando:

• Quem irá receber parte da venda

• Quanto cada um irá receber

Se o campo splits não for enviado, 100% do valor da venda ficará com a conta principal.

Estrutura do campo splits

Exemplo de uso:

{   
    "splits": [
        {
            "producerId": "cm1234",
            "amount": 30.00
        },
        {
           "producerId": "cm9876",
           "amount": 20.00
        }
     ]
}

Cada objeto dentro do array deve conter:

producerId

ID da conta que receberá o valor do split.
Esse ID deve ser informado pelo próprio produtor que irá receber.

amount

Valor em reais (BRL) que será destinado àquela conta.

Regras obrigatórias

1. O campo splits é opcional

2. O somatório de todos os amount não pode ultrapassar o valor total da transação

3. O valor deve estar em reais (BRL)

4. Utilize no máximo duas casas decimais

5. A divisão acontece automaticamente quando o pagamento for confirmado

Caso o total do split ultrapasse o valor da venda, a API retornará erro.

Split em percentual

A API não aceita percentual diretamente.

Se você quiser trabalhar com percentuais, deve:

1. Calcular o valor em reais no seu sistema

2. Enviar o valor já convertido no campo amount

Exemplo:

Venda: R$ 200,00
Split: 25% para A

Cálculo:
200 x 0,25 = 50,00

Enviar:

{   
    "splits": [
        {
            "producerId": "cm1234",
            "amount": 50.00
        }
     ]
}

Exemplo completo de pagamento com Split

Venda total: R$ 100,00
Divisão:

• Produtor A → R$ 30,00

• Produtor B → R$ 20,00

• Conta principal → R$ 50,00

Requisição:

{   
    "amount": 100.00,
    "splits": [
        {
            "producerId": "cm1234",
            "amount": 30.00
        },
        {
           "producerId": "cm9876",
           "amount": 20.00
        }
     ]
}

Resultado:

• Produtor A recebe R$ 30,00

• Produtor B recebe R$ 20,00

• Produtor principal recebe o valor restante

Boas práticas

• Valide os producerId antes de enviar

• Calcule percentuais antes da requisição

• Garanta que o total dos splits não ultrapasse o valor da venda

• Evite erro de arredondamento ajustando o último split

• Teste em ambiente seguro antes de produção

Erros comuns

• Enviar percentual ao invés de valor

• Soma dos splits maior que o total

• Utilizar mais de duas casas decimais

• Informar producerId inexistente

Como criar assinaturas via API

É possível criar assinaturas utilizando a API da plataforma.

Importante

A disponibilidade desse recurso depende da adquirente/processadora configurada em sua plataforma, pois nem todas possuem suporte para transações recorrentes.

Antes da integração, valide se a adquirente utilizada oferece a funcionalidade de assinatura.

Para confirmar essa informação basta acessar o seu painel de admin -> Configurações -> Adquirentes -> Clicar na adquirente desejada -> Clique na opção "Ver mais"

Formas de pagamento disponíveis

Cartão de crédito

Endpoint para receber pagamentos recorrentes via cartão:

https://app.seudominio.com/docs/endpoint/card/subscription

PIX recorrente

Endpoint para receber pagamentos recorrentes via Pix:

https://app.seudominio.com/docs/endpoint/pix/subscription