Implementando split de pagamentos

Na Zoop, os clientes podem ter duas funções: comprador (usuários que podem ser debitados) e a função de vendedor (usuários que podem ser creditados).
Abordaremos todas as etapas necessárias para realização do split, permitindo que você simplifique sua contabilidade e crie modelos personalizados de negócios.

Quando é realizada uma venda no Marketplace em nome de um vendedor(seller) utilizando um cartão, um objeto de transação e seus recebíveis são criados. Cada um dos recebíveis da transação tem a parcela, montante total com impostos, valor líquido e destinatário, e o vendedor que será creditado por recebê-lo, sendo 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 absoluto a ser dividido, bem como se o recebimento por divisão for passível de devolução. Somente as transações com todos os recebíveis pendentes podem ser divididas, caso contrário não será possível realizar a divisão.

Para determinar quanto dinheiro um vendedor específico receberá, disponibilizamos um endpoint para consultar todos os recebíveis pendentes, essa é a maneira recomendada de conciliar a parte de uma determinada transação que foi paga ou a que está programada para o pagamento.

Split na mesma requisição (a priori)

Essa forma é utilizada para os clientes que transacionam no plano antecipado. Nesse plano, estabelecimentos comerciais recebem os valores na hora na sua conta Zoop(conta digital).

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

Split a posteriori

Essa é a forma tradicional que já existe e é preciso chamar quantas vezes seja necessário

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

curl --location --request POST 'https://api.zoop.ws/v1/marketplaces/{marketplace_id}/transactions/61b6dfe784754310b9cff3ede9257123/split_rules' \
--header 'Authorization: Basic enBrX3Rlc3RfVGJpSkMyc2FySmllalp1QWZTczU3R21234==' \
--header 'Content-Type: application/json' \
--data-raw '{
    "recipient": "043f03d427e148a6bbaca048379e4123",
    "liable": 1,
    "charge_processing_fee": 1,
    "percentage": 10
}'

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

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

curl --location --request POST 'https://api.zoop.ws/v1/marketplaces/{marketplace_id}/transactions/61b6dfe784754310b9cff3ede9257123/split_rules' \
--header 'Authorization: Basic enBrX3Rlc3RfVGJpSkMyc2FySmllalp1QWZTczU3R21234==' \
--header 'Content-Type: application/json' \
--data-raw '{
             [
              {
               "recipient": "043f03d427e148a6bbaca048379e4123",
               "liable": 1,
               "charge_processing_fee": 1,
               "percentage": 10
               },
               "recipient": "1318982b82564c6ea1691cf0f1f82123",
               "liable": 1,
               "charge_processing_fee": 1,
               "percentage": 20
               {
               }
             ]
}'

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 é 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, devem ser realizadas logo após o recebimento do evento "receivable.created", pois o pagamento do mesmo ocorre em D+1.

Não está disponível no momento em sandbox.

❗️

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 (on_behalf_of).

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