Mercado de pagamentos divididos

Esse recurso permite que os comerciantes dividam os pagamentos entre vários destinatários, o que é particularmente útil para modelos de marketplace em que as transações precisam ser divididas entre diferentes vendedores ou partes interessadas. Os comerciantes podem especificar como o pagamento é dividido, incluindo os valores, os destinatários e quaisquer taxas aplicáveis.

A funcionalidade de pagamento dividido depende do suporte do provedor de pagamento selecionado. A Yuno atua apenas como orquestradora do pagamento, não como processadora. Certifique-se de que seu provedor ofereça suporte a pagamentos divididos antes de usar essa funcionalidade.

Principais recursos

Os principais recursos do mercado de pagamentos divididos incluem:

• Dividir pagamentos: Defina como o valor total do pagamento é distribuído entre os diferentes destinatários.
• Configuração flexível: Oferece suporte a divisões com base absoluta.
• Integração com provedores: As divisões podem ser executadas por provedores de pagamento que suportam essa funcionalidade.
• Tratamento detalhado das taxas: O sistema permite o ajuste fino de como as taxas de transação e os estornos são gerenciados.
• Transferência de integração: Permite a transferência de registros de integração entre diferentes destinatários.

Para usar esse recurso, você deve primeiro integrar seus destinatários para a divisão de pagamento e , em seguida, criar o pagamento especificando as informações necessárias.

1. Integração

O modelo de integração da Yuno foi criado para ajudar os marketplaces a conectar e gerenciar perfeitamente seus submercados em vários provedores de pagamento. No centro desse sistema está o objeto destinatário, que representa cada submercante individual dentro do ecossistema do marketplace.

• Cada proprietário de marketplace é representado na Yuno como uma organização.
• Em uma organização, podem ser criadas uma ou mais contas, cada uma configurada com seu próprio conjunto de conexões com provedores de pagamento (por exemplo, Stripe, Adyen, dLocal).
• Para cada conta, o marketplace pode registrar um ou mais destinatários - esses são os submergentes a serem integrados.
• Cada destinatário é então vinculado individualmente a uma ou mais conexões, dependendo de quais processadores de pagamento serão usados.

Essa arquitetura permite:

• Um processo de integração único e unificado.
• Controle de status independente por provedor.
• Fácil dimensionamento de operações de submergentes entre provedores.

Esse design garante flexibilidade, transparência e rastreabilidade total durante todo o ciclo de vida da integração. O endpoint de destinatários é usado para criar e gerenciar cada perfil de submercado e para acionar os fluxos de trabalho de integração específicos do provedor correspondente.

Fluxos de integração

A Yuno oferece dois fluxos de integração para submergentes, proporcionando flexibilidade com base no status atual do submergente com os provedores de pagamento.

1. Contas pré-integradas: Se um submercante já tiver concluído o processo de integração com um provedor específico (por exemplo, por meio de um painel ou plataforma externa), o marketplace poderá fornecer o recipient_id durante a criação. Nesse cenário, não é necessária nenhuma outra integração, e o status será imediatamente definido como SUCCEEDED (onboardings.type=PREVIOUSLY_ONBOARDED).

2. Integração dinâmica: Se nenhuma credencial for fornecida, o Yuno iniciará o processo de integração do provedor escolhido (onboardings.type=ONE_STEP_ONBOARDING ou TWO_STEP_ONBOARDING). Esse processo pode incluir:

   1. Envio de formulário ou redirecionamento para uma página de integração hospedada.
   2. Carregamento de documentação legal ou financeira.
   3. Conclusão das etapas de validação do KYC/KYB.

Durante todo o ciclo de vida da integração, um destinatário pode experimentar vários status que refletem o estado atual do processo:

Esses status ajudam o marketplace a entender o ciclo de vida da integração e a implementar mecanismos apropriados de repetição, alerta ou fallback quando necessário.

Essa abordagem flexível permite que os marketplaces adaptem o processo de integração às suas necessidades operacionais, mantendo o controle e a visibilidade.

Fluxo de trabalho

O fluxo de trabalho de integração segue um processo estruturado que garante que os submercantes sejam devidamente integrados ao ecossistema do marketplace. O diagrama abaixo ilustra o fluxo completo, desde a configuração inicial até o processamento do pagamento.

Etapas do fluxo de trabalho:

1. Organização e configuração de conta: O proprietário do marketplace cria uma organização no Yuno e configura contas com conexões de provedores de pagamento.

2. Criação de destinatário: Para cada submercante, o marketplace cria um destinatário usando o endpoint da API Create Recipients, especificando um dos dois:

   • provider_recipient_id para submergentes pré-embarcados
   • Detalhes da conexão do provedor para nova integração

3. Execução da integração:

   • Pré-integrado: O status se torna imediatamente SUCCEEDED
   • Nova integração: A Yuno inicia o fluxo específico do provedor com a progressão de status de CREATED → PENDING → SUCCEEDED

4. Criação de pagamentos: Quando os destinatários forem integrados com sucesso (SUCCEEDED ), o marketplace pode criar pagamentos com o status split_marketplace objeto.

5. Processamento da divisão: O provedor de pagamento executa a divisão de acordo com a distribuição definida, transferindo fundos para a parte designada de cada destinatário.

2. Integração de divisão de pagamento

Nesta seção, exploramos como o split_marketplace é usado para dividir um objeto payment entre vários destinatários. Esse objeto é uma matriz em que cada entrada especifica um destinatário e sua parte correspondente do pagamento.

ℹ️

Nessa etapa, faça referência aos destinatários criados na Etapa 1 (Onboarding).

Para type = PURCHASE ou MARKETPLACEincluem o recipient_id desse destinatário.

Para PAYMENTFEE, VAT e COMMISSION, recipient_id é opcional.

{
  "split_marketplace": [
    {
      "provider_recipient_id": "recipient_123",
      "type": "PURCHASE",
      "amount": {
        "value": 750,
        "currency": "EUR"
      }
    },
    {
      "type": "COMMISSION",
      "amount": {
        "value": 30,
        "currency": "EUR"
      }
    }
  ]
}

{
  "split_marketplace": [
    {
      "recipient_id": "4b31a9b8-4cd2-4e47-93cf-03729241bd68",
      "type": "PURCHASE",
      "amount": {
        "value": 750,
        "currency": "EUR"
      }
    },
    {
      "recipient_id": "9104911d-5df9-429e-8488-ad41abea1a4b",
      "type": "COMMISSION",
      "amount": {
        "value": 30,
        "currency": "EUR"
      }
    }
  ]
}

3. Transferência de integração

O objetivo desse fluxo é permitir a transferência de embarques entre destinatários de forma controlada e reversível.

O processo tem várias etapas. Primeiro, o destinatário inicial é criado com sua integração (uma etapa anterior). Posteriormente, quando uma transferência for necessária, siga as etapas para criar o novo destinatário, usar o serviço de transferência e, se necessário, reverter a operação.

1. Destinatário e integração (antes de qualquer transferência): Crie o destinatário e, em seguida, crie a integração.

📘

Essa etapa acontece antecipadamente quando um novo destinatário é criado e sua integração é atribuída. Ela não faz parte da transferência em si.

Se você decidir transferir a integração para outro destinatário, continue o fluxo:

2. Crie o novo destinatário e a integração: Use os endpoints create recipient e create onboarding para configurar o destinatário e o onboarding que receberão a transferência.

3. Transfira a integração: Use a transferência de integração e inclua:

   • recipient_id: a ID do destinatário de destino
   • onboarding_id: a integração para transferência

   A integração será transferida para o novo destinatário.

4. Reverter a transferência (opcional): Uso integração reversa para reverter a transferência anterior, fornecendo o mesmo recipient_id e onboarding_id.

O onboarding inclui um objeto history elemento que armazena a rastreabilidade completa da integração. Esse histórico inclui não apenas atualizações no objeto, mas também eventos relacionados a transferências entre destinatários, garantindo a visibilidade total do ciclo de vida.

Validações

Nesta seção, descrevemos as validações necessárias para garantir o sucesso dos pagamentos divididos.

• O total de todas as divisões deve corresponder ao valor total do pagamento.
• Para cada divisão, um objeto deve ser enviado para cada participante, garantindo que a soma dos valores seja igual ao valor total do pagamento.
• Em cenários em que um ID de destinatário direto não é necessário para o proprietário do marketplace (por exemplo, com a Adyen), o type pode servir como um sinalizador (por exemplo, COMMISSION) para denotar a participação do proprietário do mercado, fazendo com que o provider_recipient_id opcional para essa divisão específica.
• Ou recipient_id ou provider_recipient_id deve ser incluído na divisão, mas não em ambas.
• Se algum campo obrigatório estiver faltando ou for inválido, a solicitação resultará em um erro.
• Se estiver usando vários provedores de pagamento para pagamentos divididos, recomendamos a utilização do objeto destinatários, pois ele permite definir mais de um provedor para cada destinatário.

endpoints de API envolvidos

Esta seção lista os endpoints da API envolvidos no gerenciamento de pagamentos divididos.

• Criar destinatários: POST: https://api-sandbox.y.uno/v1/recipients
• Criar integração: POST: https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings
• Continuar a integração: POST: https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings/{onboarding_id}/continue
• Criar o pagamento: POST: https://api-sandbox.y.uno/v1/payments
• Autorização de captura: POST: https://api-sandbox.y.uno/v1/payments/{id}/transactions/{transaction_id}/capture
• Pagamento de reembolso: POST: https://api-sandbox.y.uno/v1/payments/{id}/transactions/{transaction_id}/refund
• Cancelar ou reembolsar um pagamento: POST: https://api-sandbox.y.uno/v1/payments/{id}/cancel-or-refund
• Cancelar ou reembolsar um pagamento com a transação: POST: https://api-sandbox.y.uno/v1/payments/{id}/transactions/{transaction_id}/cancel-or-refund
• Integração de transferências: POST: https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings/{onboarding_id}/transfer
• Transferência reversa de onboarding: POST: https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings/{onboarding_id}/reverse-transfer