Implementando split de pagamentos

Abordaremos todas as etapas necessárias para realização do split, permitindo que seja simplificado a sua contabilidade e criado modelos personalizados de negócios.

Quando realizada uma transação, um objeto da transação e de seus recebíveis serão criados.

Cada um dos recebíveis da transação terá uma parcela, montante total com impostos, valor líquido, destinatário e o vendedor que será creditado por recebê-lo.

Assim, poderá facilmente dividir uma determinada transação entre os vendedores(sellers) em seu Marketplace, associando a transação, e os vendedores que serão creditados através de um objeto split_rule, definindo um valor a ser dividido, bem como se o recebimento por divisão for passível de devolução.

Para determinar o valor que um vendedor específico receberá, disponibilizamos um endpoint para consultar os recebíveis por transação, essa é uma das maneiras recomendadas para conciliar a parte de uma determinada transação que foi liquidada ou a programada para liquidação.

Split "A Priori"

Essa é forma recomendada para os parceiros que transacionam com plano antecipado. Com essa regra, estabelecimentos comerciais poderão incluir o Split no ato da transação, que automaticamente será programado o comissionamento sem precisar aplicar uma regra futura.


curl --location --request POST 'https://payments.zoop.ws/v1/marketplaces/{{marketplace_id}}/transactions' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ==' \
--data-raw '{
    "amount": 4000,
    "currency": "BRL",
    "description": "venda",
    "capture": true,
    "on_behalf_of": "{{seller_id}}",
    "source": {
        "usage": "reusable",
        "amount": 4000,
        "currency": "BRL",
        "description": "Teste de Transacao",
        "type": "card",
        "card": {
            "id": "{{card_id}}"
        }
    },
    "payment_type": "credit",
    "split_rules": [
        {   "recipient": "{{sller_id}}",
            "liable": 1,
            "charge_processing_fee": 0,
            "amount": 1000
        }
    ]
}'

Split a posteriori

Essa é uma regra tradicional existente que de acordo com o número de comissionamentos por transação, será preciso executar quantas vezes forem necessário.

Exemplo 1 - Split um a um para uma mesma transação.

curl --location --request POST 'https://payments.zoop.ws/v1/marketplaces/{marketplace_id}/transactions/{{transaction_id}}/split_rules' \
--header 'Authorization: Basic enBr==' \
--header 'Content-Type: application/json' \
--data-raw '{
    "recipient": "{{seller_id}}", ---> Comissionado
    "liable": 1,
    "charge_processing_fee": 1,
    "percentage": 10
}'

Agora será possível realizar múltiplos splits conforme o exemplo 2. Essa forma é semelhante ao formato do split a priori.

Exemplo 2 - Split onde será possível passar um array e enviar multiplas estruturas.✨

curl --location --request POST 'https://payments.zoop.ws/v1/marketplaces/{marketplace_id}/transactions/{{transaction_id}}/split_rules' \
--header 'Authorization: Basic enBr==' \
--header 'Content-Type: application/json' \
--data-raw '{
             [
              {
               "recipient": "{{seller_id}}", ----> Participante 1
               "liable": 1,
               "charge_processing_fee": 1,
               "percentage": 10
               },
               "recipient": "{{seller_id}}", -----> Participante 2
               "liable": 1,
               "charge_processing_fee": 1,
               "percentage": 20
               {
               }
             ]
}'


Clique na imagem para aumentar.

1433

Fluxo split a posteriori

Consultando os recebíveis de uma transação.

Liste os recebíveis de transações para ver se a regra foi aplicada efetivamente e a divisão do recebimento está de acordo com o esperado.

Consultando split_rules da transação

Também será possível listar todo o objeto split_rulesde uma determinada transação.

Excluindo um objeto split_rule

Split só pode ser excluido antes que o recebível seja pago.

🚧

Erro 409 ao realizar split

Ao solicitar a criação do split o recebível da transação já deverá ter sido criado, caso contrario, a API retornará o erro 409 e a solicitação deverá feita novamente em alguns segundos.

❗️

Split no Pix

O split a priori deve ser feita no momento da criação do Pix.

O split nas transações do tipo Pix a posteriori, deverão ser realizadas logo após o recebimento do evento "receivable.created", pois o pagamento do mesmo ocorre em D+1.

❗️

Observações importantes

  • Recorrência (planos e assinaturas): Só será possível realizar split a posteriori.

  • Limite de Split por transação: O limite máximo de splits ou participantes de um split será de apenas 20 por transação.

❗️

Sobre split/plano de venda

  • Ao realizar um split, o "recipient" receberá o valor de acordo com o plano cadastrado para o seller responsável pela transação (on_behalf_of).

  • O split em transações com pré-autorização ("pre_authorized") só serão executados após captura.