API de a plataforma

Verificar a chave

Devolve o ambiente, os escopos e a conta associada. Use para conferir a integração antes de qualquer outra chamada.

Consultar saldo

O que pode ser gasto agora (available), o retido, o saldo bruto e o que ainda está dentro do prazo de recebimento (pending — boleto/cartão já pago e ainda não liberado; "0.00" quando o white-label não usa prazo). Valores em decimal com duas casas.

Listar movimentações

Extrato paginado. Aceita limit (até 100) e offset. Ordenado da mais recente para a mais antiga.

Detalhe de uma movimentação

O comprovante completo, com contraparte e taxas. É o que você mostra ao seu usuário como recibo.

Criar link de pagamento

Uma página hospedada que fica aberta e recebe de várias pessoas, até ser cancelada ou expirar. Diferente da cobrança avulsa, que é um QR para um pagamento só. Use link quando o valor for divulgado: uma vaquinha, uma mensalidade, um catálogo.

Listar links

Os links da conta, com quanto cada um já recebeu e quantos pagamentos teve.

Cancelar link

Fecha o link. Quem abrir depois vê que não está mais disponível; os pagamentos já recebidos continuam na conta.

Transferir

Move dinheiro da sua conta para outra da mesma plataforma. O destino pode ser o apelido (@loja ou loja) ou o id da conta.

Cobrar por Pix

Cobrança avulsa: um QR para um pagamento. Devolve o código copia-e-cola, que também serve para gerar o QR. Não cria link nem página pública — use quando o pedido já existe no seu sistema e só falta receber. O pagamento cai direto na sua conta e você é avisado pelo webhook charge.paid. Opcional `split`: a cobrança já pode nascer dividida entre até 5 contas destino (CPF, CNPJ ou e-mail) — a fatia de cada uma é creditada automaticamente no instante em que é paga, sem chamada extra.

Consultar cobrança

Estado atual da cobrança. Use para conferir um pagamento pontual — para acompanhar em tempo real, prefira o webhook: consultar em laço gasta requisição e chega depois.

Enviar Pix

Envia Pix da sua conta para uma chave externa de qualquer banco (Pix de saída). Diferente de Transferir, que move entre contas desta plataforma. Sai dinheiro da conta — por isso pede o escopo próprio pix:send e Idempotency-Key obrigatória. O desfecho final chega pelos webhooks pix.payout.completed e pix.payout.failed (só para quem os assina pelo nome) e pode ser conferido com GET /v1/transactions/{id} — o status vai de PENDING para SETTLED (enviado) ou FAILED (o valor e a tarifa voltam à conta sozinhos).

Ler um QR Code Pix

Lê um Pix copia e cola (o texto que está por trás do QR Code) e diz o que ele pede, antes de mexer em dinheiro: quem recebe, o valor, a validade, a tarifa e se o saldo cobre. Mostre isso ao seu usuário e só então chame /v1/pix/qr/pay.

Disponibilidade

Só em contas cuja provedora de pagamento paga QR Code (hoje a Efí). Nas demais responde qr_not_supported.

QR estático sem valor

Devolve amount: null e amountEditable: true. Envie em `amount` o valor que quer pagar e a tarifa, o total e a conferência de saldo são calculados para ele.

QR dinâmico

A plataforma consulta o endereço que vem dentro do código (só HTTPS; endereços internos são recusados). Código já pago, vencido ou que não está mais ativo é recusado com qr_not_active ou qr_expired.

Não suportado

Código que permite o pagador alterar o valor é recusado com qr_amount_editable.

Pagar um QR Code Pix

Paga um Pix copia e cola da sua conta: "ler o QR e pagar". Envie em `amount` o valor que você mostrou ao seu usuário — o servidor lê o código de novo e RECUSA (qr_amount_changed) se mudou desde a consulta, então ninguém paga um valor diferente do que viu. Sai dinheiro da conta: escopo próprio pix:send e Idempotency-Key obrigatória.

Desfecho

status volta como processing. O desfecho final chega pelos webhooks pix.payout.completed e pix.payout.failed (só para quem os assina pelo nome) e pode ser conferido com GET /v1/transactions/{id} — o status vai de PENDING para SETTLED (pago) ou FAILED (o valor e a tarifa voltam à conta sozinhos).

Timeout

Se receber pending_reconciliation, o pagamento pode ter saído. NÃO envie de novo: consulte GET /v1/transactions/{id}. Repetir a mesma Idempotency-Key é sempre seguro.

Conta bloqueada

Conta com saídas bloqueadas responde outbound_blocked.

Erros

brcode_invalid / brcode_crc (código não copiado inteiro), qr_expired, qr_not_active, qr_amount_changed, qr_amount_editable, qr_not_supported, insufficient_funds, limit_exceeded, daily_limit_exceeded, outbound_blocked, provider_rejected (nada foi debitado), pending_reconciliation.

Cobrar por boleto

Cobrança avulsa por boleto: devolve a linha digitável do pagamento e, quando o provedor suporta, um link para o PDF. Não cria link nem página pública — use quando o pedido já existe no seu sistema.

Documento de quem paga

Boleto exige nome e documento de quem paga. Atenção: a API só valida o tamanho do documento, não o dígito verificador de CPF/CNPJ, então valide isso também do seu lado.

Confirmação não é instantânea

A confirmação do pagamento chega pelo webhook charge.paid, normalmente em até um dia útil depois do pagamento.

Idempotency-Key

Opcional aqui mas recomendado: sem ele, um retry de rede gera um segundo boleto pro mesmo pedido.

Split

Funciona exatamente como em pix/charges.

Consultar cobrança de boleto

Estado atual do boleto. Mesmo formato de GET /v1/pix/charges/{id} — prefira o webhook charge.paid para acompanhar o pagamento em tempo real.

Cobrar no cartão de crédito

Cobrança server-to-server: você já tem os dados do portador em mãos e cobra direto, sem página de checkout hospedada no meio. A resposta já diz se foi aprovado — não existe instrumento para o pagador copiar depois, como acontece com Pix e boleto.

PCI-DSS

Número, validade e CVV do cartão chegam SÓ como parâmetro desta chamada — a plataforma nunca grava nem loga esses dados; eles vão direto para o provedor e saem de escopo assim que a resposta volta. Lidar com dados de cartão desse jeito coloca SUA integração sob escopo de PCI-DSS: cuide do TLS de ponta a ponta e não persista esses campos do seu lado sem o cuidado equivalente.

Idempotency-Key

Opcional, mas FORTEMENTE recomendado aqui — mais do que em Pix ou boleto. Sem ele, um retry de rede pode cobrar o cartão do cliente duas vezes de verdade, não só criar uma cobrança pendente duplicada.

Validação

Se a validação falhar, a resposta reporta só o primeiro campo inválido, não a lista completa.

Split

Funciona exatamente como em pix/charges — resolvido antes de cobrar no cartão, para que um destino inválido nunca deixe um cartão já cobrado sem o split aplicado.

Consultar cobrança de cartão

Estado atual da cobrança de cartão. Mesmo formato de GET /v1/pix/charges/{id}. Como a cobrança de cartão é síncrona na maioria dos casos, a resposta de POST /v1/card/charges já diz o desfecho — use este endpoint mais para conciliar depois do que para consultar logo em seguida da cobrança. Importante: enquanto a cobrança está em análise de risco, este endpoint mostra status "open", nunca "awaiting_risk_analysis" — esse valor só aparece na resposta do POST. Um cartão recusado na hora aparece aqui como "cancelled".

Consultar split

Estado atual do split da conta: quanto o administrador do white-label já reservou (só o percentual — o destino nunca é mostrado à conta), quanto ainda está livre, e as regras da própria conta. A mesma leitura que a tela de split da conta usa.

Configurar split

Configura a regra PERMANENTE de split da conta: toda cobrança futura (Pix, boleto pago, transferência interna recebida) já sai dividida automaticamente, sem precisar mandar o campo split em cada chamada. Substitui a lista inteira — não soma à anterior. Uma lista vazia remove todas as regras desta conta, sem mexer no que o administrador do white-label configurou.

Confirmar destino do split

Resolve um CPF, CNPJ ou e-mail para a conta que ele pertence, antes de salvar uma regra — a mesma confirmação que a tela da própria conta mostra ("vai enviar para fulano?"). Use para evitar salvar uma regra apontando para o destino errado.

Configurar split para chave Pix

Regra PERMANENTE de split em que o dinheiro sai por Pix para uma chave FORA da plataforma (fornecedor, sócio, outro banco). Substitui a lista inteira de linhas Pix (até 5, que somadas às linhas de conta e ao que o administrador do white-label reservou nunca passam de 100%). Mande a chave completa numa linha NOVA, ou só o `ruleId` para manter uma chave que já existe (a chave inteira nunca volta nas leituras). `feePayer` diz quem arca com a tarifa do Pix: SOURCE (você), DESTINATION (quem recebe) ou SHARED (padrão). O Pix só sai quando a venda liquida (boleto e cartão respeitam o prazo) e fatia abaixo de `pix.minimum` fica com a conta. Só funciona se o white-label liberou o recurso: confira `pix.enabled` e `pix.ready` em GET /v1/split, senão a chamada falha com erro claro.

Extrato do split

O que já saiu desta conta por split (conta e Pix juntos), com os totais do filtro. `kind` é opcional: ACCOUNT ou PIX. `limit` até 100. `status` do item: SENT, WAITING_RELEASE (esperando o prazo de liquidação), QUEUED, SENDING, FAILED, CANCELLED. `summary` conta só o que de fato saiu (SENT).

Resumo da folha

Se a folha está ligada para a conta (`availability.enabled` — o white-label liga o serviço e define a tarifa por pagamento), quantos funcionários ativos, o total da folha mensal e as próximas folhas. Valem as mesmas regras, limites e tarifas do Pix de saída do portal: a folha é paga pelo Pix de saída da conta.

Listar funcionários

Seus funcionários (`status` ACTIVE ou INACTIVE, `q` busca por nome). A chave Pix vem mascarada (`pixKeyMasked`); a chave completa nunca é devolvida por esta API.

Cadastrar funcionário

Cadastra um funcionário. ATENÇÃO: com `autoPay: true` (padrão) o funcionário é pago SOZINHO no `payDay`, sem nenhuma chamada a mais — então esta chave move dinheiro. `salary` é o valor LÍQUIDO a pagar (taxMode NET) ou o salário BRUTO (taxMode CLT: INSS/IRRF vêm calculados pelas tabelas do ano, FGTS é informativo). `businessDayRule`: PREVIOUS, NEXT ou EXACT (quando `payDay` não é dia útil). Devolve `{ "id": "..." }`. Atualize com PUT /v1/payroll/employees/{id} (mesmo corpo); chave Pix trocada ou salário aumentado valem também para os itens pendentes.

Desligar, reativar e excluir

POST /v1/payroll/employees/{id}/terminate (corpo opcional: `{ "date": "2026-10-31", "reason": "..." }`) para os pagamentos futuros; POST .../reactivate traz o funcionário de volta; DELETE /v1/payroll/employees/{id} remove quem nunca recebeu pagamento. Todos devolvem `{ "ok": true }`.

Valores sugeridos

O que pagar a cada funcionário ativo num tipo de folha: SALARY, ADVANCE, THIRTEENTH_FIRST, THIRTEENTH_SECOND, VACATION, BONUS ou OTHER. Para CLT a resposta já traz as linhas de desconto (INSS, IRRF) e o FGTS informativo. Use para montar o `items` de POST /v1/payroll/runs.

Criar folha

Cria uma folha (até 500 itens) para uma data de hoje em diante. ATENÇÃO: folha agendada é PAGA SOZINHA em `scheduledFor` — você não precisa chamar o pagar. O mesmo funcionário não é pago duas vezes no mesmo período e tipo (erro `DUPLICATE_PERIOD`). `lines` são ajustes opcionais (negativo = desconto, positivo = acréscimo). Devolve `{ "id": "..." }`. Edite com PATCH /v1/payroll/runs/{id} (`scheduledFor`, `title`, `note`), PUT /v1/payroll/runs/{id}/items/{itemId} (`amount`, `lines`, `remove`), POST /v1/payroll/runs/{id}/items (`employeeId`) e cancele com POST /v1/payroll/runs/{id}/cancel — tudo só enquanto a folha não começou a pagar (senão `NOT_EDITABLE`).

Consultar folha

A folha com cada item e um `preview` (total a pagar, tarifas estimadas, saldo e o que falta). `status` da folha: SCHEDULED, AWAITING_FUNDS (saldo insuficiente: tenta de novo quando entrar saldo), PROCESSING, COMPLETED, PARTIAL, FAILED, CANCELLED. `status` do item: PENDING, SENT (Pix enviado, aguardando o banco), PAID, FAILED (o banco confirmou que não saiu; valor e tarifa já voltaram), SKIPPED. Liste com GET /v1/payroll/runs?status=…

Pagar a folha agora

Paga agora uma folha SCHEDULED ou AWAITING_FUNDS, sem esperar a data. O dinheiro sai por Pix de saída com os limites e tarifas da conta; se o saldo não bastar, a folha vai para AWAITING_FUNDS e nada é enviado. Chamar duas vezes é seguro: só um processo pega a folha. Depois, acompanhe em `GET /v1/payroll/runs/{id}`; Pix que não sai volta para a conta. `POST /v1/payroll/runs/{id}/retry` repete SÓ os itens que o banco confirmou que não saíram (nunca repete um Pix que pode ter saído). Comprovante por item: GET /v1/payroll/runs/{id}/items/{itemId}/receipt. Extrato de tudo que foi pago: GET /v1/payroll/history?from=&to=&status=SENT|PAID|FAILED&employeeId=&limit=&offset= (devolve `items`, `totals` e `page`).