Como o split é um produto novo, precisamos fazer um setup inicial para garantir que o cliente que irá praticar o split é elegível para utiliza-lo;
A conta deve ter as seguintes configurações:
- Gateway Vindi Pagamentos;
- O id de sua conta deve ser adicionado no toggle
split_payment;
Para utilizar o split na recorrência precisamos cadastrar um Participante, este que receberá uma parte de um pagamento que for configurado com split e que for adicionado como participante da assinatura/fatura;
Para criar e gerenciar um participante utilize a API de participantes da plataforma;
Na api é necessário passar o seguinte dado:
- login => e-mail do participante (deve ser cadastrado na Vindi Pagamentos);
Importante: Para cadastrar um participante é necessário que seja informado seu e-mail, este e-email deve necessáriamente ser o mesmo e-mail da conta deste participante na vindi pagamentos; Um participante só sera ativo se tiver uma conta ativa e verificada no vindi pagamentos;
Para que seja possível adicionarmos um participante em uma transação é obrigatório que este participante tenha uma conta verificada (nivel 5) na vertical de pagamentos. Para garantirmos que consigamos transacionar nós fazemos uma verificação no momento que um participante é cadastrado.
Cada participante tem um status do cadastro, este status reflete em seu estado na vertical de pagamentos, podemos assim garantir que só vamos transacionar se este participante tem conta na Vindi Pagamentos. Importante: A verificação é realizada a partir do e-mail informado no ato do cadastro do participante
Ao cadastrar um participante o sistema de recorrência seu status fica como Aprovação Pendente (pending_approval), assim o sistema automáticamente vai verificar se este email tem uma conta cadastrada e verificada na vertical de pagamentos (estima-se que a verificação pode demorar por volta de 5 minutos).
Se esta conta existir e for verificeada na vertical de pagamentos, seu status será atualizado para Ativa (active), e este participante estará pronto para ser incluido em assinaturas e faturas.
Se esta conta não existir na vertical de pagamentos, seu status será atualizado para Bloqueado (blocked), assim não sendo possível transacionar.
Existe uma nova API onde é possível verificar se um participante tem uma conta ativa na vertical de pagamentos após ele já ter sido cadastrado e estar bloqueado.
Pensando no seguinte cenário:
- Foi cadastrado um participante;
- Quando a Vertical de Recorrência foi verificar este participante em pagamentos foi constatado que ele não tinha uma conta, ou a sua conta não estava verificada (nivel 5);
- Então, naturalmente, o status do participante foi alterado para
Bloqueado (blocked); - Tendo esta informação, o participante regularizou a situação de sua conta na vertical de pagamentos;
- Mesmo ele tendo atualizado sua conta, na vertical de Recorrência sua conta continua bloqueada;
Foi pensando neste cenário que foi desenvolvido o endpoint onde é possível re-verificar esta conta.
O endpoint é o PUT /api/v1/affiliates/<id>/verify.
Ao enviar uma requisição para este endpoint, vamos novamente verificar na vertical de pagamentos a conta deste participante, atualizando novamente seu status para Aprovação Pendente (pending_approval), e depois de verificado, para Ativa (active) se estiver ativa e verificada, ou voltar para Bloquado (blocked) se esta conta continuar não verificada.
- Só é possível abrir uma nova verificação para contas que estão BLOQUEADAS;
- Contas já ativas ou com aprovação pendente vão retornar um erro e não vão realizar nenhum processamento;
- A aprovação é verificada de forma ASSINCRONA, ou seja, o sistema irá realizar a verificação após dar a resposta para a chamada, sendo necessário verificar o participante após a chamada da verificação (que estima-se que pode demorar por volta de 5 minutos);
Para adicionar participantes em uma fatura avulsa podemos adicionar as seguintes informações na chamada da API de sua criação:
- affiliate_id => ID do participante préviamente cadastrado;
- amount_type => Aqui vamos dizer se o valor que este participante vai receber vai ser uma porcentagem do valor total da fatura, ou será um valor absoluto idependente do valor da fatura, os valores que podemos passar aqui são:
- percentage: Valor definido será uma porcentagem;
- amount: Valor definido será um valor absoluto;
- amount: Valor que será repassado para o participante, esse valor é um número, que representa o valor absoluto ou a porcentagem do repasse, dependendo do parâmetro passado no
amount_type;
Esses parâmetros devem ser passados em uma nova chave no corpo da API, exemplo:
{
"customer_id": 1234,
"payment_method_code": "credit_card",
"bill_items": [
{
"product_id": 4321,
"amount": 100
}
],
"bill_affiliates": [
{
"affiliate_id": 1,
"amount": 10,
"amount_type": "percentage"
}
]
}Neste exemplo estamos repassando um valor de 10% da fatura para o participante de id 1;
A chave de bill_affiliates recebe uma lista de participantes, podendo ser definidos mais de um participante para uma fatura;
Para adicionar participantes em uma assinatura podemos adicionar as seguintes informações na chamada da API de sua criação:
- affiliate_id => ID do participante préviamente cadastrado;
- amount_type => Aqui vamos dizer se o valor que este participante vai receber vai ser uma porcentagem do valor total da assinatura, ou será um valor absoluto idependente do valor da assinatura, os valores que podemos passar aqui são:
- percentage: Valor definido será uma porcentagem;
- amount: Valor definido será um valor absoluto;
- amount: Valor que será repassado para o participante, esse valor é um número, que representa o valor absoluto ou a porcentagem do repasse, dependendo do parâmetro passado no
amount_type;
Esses parâmetros devem ser passados em uma nova chave no corpo da API, exemplo:
{
"plan_id": 1234,
"customer_id": 321,
"payment_method_code": "credit_card",
"product_items": [
{
"product_id": 1
}
],
"subscription_affiliates": [
{
"affiliate_id": 1,
"amount_type": "amount",
"amount": 10
}
]
}
Neste exemplo estamos repassando um valor de R$ 10,00 de cada ciclo da assinatura para o participante de id 1;
A chave de subscription_affiliates recebe uma lista de participantes, podendo ser definidos mais de um participante para uma assinatura;