Fast Connect

O FastConnect é um módulo da FastPay que possibilita a criação de marketplaces. Ele permite que determinados usuários (MerchantMaster), liberados pelo administrador FastPay, possam criar e gerenciar SubMerchants (subcontas vinculadas) com controle de taxas, permissões, acessos e rastreabilidade nas transações.

Onboarding

Entre em contato com nossa equipe para obter a liberação e a instalação do módulo em sua plataforma.

Criação dos SubMerchants

Com o módulo ativo, utilize o endpoint /v1/submerchants para criar suas subcontas vinculadas. Informe o campo postbackUrl no momento do cadastro, para ser notificado assim que uma subconta tiver o status alterado no processo de credenciamento. Exemplo de notificação:

{
  "merchantId": "2vorkDcXyvzifL63YX09S9VqcnI",
  "status": "active",
  // Os possíveis status são: `pending`, `pre_approved`, `active`, `correcting`, `rejected`, `blocked` ou `inactive`.
  "date": "2026-01-13T12:39:48Z"
}

Credenciamento

Após criação do SubMerchant, é necessário passar pelo processo de KYC. Para isso, utilize o endpoint /v1/submerchants/{id}/document para fazer o upload dos documentos necessários para aprovação.

O upload direto acima vincula os documentos de pessoa sempre ao representante legal (principal). Se a empresa tem sócios adicionais, os documentos de cada sócio são enviados pelo fluxo com token — veja Sócios adicionais e documentos por sócio abaixo.

Todo submerchant herda taxas, permissões e configurações do MerchantMaster no momento da criação. Uma vez aprovado, o SubMerchant está apto a realizar transações.

Sócios adicionais e documentos por sócio

Empresas com mais de um sócio podem ser cadastradas com todos os sócios de uma vez: além do legalRepresentative (obrigatório, sempre o representante legal), envie o array opcional additionalRepresentatives na criação da subconta — cada item com o mesmo formato do representante. A resposta da criação retorna legalRepresentatives[] (o principal primeiro, com isPrimary: true). Guarde os id — são eles que vinculam os documentos de cada sócio. Fluxo de documentos por sócio:

Emita um token de upload para o sócio

POST /v1/submerchants/{merchantId}/document/upload-token com { "legalRepresentativeId": "<id do sócio>" }. Sem o campo, os documentos vinculam ao representante legal.

Envie os documentos com o token

POST /v1/document-uploads (Bearer = token, multipart com o fieldname = nome do documento: responsible_document_front, responsible_document_back, selfie_with_document). Reenviar substitui apenas o documento daquele sócio.

Consulte sócios e documentos

GET /v1/submerchants/{merchantId}/legal-representatives?include=documents — retorna cada sócio com idFront/idBack/selfie e o status de análise. As URLs são assinadas e expiram em 1 hora.

Documentos de empresa (cnpj_card, social_contract, irs_letter) não usam o vínculo por sócio — continuam valendo para a subconta como um todo.

Split de Pagamentos

Cobra uma taxa própria sobre as vendas das subcontas? O percentual de split não é o mesmo que você cobra — a Fastpay aplica o split sobre o valor líquido (após as taxas dela). Veja como calcular o percentual correto, com calculadora interativa, em Cálculo de split com taxa do subadquirente.

Configuração e Participantes

Com a estrutura de MerchantMaster e SubMerchants pronta, será possível utilizar o Split de Pagamentos. A configuração dos participantes pode ser feita de duas formas, e deve seguir as regras informadas.

A soma dos percentuais não deve exceder 100%.
Caso o split tenha menos de 100%, o valor restante permanecerá com o originador da transação.
Todas as contas participantes devem pertencer ao mesmo Connect.

Cenários de relacionamentos permitidos

Originador	Recebedor
MerchantMaster	SubMerchant
SubMerchant	MerchantMaster
SubMerchant	SubMerchant (dentro do mesmo Connect)

Para vincular transações aos respectivos originadores, a autenticação deve ser feita utilizando as credenciais do SubMerchant originador. Utilize o endpoint v1/submerchants/{id}/api-keys para obter as chaves de API.

1. Via Painel

No painel da FastPay, navegue até: FastConnect > Gestão de Subcontas > Configurar Split Informe os participantes e o percentual de split destinado para cada um em cada transação gerada pela conta. Os valores configurados serão definidos como padrão do merchant, e todas as transações originadas por ele no futuro seguirão a regra de split definida. É possível configurar participantes e porcentagens de split personalizadas por meio de pagamento.

2. Via API

Alternativamente, você pode configurar o split diretamente no momento da criação de uma cobrança. Basta informar no endpoint /v1/charges o campo split seguindo a estrutura do exemplo abaixo:

{
  "amount": 100,
  "currency": "BRL",
  "customer": {
    // ... dados do cliente
  },
  // ... demais informações da cobrança
  "split": [
    {
      "merchantId": "2vorkDcXyvzifL63YX09S9VqcnI",
      "percentage": 10
    }
  ]
}

A configuração informada via API é exclusiva daquela transação gerada, e prevalecerá sobre a configuração padrão feita via Painel.

Liquidação e Repasse

O repasse dos valores de split configurados para cada participante ficam reservados e serão feitos no momento da liquidação no saldo do originador da transação.

Saques para Submerchants

O Fast Connect permite que submerchants solicitem saques de seus saldos disponíveis. O processo funciona em etapas, desde a criação da solicitação até a aprovação ou rejeição pelo gateway.

Pré-requisitos

Antes de solicitar um saque, certifique-se de que:

Fast Connect está habilitado no merchant master (enable_fast_connect = 'true')
Submerchant está ativo (status = 'active')
CNPJ está configurado no submerchant (company_tax_id)
Taxa de saque está configurada (fee_definitions com fee_type = 'payout')

Fluxo de Saque

1. Criação da Solicitação

O submerchant cria uma solicitação de saque através do endpoint:

POST /v1/submerchants/:merchantId/payout-requests

Exemplo de requisição:

{
  "amount": 100
}

O sistema irá:

Validar se o submerchant está ativo e possui CNPJ
Calcular as taxas de saque (fixa + percentual)
Criar o registro com status pending
Retornar o ID da solicitação criada

Exemplo de resposta:

{
  "id": "2vorkDcXyvzifL63YX09S9VqcnI"
}

Após a criação, a solicitação fica com status pending e aguarda processamento pelo gateway.

Cálculo de Taxas

As taxas de saque são calculadas automaticamente na criação da solicitação:

Taxa Fixa: Valor fixo configurado em fee_definitions
Taxa Percentual: Percentual sobre o valor do saque
Cálculo: totalFee = fixedFee + (amount * variableFee / 100)
Valor Líquido: netAmount = amount - totalFee

Consulta de Solicitações

Você pode consultar as solicitações de saque de diferentes formas: Listar todas as solicitações:

GET /v1/payout-requests

Obter uma solicitação específica:

GET /v1/payout-requests/:payoutRequestId

Filtros disponíveis:

merchantId: Filtrar por submerchant
status: Filtrar por status (pending, approved, rejected, processing)
currency: Filtrar por moeda
createdAt: Filtrar por data de criação
processedAt: Filtrar por data de processamento

Notificações via Webhook

Quando uma solicitação é aprovada ou rejeitada, o sistema envia automaticamente um webhook para o submerchant: Eventos disponíveis:

payout.approved: Enviado quando o saque é aprovado
payout.rejected: Enviado quando o saque é rejeitado

Exemplo de webhook de aprovação:

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "payout.approved",
  "data": {
    "id": "2vorkDcXyvzifL63YX09S9VqcnI",
    "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
    "amount": 100,
    "currency": "BRL",
    "status": "approved",
    "payoutFee": 1,
    "netAmount": 99,
    "processedAt": "2025-12-04T18:45:52.988Z"
  }
}

Para mais detalhes sobre webhooks de saque, consulte a documentação completa de webhooks de saque.

Valores e Moedas

Todos os valores são em reais (BRL) — o número é o próprio valor em reais (ex: 100 = R $100,00) e aceita casas decimais (ex: `100.50` = R$ 100,50). Mínimo de R$ 1,00 por saque
A moeda é sempre BRL para submerchants
O saque é realizado via PIX usando o CNPJ do submerchant como chave PIX

Segurança

Apenas submerchants vinculados ao merchant master podem criar solicitações
Todas as operações são transacionais e auditáveis

Documentação de Referência

Para mais detalhes sobre os endpoints de saque, consulte:

Taxas e dados cadastrais da subconta

Consulte as taxas (transacionais e de antecipação) e os dados cadastrais (razão social e CNPJ) de uma subconta:

GET /v1/fast-connect/sub-accounts/:id/fees-info

Autenticação por Secret Key (sk_, via Basic) ou Bearer (JWT do merchant). O comportamento depende de qual conta está autenticada:

Conta autenticada	Comportamento
Master	Usa o `:id` e retorna a subconta vinculada. Id não vinculado, inexistente, ou o próprio id do master → `404`. Requer `enable_fast_connect` habilitado (senão `403`).
Subconta	Retorna sempre os próprios dados; o `:id` é ignorado.

A resposta traz merchant (id, legalName, companyTaxId) e fees — uma lista plana de taxas próprias da subconta (array vazio se não houver taxas próprias). Cada item tem feeType (tx_spread ou anticipation), paymentMethod, currencyCode, brand e definition (fixed + percentages por parcela: índice 0 = à vista … 11 = 12x).

As taxas vêm como estão: a rota não mescla overrides de bandeira (brand: "visa") com a taxa padrão (brand: null), nem faz fallback para taxas default. Calcular a taxa efetiva por bandeira/parcela é responsabilidade do consumidor.

Detalhe completo (parâmetros, exemplos e respostas) em Taxas e dados da subconta.

Introdução

Autenticação

Homologação

Recursos

Webhooks

Onboarding

Criação dos SubMerchants

Credenciamento

Sócios adicionais e documentos por sócio

Split de Pagamentos

Configuração e Participantes

Cenários de relacionamentos permitidos

1. Via Painel

2. Via API

Liquidação e Repasse

Saques para Submerchants

Pré-requisitos

Fluxo de Saque

1. Criação da Solicitação

Cálculo de Taxas

Consulta de Solicitações

Notificações via Webhook

Valores e Moedas

Segurança

Documentação de Referência

Taxas e dados cadastrais da subconta

​Onboarding

​Criação dos SubMerchants

​Credenciamento

​Sócios adicionais e documentos por sócio

​Split de Pagamentos

​Configuração e Participantes

​Cenários de relacionamentos permitidos

​1. Via Painel

​2. Via API

​Liquidação e Repasse

​Saques para Submerchants

​Pré-requisitos

​Fluxo de Saque

​1. Criação da Solicitação

​Cálculo de Taxas

​Consulta de Solicitações

​Notificações via Webhook

​Valores e Moedas

​Segurança

​Documentação de Referência

​Taxas e dados cadastrais da subconta

Onboarding

Criação dos SubMerchants

Credenciamento

Sócios adicionais e documentos por sócio

Split de Pagamentos

Configuração e Participantes

Cenários de relacionamentos permitidos

1. Via Painel

2. Via API

Liquidação e Repasse

Saques para Submerchants

Pré-requisitos

Fluxo de Saque

1. Criação da Solicitação

Cálculo de Taxas

Consulta de Solicitações

Notificações via Webhook

Valores e Moedas

Segurança

Documentação de Referência

Taxas e dados cadastrais da subconta