Pagamentos multidestino

Uma ordem de pagamento multidestino envia parte do pagamento para a sua carteira e o restante para a carteira de um dos seus parceiros. As duas transferências acontecem na mesma transação blockchain, então nenhum dos lados depende da liquidação do outro.

O parceiro não precisa ter conta na Bitpayway. Se o parceiro também for um negócio da Bitpayway, a carteira cadastrada nesse vínculo é usada apenas nas suas ordens multidestino e nunca altera a forma como aquele negócio recebe os próprios pagamentos.

As ordens tradicionais continuam iguais. Omitir paymentModel preserva o comportamento e o formato de resposta existentes.

Como o multidestino aparece na API

Na API, os pagamentos multidestino são chamados de split. Sempre que esse nome aparecer em um campo ou rota, ele se refere a esse recurso:

Onde aparece	O que é
paymentModel	Campo opcional do POST /api/order que define o tipo da ordem. Envie "split" para criar uma ordem multidestino; sem ele, a ordem é tradicional.
Objeto split	Dados da divisão da ordem: o parceiro e a parcela dele. É enviado ao criar a ordem e devolvido nas consultas e nos webhooks.
splitEnabled	Campo de cada token em GET /api/currency-token. true indica que o token aceita pagamentos multidestino.
Rotas /api/split/...	Rotas para cadastrar parceiros e carteiras multidestino, como POST /api/split/partners e PATCH /api/split/wallet. A lista completa está em Configurando pela API.

O que a versão atual suporta

Suportado	Não suportado
Um parceiro por ordem	Vários parceiros na mesma ordem
Divisão expressa em valor bruto	Divisão expressa em percentual na API
Pagamentos parciais e pagamentos excessivos	Alterar a divisão depois de criar a ordem

Se a sua interface oferecer um percentual, converta-o em valor bruto antes de criar a ordem.

Modelo das carteiras e responsabilidades

Os pagamentos tradicionais e multidestino usam cadastros de carteira independentes. Alterar uma carteira multidestino não muda o destino dos pagamentos tradicionais, e alterar uma carteira de recebimento tradicional não afeta os pagamentos multidestino.

Configuração	Escopo	Onde é gerenciada
Carteira multidestino do seu negócio	Um negócio e token/provedor; reutilizada com todos os parceiros	Painel do negócio ou API
Vínculo e carteira do parceiro	Uma combinação de negócio, parceiro e token	Somente API
Carteira de recebimento tradicional	Um negócio e token para pagamentos tradicionais	Painel do negócio

A carteira multidestino do seu negócio é definida por negócio e token/provedor. Você a cadastra uma vez para o token, e o registro a reutiliza com todos os parceiros do seu negócio no mesmo token. Adicionar um parceiro não exige outro cadastro da carteira do seu negócio. Alterar a carteira muda o destino da parcela do seu negócio nos pagamentos multidestino futuros com qualquer parceiro naquele token.

A carteira de parceiro possui um escopo propositalmente mais restrito: pertence a uma combinação de negócio, parceiro e token. Se o mesmo parceiro trabalhar com outro negócio, esse outro vínculo terá sua própria configuração. Os vínculos e as carteiras dos parceiros só podem ser criados, alterados, ativados ou desativados pela API.

As duas carteiras e o vínculo precisam estar válidos mesmo quando uma parcela é zero. Nenhuma carteira de destino pode ser a pagadora da transação de pagamento nem o próprio contrato do provedor; o seu negócio e o parceiro podem usar o mesmo endereço de destino.

Configure os pagamentos multidestino antes da primeira ordem

Conclua estas três etapas para cada token que você pretende aceitar:

1. selecione um token compatível com pagamentos multidestino;
2. cadastre e habilite a carteira multidestino do seu negócio para aquele token; e
3. crie o vínculo do parceiro e cadastre a carteira dele.

As carteiras do seu negócio e do parceiro precisam estar registradas on-chain antes da criação de uma ordem que use aquela combinação de negócio, parceiro e token.

1. Selecione um token compatível com pagamentos multidestino

O painel exibe um cartão de carteira para pagamentos multidestino somente quando o token possui um provedor multidestino habilitado. Uma integração de servidor pode consultar a mesma disponibilidade em GET /api/currency-token: use um token cujo campo splitEnabled seja true e guarde seu contractId como o tokenContractId usado nas rotas de carteira.

A configuração é independente para cada token. Repita as etapas seguintes para USDT, USDC ou qualquer outro token que deseja usar. Se um provedor passar a usar um novo registro de carteiras, cadastre as carteiras do seu negócio e do parceiro também nesse novo registro.

2. Cadastre pelo painel a carteira multidestino do seu negócio para o token

Abra a página Configuração do negócio e encontre Carteiras de recebimento do split. No cartão do token selecionado:

1. informe a carteira que receberá a parcela do seu negócio;
2. conecte uma carteira do navegador;
3. selecione Atualizar carteira de split e aprove a transação; e
4. aguarde até o cartão indicar Habilitada. Use Verificar status para atualizar o estado.

Isso fará com que a carteira seja salva na blockchain.

A carteira informada não precisa ser igual à carteira conectada que você esteja usando para fazer essa operação.

Você pode integrar com a sua aplicação para realizar esta operação utilizando PATCH /api/split/wallet.

3. Crie o parceiro e cadastre sua carteira pela API

O gerenciamento de parceiros ocorre no servidor e exige Authorization: ApiKey <sua-api-key>. Primeiro, crie o vínculo com POST /api/split/partners:

{
  "name": "Parceiro do marketplace",
  "external_id": "vendedor-marketplace-42"
}

external_id é opcional e aceita de 1 a 255 caracteres. Quando informado, é único entre os parceiros do seu negócio. Reutilizá-lo no mesmo negócio retorna 409; outro negócio pode usar o mesmo valor. Um parceiro criado sem esse campo retorna "external_id": null.

Use o id retornado do parceiro para salvar e autorizar sua carteira no token selecionado com PATCH /api/split/partners/{partnerId}/wallet. Repita o cadastro da carteira do parceiro para cada token que ele utilizará.

Definir o vínculo como active:false e enviar sua autorização bloqueia novas ordens e pagamentos multidestino que usem o vínculo. A reativação exige outra autorização. Alterar qualquer uma das carteiras afeta pagamentos futuros, inclusive pagamentos de ordens que já existem.

Autorização e estado on-chain

Toda alteração de carteira possui dois estados: a configuração salva pela Bitpayway e o estado atualmente registrado on-chain. Aplicar uma alteração exige salvar a carteira desejada e enviar a transação autorizada ao registro.

O painel automatiza as duas ações para a carteira multidestino do seu negócio naquele token depois que o usuário aprova a transação na carteira do navegador. Ao usar a API — para o seu negócio ou para um parceiro — sua integração ou relayer deve enviar a autorização retornada. A chamada da API sozinha não gasta gas nem envia a transação.

A resposta do PATCH da carteira contém tudo o que é necessário para enviar a transação: network, walletRegisterAddress, a abi do registro, a functionName a chamar e seus args já na ordem da chamada.

functionName é o nome do método do contrato de registro de carteiras que você deve chamar; ele está na abi retornada. Chame esse método no walletRegisterAddress, na rede indicada em network.chainId, passando os args. O valor é setClientWalletWithAuth para a carteira multidestino do seu negócio naquele token e setSplitWalletWithAuth para a carteira e o estado ativo de um parceiro; use o valor retornado, sem precisar escolhê-lo.

Os signatureParams assinados continuam disponíveis caso você prefira montar a chamada por conta própria, e expiresAt é a forma ISO 8601 de signatureParams.deadline.

A conta que envia a transação funciona apenas como relayer. Ela paga o gas, mas não precisa ser igual a nenhuma das carteiras de recebimento. A assinatura impede que ela altere o negócio, token, destino, estado do parceiro ou prazo.

Uma autorização expira depois de dez minutos e só pode ser consumida uma vez. Se ela expirar, for rejeitada ou usar um nonce já consumido, solicite outra em vez de reenviá-la. Até a confirmação da transação, a configuração salva e o estado on-chain serão diferentes, e isEnabled permanecerá false.

A resposta de status separa esses estados: configured é o valor salvo, enquanto wallet e active são lidos da blockchain. isEnabled:true significa que eles coincidem. Em uma desativação confirmada de parceiro, ele pode portanto ser true enquanto active é false; o vínculo ainda assim não pode receber novos pagamentos multidestino.

Configurando pela API

Uma integração de servidor pode configurar a carteira do seu negócio como alternativa ao painel e deve ser usada para toda configuração de parceiros. Envie Authorization: ApiKey <sua-api-key>. A chave identifica o negócio, por isso estas rotas não recebem um ID do negócio:

Operação	Rota
Descobrir tokens	GET /api/currency-token
Listar parceiros	GET /api/split/partners
Criar um parceiro	POST /api/split/partners
Salvar sua carteira e obter uma autorização	PATCH /api/split/wallet
Salvar a carteira de um parceiro e obter uma autorização	PATCH /api/split/partners/{partnerId}/wallet
Reemitir a autorização da sua carteira	POST /api/split/wallet/authorization
Reemitir a autorização da carteira de um parceiro	POST /api/split/partners/{partnerId}/wallet/authorization
Consultar o registro da sua carteira	GET /api/split/wallet/status
Consultar o registro da carteira de um parceiro	GET /api/split/partners/{partnerId}/wallet/status

GET /api/split/partners aceita os filtros opcionais por correspondência exata id (o UUID público do parceiro) e external_id. Os filtros podem ser combinados e nunca retornam parceiros de outro negócio. Por exemplo:

GET /api/split/partners?external_id=vendedor-marketplace-42
GET /api/split/partners?id=9f1c2d64-5717-4562-b3fc-2c963f66afa6

Use o contractId de um token cujo campo splitEnabled seja true como tokenContractId. As requisições de carteira usam o corpo abaixo:

{
  "tokenContractId": "28a555aa-d6bb-4a0b-9266-0b6668f824b5",
  "wallet": "0x1111111111111111111111111111111111111111",
  "active": true
}

active se aplica aos vínculos de parceiro e assume true por padrão. Omita-o ao configurar a carteira multidestino do seu negócio para o token, que não pode ser desativada.

A resposta do PATCH retorna o endereço do registro, a ABI e os parâmetros assinados para a configuração salva. Sua integração ou relayer deve enviar essa autorização ao registro antes que ela expire e então consultar a rota de status até que isEnabled seja true. Se a autorização expirar ou a transação não for enviada, envie tokenContractId à rota de autorização para reemiti-la. A API não gasta gas nem envia a transação blockchain por você.

Para exemplos prontos em ethers, consulte a referência técnica opcional Enviando autorizações de carteira.

Criando uma ordem

Acrescente paymentModel e split à requisição existente de POST /api/order:

{
  "requestId": "2f3c9d2c-1b75-4e9d-9b2f-67d0a9c3c7d1",
  "description": "Pedido #1234",
  "amount": "1000",
  "network": "sepolia",
  "token": "USDC",
  "paymentModel": "split",
  "split": {
    "partnerId": "9f1c2d64-5717-4562-b3fc-2c963f66afa6",
    "partnerAmount": "300"
  }
}

• partnerId é o UUID retornado por POST /api/split/partners.
• partnerAmount é a parcela bruta do parceiro, antes da comissão da plataforma. É uma string decimal na unidade de exibição do token, entre zero e amount, com no máximo a quantidade de decimais que o token suporta.
• amount precisa ser maior que zero.

A ordem fixa o provedor, o parceiro e a divisão no momento da criação. Reutilize o mesmo requestId para repetir a mesma criação com segurança; a ordem existente é retornada. Um 409 indica que aquele requestId já foi usado com dados diferentes.

Consultando uma ordem

As ordens multidestino trazem os campos adicionais abaixo em GET /api/order, GET /api/order/request/{requestId} e nos webhooks:

Campo	Significado
paymentModel	split nas ordens multidestino; ausente nas tradicionais.
split.partnerId	UUID do vínculo do parceiro.
split.partnerCodeId	Identificador on-chain do vínculo do parceiro.
split.partnerAmount	Parcela bruta acordada na criação da ordem.
settlementStatus	pending, matched ou mismatch.
settlementVersion	Aumenta sempre que os valores confirmados mudam.

Os valores são strings decimais no token da ordem:

Campo	Significado
paidAmount	Valor bruto confirmado da ordem.
netAmount	Valor efetivamente recebido por você.
partnerNetAmount	Valor efetivamente recebido pelo parceiro.
partnerGrossAmount	Valor bruto acumulado destinado ao parceiro.
fee	Comissão nominal total da plataforma.
clientCommission	Comissão nominal sobre a sua parcela.
partnerCommission	Comissão nominal sobre a parcela do parceiro.
commissionReceived	Valor efetivamente recebido pela plataforma.

{
  "order": {
    "id": "7f7f5a2a-5c4f-4c6b-9cbb-1f0f4b4e42f2",
    "date": "2026-02-12T18:12:43.384Z",
    "requestId": "2f3c9d2c-1b75-4e9d-9b2f-67d0a9c3c7d1",
    "clientId": "12345",
    "orderId": "42",
    "description": "Pedido #1234",
    "amount": "1000",
    "status": "partial paid",
    "gatewayUrl": "https://pay.example.com/?id=7f7f5a2a-5c4f-4c6b-9cbb-1f0f4b4e42f2",
    "paymentModel": "split",
    "settlementStatus": "pending",
    "settlementVersion": 1,
    "split": {
      "partnerId": "9f1c2d64-5717-4562-b3fc-2c963f66afa6",
      "partnerCodeId": "7",
      "partnerAmount": "300"
    },
    "paidAmount": "500",
    "netAmount": "346.5",
    "partnerNetAmount": "148.5",
    "partnerGrossAmount": "150",
    "fee": "5",
    "clientCommission": "3.5",
    "partnerCommission": "1.5",
    "commissionReceived": "5"
  }
}

Use netAmount e partnerNetAmount como os valores efetivamente recebidos, em vez de reconstruí-los a partir do bruto menos a comissão.

As estatísticas do seu negócio contam apenas a sua parcela. Somar a sua parcela à do parceiro não produz a sua receita líquida.

Comissão e pagamentos parciais

A comissão da plataforma é aplicada a cada contribuição e dividida entre você e o parceiro conforme a parcela de cada um. Um pagamento parcial é dividido na mesma proporção da ordem completa. Veja como o cálculo funciona, com exemplo, em Taxas.

Dois pagamentos cotados sobre o mesmo acumulado confirmado podem divergir por arredondamento e exigir conciliação.

Confirmação e divergência

Um receipt de transação bem-sucedido não é uma ordem aprovada. A Bitpayway finaliza um pagamento multidestino somente depois de doze confirmações de bloco. Enquanto isso, um pagamento que completa a ordem com a divisão acordada deixa a ordem em paid waiting confirmations, e um pagamento parcial mantém o status. A ordem aceita pagamentos por 30 minutos depois de criada.

Os contratos permitem que o pagador escolha a divisão enviada. A Bitpayway detecta uma divisão divergente da acordada depois que as transferências já ocorreram e não aprova esse pagamento automaticamente. As transferências on-chain não podem ser revertidas pela plataforma.

É isso que o settlementStatus informa:

• pending: não há divergência confirmada e a ordem ainda pode estar liquidando.
• matched: os valores confirmados seguem a divisão acordada.
• mismatch: os valores confirmados divergem e a ordem exige conciliação com o parceiro.

O settlement é uma dimensão financeira e não substitui o status comercial. Uma ordem já aprovada permanece paid se um pagamento posterior trouxer uma divisão divergente; ela é marcada como mismatch, e seus totais e o settlementVersion são atualizados. Uma ordem cancelada permanece cancelada mesmo que recursos cheguem depois.

Webhooks

Uma ordem multidestino envia os campos acima dentro da notificação de webhook existente, verificada com a mesma assinatura HMAC. Duas diferenças importam nas ordens multidestino:

• Uma mudança de settlement pode gerar um webhook depois de um status terminal, então uma ordem pode ser notificada mais de uma vez.
• O settlementVersion identifica a versão dos valores. Uma resposta a uma notificação antiga não confirma a entrega de uma mais recente.

Trate notificações repetidas de forma idempotente e não repita a entrega comercial a cada atualização financeira. Consulte o guia de webhook para o formato da requisição e a verificação da assinatura.