API de gestão do split recorrente

A API da Vindi Recorrência permite que a conta master faça a gestão dos participantes de assinaturas que tenham comissionamento. Veremos abaixo as variáveis mais importantes para a inclusão de usuários na lista de participantes e posteriormente, nas assinaturas e/ou faturas.

API de solicitação de verificação de um participante

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 (nível 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 essa conta continuar não verificada.

Validações da API de verificação de participante

• 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 ASSÍNCRONA, 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 se estima que pode demorar por volta de 5 minutos);

Assinatura

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 previamente 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 independente 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;

Fatura avulsa

Além de assinaturas, é possível incluir participantes também em faturas avulsas.

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 previamente 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 independente 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.

📚 Veja também:

• O que é split de pagamento?
• O que é split na recorrência?
• Requisitos e configurações do split recorrente
• Gestão do split de assinaturas no painel Vindi Recorrência
• Índice da Base de conhecimento Vindi Recorrência