Como funciona o split de pagamento?
O split de pagamentos com a API do Asaas permite dividir o valor de uma transação entre diferentes recebedores de forma automática e transparente. Isso é especialmente útil para marketplaces, plataformas de afiliados ou qualquer sistema que necessite gerenciar múltiplos destinatários em uma única transação.
Como funciona o split de pagamento no Asaas?
Definição de recebedores: Cada recebedor deve possuir uma Wallet ID (carteira digital) vinculada à sua conta no Asaas. Valor fixo (fixedValue): Um valor fixo do total será enviado a um recebedor específico. Percentual (percentage): Um percentual do total será enviado a um recebedor. Valor total fixo (totalFixedValue): Define como o valor total da cobrança será distribuído entre os recebedores. Durante a criação de uma cobrança ou assinatura, o objeto split é utilizado para especificar as regras de divisão. Endpoint principal para split de pagamento
Ao criar uma cobrança, o endpoint a ser utilizado é:
POST /payments
Parâmetros para split:
walletId: Identificador da carteira do recebedor. fixedValue: Valor fixo para o recebedor. percentage: Percentual do total para o recebedor. totalFixedValue: Valor total que será dividido entre todos os recebedores. Exemplo de payload:
json
Copiar código
{
"customer": "customer_id",
"value": 200.00,
"description": "Venda no marketplace",
"dueDate": "2024-12-01",
"split": [
{
"walletId": "wallet_id_dono_produto",
"percentage": 70
},
{
"walletId": "wallet_id_marketplace",
"fixedValue": 30.00
},
{
"walletId": "wallet_id_seller",
"totalFixedValue": 100.00
}
]
}
Resultado esperado:
Dono do produto: Receberá 70% (R$ 140,00). Marketplace: Receberá um valor fixo de R$ 30,00. Seller: Receberá o restante para completar os R$ 200,00 (R$ 30,00). Fluxo de implementação
Certifique-se de que todos os recebedores estejam cadastrados no Asaas e possuam uma Wallet ID. Envie a requisição para criar o pagamento com o objeto split configurado. Utilize os endpoints da API para acompanhar o status do pagamento. Configure webhooks para receber notificações em tempo real sobre o processamento da cobrança. Considerações importantes
As taxas são cobradas pela plataforma e podem variar dependendo dos valores e recebedores envolvidos. Certifique-se de incluir isso no cálculo. Verifique o limite máximo de recebedores por transação, conforme a documentação do Asaas. Estornos e cancelamentos: No caso de cancelamentos ou estornos, os valores são ajustados automaticamente entre as carteiras, conforme configurado no split. Para garantir que os valores sejam corretamente direcionados, valide previamente os Wallet IDs e as regras de divisão. Exemplo prático para marketplaces
Imagine um marketplace onde:
O dono do produto recebe 80% do valor da venda. O marketplace recebe 15% como comissão. Um afiliado recebe 5% por promover o produto. Configuração do split:
json
Copiar código
{
"split": [
{
"walletId": "wallet_id_dono_produto",
"percentage": 80
},
{
"walletId": "wallet_id_marketplace",
"percentage": 15
},
{
"walletId": "wallet_id_afiliado",
"percentage": 5
}
]
}
Com essa configuração, o fluxo financeiro é automatizado, reduzindo erros e economizando tempo. Se precisar de ajuda com um exemplo prático de código ou dúvidas adicionais, é só avisar!
4o
Consigo fazer o split de pagamento 3 etapas ?
Sim, é possível realizar um split de pagamentos em 3 etapas envolvendo diferentes partes como o dono do produto do marketplace, o dono do marketplace, e os sellers utilizando plataformas como o Asaas.
Como funciona o split no Asaas
O split de pagamentos no Asaas é configurado diretamente na criação de cobranças ou assinaturas por meio do objeto split, onde você pode definir:
Wallet IDs: Identificadores das carteiras digitais que receberão os valores. Valor fixo: Define valores específicos para cada recebedor. Percentual: Divide com base em percentuais do valor total da transação. Total fixed value: Determina como o valor total será distribuído. Exemplo de aplicação
No cenário apresentado, você pode configurar a API para dividir o pagamento em três etapas:
Dono do produto: Recebe uma porcentagem ou valor fixo do total da transação, representando o ganho pela venda. Dono do marketplace: Recebe uma taxa ou comissão pela utilização da plataforma. Sellers: Caso haja outros vendedores envolvidos (por exemplo, afiliados), eles também podem receber uma parte proporcional. Configuração na prática
Abaixo está um exemplo genérico da estrutura JSON para um split de pagamento no Asaas:
json
Copiar código
{
"value": 100.00,
"description": "Venda de produto",
"split": [
{
"walletId": "wallet_id_dono_produto",
"fixedValue": 50.00
},
{
"walletId": "wallet_id_marketplace",
"percentage": 10
},
{
"walletId": "wallet_id_seller",
"fixedValue": 40.00
}
]
}
fixedValue: Valor fixo para um recebedor. percentage: Percentual do valor total. Benefícios do Split em 3 etapas
Automação do fluxo financeiro: Reduz a necessidade de intervenções manuais. Customização do modelo de negócio: Suporte para comissões, afiliados, ou múltiplos vendedores. Transparência: Cada recebedor tem visibilidade clara de seus ganhos. Webhooks como complemento
Os webhooks são fundamentais para acompanhar eventos em tempo real, como:
Confirmação do pagamento. Notificação de falhas ou cancelamentos. Alterações em assinaturas. Ao integrar webhooks, você pode automatizar notificações e atualizações para os participantes do split.
Como funciona nos casos de estorno e cancelamento?
O cancelamento e estorno de pagamentos no Asaas com o uso de split de pagamentos envolvem alguns passos específicos devido à divisão do valor entre múltiplos recebedores. A API do Asaas oferece suporte para essas operações, mas é importante observar como os valores alocados para diferentes carteiras são ajustados no processo.
Funcionamento do cancelamento e estorno com split
Cancelamento antes do pagamento confirmado: Se o pagamento ainda não foi confirmado, a cobrança pode ser cancelada diretamente. Nesse caso, não há movimentação financeira para as carteiras envolvidas, já que o pagamento ainda não foi processado. Estorno após o pagamento confirmado: Quando o pagamento já foi confirmado e os valores distribuídos entre as carteiras, é necessário realizar um estorno parcial ou total. O estorno retorna os valores às carteiras envolvidas, seguindo a lógica do split configurado na transação original. Fluxo de estorno com API
1. Verificar o status da transação
Antes de solicitar o estorno, você deve verificar o status da cobrança. Use o endpoint:
GET /payments/{id}
CONFIRMED: Pode ser estornado. PENDING ou OVERDUE: Pode ser cancelado. REFUNDED: Já foi estornado. 2. Solicitar o estorno
O estorno é realizado utilizando o endpoint:
POST /payments/{id}/refund
Parâmetros relevantes:
id: Identificador da cobrança. value (opcional): Valor a ser estornado. Se não informado, o valor total será estornado. splitId (opcional): Permite especificar o recebedor do split para realizar estorno parcial. Exemplo de solicitação para estorno total:
json
Copiar código
POST /payments/{id}/refund
{
"value": 100.00
}
Exemplo de solicitação para estorno parcial em um split:
json
Copiar código
POST /payments/{id}/refund
{
"value": 40.00,
"splitId": "wallet_id_seller"
}
Observações importantes
Ajuste automático dos recebedores: Se você estornar o valor total da cobrança, o Asaas ajustará automaticamente os valores nas carteiras dos recebedores originais. Para estornos parciais, apenas os valores relacionados ao splitId informado serão revertidos. Em muitos casos, as taxas de transação não são reembolsáveis. O custo deve ser considerado ao realizar o estorno. Webhooks para monitoramento: Use os webhooks do Asaas para monitorar eventos relacionados a cancelamentos e estornos. Configure eventos como: PAYMENT_REFUNDED: Notifica quando um pagamento é estornado. PAYMENT_DELETED: Notifica quando uma cobrança é cancelada. Exemplos de casos de uso
Caso 1: Estorno total
Um cliente solicita reembolso integral. A API estorna o valor total e ajusta as carteiras automaticamente. Caso 2: Estorno parcial de um recebedor
Um vendedor (seller) comete um erro e deseja devolver sua parte. O valor referente ao walletId do vendedor é estornado, enquanto os outros recebedores mantêm seus valores. Split de pagamento com múltiplos vendedores usando a API do Asaas
Para implementar o split de pagamento com múltiplos vendedores usando a API do Asaas, você precisa configurar corretamente a divisão do pagamento de forma que cada vendedor receba sua parte de uma transação, incluindo o repasse do frete, se aplicável. Abaixo explico como isso pode ser feito, o que precisa ser configurado e os passos gerais:
1. Configuração da API do Asaas
O Asaas oferece uma funcionalidade chamada split de pagamento que permite dividir automaticamente o valor de uma transação entre diferentes contas (wallets). Para usar essa funcionalidade, você precisa:
Ter uma conta configurada no Asaas com acesso às APIs. Configurar as wallets (carteiras) dos vendedores para que a API saiba para onde enviar cada parte do pagamento. 2. O que é necessário configurar
Cada vendedor precisa ter uma wallet ID associada. Isso pode ser obtido durante o processo de cadastro do vendedor na plataforma. As wallets devem estar configuradas para receber transferências de pagamento. Estrutura do Split de Pagamento: A configuração do split deve ser incluída no objeto de criação de cobrança ou transação. Você pode dividir o pagamento em valores fixos, percentuais ou valores totais. Para dividir o pagamento entre múltiplos vendedores, você deve especificar a walletId de cada um e o valor que cada um deve receber (pode ser em valores fixos ou percentuais). O exemplo de configuração pode ser assim: json
Copiar código
{
"customer": "customerId",
"billingType": "BOLETO",
"value": 100.00,
"dueDate": "2024-12-10",
"split": [
{
"walletId": "walletId_vendedor_A",
"fixedValue": 40.00
},
{
"walletId": "walletId_vendedor_B",
"fixedValue": 30.00
},
{
"walletId": "walletId_vendedor_C",
"fixedValue": 30.00
}
]
}
Observação: O parâmetro split é incluído na requisição para criar a cobrança. Cada item do array define uma divisão de valor, onde walletId é a identificação da conta do vendedor, e fixedValue é o valor que esse vendedor deve receber. 3. Processo de Criação de Cobrança e Divisão
Criação de cobrança: Para criar uma cobrança no Asaas, você deve usar o endpoint de POST /payments ou POST /subscriptions, dependendo do tipo de pagamento. Definição do split: No corpo da requisição, inclua a propriedade split com as informações necessárias para cada vendedor. Recebimento do pagamento: Quando o pagamento for processado, o Asaas vai dividir automaticamente o valor entre as wallets especificadas, enviando as quantias apropriadas para cada um. 
