Guides
  1. AUTENTICAÇÃO

Coprodutores e Split

O split permite dividir o valor de uma cobrança entre múltiplos recebedores (produtor, coprodutor, afiliado) no momento do pagamento.

O problema do split gateway-específico

A maioria das integrações faz isso:

"split": [
  { "type": "percentage", "amount": 92, "recipient_id": "re_abc123" }
]

O problema: re_abc123 é um ID válido somente no Pagar.me. Se o gateway principal falhar e o fallback assumir (ex: Asaas), esse ID não existe lá — o split quebra silenciosamente.

A solução: coprodutores cadastrados

Cadastre cada coprodutor uma vez com os IDs de recebedor em cada gateway. O Toktus API resolve automaticamente o ID correto para qualquer gateway, incluindo o fallback.

Pagar.me falha → Asaas assume → sistema usa o ID do Asaas do coprodutor, sem intervenção manual

Configuração (3 passos)

Passo 1 — Criar o coprodutor

curl -X POST https://api.toktus.com/api/v1/coproducers \
  -H "x-api-key: tk_SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "email": "[email protected]"
  }'

Resposta:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Maria Souza",
    "email": "[email protected]",
    "isActive": true,
    "recipients": []
  }
}

[!NOTE]
Guarde o id retornado — você vai usá-lo no campo split[].coproducerId das cobranças.

Passo 2 — Adicionar o ID de recebedor por gateway

Repita para cada gateway que você usa (incluindo os de fallback):

Passo 3 — Usar nas cobranças

Referencie pelo e-mail ou UUID do coprodutor:

Por e-mail (mais legível)

    {
      "gateway": "pagarme",
      "paymentMethod": "pix",
      "amount": 10000,
      "customer": { "name": "João", "email": "[email protected]", "document": "12345678900" },
      "pix": { "expiresInSeconds": 3600 },
      "split": [
        {
          "type": "percentage",
          "amount": 8,
          "coproducerEmail": "[email protected]",
          "options": { "liable": true, "charge_processing_fee": true, "charge_remainder_fee": true }
        },
        {
          "type": "percentage",
          "amount": 92,
          "coproducerEmail": "[email protected]",
          "options": { "liable": true, "charge_processing_fee": false, "charge_remainder_fee": false }
        }
      ]
    }
    ```

## Por UUID (mais preciso)

```json
    {
      "gateway": "pagarme",
      "paymentMethod": "pix",
      "amount": 10000,
      "split": [
        {
          "type": "percentage",
          "amount": 8,
          "coproducerId": "550e8400-e29b-41d4-a716-446655440000"
        },
        {
          "type": "percentage",
          "amount": 92,
          "coproducerId": "661f9511-f30c-52e5-b827-557766551111"
        }
      ]
    }
    ```

## ID direto (sem fallback)

```json
{
  "gateway": "pagarme",
  "paymentMethod": "pix",
  "amount": 10000,
  "split": [
    {
      "type": "percentage",
      "amount": 92,
      "recipientId": "re_cmk4nadrmhbn70l9t8z2pbcz5"
    }
  ]
}

[!WARNING]
O recipientId direto é gateway-específico. Se o fallback for acionado, o split falhará pois esse ID não existe no gateway alternativo.

Regras do split

  • Tipo percentage — A soma dos amount deve ser exatamente 100. Cada item representa a porcentagem do recebedor.
  • Tipo flat — Valor fixo em centavos. A soma não precisa ser 100 — o restante vai para o recebedor principal.

Campo options (Pagar.me)

CampoDescrição
liableRecebedor responsável em caso de chargeback
charge_processing_feeRecebedor arca com a taxa de processamento
charge_remainder_feeRecebedor arca com o restante das taxas

Configuração padrão (plataforma):

  • Recebedor principal: liable: true, charge_processing_fee: true, charge_remainder_fee: true
  • Demais recebedores: liable: false, todos os charge_*: false

Gerenciar coprodutores

Listar todos

curl https://api.toktus.com/api/v1/coproducers \
  -H "x-api-key: tk_SUA_API_KEY"

Atualizar dados

curl -X PATCH https://api.toktus.com/api/v1/coproducers/{id} \
  -H "x-api-key: tk_SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Maria A. Souza", "isActive": false }'

Remover ID de recebedor de um gateway

curl -X DELETE https://api.toktus.com/api/v1/coproducers/{id}/recipients/pagarme \
  -H "x-api-key: tk_SUA_API_KEY"

Próximos Passos

Updated about 2 hours ago