MarketplaceRecebedores

Recebedores são pessoas físicas ou jurídicas que recebem uma parte do pagamento via split. Pense num marketplace: o comprador paga R$ 100, R$ 30 vai pro vendedor A, R$ 20 pro vendedor B e o restante fica com você.

Fluxo completo

1. Você cadastra o recebedor via API          →  status: draft
2. Nossa equipe aprova e envia                →  status: active
3. Você usa o ID nos pagamentos               →  split automático
4. PIX liquida em D0, cartão em D+30         →  saldo disponível
5. Recebedor solicita transferência           →  status: pending
6. Administrador aprova e realiza o TED/PIX  →  status: approved
7. Webhook dispara para o seu domínio        →  você é notificado

Cadastrar recebedor

POST https://isolutionpay.com/api/sub-recipients

Autenticação via header token (mesma API Key das cobranças).

Pessoa Física

curl -X POST https://isolutionpay.com/api/sub-recipients \
  -H "Content-Type: application/json" \
  -H "token: isolutionpay_sk_SUA_CHAVE_AQUI" \
  -d '{
    "register_information": {
      "type": "individual",
      "document_number": "123.456.789-09",
      "name": "João da Silva",
      "birthdate": "15/03/1990",
      "mother_name": "Maria da Silva",
      "email": "joao@email.com",
      "monthly_income": 500000,
      "address": {
        "street": "Rua das Flores",
        "number": "123",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "state": "SP",
        "zip_code": "01310100"
      },
      "phone_numbers": [
        { "ddd": "11", "number": "987654321" }
      ]
    },
    "bank_account": {
      "bank_code": "341",
      "agencia": "0001",
      "conta": "12345",
      "conta_dv": "6",
      "type": "conta_corrente",
      "document_number": "123.456.789-09",
      "legal_name": "João da Silva"
    }
  }'

Pessoa Jurídica

curl -X POST https://isolutionpay.com/api/sub-recipients \
  -H "Content-Type: application/json" \
  -H "token: isolutionpay_sk_SUA_CHAVE_AQUI" \
  -d '{
    "register_information": {
      "type": "corporation",
      "document_number": "11.222.333/0001-81",
      "company_name": "Empresa Ltda",
      "annual_revenue": 12000000,
      "email": "contato@empresa.com",
      "address": {
        "street": "Av. Paulista",
        "number": "1000",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "zip_code": "01310100"
      },
      "phone_numbers": [
        { "ddd": "11", "number": "33334444" }
      ],
      "managing_partners": [
        {
          "name": "Sócio Nome",
          "document_number": "123.456.789-09",
          "birthdate": "10/01/1985",
          "mother_name": "Mãe do Sócio",
          "email": "socio@empresa.com",
          "phone_numbers": [{ "ddd": "11", "number": "999999999" }],
          "address": {
            "street": "Rua do Sócio",
            "street_number": "50",
            "neighborhood": "Jardins",
            "city": "São Paulo",
            "state": "SP",
            "zipcode": "01452001"
          }
        }
      ]
    },
    "bank_account": {
      "bank_code": "033",
      "agencia": "1234",
      "conta": "56789",
      "conta_dv": "0",
      "type": "conta_corrente",
      "document_number": "11.222.333/0001-81",
      "legal_name": "Empresa Ltda"
    }
  }'

Campos obrigatórios

register_information

CampoPFPJDescrição
type✅✅"individual" (PF) ou "corporation" (PJ)
document_number✅✅CPF (PF) ou CNPJ (PJ), com ou sem pontuação
name✅—Nome completo
birthdate✅—Data de nascimento em DD/MM/YYYY
mother_name✅—Nome da mãe
company_name—✅Razão social
address.*✅✅street, number, neighborhood, city, state, zip_code
phone_numbers[0]✅✅Objeto com ddd e number
managing_partners[0]—✅Sócio administrador (campos iguais ao PF)
email❌❌E-mail de contato
monthly_income❌—Renda mensal em centavos
annual_revenue—❌Faturamento anual em centavos

bank_account

CampoObrigatórioDescrição
bank_code✅Código do banco com 3 dígitos (ex: "341" = Itaú)
agencia✅Número da agência
conta✅Número da conta
conta_dv❌Dígito verificador da conta
agencia_dv❌Dígito verificador da agência
type❌"conta_corrente" (padrão) ou "conta_poupanca"
legal_name❌Nome do titular da conta
document_number❌CPF/CNPJ do titular (usa o do register_information se omitido)

Resposta do cadastro

{
  "id": "3f2e1d0c-...",
  "status": "draft",
  "document_type": "CPF",
  "document": "***.456.789-**",
  "name": "João da Silva",
  "created_at": "2025-01-15T10:30:00.000Z"
}
CampoDescrição
idID do recebedor. Salve — você vai usar no campo splits
statusComeça como draft, vira active após aprovação
documentDocumento mascarado (nunca exposto completo)

A chamada é idempotente: enviar o mesmo CPF/CNPJ duas vezes retorna o registro existente com "already_exists": true.

Ciclo de vida do status

StatusSignificado
draftCadastrado, aguardando envio para a adquirente
pendingEnviado para análise da adquirente
activeAprovado — pode receber split
rejectedRecusado — verifique os dados e recadastre

Listar recebedores

GET https://isolutionpay.com/api/dashboard/sub-recipients?search=nome&page=1

Aceita ?search=nome e ?page=1 para filtrar e paginar.

Extrato e saldo do recebedor

GET https://isolutionpay.com/api/dashboard/sub-recipients/{id}/splits

Retorna o extrato de splits do recebedor com saldos consolidados.

curl https://isolutionpay.com/api/dashboard/sub-recipients/3f2e1d0c-.../splits \
  -H "token: isolutionpay_sk_SUA_CHAVE_AQUI"

Resposta:

{
  "items": [
    {
      "id": "split-uuid",
      "payment_id": "payment-uuid",
      "amount_cents": 4000,
      "status": "available",
      "paid_at": null,
      "created_at": "2025-01-15T10:30:00.000Z",
      "payment": {
        "nome": "Maria Souza",
        "cpf": "987.654.321-00",
        "gross_amount": 10000,
        "payment_method": "pix",
        "balance_available_at": null
      }
    }
  ],
  "total": 1,
  "page": 1,
  "pages": 1,
  "balance": {
    "available": 4000,
    "pending": 0,
    "paid": 0
  }
}

Status do split

StatusSignificado
pendingAguardando liquidação (cartão D+30 ou PIX não confirmado)
availableDisponível para saque
paidTransferido — saque aprovado pelo administrador

Solicitar saque

Quando o saldo do recebedor tiver splits com status available, você pode solicitar a transferência. O administrador ISolutionPay revisa e executa o TED/PIX para a conta bancária cadastrada.

POST https://isolutionpay.com/api/dashboard/sub-recipients/{id}/withdraw

Não há body — a requisição consolida automaticamente todos os splits available do recebedor.

curl -X POST https://isolutionpay.com/api/dashboard/sub-recipients/3f2e1d0c-.../withdraw \
  -H "token: isolutionpay_sk_SUA_CHAVE_AQUI"

Resposta:

{
  "success": true,
  "withdrawal_id": "w-uuid-...",
  "amount_cents": 4000,
  "status": "pending"
}

Só é possível ter um saque pendente por recebedor ao mesmo tempo. Uma nova solicitação só pode ser feita após o saque atual ser aprovado ou recusado.

Histórico de saques

GET https://isolutionpay.com/api/dashboard/sub-recipients/{id}/withdraw
{
  "items": [
    {
      "id": "w-uuid-...",
      "amount_cents": 4000,
      "status": "approved",
      "created_at": "2025-01-15T10:30:00.000Z",
      "approved_at": "2025-01-16T09:00:00.000Z",
      "notes": null
    }
  ]
}
StatusSignificado
pendingAguardando aprovação do administrador
approvedAprovado — TED/PIX enviado para a conta do recebedor
rejectedRecusado — consulte notes para o motivo

Antecipação de recebíveis (cartão)

Pagamentos via cartão só ficam disponíveis após D+30. Para receber antes, use a antecipação com desconto de taxa.

Consultar recebíveis antecipáveis

GET https://isolutionpay.com/api/dashboard/sub-recipients/{id}/anticipate
curl https://isolutionpay.com/api/dashboard/sub-recipients/3f2e1d0c-.../anticipate \
  -H "token: isolutionpay_sk_SUA_CHAVE_AQUI"

Resposta:

{
  "items": [
    {
      "id": "split-uuid",
      "amount_cents": 2500,
      "payment_method": "credit_card",
      "balance_available_at": "2025-02-14T00:00:00.000Z",
      "payment_nome": "Carlos Lima",
      "fees": {
        "d2":  { "target_days": 2,  "rate_percent": 2.38, "fee_cents": 60,  "net_cents": 2440 },
        "d7":  { "target_days": 7,  "rate_percent": 2.0,  "fee_cents": 50,  "net_cents": 2450 },
        "d15": { "target_days": 15, "rate_percent": 1.5,  "fee_cents": 38,  "net_cents": 2462 }
      }
    }
  ],
  "rates": { "d2": 2.38, "d7": 2.0, "d15": 1.5 }
}

Antecipar

POST https://isolutionpay.com/api/dashboard/sub-recipients/{id}/anticipate
curl -X POST https://isolutionpay.com/api/dashboard/sub-recipients/3f2e1d0c-.../anticipate \
  -H "Content-Type: application/json" \
  -H "token: isolutionpay_sk_SUA_CHAVE_AQUI" \
  -d '{
    "split_ids": ["split-uuid-1", "split-uuid-2"],
    "target_days": 7
  }'
CampoObrigatórioDescrição
split_ids✅Array de IDs de splits a antecipar
target_days✅2, 7 ou 15 — prazo de antecipação

Resposta:

{
  "success": true,
  "anticipated_count": 2,
  "original_cents": 5000,
  "fee_cents": 100,
  "net_cents": 4900,
  "target_days": 7,
  "rate_percent": 2.0
}

Após a antecipação, os splits passam para status available com o valor já descontado da taxa. O saldo disponível para saque é atualizado imediatamente.

Webhooks de recebedor

A ISolutionPay dispara eventos para a URL configurada na sua API Key sempre que o status de um recebedor ou saque muda.

Recebedor aprovado

{
  "event": "recipient.approved",
  "recipient": {
    "id": "3f2e1d0c-...",
    "status": "active",
    "name": "João da Silva",
    "document_type": "CPF"
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Recebedor recusado

{
  "event": "recipient.rejected",
  "recipient": {
    "id": "3f2e1d0c-...",
    "status": "rejected",
    "name": "João da Silva",
    "document_type": "CPF"
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Saque aprovado

{
  "event": "withdrawal.approved",
  "withdrawal": {
    "id": "w-uuid-...",
    "sub_recipient_id": "3f2e1d0c-...",
    "amount_cents": 4000,
    "status": "approved",
    "notes": null
  },
  "timestamp": "2025-01-16T09:00:00.000Z"
}

Saque recusado

{
  "event": "withdrawal.rejected",
  "withdrawal": {
    "id": "w-uuid-...",
    "sub_recipient_id": "3f2e1d0c-...",
    "amount_cents": 4000,
    "status": "rejected",
    "notes": "Dados bancários divergentes. Verifique a conta cadastrada."
  },
  "timestamp": "2025-01-16T09:00:00.000Z"
}

Todos os webhooks chegam com o header Authorization: csw_... (seu Webhook Secret) e X-Webhook-Event com o nome do evento.

Pagamento com CartãoSplit de Pagamentos