Visão geral

Introdução

Taxas e limites

Os valores abaixo são lidos de /v1/public/pricing quando a página abre.

{
  "deposit_fee_cents": 99,
  "withdraw_fee_bps": 299,
  "withdraw_provider_fee_estimate_bps": 100,
  "withdraw_provider_fee_min_cents": 100,
  "transfer_fee_bps": 300,
  "settlement_delay_hours": 24,
  "tranche_limit_cents": 600000,
  "deposit_min_cents": 1000,
  "deposit_max_cents": 600000,
  "charge_min_cents": 1000,
  "charge_max_cents": 10000000,
  "withdraw_min_cents": 1000,
  "contact_email": "..."
}

Introdução

Valores e formatos

Na API, todo valor em dinheiro é um inteiro em centavos num campo terminado em _cents. Texto, número com casas decimais ou booleano são recusados.

No painel, os campos de valor aceitam o formato brasileiro:

• 10 é R$ 10,00.
• 10,50 e 10.50 são R$ 10,50.
• 1.234,56 é R$ 1.234,56.
• 1.000 é recusado (ambíguo).

CPF e CNPJ podem ir com ou sem pontuação, mas precisam ter dígitos verificadores válidos. Datas vêm em ISO-8601 com fuso (2026-09-16T12:00:00Z). IDs são UUID em texto.

{
  "amount_cents": 150000,      // R$ 1.500,00
  "payer_document": "123.456.789-09",
  "created_at": "2026-09-16T12:00:00Z"
}

Para usuários

Conta e acesso

A entrada é por convite: o convite traz o usuário e um código de recuperação. No primeiro acesso, defina a senha em /login#esqueci com os dois. A cada senha definida aparece um código novo, uma única vez: anote. Ele é a única forma de redefinir a senha.

Regras

usuário

De 3 a 32 caracteres: letras, números, ponto, hífen e sublinhado. Maiúsculas e minúsculas não diferenciam contas.

senha

De 15 a 256 caracteres, diferente do usuário. Espaços contam: uma frase curta serve.

sessão

Vale 12 h desde o último uso (no máximo 7 dias). Em Configurações você vê as sessões abertas e pode encerrá-las.

Logo depois do convite a conta fica "em preparação" por alguns instantes. Nesse período, depósitos e saques respondem "Sua conta ainda está sendo preparada".

usuário: meu_usuario
código:  ABCDE-FGHIJ-KLMNO-PQRST
nova senha: ********

Para usuários

Depósito por PIX

Em Depositar, informe o valor e o CPF/CNPJ de quem vai pagar. O painel mostra o QR Code e o PIX copia e cola, com a contagem até o código expirar.

Como funciona

• Mínimo de R$ 10,00 e máximo de R$ 6.000,00 por PIX.
• O mesmo CPF/CNPJ pode pagar até R$ 6.000,00 somados em 24 horas.
• A provedora desconta R$ 0,99 de cada pagamento; o resto é o valor líquido.
• Pago o PIX, o status vira "Pagamento recebido" e o valor líquido entra em "Valores a entrar".
• O saldo disponível aumenta 24 h depois do pagamento (D+1, garantido pela Solit). A hora exata da liberação aparece em "Valores a entrar", e é a hora em que o valor entra no saldo.
• Se o código expirar e você já tiver pago, use "Verificar agora": o pagamento aparece em instantes.

Valor do PIX ........ R$ 100,00
Taxa da provedora ... R$   0,99
Valor líquido ....... R$  99,01  (disponível em D+1)

Aguardando pagamento
Prazo do PIX encerrado
Pagamento recebido — em liberação
Creditado
Em devolução
Falhou

Para usuários

Valores a entrar

São os pagamentos já recebidos que ainda não estão no saldo disponível: os PIX pagos dos seus depósitos (pelo painel ou pela API da conta) e dos seus links de pagamento.

Para cada item o painel mostra:

• o tipo e a descrição;
• valor bruto, taxa da provedora e valor líquido;
• quando foi pago e a previsão de liberação;
• a marca "atrasado" quando a previsão já passou (a liberação continua a caminho).

O item sai da lista quando o valor entra no saldo disponível, ou se o pagamento for devolvido.

Valores a entrar ........ R$ 5.198,02
próxima liberação: 17/09 14:32

Depósito via PIX
  bruto R$ 1.500,00 · taxa R$ 0,99 · líquido R$ 1.499,01

Link de pagamento · Consultoria de setembro
  bruto R$ 3.700,00 · taxa R$ 0,99 · líquido R$ 3.699,01

Para usuários

Receber por link

Em Receber por link, você cria um link com valor fixo e manda ao seu cliente. Ele abre o link, informa o próprio CPF/CNPJ e paga por PIX. O valor entra no seu saldo, como um depósito.

Como funciona

• Você informa o valor, de R$ 10,00 a R$ 100.000,00, e o que o cliente está pagando. Essa descrição aparece para ele: inclua o seu nome ou o da sua empresa.
• O link vale 7 dias (dá para escolher 24 horas ou 30 dias) e é de uso único: um cliente, um CPF/CNPJ.
• Cada PIX vai até R$ 6.000,00. Acima disso, o cliente paga em mais de um PIX, um por dia, voltando ao mesmo link.
• O PIX precisa sair de uma conta do CPF/CNPJ que o cliente informou; de outra conta, ele é devolvido. O mesmo CPF/CNPJ paga até R$ 6.000,00 somados em 24 horas e gera até 10 PIX por hora na página dos links.
• A provedora desconta R$ 0,99 de cada PIX. Pago o PIX, o valor líquido aparece em "Valores a entrar" e entra no saldo 24 horas depois.
• Você pode ter até 10 links em aberto. Dá para cancelar um link enquanto nenhum pagamento estiver a caminho: com um PIX gerado e ainda não pago, o cancelamento espera o código vencer (até 50 minutos depois de gerado); o que já entrou continua no seu saldo.
• Quem paga não vê o seu nome nem o seu usuário: vê só a descrição e o valor.
• Com o cartão liberado na sua conta, o link pode aceitar PIX, cartão ou PIX e cartão. No de PIX e cartão, quem paga escolhe num menu: tudo no PIX, tudo no cartão ou uma parte em cada (pelo menos R$ 10,00 no PIX; o resto no cartão).
• O cartão é pago numa página segura da solitpmt, em solitpmt.com, com a confirmação do banco quando a bandeira pede. No link com cartão, você escolhe quem paga as taxas do cartão e até quantas vezes ele pode ser dividido.
• Quem paga as taxas do cartão. No padrão, quem paga o link: a taxa e os juros do cartão vão no total de quem paga e aparecem antes de pagar, e entra no seu saldo o valor inteiro da parte no cartão. Com Eu pago, quem paga paga só o valor cobrado no cartão (o valor do link ou, na divisão com o PIX, a parte do link no cartão), em qualquer número de vezes e sem juros, e a taxa e os juros do cartão saem do que entra no seu saldo, pela tabela de taxas do cartão do dia do pagamento (quanto mais vezes, maior a taxa).
• Até quantas vezes no cartão, de 1 (só à vista) a 12 (o padrão). Quando você paga as taxas, quem paga tende a escolher o máximo, porque não paga juros: ao criar o link, o painel mostra quanto entra nesse pior caso. Se a tabela de taxas mudar e nenhuma opção couber mais, o detalhe do link avisa, e quem paga não consegue pagar no cartão.
• Declaração de recebimento (opcional, só no link com cartão). Com Pedir a declaração de recebimento assinada no gov.br marcado, depois de pagar no cartão quem pagou vê na página do pagamento um PDF da solitpmt com os dados que informou (nome, CPF, e-mail, celular, onde mora, os dados da fatura, o cartão, o valor, as vezes, a data e a descrição do link) e uma declaração de texto fixo: fez a compra, usou cartão próprio ou com autorização do titular, recebeu ou vai receber o produto ou serviço conforme o combinado e reconhece a compra. A pessoa assina no assinador.iti.br com a conta gov.br (nível prata ou ouro) e envia o arquivo assinado na mesma página; a solitpmt confere a assinatura do gov.br, que o CPF de quem assinou é o de quem pagou e que o documento é o que ela gerou.
• O pagamento não espera a assinatura, e ela não muda a carência do cartão. Em cada pagamento com cartão, o detalhe do link mostra a situação da declaração: pedida, disponível depois do pagamento aprovado; aguardando a assinatura de quem pagou, com a data em que o documento foi gerado; recusada, com o motivo da recusa do último arquivo; ou assinada, com a data e o CPF mascarado de quem assinou. Assinada, você baixa o PDF assinado. Se quem pagou perdeu a página do pagamento, baixe o documento para assinar, mande a essa pessoa e envie pelo painel o arquivo que ela assinou: a conferência é a mesma. A declaração não vale para quem paga com CNPJ (o gov.br assina só como pessoa física). A assinatura do gov.br traz o nome, o CPF e a data de nascimento de quem assina, e a declaração fica guardada na solitpmt.
• O que entra pelo cartão fica a liberar pela carência do cartão antes de poder sair em saque. Um chargeback é seu: o valor sai do seu saldo. O estorno da compra inteira e o comprovante do estorno ficam no detalhe do pagamento.

Link de R$ 3.700,00
  1 PIX · taxa R$ 0,99 · entra no saldo R$ 3.699,01

Link de R$ 9.000,00
  2 PIX (R$ 6.000,00 e R$ 3.000,00), em pelo menos 2 dias
  taxa R$ 1,98 · entra no saldo R$ 8.998,02

Aguardando o cliente
PIX ainda não gerado
PIX gerado, aguardando pagamento
Pago · libera na data e hora indicadas
Pago em parte
Pagamento com cartão em andamento
Concluído
Expirado
Cancelado

Pedem atenção:
O cliente informou o CPF/CNPJ, mas o PIX não foi gerado
PIX gerado e não pago

Para usuários

Saque

Em Sacar, escolha uma chave PIX cadastrada ou informe uma nova (tipo, chave, nome completo e CPF/CNPJ do titular) e o valor a receber. As taxas vão por fora: sai do seu saldo o valor mais as taxas. "Sacar tudo" preenche o maior valor a receber cujo débito cabe no que você pode sacar agora (o menor entre o saldo disponível, o teto por pedido e o que resta do limite de hoje). O mínimo, o teto por pedido e o limite do dia valem sobre o que sai do saldo.

Taxas

• Taxa da plataforma: 2,99% sobre o valor a receber, somada a ele (arredondada para cima).
• Taxa da provedora: 1% do valor repassado a ela (arredondado para cima), também somada ao débito; a provedora a desconta no pagamento do PIX, e a conta é feita para chegar exatamente o valor pedido; abaixo de R$ 100,00 vale a tarifa mínima do item seguinte.
• Tarifa mínima da provedora: em saques abaixo de R$ 100,00, ela cobra R$ 1,00 por saque, e não 1%. A tarifa mínima entra no débito: para receber R$ 10,00, por exemplo, saem R$ 11,30 do saldo (R$ 0,30 da plataforma e R$ 11,00 para a provedora) e chegam exatamente os R$ 10,00. O painel avisa antes do pedido.
• Antes de pedir, o painel mostra o débito exato. O pedido confere a cotação da provedora: se ela cobrar diferente, o valor repassado é corrigido uma vez (e o débito muda junto) ou o pedido é recusado, sem nada debitado.

Limites

• Mínimo de R$ 10,00 e máximo de R$ 5.000,00 por pedido.
• Até R$ 5.000,00 somados e 2 saques por dia (horário de Brasília). O dia vira à meia-noite.
• Pedido cancelado, recusado ou vencido devolve a cota do dia (valor e contagem).

Aprovação

Todo saque passa por aprovação do administrador. Enquanto o pedido aguarda aprovação você pode cancelá-lo; o valor reservado volta ao saldo. O saque é realizado em até 24 horas; pedidos sem aprovação nesse prazo expiram e o valor volta ao saldo. Você pode ter até 2 pedidos aguardando ao mesmo tempo.

Valor a receber ............. R$ 1.000,00
Taxa da plataforma (2,99%) .. R$    29,90
Taxa da provedora (1%) ...... R$    10,11
Sai do seu saldo ............ R$ 1.040,01
Você recebe ................. R$ 1.000,00

Aguardando aprovação
Aprovado — em preparação
Em processamento
Concluído — PIX pago
Não concluído — valor devolvido
Recusado · Cancelado · Expirado

Para usuários

Chaves PIX

Em Configurações você cadastra até 10 chaves para reusar nos saques. Depois de salva, a chave aparece só mascarada.

tipo

CPF, CNPJ, e-mail, telefone (com ou sem +55) ou chave aleatória.

titular

Nome completo e CPF/CNPJ de quem recebe. Para chave CPF/CNPJ, o documento é a própria chave.

apelido Opcional

Até 40 caracteres, para achar a chave na hora do saque.

Conta principal · E-mail jo***@exemplo.com
Titular: Maria Souza · ***.***.*89-01

Para usuários

Transferência

Em Transferir, informe o usuário de destino e o valor. O painel mostra a taxa (3%) e quanto o destino recebe; você confirma com a sua senha.

• O valor transferido sai do seu saldo na hora. Para você, a transferência fica "Em processamento" e depois "Concluída".
• O destinatário vê o valor como "A liberar" até ele ficar disponível e, só então, recebe o aviso "Transferência recebida".
• Se a transferência não puder ser concluída, ela aparece como "Não concluída — valor devolvido" e o valor volta para você; para o destinatário, ela aparece como "Não concluída".
• Se a conta de destino não puder receber no momento, o painel avisa "A conta de destino não pode receber agora." e nada sai do seu saldo.
• Não é possível transferir para a própria conta.

Valor transferido .. R$ 200,00
Taxa (3%) .......... R$   6,00
Destino recebe ..... R$ 194,00

Para usuários

Notificações e segurança

O sino do painel mostra só os avisos da sua conta: pagamento recebido (valor a entrar, com a previsão de liberação), depósito creditado, saque aprovado, recusado ou concluído, ajuste de saldo, senha alterada e outros. O painel verifica novidades a cada 10 segundos e pode mostrar avisos do navegador, se você permitir.

• Saque, troca de senha, novo código de recuperação e "encerrar todas as sessões" pedem a sua senha.
• Nenhum aviso traz o documento ou a chave PIX completos.
• Muitas tentativas de login erradas bloqueiam novas tentativas por alguns minutos.

Integração (API)

API da sua conta

Com a chave de API gerada na aba Integração do painel, o seu programa usa a sua própria conta: cria depósitos por PIX e links de pagamento (PIX, cartão ou os dois) e consulta saldo, valores a entrar, extrato e transações. Saque, chaves PIX, senha e as próprias chaves de API ficam só no painel: a chave não faz saque.

Regras

• Toda chamada leva a chave no cabeçalho X-Api-Key. A sessão do painel não abre estas rotas, e a chave não abre as do painel. Só vale a chave gerada no painel.
• O depósito é o mesmo do painel: mesma taxa, mesmo prazo de liberação (D+1) e os mesmos limites, inclusive o limite de 24 horas por CPF/CNPJ de quem paga.
• POST /v1/client/deposits exige Idempotency-Key (aqui ela é obrigatória): repetir a chamada com a mesma chave e o mesmo corpo devolve o mesmo depósito na situação atual, sem o PIX; outro corpo com a mesma chave recebe 422 idempotency_mismatch.
• O PIX copia e cola e o QR só aparecem enquanto o depósito pode ser pago.
• POST /v1/client/payment-links leva amount_cents, description, expires_in_hours (padrão 168) e methods: pix (padrão), card ou both, e exige Idempotency-Key. As regras são as do painel (valor, até 10 links em aberto, cartão só com ele liberado na conta).
• Com methods card ou both, dois campos opcionais: card_fee_payer: payer (padrão; a taxa e os juros do cartão vão no total de quem paga e a parte no cartão entra inteira no saldo) ou receiver (quem paga paga só o valor cobrado no cartão, em qualquer número de vezes, e a taxa e os juros saem do que entra no saldo, pela tabela de taxas do dia do pagamento); e card_max_installments, de 1 a 12 (padrão 12), até quantas vezes o cartão pode ser dividido. Com methods: pix, os dois só aceitam o padrão; fora dele, 422 validation_error. A lista e o detalhe do link trazem os dois campos, e cada pagamento com cartão traz fee_payer, total_cents (o que quem paga pagou) e net_cents (o que entrou no saldo).
• Também com cartão, card_declaration (opcional, padrão false): com true, quem pagar no cartão recebe na página do pagamento a declaração de recebimento para assinar com a conta gov.br (veja Receber por link). Com methods: pix, true dá 422 validation_error. A lista e o detalhe do link trazem card_declaration, e cada pagamento com cartão traz declaration: required, status (collecting, pedida, com o documento gerado depois do pagamento aprovado; pending, aguardando a assinatura de quem pagou; rejected, o último arquivo recusado; signed, assinada e conferida; void, não se aplica), generated_at (quando o documento para assinar foi gerado, ou null antes disso), reject_reason (o código do motivo da recusa do último arquivo, só com rejected), signed_at e signer_cpf_masked (com signed), ou null sem a declaração. Os PDFs, o documento e o assinado, ficam no painel.
• Quem paga sempre paga na página da solitpmt, em https://solitpmt.com/pagar/…: o PIX, o menu de formas e o cartão (a página segura do cartão, com a confirmação do banco). Mande a pessoa para a url do link, numa aba nova ou num redirecionamento; nunca peça os dados do cartão no seu site. A url vem na criação e no detalhe enquanto o link estiver em aberto; a repetição com a mesma Idempotency-Key devolve url: null (releia o detalhe).
• Para saber se o link foi pago, consulte o detalhe: situation, received_cents, as partes (plan e card) e card_payments.
• Em /v1/client/transactions, type aceita all, deposits, payments e withdrawals; range aceita all, today, 7d e 30d.
• Trocar ou recuperar a senha revoga as chaves da conta: depois, gere outra no painel.

Erros mais comuns

curl https://solitpmt.com/v1/client/account \
  -H "X-Api-Key: slt_..."

curl -X POST https://solitpmt.com/v1/client/deposits \
  -H "X-Api-Key: slt_..." \
  -H "Idempotency-Key: deposito-0001" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 1000,
       "payer_document": "12345678909"}'

curl -X POST https://solitpmt.com/v1/client/payment-links \
  -H "X-Api-Key: slt_..." \
  -H "Idempotency-Key: link-0001" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 25000,
       "description": "Consultoria de outubro - Maria Souza",
       "methods": "both",
       "card_fee_payer": "receiver",
       "card_max_installments": 6,
       "card_declaration": true}'

→ 201 {"id": "…", "status": "open", "methods": "both",
       "card_fee_payer": "receiver", "card_max_installments": 6,
       "card_declaration": true,
       "url": "https://solitpmt.com/pagar/…", …}

Integração (API)

Como integrar

A integração é de quem usa a Solit: não existe cadastro de loja e nada precisa ser pedido ao administrador. Você se registra, gera a sua chave de API no seu painel e passa a cobrar pela API. Todo pagamento das suas cobranças entra na sua conta, com as mesmas taxas, o mesmo prazo de liberação (D+1) e o mesmo extrato do painel.

Passo a passo

1. Crie a sua conta em /registrar (ou entre na que você já tem).
2. No painel, abra Integração e clique em "Gerar chave". A chave é confirmada com a sua senha e aparece uma única vez: guarde-a no servidor da sua aplicação. Você pode ter até 5 chaves ativas e revogar qualquer uma na hora.
3. Opcional: em "Meus sites", cadastre os sites em que você vende (até 5), para que quem paga veja o nome da sua loja e tenha um botão de volta depois de pagar (Sites).
4. Ainda em Integração, gere o segredo do webhook e salve a URL https:// que vai receber os avisos.
5. Crie a cobrança com POST /v1/merchant/charges e mostre o PIX ao pagador.
6. Trate os eventos pagamento.recebido e pagamento.liberado conferindo a assinatura de cada aviso.

A chave é pessoal e vale como senha: quem a tiver cobra em seu nome. Se desconfiar de vazamento, gere outra e revogue a antiga no painel.

curl -X POST https://solitpmt.com/v1/merchant/charges \
  -H "X-Api-Key: slt_..." \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 1000,
       "payer_document": "12345678909",
       "external_ref": "pedido-1",
       "description": "Primeiro teste"}'

https://solitpmt.com/dashboard#integracao

Integração (API)

Gift cards por PIX

O comprador paga sem cadastro em /swap, verifica o e-mail e recebe um gift no mesmo valor do PIX após a liberação. A Solit cobre a tarifa do provedor. O código pode ser compartilhado com o cliente da API escolhido pelo comprador.

No painel Gift cards, gere uma chave exclusiva gift:redeem. Ela aparece uma única vez e não acessa cobranças ou a API geral. O administrador precisa habilitar o resgate da sua conta antes do primeiro uso.

Envie o código recebido em POST /v1/merchant/gift-redemptions, junto de external_ref e Idempotency-Key. A resposta pode ficar processing; aguarde credited consultando GET /v1/merchant/gift-redemptions/{id} antes de liberar saldo ao cliente no seu sistema. O valor entra na conta Solit do titular da chave.

curl -X POST https://solitpmt.com/v1/merchant/gift-redemptions \
  -H "X-Api-Key: slt_..." \
  -H "Idempotency-Key: seu-pedido-unico" \
  -H "Content-Type: application/json" \
  -d '{"code":"SG_...","external_ref":"pedido-123"}'

Guarde a chave no servidor. Um gift só pode ser resgatado uma vez. Para listar suas chaves de gift, use GET /v1/me/gift-api-keys no painel autenticado; para gerar, POST /v1/me/gift-api-keys pede senha e Idempotency-Key.

Integração (API)

Sites

Você mesmo cadastra os seus sites no painel, em Integração → "Meus sites": até 5 sites ativos, cada um com um nome, a URL https:// do site e, se quiser, uma URL de retorno. O cadastro e a edição pedem a sua senha; remover não pede. Cada site serve para três coisas:

• Identificar a sua loja para quem paga. A página de pagamento e o comprovante mostram "Pagamento para" e o nome do site, com o domínio embaixo.
• Liberar o navegador do site. Só a origem exata de um site ativo pode chamar as rotas de cobrança pelo navegador (veja Chamada do navegador).
• Levar quem pagou de volta. Com a URL de retorno, as telas "Pagamento recebido" e "Pagamento concluído" mostram o botão "Voltar para" com o nome do site. A URL é aberta como está, sem parâmetros acrescentados: a sua loja identifica o pedido pela própria sessão.

Regras da URL

• O site é gravado como origem: https:// + domínio (+ porta, se não for a 443). Caminho e consulta são descartados: https://Loja.com.br/produtos vira https://loja.com.br, e o painel mostra o valor gravado.
• Só https:// com domínio público: IP, localhost e redes internas são recusados.
• A URL de retorno precisa ser da mesma origem do site (outro domínio ou subdomínio é recusado; para outro subdomínio, cadastre outro site).
• A URL do site não muda depois de cadastrada: para trocar, remova o site e cadastre outro. O nome e a URL de retorno podem ser editados.
• O suporte pode desativar um site que viole as regras de uso. Ele aparece no painel como "Desativado pelo suporte" e a mesma origem não pode ser cadastrada de novo.

Chave e site da cobrança

Ao gerar uma chave, você escolhe "Todos os sites" ou um site só. Com a chave amarrada a um site, toda cobrança criada por ela mostra esse site e só o navegador dele é liberado. Com a chave que vale para todos, envie o campo site_id em POST /v1/merchant/charges para escolher o site exibido; sem ele, a cobrança não mostra loja. Os ids dos seus sites ativos vêm em GET /v1/merchant/me. A cobrança guarda o site da criação: trocar ou revogar a chave não muda as cobranças antigas.

Um site removido ou desativado some na hora da página de pagamento (inclusive das cobranças já criadas) e deixa de ter o navegador liberado. As chaves amarradas a ele continuam valendo, mas passam a criar cobranças sem site. Para cortar uma chave, revogue a chave.

curl -X POST https://solitpmt.com/v1/merchant/charges \
  -H "X-Api-Key: slt_..." \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 5000,
       "payer_document": "12345678909",
       "external_ref": "pedido-77",
       "site_id": "0192f0d1-..."}'

HTTP/1.1 201 Created
{
  "id": "0192f0c6-...",
  "external_ref": "pedido-77",
  "payment_url": "https://solitpmt.com/pagar/Ab3...",
  "site": {"id": "0192f0d1-...",
           "name": "Loja da Maria",
           "url": "https://lojadamaria.com.br",
           "status": "active"},
  ...
}

Pagamento para Loja da Maria
lojadamaria.com.br

Integração (API)

Chamada do navegador

A integração recomendada continua sendo pelo servidor da sua aplicação. Se precisar chamar a API direto do navegador, a Solit libera (CORS) só a origem exata de um site ativo seu, e só nas rotas de cobrança (/v1/merchant e /api/v1/cobrancas). Uma origem não cadastrada vê erro de rede no navegador.

• A origem precisa bater exatamente com a URL gravada do site: https://www.loja.com.br e https://loja.com.br são sites diferentes.
• Chave amarrada a um site: só a origem daquele site é liberada. Chave para todos os sites: qualquer site ativo seu.
• Métodos GET e POST; cabeçalhos X-Api-Key, Authorization, Content-Type, Idempotency-Key e X-Request-Id. A página consegue ler Retry-After, Idempotent-Replay e X-Request-Id da resposta.
• Nunca há cookie nem credencial do navegador: chame com credentials: "omit". Um fetch com credentials: "include" é bloqueado pelo navegador.
• A liberação não substitui a chave: quem autentica é sempre a chave.

// em https://lojadamaria.com.br (site ativo)
const resp = await fetch("https://solitpmt.com/v1/merchant/charges", {
  method: "POST",
  credentials: "omit",
  headers: {
    "X-Api-Key": "slt_...",   // chave só do navegador, amarrada ao site
    "Content-Type": "application/json",
    "Idempotency-Key": "pedido-78"
  },
  body: JSON.stringify({
    amount_cents: 5000,
    payer_document: "12345678909",
    external_ref: "pedido-78"
  })
});
const cobranca = await resp.json();
location.href = cobranca.payment_url;

Integração (API)

Autenticação

A chave de API (começa com slt_) é gerada por você mesmo, no seu painel, em "Integração"; ela é mostrada uma única vez. O segredo de assinatura dos webhooks também é gerado ali. Guarde os dois no servidor da sua aplicação. O segredo do webhook nunca vai para o navegador; a chave, só no caso de Chamada do navegador, e então uma chave própria, amarrada ao site.

X-Api-Key

Cabeçalho com a chave. Alternativa: Authorization: Bearer <chave>.

Content-Type

application/json em toda requisição com corpo.

Você pode manter até 5 chaves ativas, cada uma com o seu rótulo — os rótulos servem para você separar as suas aplicações e revogar uma sem derrubar as outras. Todas as chaves da sua conta veem as mesmas cobranças e os mesmos eventos, então uma chave entregue a um terceiro lê e cancela tudo. Para trocar a chave, gere a nova no painel e revogue a antiga: a revogação vale na hora.

curl https://solitpmt.com/v1/merchant/me \
  -H "X-Api-Key: slt_..."

{
  "id": "0192f0c4-...",
  "name": "maria",
  "status": "active",
  "webhook": {"configured": true, "format": "solit_v1"},
  "key": {"prefix": "slt_Ab12", "site_id": null},
  "sites": [
    {"id": "0192f0d1-...", "name": "Loja da Maria",
     "url": "https://lojadamaria.com.br",
     "return_url": "https://lojadamaria.com.br/obrigado"}
  ]
}

GET /v1/merchant/health
{"ok": true,
 "merchant": {"id": "...", "name": "maria", "status": "active"},
 "webhook": {"configured": true, "format": "solit_v1",
             "pending": 0, "delivered": 12, "dead": 0}}

Integração (API)

POST /v1/merchant/charges

Cria uma cobrança e já gera o primeiro PIX. Responde 201 quando a cobrança é nova e 200 quando a mesma external_ref já existia com os mesmos dados (nesse caso, se o PIX anterior falhou, a Solit tenta gerar de novo).

Campos

amount_cents Obrigatório

Inteiro de 1000 (R$ 10,00) a 10000000 (R$ 100.000,00).

payer_document Obrigatório

CPF ou CNPJ de quem paga, com dígitos verificadores válidos.

external_ref Obrigatório

Sua referência (1 a 100 caracteres, sem espaços). É única por conta.

description Opcional

Até 200 caracteres; aparece para o pagador.

expires_in_hours Opcional

Validade da cobrança, de 1 a 720 horas (padrão 24).

site_id Opcional

Id de um site ativo seu, exibido para quem paga (veja Sites). Com chave amarrada a um site, vale o site da chave, e outro valor é recusado com 422.

Mostre ao cliente o payment_url (página de pagamento da Solit) ou o QR e o copia e cola de current_tranche. Se o primeiro PIX não puder ser gerado, a cobrança é criada mesmo assim, com current_tranche: null e tranche_error.

curl -X POST https://solitpmt.com/v1/merchant/charges \
  -H "X-Api-Key: slt_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{"amount_cents": 150000,
       "payer_document": "12345678909",
       "external_ref": "pedido-1234",
       "description": "Pedido 1234",
       "expires_in_hours": 24}'

HTTP/1.1 201 Created
{
  "id": "0192f0c5-...",
  "external_ref": "pedido-1234",
  "status": "started",
  "situation": "aguardando",
  "amount_cents": 150000,
  "paid_cents": 0,
  "remaining_cents": 150000,
  "completed": false,
  "description": "Pedido 1234",
  "payment_url": "https://solitpmt.com/pagar/Xy7...",
  "expires_at": "2026-09-17T12:00:00Z",
  "created_at": "2026-09-16T12:00:00Z",
  "site": null,
  "current_tranche": {
    "seq": 1,
    "deposit_id": "a1b2c3...",
    "amount_cents": 150000,
    "phase": "awaiting_payment",
    "pix_copy_paste": "00020126...",
    "qr_url": "https://solitpmt.com/v1/public/qr/....png",
    "window_expires_at": "2026-09-16T12:20:00Z"
  },
  "tranches": [
    {"seq": 1, "deposit_id": "a1b2c3...",
     "amount_cents": 150000, "status": "open",
     "confirmed_at": null}
  ]
}

Integração (API)

Consultar cobranças

GET /v1/merchant/charges/{id} devolve a cobrança completa. A listagem GET /v1/merchant/charges aceita filtros e é paginada.

status

open, started, paid, expired ou canceled (vários separados por vírgula).

external_ref

Busca pela sua referência.

limit / cursor

Até 100 itens por página (padrão 20). Use next_cursor da resposta para a próxima página.

O copia e cola e o QR só vêm enquanto o PIX pode ser pago. Nenhuma resposta traz prazo de liberação; a previsão aparece em "Valores a entrar" no seu painel.

curl "https://solitpmt.com/v1/merchant/charges?status=started&limit=20" \
  -H "X-Api-Key: slt_..."

{
  "items": [ { "id": "...", "external_ref": "pedido-1234", ... } ],
  "next_cursor": "MjAyNi0wOS0xNlQ..."
}

Integração (API)

Parcelas

Um PIX tem no máximo R$ 6.000,00. Cobranças maiores são pagas em parcelas, uma de cada vez, e nenhuma parcela fica abaixo de R$ 10,00.

• A próxima parcela fica disponível assim que a anterior é liberada (evento pagamento.liberado).
• tranches[].status: open (parcela gerada, ainda não liberada), confirmed (parcela liberada) ou failed (o PIX falhou, expirou sem pagamento ou foi pago depois do prazo; nesse último caso, se o valor for aceito na cobrança depois da análise, a parcela passa a confirmed e você recebe pagamento.liberado). Não existem outros valores. confirmed e confirmed_at marcam a liberação da parcela, o mesmo marco do evento pagamento.liberado.
• POST /v1/merchant/charges/{id}/tranches gera a próxima parcela, ou um novo PIX quando o anterior expirou ou falhou.
• A página payment_url faz isso sozinha para o pagador.
• Respostas 409: tranche_open (já existe parcela aberta), order_locked (outra geração em curso), nothing_due (cobrança quitada), invalid_state.

parcela 1 ... R$ 6.000,00
parcela 2 ... R$ 6.000,00
parcela 3 ... R$ 3.000,00

curl -X POST https://solitpmt.com/v1/merchant/charges/0192f0c5-.../tranches \
  -H "X-Api-Key: slt_..."

Integração (API)

Cancelar cobrança

POST /v1/merchant/charges/{id}/cancel com {"reason": "..."} (opcional, até 200 caracteres). Enquanto houver um PIX que ainda pode ser pago, ou um pagamento em andamento, a resposta é 409 tranche_in_flight: espere o PIX expirar ou o pagamento ser confirmado.

Valores já pagos não são devolvidos pelo cancelamento. Você recebe o evento cobranca.cancelada.

curl -X POST https://solitpmt.com/v1/merchant/charges/0192f0c5-.../cancel \
  -H "X-Api-Key: slt_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "cliente desistiu"}'

Integração (API)

Situações

O campo situation resume a cobrança no vocabulário da integração:

O campo status é o estado técnico: open, started, paid, expired ou canceled.

12:00  aguardando   (cobrança criada, PIX gerado)
12:03  recebido     (cliente pagou; evento pagamento.recebido)
+24 h  liberado     (evento pagamento.liberado)

Integração (API)

Webhooks

Se você tiver URL de webhook configurada no painel, a Solit envia um POST JSON a cada evento. Só respostas 2xx contam como entregues; as outras são repetidas com intervalo crescente.

• A ordem é garantida por referência: liberado nunca chega antes de recebido da mesma parcela.
• O mesmo event_id pode chegar mais de uma vez: trate cada um só uma vez.
• Tempo limite de 15 s por entrega, sem seguir redirecionamentos.
• GET /v1/merchant/webhook-events lista as entregas; POST /v1/merchant/webhook-events/{id}/redeliver reenvia uma delas.
• valor_cents é o valor pago em recebido, o valor da parcela em liberado/falhou e null em cancelado.

POST /seu/webhook
Content-Type: application/json
User-Agent: Solit-Webhooks/1
X-Solit-Event: 0192f0d0-...
X-Solit-Event-Type: pagamento.liberado
X-Solit-Timestamp: 1789574400
X-Solit-Signature: v1=5f2c...

{
  "event_id": "0192f0d0-...",
  "type": "pagamento.liberado",
  "reference": "a1b2c3...",
  "created_at": "2026-09-17T12:03:10Z",
  "data": {
    "cobranca_id": "Xy7...",
    "charge_id": "0192f0c5-...",
    "referencia_externa": "pedido-1234",
    "deposito_id": "a1b2c3...",
    "valor_cents": 150000,
    "status": "liberado",
    "motivo": null,
    "total_cents": 150000,
    "pago_cents": 150000,
    "restante_cents": 0,
    "quitado": true,
    "parcela_seq": 1
  }
}

Integração (API)

Verificar assinaturas

Sempre confira a assinatura com o corpo bruto recebido (os bytes, antes de interpretar o JSON) e compare em tempo constante.

solit_v1 (recomendado)

X-Solit-Signature = "v1=" + hex(HMAC-SHA256(segredo, timestamp + "." + corpo)), com o timestamp de X-Solit-Timestamp (segundos Unix). Recuse eventos com mais de 300 s de diferença do seu relógio.

nexogate_v1 (compatibilidade)

Formato mantido para integrações antigas. Corpo {"event_id", "tipo", "referencia", "dados"} e cabeçalhos X-Nexogate-Event e X-Nexogate-Signature = hex(HMAC-SHA256(segredo, corpo)). Como não tem timestamp, deduplique pelo event_id. Prefira solit_v1 em integrações novas.

import hashlib
import hmac
import time


def _bytes(valor: str) -> bytes:
    # cabeçalho vindo de fora: compare sempre em bytes (str com acento faria compare_digest falhar)
    return valor.encode("utf-8", "replace")


def verificar_solit_v1(segredo: str, corpo: bytes, cabecalhos) -> bool:
    ts = cabecalhos.get("X-Solit-Timestamp", "")
    recebida = cabecalhos.get("X-Solit-Signature", "")
    # só dígitos ASCII e tamanho curto (isdigit sozinho aceita "²" e números enormes)
    if not (ts.isascii() and ts.isdigit() and len(ts) <= 12):
        return False
    if abs(time.time() - int(ts)) > 300:
        return False
    mac = hmac.new(segredo.encode(), f"{ts}.".encode() + corpo, hashlib.sha256)
    return hmac.compare_digest(("v1=" + mac.hexdigest()).encode(), _bytes(recebida))


def verificar_formato_compat(segredo: str, corpo: bytes, cabecalhos) -> bool:
    recebida = cabecalhos.get("X-Nexogate-Signature", "")
    mac = hmac.new(segredo.encode(), corpo, hashlib.sha256)
    return hmac.compare_digest(mac.hexdigest().encode(), _bytes(recebida))

const crypto = require('node:crypto');

function iguais(a, b) {
  const x = Buffer.from(a);
  const y = Buffer.from(b);
  return x.length === y.length && crypto.timingSafeEqual(x, y);
}

// corpoBruto: Buffer com o corpo exatamente como chegou
function verificarSolitV1(segredo, corpoBruto, cabecalhos) {
  const ts = cabecalhos['x-solit-timestamp'] || '';
  const recebida = cabecalhos['x-solit-signature'] || '';
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const mac = crypto.createHmac('sha256', segredo)
    .update(ts + '.')
    .update(corpoBruto)
    .digest('hex');
  return iguais('v1=' + mac, recebida);
}

function verificarFormatoCompat(segredo, corpoBruto, cabecalhos) {
  const recebida = cabecalhos['x-nexogate-signature'] || '';
  const mac = crypto.createHmac('sha256', segredo).update(corpoBruto).digest('hex');
  return iguais(mac, recebida);
}

Integração (API)

Idempotência

Repetir uma requisição nunca cria cobrança em dobro. A chave natural é a external_ref: a mesma referência com o mesmo valor e documento devolve a cobrança existente (200); com dados diferentes, 422 idempotency_mismatch.

Opcionalmente, envie também o cabeçalho Idempotency-Key (8 a 128 caracteres: letras, números e _ . : -). A mesma chave com o mesmo corpo devolve a resposta gravada, com o cabeçalho Idempotent-Replay: true. Uma chave em uso por outra requisição simultânea devolve 409 idempotency_in_progress.

# 1ª tentativa: tempo esgotado na sua rede
POST /v1/merchant/charges   Idempotency-Key: pedido-1234
# 2ª tentativa com a mesma chave e o mesmo corpo
POST /v1/merchant/charges   Idempotency-Key: pedido-1234
HTTP/1.1 201 Created
Idempotent-Replay: true

Integração (API)

API de compatibilidade

Para integrações antigas continuam disponíveis POST /api/v1/cobrancas, GET /api/v1/cobrancas/{cobranca_id} e GET /api/v1/saude, com a mesma chave de API. Os erros vêm no formato {"detail": "..."}. Integrações novas devem usar /v1/merchant.

Campos de POST /api/v1/cobrancas

valor_cents Obrigatório

Inteiro (ou texto só com dígitos) de 1000 a 10000000.

documento Obrigatório

CPF ou CNPJ do pagador, com dígitos verificadores válidos.

referencia_externa Obrigatório

Sua referência única.

descricao / validade_horas Opcionais

Descrição (até 200 caracteres) e validade de 1 a 720 horas (padrão 24).

Respostas: 201 (nova), 200 (mesma referência e dados), 409 (referência já usada com outros dados), 502 (a cobrança foi criada, mas o PIX não; repita a mesma referência). situacao vira liberado só com a cobrança quitada; cobrança cancelada aparece como falhou com cancelada: true.

curl -X POST https://solitpmt.com/api/v1/cobrancas \
  -H "X-Api-Key: slt_..." \
  -H "Content-Type: application/json" \
  -d '{"valor_cents": 5000, "documento": "12345678909",
       "referencia_externa": "pedido-99"}'

{
  "cobranca_id": "Xy7...",
  "referencia_externa": "pedido-99",
  "situacao": "aguardando",
  "valor_cents": 5000,
  "url_pagamento": "https://solitpmt.com/pagar/Xy7...",
  "pago_cents": 0,
  "restante_cents": 5000,
  "deposito_id": "a1b2c3...",
  "pix_copia_cola": "00020126...",
  "qr_url": "https://solitpmt.com/v1/public/qr/....png",
  "expira_em": 1789574400,
  "total_cents": 5000,
  "quitado": false,
  "cancelada": false,
  "charge_id": "0192f0c5-..."
}

GET /api/v1/saude
{"ok": true,
 "fila_de_avisos": {"pendentes": 0, "entregues": 12, "travados": 0}}

Integração (API)

Erros

As rotas /v1 respondem erros sempre no mesmo formato, com um code estável, uma mensagem em português e detalhes quando houver. Informe o request_id ao suporte.

provider_blocked significa que a provedora não aceita gerar PIX para aquele documento: não adianta repetir; combine outra forma de pagamento com o cliente.

HTTP/1.1 422 Unprocessable Entity
{
  "error": {
    "code": "validation_error",
    "message": "Dados inválidos.",
    "details": {
      "fields": [{"loc": ["body", "amount_cents"],
                  "msg": "deve ser no mínimo 1000"}]
    }
  },
  "request_id": "9f1c2a7e-..."
}

Integração (API)

Limites de uso

Acima destes limites a API responde 429 rate_limited com o cabeçalho Retry-After (em segundos).

Toda resposta da API tem Cache-Control: no-store e o cabeçalho X-Request-Id.