Documentação
Visão geral
A solitpmt é uma conta privada, por convite, para receber e sacar por PIX. Use pelo painel em
solitpmt.com ou ligue o seu sistema à API da conta: o titular
gera a própria chave de API no painel dele, cria depósitos e links de pagamento e consulta a conta.
Não existe cadastro de loja: quem integra é você.
Todo pagamento recebido fica disponível no saldo em D+1. Até lá, ele aparece em "Valores a entrar" no painel, com a previsão de liberação.
Esta página tem duas partes: o guia do usuário (depósito, links de pagamento, saque e chaves PIX) e o guia de integração do cliente (a chave de API, os depósitos e os links de pagamento pela API, o webhook dos links, o ambiente de testes, os erros e os limites de uso). A API usa JSON em UTF-8, valores em centavos inteiros e datas em ISO-8601 UTC.
Painel do usuário:
https://solitpmt.com/dashboard
Base da API:
https://solitpmt.com/v1
Taxas e limites vigentes (público):
GET https://solitpmt.com/v1/public/pricing
Introdução
Taxas e limites
Os valores abaixo são lidos de /v1/public/pricing quando a página abre.
| Item | Valor |
|---|---|
| Taxa por pagamento recebido (provedora) | R$ 0,99, descontada do valor |
| Taxa de saque (plataforma) | 2,99% sobre o valor a receber, por fora |
| Taxa de saque (provedora, estimada) | 1% sobre o valor que vai à provedora (arredondado para cima), por fora; abaixo de R$ 100,00, a provedora cobra a tarifa mínima de R$ 1,00 por saque, também somada ao débito |
| Taxa de transferência | 3% do valor transferido |
| Prazo de liberação | 24 h (D+1), garantido pela Solit |
| Depósito próprio | R$ 10,00 a R$ 6.000,00 por PIX |
| Link de pagamento (Receber por link) | R$ 10,00 a R$ 100.000,00, até R$ 6.000,00 por PIX |
| Cobrança pela API e link | R$ 10,00 a R$ 100.000,00 |
| Valor máximo por PIX (parcela) | R$ 6.000,00 |
| Saque mínimo | R$ 10,00 |
| Saque máximo por pedido | R$ 5.000,00 |
| Limite diário de saque | R$ 5.000,00 e 2 saques por dia |
{
"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": "..."
}
Taxas em bps: 100 bps = 1%.
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,50e10.50sã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".
Na tela de entrada, clique em "Esqueci a senha" (ou abra /login#esqueci) e informe:
usuário: meu_usuario
código: ABCDE-FGHIJ-KLMNO-PQRST
nova senha: ********
Um código novo aparece na hora (o antigo deixa de valer) e todas as sessões são encerradas.
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)
Status possíveis do depósito:
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.brcom 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
Situações de um link no painel:
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
Se o cliente não conseguiu pagar, cancele e crie outro igual.
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
A taxa da provedora no débito é a tarifa dela sobre o valor repassado: dos R$ 1.010,11 repassados, ela desconta 1% arredondado para cima (R$ 10,11), e chegam exatamente R$ 1.000,00.
Status do pedido:
Aguardando aprovação
Aprovado — em preparação
Em processamento
Concluído — PIX pago
Não concluído — valor devolvido
Recusado · Cancelado · Expirado
Depois da aprovação, o pedido fica "Em processamento" até o PIX ser pago. Se ele não puder ser concluído, o valor volta para o seu saldo e o pedido aparece como "Não concluído — valor devolvido".
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.
apelidoOpcional- 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.
Pagamento recebido
Pagamento de R$ 99,01 recebido — liberação prevista em 17/09 às 14:32.
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.
| Rota | O que faz |
|---|---|
GET /v1/client/account | Saldo disponível, reservado e valores a entrar |
GET /v1/client/summary | Resumo do período (?days= de 1 a 90; padrão 30) |
GET /v1/client/incoming | Valores a entrar, com o total líquido |
GET /v1/client/ledger | Extrato da conta |
GET /v1/client/transactions | Depósitos, saques e transferências (?type=, ?range=, ?q=) |
POST /v1/client/deposits | Cria o depósito e devolve o PIX copia e cola e o QR |
GET /v1/client/deposits | Lista os seus depósitos |
GET /v1/client/deposits/{id} | Situação de um depósito |
POST /v1/client/deposits/{id}/refresh | Pede uma nova consulta à provedora |
POST /v1/client/payment-links | Cria o link de pagamento e devolve a url da página de pagamento da solitpmt |
GET /v1/client/payment-links | Lista os links (?section=live, os em aberto, ou closed, paginado); com ?section=ref&external_ref=…, os links de uma referência |
GET /v1/client/payment-links/{id} | Situação do link, as partes (PIX e cartão) e os pagamentos com cartão |
POST /v1/client/payment-links/{id}/cancel | Cancela o link (o que já foi pago continua no saldo) |
GET /v1/client/webhook-events | Entregas do webhook da conta, com o resumo (?status=, paginado) |
POST /v1/client/webhook-events/{event_id}/redeliver | Reenvia uma entrega do webhook (veja Webhooks da sua conta) |
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/depositsexigeIdempotency-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 recebe422 idempotency_mismatch.- O PIX copia e cola e o QR só aparecem enquanto o depósito pode ser pago.
POST /v1/client/payment-linkslevaamount_cents,description,expires_in_hours(padrão 168) emethods:pix(padrão),cardouboth, e exigeIdempotency-Key. As regras são as do painel (valor, até 10 links em aberto, cartão só com ele liberado na conta).external_ref(opcional) é a referência do seu pedido no link: de 1 a 100 caracteres, sem espaços nem caracteres de controle ou invisíveis. Os espaços das pontas saem, e o texto vazio vale como sem referência; fora disso,422 validation_error("use de 1 a 100 caracteres, sem espaços"). A lista e o detalhe do link trazemexternal_ref(ounull), o item do link emGET /v1/client/incominga traz emcharge.external_ref, e o aviso do webhook, emreferencia_externa. Ela é única entre os links abertos, iniciados e pagos da conta: repetida, a criação dá409 conflict(tabela abaixo).- Para achar o link de um pedido, use
GET /v1/client/payment-links?section=ref&external_ref=pedido-123:itemstraz todos os links da conta com essa referência, em qualquer situação, do mais novo ao mais antigo (até 100, comnext_cursor: null). Aceite só o item cujoexternal_refé igual ao do pedido e trate um422como erro, nunca como "sem link".section=refsemexternal_ref, ouexternal_refsemsection=ref, dá422 validation_error. A busca é a reserva: guarde oiddo link junto do pedido quando criar o link. Não use CPF nem e-mail como referência: ela vai na URL da requisição. - Quanto tempo a referência fica presa: o link pago a segura para sempre, mesmo depois de um
estorno (use outra, como
pedido-123-2); o iniciado, mesmo vencido, até ser cancelado ou encerrado; o aberto que já venceu, sem pagamento com cartão, não conta (a criação o encerra e segue). O409pode apontar para um link aberto comsituationexpirado(com um pagamento com cartão em andamento ou com a parte do cartão paga), que solta a referência quando a manutenção o encerrar, comcobranca.cancelada. Ligue os avisos ao pedido pelolink_id: areferencia_externaé só o rótulo do pedido e pode repetir entre um link encerrado e o novo (ocobranca.canceladado link vencido que a criação encerra chega depois do201do novo). - Com
methodscardouboth, 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) oureceiver(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); ecard_max_installments, de 1 a 12 (padrão 12), até quantas vezes o cartão pode ser dividido. Commethods: 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 trazfee_payer,total_cents(o que quem paga pagou) enet_cents(o que entrou no saldo). - Também com cartão,
card_declaration(opcional, padrãofalse): comtrue, 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). Commethods: pix,truedá422 validation_error. A lista e o detalhe do link trazemcard_declaration, e cada pagamento com cartão trazdeclaration: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, ounullantes disso),reject_reason(o código do motivo da recusa do último arquivo, só comrejected),signed_atesigner_cpf_masked(comsigned), ounullsem 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 aurldo link, numa aba nova ou num redirecionamento; nunca peça os dados do cartão no seu site. Aurlvem na criação e no detalhe enquanto o link estiver em aberto; a repetição com a mesmaIdempotency-Keydevolveurl: null(releia o detalhe). - Para saber se o link foi pago, receba o aviso no webhook da conta (veja
Webhooks da sua conta) e use a consulta do detalhe
como reserva:
situation,received_cents, as partes (planecard) ecard_payments. Antes de entregar, confira o detalhe. - Em
/v1/client/transactions,typeaceitaall,deposits,paymentsewithdrawals;rangeaceitaall,today,7de30d. - O que entra pelo cartão vai para o saldo em reais da conta, que a API da conta não mostra: ele
só aparece em
incoming_cents, durante a carência.balance_cents,available_cents,/v1/client/ledger,/v1/client/incominge/v1/client/transactionssão só PIX e depósitos: acompanhe o cartão pelocard_paymentsdo link e pelo webhook. - Trocar ou recuperar a senha revoga as chaves da conta: depois, gere outra no painel.
- Para testar a integração sem dinheiro de verdade, use o
Ambiente de testes: as mesmas rotas em
/v1/sandbox, com uma chave de teste.
Erros mais comuns
| Código | Quando |
|---|---|
401 unauthorized | Chave ausente, revogada, amarrada a um site ou de outro tipo |
403 account_disabled | Conta desativada |
409 account_frozen | Conta em revisão; fale com o suporte |
409 account_not_ready | A conta ainda está sendo preparada; tente em instantes |
400 idempotency_key_required | Depósito ou link sem Idempotency-Key |
409 too_many_pending | Já há 10 links em aberto |
422 validation_error | Campo fora da regra; em amount_cents, no link só de cartão, o valor fora da faixa do cartão e, com receiver, o valor abaixo do mínimo que paga a taxa do cartão (no link com both, só esse mínimo); em card_fee_payer ou card_max_installments, a opção fora do padrão num link só de PIX; em card_declaration, true num link só de PIX; em external_ref, a referência fora da regra; na lista, section=ref sem external_ref ou o contrário |
409 conflict | Com details.reason external_ref_in_use: já existe um link aberto, iniciado ou pago da conta com a mesma external_ref, e details.link_id diz qual. O link aberto que já venceu, sem pagamento com cartão, não conta. A recusa não fica gravada na Idempotency-Key: solta a referência, a mesma chave repete a criação |
409 invalid_state | Com details.reason terms_required: a conta ainda não aceitou os Termos de Uso; aceite no painel e tente de novo. Quem paga aceita os termos na página de pagamento da solitpmt, antes de pagar |
409 invalid_state | Com details.reason card_unavailable: esta conta não pode receber pagamento com cartão agora (link com card ou both) |
409 invalid_state | Com details.reason card_no_option, que não volta na criação: na página de quem paga, a tabela de taxas do cartão do dia ou a faixa do cartão mudaram e nenhuma parcela fecha a parte no cartão. O detalhe do link avisa com card.no_option: true |
409 document_busy | Outra operação com o mesmo CPF/CNPJ em andamento; tente em instantes |
422 daily_limit_exceeded | Passou do limite de 24 horas do CPF/CNPJ; details.remaining_cents diz quanto ainda cabe |
503 feature_paused | Função pausada; details.flag diz qual: deposits_paused ou charges_paused (depósitos e links pausados pelo administrador) ou card_payments_paused (o cartão não está disponível agora, num link com card ou both; o link só de PIX continua) |
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",
"external_ref": "pedido-123",
"methods": "both",
"card_fee_payer": "receiver",
"card_max_installments": 6,
"card_declaration": true}'
→ 201 {"id": "…", "status": "open", "external_ref": "pedido-123",
"methods": "both",
"card_fee_payer": "receiver", "card_max_installments": 6,
"card_declaration": true,
"url": "https://solitpmt.com/pagar/…", …}
O link de um pedido, pela referência:
curl "https://solitpmt.com/v1/client/payment-links?section=ref&external_ref=pedido-123" \
-H "X-Api-Key: slt_..."
→ 200 {"items": [{"id": "…", "external_ref": "pedido-123",
"status": "open", "situation": "aguardando_cliente", …}],
"next_cursor": null, …}
Integração (API)
Webhooks da sua conta
Com o webhook ligado, a solitpmt avisa o seu servidor a cada evento dos links de pagamento da sua
conta: um POST em JSON, assinado, na URL do webhook que você cadastrou. Vale para todo
link da conta, criado no painel ou pela API, no PIX e no cartão.
O aviso sai segundos depois do evento, e a entrega é pelo menos uma vez: o mesmo aviso pode chegar
repetido e atrasa enquanto o seu servidor estiver fora do ar. Por isso a consulta do link
(GET /v1/client/payment-links/{id}) continua sendo a reserva. Os
depósitos (POST /v1/client/deposits) não geram aviso: acompanhe cada
um com GET /v1/client/deposits/{id}.
Configurar
- No painel, abra Integração e, em Webhook, informe a URL do webhook e a sua senha e clique em Salvar.
- A primeira URL salva gera o segredo da assinatura, mostrado uma única vez: copie-o e guarde-o no servidor da sua aplicação, junto da chave de API.
- Clique em Enviar evento de teste e veja a resposta do seu servidor.
- Trate os avisos: confira a assinatura, responda
2xxe reconsulte o link antes de entregar o produto.
- Um webhook por conta: a mesma URL e o mesmo segredo para todos os links, sempre no formato
solit_v1. - Trocar a URL mantém o segredo. Gerar novo segredo troca o segredo na hora: os avisos seguintes já saem assinados com o novo, e os que o seu servidor recusar até ser atualizado voltam nas novas tentativas.
- Desligar para os avisos e guarda o segredo, que volta a valer quando você salvar uma URL de novo. Com o webhook desligado, nenhum aviso novo é criado: o que acontecer nesse período não chega depois (use a consulta), e os que já estavam na fila esperam a URL voltar.
- Salvar, gerar novo segredo e desligar pedem a sua senha e só existem no painel: quem tiver a chave de API não muda o webhook nem vê o segredo.
Regras da URL
- Começa com
https://, em minúsculas, e tem de 12 a 500 caracteres, sem espaço,#nem@(nada de usuário e senha na URL). - Host público: um domínio completo ou um IP público.
localhost, redes internas e IPs reservados são recusados ao salvar e de novo em cada entrega, quando o domínio precisa resolver só para IPs públicos. - Porta 443 (a padrão) ou a partir de 1024.
- Sem redirecionamento: a solitpmt não segue
301nem302, que contam como falha. Cadastre a URL final, com certificado válido.
Eventos
| Evento | O que quer dizer |
|---|---|
pagamento.recebido | No PIX, o cliente pagou; o aviso sai segundos depois. O valor fica em Valores a entrar até a liberação (D+1) e, até lá, ainda pode ser devolvido. No cartão, o pagamento foi aprovado, e o valor fica a liberar pela carência do cartão, quando houver. |
pagamento.liberado | No PIX, o valor entrou no seu saldo, cerca de 24 horas depois do pagamento. No cartão, a carência acabou (sem carência, ele chega logo depois do pagamento.recebido). |
pagamento.falhou | No PIX, o código venceu sem pagamento, o PIX foi devolvido ou deu erro. No cartão, o pagamento foi recusado ou deu erro. O link continua pagável: o cliente pode tentar de novo. |
pagamento.estornado | No cartão, o estorno do pagamento foi concluído: pedido por você no painel ou pelo suporte, ou feito direto na processadora do cartão. O valor volta a quem pagou e sai do seu saldo. O link fica como estava (um link pago continua pago): confira o pagamento na consulta. O chargeback não gera evento. |
cobranca.cancelada | O link foi cancelado, por você ou pelo suporte (motivo cancelada), ou venceu sem o pagamento completo (motivo expirada). O link iniciado e pago em parte (por exemplo, só parte dos PIX de um link de mais de um PIX, ou o PIX quitado esperando a parte do cartão) não recebe aviso no vencimento: sem o resto do pagamento, a solitpmt o encerra 30 dias depois do prazo, e só então chega o cobranca.cancelada, com motivo expirada. Até lá, acompanhe pela consulta do link. O que já foi pago continua no seu saldo. |
webhook.teste | O evento de teste do painel. Nunca vem de um pagamento. |
Criar o link e gerar o PIX não geram aviso.
Link pago no PIX:
21:00 link criado (POST /v1/client/payment-links)
21:03 pagamento.recebido o cliente pagou; o valor fica a liberar
+24 h pagamento.liberado o valor entrou no saldo
Link abandonado, criado com expires_in_hours: 1:
21:00 link criado
21:05 o cliente gera o PIX e não paga
21:25 pagamento.falhou motivo vencido
22:00 cobranca.cancelada motivo expirada
Quando entregar o produto
O aviso diz o que aconteceu; quando entregar é decisão sua. Em todos os casos, reconsulte o link
antes: com situation pago_a_liberar ou concluido, o valor
inteiro do link foi pago.
- PIX, no
pagamento.recebido. O cliente pagou, mas o valor ainda está a liberar e pode ser devolvido até a liberação (por exemplo, quando o PIX sai da conta de outro CPF/CNPJ). Se for, chegapagamento.falhoucommotivodevolvido. - PIX, no
pagamento.liberado. O valor entrou no seu saldo, cerca de 24 horas depois do pagamento (situationconcluido). É o ponto mais seguro para o que não dá para desfazer, como uma chave, um acesso ou um arquivo. - Cartão, no
pagamento.recebido. O pagamento foi aprovado. O valor fica a liberar pela carência do cartão (hoje, 14 dias; o fim de cada uma vem emgrace_until, noscard_paymentsdo detalhe), e opagamento.liberadochega quando ela acaba. Sem carência, opagamento.liberadochega logo depois dopagamento.recebido. Um chargeback, mesmo depois, é seu: o valor sai do seu saldo. - Cartão, no
pagamento.estornado. O valor do pagamento voltou a quem pagou e saiu do seu saldo, mas ostatusdo link não muda (um linkpaidcontinuapaid, com asituationconcluido). Na consulta, o pagamento estornado fica comstatusrefundedemcard_paymentse sai dereceived_cents; no link ainda aberto ou iniciado, asituationacompanha e a parte do cartão volta a ser devida. Decida pela consulta se o pedido continua pago. - Mesmo liberado, um PIX ainda pode voltar pelo MED do PIX, a devolução pedida pelo banco de quem pagou em caso de fraude.
Corpo e cabeçalhos
Cada aviso é um POST com Content-Type: application/json,
User-Agent: Solit-Webhooks/1 e quatro cabeçalhos X-Solit-*.
O corpo chega compacto, numa linha só; abaixo, formatado para leitura. Confira a assinatura sobre
os bytes recebidos, nunca sobre o JSON remontado.
POST /webhooks/solitpmt HTTP/1.1
Host: loja.exemplo.com.br
Content-Type: application/json
User-Agent: Solit-Webhooks/1
X-Solit-Event: 6f1c0a52-...
X-Solit-Event-Type: pagamento.recebido
X-Solit-Timestamp: 1793998992
X-Solit-Signature: v1=8c3e...
{
"event_id": "6f1c0a52-...",
"type": "pagamento.recebido",
"reference": "0193a1c9-...",
"created_at": "2026-11-06T21:03:10Z",
"data": {
"link_id": "0193a1c4-...",
"referencia_externa": "pedido-123",
"metodo": "pix",
"pagamento_id": "0193a1c9-...",
"valor_cents": 10000,
"link_valor_cents": 10000,
"status": "recebido",
"motivo": null,
"teste": false
}
}
event_id- Identificador do evento, o mesmo em todas as tentativas e nos reenvios (também em
X-Solit-Event). É por ele que você deduplica. type- O evento (também em
X-Solit-Event-Type). reference- A referência que define a ordem: o
pagamento_idnos eventos de pagamento e olink_idemcobranca.cancelada. created_at- Quando o evento nasceu, em ISO-8601 UTC. Não muda nas novas tentativas.
data- O corpo da conta, com as chaves abaixo, as mesmas em todo evento.
Em data:
link_id- O
iddo link, o mesmo deGET /v1/client/payment-links/{id}. referencia_externa- O
external_refdo link, a referência do seu pedido informada na criação (veja API da sua conta), ounullno link sem ela e no evento de teste. Ligue o aviso ao pedido pelolink_id, guardado junto do pedido quando você criou o link: a referência é só o rótulo do pedido e pode repetir entre um link encerrado e o novo. metodopixoucartao;nullemcobranca.cancelada.pagamento_id- O pagamento que gerou o evento: cada PIX e cada pagamento com cartão do link tem o seu (no cartão, é o
idemcard_payments).nullemcobranca.cancelada. valor_cents- A parte do valor do link que este pagamento cobre, antes das taxas: no PIX, o valor pago no
recebidoe o valor do PIX noliberadoe nofalhou.nullemcobranca.cancelada. link_valor_cents- O valor do link.
statusrecebido,liberado,falhou,estornadooucancelado(testeno evento de teste).motivo- Em
pagamento.falhouecobranca.cancelada(tabela abaixo);nullnos outros eventos. testetrueno evento de teste (webhook.teste) e em todo evento do ambiente de testes;falsenos eventos de pagamentos de verdade. Em produção, não entregue nada por evento comteste: true.
O corpo não traz o token nem a URL do link, nem dados de quem pagou. Ele é gravado quando o evento nasce: as novas tentativas e os reenvios levam os mesmos dados, mesmo que o link tenha mudado depois.
motivo | Quando |
|---|---|
vencido | O código PIX venceu sem pagamento. |
devolvido | O PIX foi devolvido a quem pagou. |
cancelado | O código PIX foi cancelado pela provedora. |
recusado | O cartão foi recusado, ou o suporte não aceitou o PIX. |
parcial | O PIX foi pago com valor menor que o do código. |
encerrado | O suporte encerrou o PIX em aberto, para o cliente gerar outro. |
erro | Erro no PIX ou no cartão. |
cancelada | Em cobranca.cancelada: o link foi cancelado. |
expirada | Em cobranca.cancelada: o prazo do link acabou sem o pagamento completo. No link iniciado e pago em parte, o aviso só chega 30 dias depois do prazo, quando a solitpmt encerra o link; no vencimento, nenhum aviso sai. |
Verificar a assinatura
X-Solit-Signature = "v1=" + hex(HMAC-SHA256(segredo, timestamp + "." + corpo)),
em hexadecimal minúsculo, com o timestamp de X-Solit-Timestamp (segundos Unix, o
horário desta tentativa) e o segredo como está, em texto, sem decodificar.
- Leia o corpo bruto: os bytes, antes de interpretar o JSON.
- Recuse o timestamp que não for número ou que estiver a mais de 300 s do seu relógio (mantenha o relógio do servidor certo).
- Calcule o HMAC e compare com
X-Solit-Signatureem tempo constante. - Só então interprete o JSON. Sem assinatura válida, responda
401e não faça nada.
import hashlib
import hmac
import time
def verificar_solit_v1(segredo: str, corpo: bytes, cabecalhos) -> bool:
# corpo: os bytes exatos da requisição (Flask: request.get_data(); Django: request.body)
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)
esperada = ("v1=" + mac.hexdigest()).encode()
# em bytes e em tempo constante (str com acento faria compare_digest falhar)
return hmac.compare_digest(esperada, recebida.encode("utf-8", "replace"))
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: o Buffer cru, com o corpo exatamente como chegou
function verificarSolitV1(segredo, corpoBruto, cabecalhos) {
if (!Buffer.isBuffer(corpoBruto)) return false;
const ts = String(cabecalhos['x-solit-timestamp'] || '');
const recebida = String(cabecalhos['x-solit-signature'] || '');
if (!/^\d{1,12}$/.test(ts)) return false;
if (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);
}
O corpo precisa ser o Buffer cru, e a primeira linha recusa o que não for. Com
express.raw({ type: 'application/json' }), um pedido com outro
Content-Type chega com req.body igual a {}. Sem essa
conferência, o update lançaria um TypeError, e num handler
async (como o do exemplo de Express, mais abaixo) o Express 4 não trata o erro:
ele derruba o processo.
Entrega e novas tentativas
- A solitpmt espera a resposta por até 15 s. Só
2xxconta como entregue; outro código, redirecionamento, erro de rede ou tempo esgotado é falha. - Depois de uma falha, ela tenta de novo em 15 s, 1 min, 5 min e 15 min e, daí em diante, de hora em hora, até 48 tentativas (cerca de 44 horas). Esgotadas as tentativas, o evento fica como Sem entrega no histórico, e dá para reenviar.
- Cada tentativa leva
X-Solit-Timestampe assinatura novos; oevent_ide o corpo são os mesmos. - O mesmo
event_idpode chegar mais de uma vez (uma resposta perdida no caminho, um reenvio): trate cada evento uma vez só. - A ordem vale por referência: o
pagamento.liberadonunca chega antes dopagamento.recebidodo mesmo pagamento, nem opagamento.estornadoantes dos dois (depois de um estorno, opagamento.liberadonão vem mais), e o evento seguinte espera o anterior da mesma referência ser entregue ou esgotar as tentativas. Entre referências diferentes (dois pagamentos do mesmo link, ou um pagamento e ocobranca.canceladado link), a ordem não é garantida.
Boas práticas
- Responda
2xxem poucos segundos e faça o trabalho fora da requisição, numa fila. - Deduplique pelo
event_id: grave-o com uma restrição de unicidade e responda2xxao repetido, sem tratá-lo de novo. - Antes de entregar, reconsulte o link com
GET /v1/client/payment-links/{id}(olink_iddo aviso) e decida pelasituation. Entregue uma vez por link, não por evento: um link pode ter mais de um pagamento. - Mantenha uma conferência de reserva: a cada poucos minutos, consulte os links dos pedidos que
ainda esperam pagamento e, de vez em quando, as entregas que esgotaram as tentativas
(
GET /v1/client/webhook-events?status=dead). - Responda
2xx, sem fazer nada, aos eventos que você não trata e, no servidor de produção, a todo evento comteste: true: owebhook.testee os eventos do ambiente de testes (que só chegam à URL real se você cadastrar a mesma URL no webhook de teste). - Autentique pela assinatura, não pelo IP de origem. O segredo fica no servidor, junto da chave de API, e não vai para o navegador nem para o aplicativo.
const express = require('express');
const app = express();
const SEGREDO = process.env.SOLIT_WEBHOOK_SECRET; // o segredo do webhook
const CHAVE = process.env.SOLIT_API_KEY; // a chave de API (slt_...)
const API = 'https://solitpmt.com/v1/client';
// o valor inteiro do link foi pago (veja "Quando entregar o produto")
const PAGO = new Set(['pago_a_liberar', 'concluido']);
// express.raw: o corpo chega como Buffer, nos bytes que a assinatura cobre; com outro
// Content-Type, req.body vem {} e verificarSolitV1 recusa (401)
app.post('/webhooks/solitpmt', express.raw({ type: 'application/json' }), async (req, res) => {
if (!verificarSolitV1(SEGREDO, req.body, req.headers)) return res.status(401).end();
const evento = JSON.parse(req.body.toString('utf8'));
// o webhook.teste e os eventos do ambiente de testes (teste: true) não entregam nada em produção
if (evento.type === 'webhook.teste' || evento.data.teste === true) return res.status(200).end();
try {
// INSERT ... ON CONFLICT (event_id) DO NOTHING: o repetido não entra duas vezes
await eventos.gravar(evento.event_id, evento.type, evento.data.link_id);
} catch (erro) {
return res.status(500).end(); // a solitpmt tenta de novo
}
res.status(200).end(); // responde logo; o limite é de 15 s
});
// fora da requisição, para cada evento gravado e ainda não tratado
async function tratar(registro) {
const resp = await fetch(API + '/payment-links/' + encodeURIComponent(registro.linkId), {
headers: { 'X-Api-Key': CHAVE },
});
if (!resp.ok) throw new Error('consulta do link: HTTP ' + resp.status); // tente de novo depois
const link = await resp.json();
// quem decide a entrega é o link consultado, não só o aviso
if (PAGO.has(link.situation)) await pedidos.entregarUmaVez(registro.linkId);
await eventos.marcarTratado(registro.eventId);
}
A tabela dos eventos gravados serve de fila. No Python, o caminho é o mesmo, com
verificar_solit_v1 e o corpo bruto da requisição.
Teste e histórico
- Enviar evento de teste (painel, em Integração, Webhook) manda na hora um
webhook.testecom o corpo e os cabeçalhos da entrega real, assinado com o segredo atual, e mostra a resposta do seu servidor: o código HTTP, o tempo e o começo da resposta, ou o erro. No teste,referenceétestee odatatrazteste: true,status: "teste", os ids zerados e R$ 10,00. Ele não entra na fila, não é repetido nem aparece no histórico. Até 1 teste a cada 10 s e 30 por hora. Enquanto a solitpmt estiver com os avisos pausados, o teste é recusado com503 feature_paused. - Entregas recentes (painel): cada evento com o horário, o tipo, o link, a situação (Entregue, Pendente ou Sem entrega), as tentativas e a última resposta. Reenviar manda de novo um evento entregue ou sem entrega.
- Pela chave,
GET /v1/client/webhook-eventslista as entregas, da mais nova para a mais antiga (?status=compending,deliveredoudead, separados por vírgula;?limit=até 100;?cursor=), com o resumo emsummary, ePOST /v1/client/webhook-events/{event_id}/redeliverreenvia uma entrega, com202. Um evento ainda pendente dá409 invalid_state; um que não é da sua conta,404 not_found. - O reenvio zera as tentativas e manda o mesmo evento: o mesmo
event_ide o mesmodata, com horário e assinatura novos. Até a primeira tentativa nova, a entrega ficapendingcomattempts0, elast_http_statuselast_errorainda podem trazer a resposta de antes do reenvio. - Em cada entrega,
statusépending(esperando a entrega ou a próxima tentativa),delivered(o seu servidor respondeu2xx) oudead(esgotou as tentativas), elast_errortraz a última falha:HTTP 500,destination_blocked(a URL não resolveu ou resolveu para um IP que não é público), o nome do erro de rede (comoConnectTimeout),waiting_previous_event(esperando o evento anterior da mesma referência),webhook_not_configured(webhook desligado) ouwebhooks_paused(entregas pausadas pelo administrador). - Para ver cada evento de pagamento chegar (recebido, liberado, falhou, estornado e cancelado) sem dinheiro de verdade, use o webhook de teste do Ambiente de testes, com URL e segredo próprios.
curl "https://solitpmt.com/v1/client/webhook-events?status=dead&limit=20" \
-H "X-Api-Key: slt_..."
{
"items": [
{"id": "6f1c0a52-...", "event_type": "pagamento.recebido",
"ref_key": "0193a1c9-...", "link_id": "0193a1c4-...",
"status": "dead", "attempts": 48,
"last_http_status": 500, "last_error": "HTTP 500",
"next_attempt_at": "2026-11-08T16:24:30Z",
"delivered_at": null,
"created_at": "2026-11-06T21:03:10Z"}
],
"next_cursor": null,
"summary": {"pending": 0, "delivered": 31, "dead": 1}
}
curl -X POST https://solitpmt.com/v1/client/webhook-events/6f1c0a52-.../redeliver \
-H "X-Api-Key: slt_..."
→ 202 {"id": "6f1c0a52-...", "status": "pending"}
Limites dos links
Os limites dos links são os mesmos com o webhook. Para uma loja, os que mais pesam:
- Até 10 links em aberto. O link aberto (o cliente ainda não informou o
CPF/CNPJ) deixa de contar na hora em que vence; o iniciado (o cliente já informou) conta até o
fim do prazo e mais cerca de 30 minutos; o pago no PIX, até a liberação; o pago em parte, até
30 dias depois do prazo. Crie o link na hora da compra, com prazo curto
(
expires_in_hours: 1, o mínimo), e cancele o abandonado comPOST /v1/client/payment-links/{id}/cancel: o cancelamento libera a vaga na hora. - O link pago em parte não recebe aviso no vencimento. O link iniciado que
recebeu só parte do valor (por exemplo, parte dos PIX de um link de mais de um PIX, ou o PIX
quitado esperando a parte do cartão) não é encerrado no prazo: continua contando entre os 10
em aberto e, sem o resto do pagamento, a solitpmt o encerra 30 dias depois do prazo, com
cobranca.canceladaemotivoexpirada. No vencimento, nenhum aviso sai: consulte o link (situationpago_em_parteereceived_cents) para saber em que pé ele está e cancele o que não vai ser terminado (o que já foi pago continua no seu saldo). - Com um PIX gerado e ainda não pago, o cancelamento espera o código vencer: a resposta é
409 tranche_in_flight, comdetails.cancel_blocked_until, e o detalhe do link trazcan_cancelecancel_blocked_until. - 10 pagadores diferentes por dia no PIX. A conta recebe por PIX de até 10 CPF/CNPJ diferentes em 24 horas. Acima disso, a página de pagamento não gera o PIX, sem dizer o motivo a quem paga, e nenhum aviso sai. O limite é só do PIX: com o cartão no link, quem paga ainda pode pagar no cartão.
- A criação aceita 1 link a cada 5 s e 30 por hora; acima disso,
429 rate_limited.
Cartão pelo link
- Com o cartão liberado na sua conta, crie o link com
"methods": "card"(só cartão) ou"methods": "both"(PIX e cartão: quem paga escolhe na página e pode dividir). Quem paga sempre paga na página segura da solitpmt. - No cartão,
pagamento.recebidoé o pagamento aprovado,pagamento.falhoué a recusa ou o erro (o link continua pagável),pagamento.liberadoé o fim da carência (sem carência, logo depois dopagamento.recebido) epagamento.estornadoé o estorno concluído: na consulta do link, o pagamento estornado sai dereceived_cents. Quem abre o cartão e desiste não gera evento, e o chargeback também não. - Quando a resposta da operadora do cartão fica incerta, a solitpmt continua procurando o resultado
por até 24 horas: nesse tempo o pagamento aparece em análise na consulta, e o
pagamento.falhousó chega se ele não for encontrado. Raramente, um pagamento achado depois disso é creditado pelo suporte e chega umpagamento.recebidodepois dopagamento.falhou: por isso, confira sempre a consulta antes de entregar. - No link com PIX e cartão, cada pagamento tem os próprios eventos, e
valor_centsé a parte do link que ele cobre. Para saber se o link inteiro foi pago, use a consulta (situationereceived_cents), não a soma dos avisos. - O link só de cartão não entra no limite de pagadores do PIX nem fica iniciado: deixa de contar entre os 10 em aberto quando vence ou é pago.
Integração (API)
Ambiente de testes
O ambiente de testes é a API da sua conta com dinheiro de mentira: links, depósitos, saldo e webhook de teste, em que você mesmo simula cada desfecho de pagamento, para ver as respostas da API e os avisos do webhook antes de ligar o seu sistema à conta real. Nada ali movimenta dinheiro de verdade: nenhum PIX nem cartão é cobrado, e nada do teste aparece no saldo, no extrato ou nas consultas da conta real.
Como começar
- No painel, abra a aba Testes e clique em Gerar chave de teste.
A chave começa com
slt_test_e aparece uma única vez: guarde-a no servidor da sua aplicação, como a chave real. - No seu código, troque a base
/v1/clientpor/v1/sandboxe a chave real pela de teste, no mesmo cabeçalhoX-Api-Key. Os corpos, os campos e as respostas são os da conta real. - Crie um link de teste, simule o pagamento (abaixo) e acompanhe a consulta do link e os avisos do webhook de teste.
- A chave de teste é segredo, como a real: não vai para repositório, log nem navegador. É uma por conta: gerar outra troca na hora, e a aba Testes também a revoga. Trocar ou recuperar a senha, encerrar todas as sessões e a desativação da conta revogam a chave de teste.
- A chave de teste só abre
/v1/sandbox: nas rotas reais, ela recebe401 unauthorized("Esta é uma chave de teste: use as rotas /v1/sandbox."), e a chave real, nas rotas de teste, também ("Use a chave de teste (slt_test_…) nas rotas /v1/sandbox."). A aba Testes do painel usa as mesmas rotas, pela sua sessão. - No teste, o link, o depósito e a conta trazem
"teste": true; o resto do JSON é o da conta real, com as mesmas chaves e os mesmos valores possíveis. A diferença: aurldo link aponta para a página de teste, e o depósito traz um código de exemplo no lugar do PIX.
Rotas
| Rota | O que faz |
|---|---|
GET /v1/sandbox/account | Saldo de teste, como /v1/client/account |
GET /v1/sandbox/summary | Resumo do período, com os dados de teste |
GET /v1/sandbox/incoming | Valores a entrar de teste |
GET /v1/sandbox/ledger | Extrato de teste |
GET /v1/sandbox/transactions | Depósitos e pagamentos de teste |
POST /v1/sandbox/deposits | Cria o depósito de teste, com um código de exemplo que nenhum banco paga |
GET /v1/sandbox/deposits | Lista os depósitos de teste |
GET /v1/sandbox/deposits/{id} | Situação de um depósito de teste |
POST /v1/sandbox/deposits/{id}/refresh | Como no real; no teste, não muda nada |
POST /v1/sandbox/deposits/{id}/simulate | Simula o desfecho do depósito (só no teste) |
POST /v1/sandbox/payment-links | Cria o link de teste e devolve a url da página de teste |
GET /v1/sandbox/payment-links | Lista os links de teste (?section=live, closed ou ref, como no real) |
GET /v1/sandbox/payment-links/{id} | Situação do link de teste, com os PIX (tranches) e os pagamentos com cartão (card_payments) |
POST /v1/sandbox/payment-links/{id}/cancel | Cancela o link de teste |
POST /v1/sandbox/payment-links/{id}/simulate | Simula um pagamento, a entrada no saldo, uma falha, o estorno ou o vencimento (só no teste) |
GET /v1/sandbox/webhook-events | Entregas do webhook de teste, com o resumo |
POST /v1/sandbox/webhook-events/{event_id}/redeliver | Reenvia uma entrega do webhook de teste |
POST /v1/sandbox/balance | Adiciona saldo de teste (só no teste) |
POST /v1/sandbox/reset | Zera o ambiente de testes (só no teste) |
A chave de teste e o webhook de teste só mudam na aba Testes do painel.
Simular um link de teste
POST /v1/sandbox/payment-links/{id}/simulate recebe
{"action": …} e os campos da ação; cada ação aceita só os seus campos,
e outro campo dá 422 validation_error. A resposta é o detalhe do link
depois da ação, o mesmo de GET /v1/sandbox/payment-links/{id}, e a ação
que muda um pagamento gera, no webhook de teste, o mesmo aviso do real.
| Ação | Campos | O que faz e o aviso |
|---|---|---|
plan | method: pix, card ou split; pix_cents só no split | Escolhe a forma do link both, como o menu da página de quem paga. Sem aviso |
start | Nenhum | O link aberto passa a iniciado, sem pagamento (quem paga começou e parou). No link both sem forma, grava tudo no PIX; depois dele, a forma não muda mais (plan_locked). Sem parte no PIX, dá no_pix_part. Sem aviso |
pay | method: pix | Um PIX pago, com o valor que o servidor decide; o líquido entra em valores a entrar. pagamento.recebido |
pay | method: card; installments opcional | O cartão aprovado, cobrindo o que falta da parte no cartão. pagamento.recebido |
release | seq (PIX) ou payment_id; sem eles, o pagamento recebido mais antigo | O valor recebido entra no saldo disponível de teste (no real, a liberação do PIX e o fim da carência do cartão). pagamento.liberado |
fail | method: pix; reason: vencido, cancelado, erro, recusado, parcial ou encerrado | Uma tentativa de PIX que não foi concluída, sem saldo. pagamento.falhou |
fail | method: pix; reason: devolvido; seq ou payment_id de um PIX recebido | O PIX recebido devolvido a quem pagou: sai de valores a entrar. pagamento.falhou |
fail | method: card; reason: recusado ou erro | O cartão recusado ou com erro, sem saldo. pagamento.falhou |
refund | payment_id de um cartão recebido ou liberado | O estorno do cartão: o valor sai do saldo de teste do cartão e de received_cents, e o status do link fica como está; no link aberto ou iniciado, a situation acompanha e a parte do cartão volta a ser devida. pagamento.estornado |
expire | Nenhum | O prazo do link acaba agora (o vencimento, abaixo). cobranca.cancelada, com motivo expirada |
- O
seqde cada PIX vem detranches[].seqno detalhe do link; opayment_idde cada cartão, decard_payments[].id, e o de qualquer pagamento, dopagamento_iddo aviso. - A ação fora do estado do link dá
409 invalid_statecomdetails.reason:link_not_payable(o link não aceita mais pagamento),tranche_open(já há um PIX recebido fora do saldo),nothing_due(nada a pagar nessa forma),plan_required(o cartão num linkbothsem forma),plan_locked(a forma não muda mais),plan_fixed(o link não éboth),no_pix_part(o link ficou todo no cartão),payment_not_received,payment_not_card,payment_in_flightoumethod_not_allowed(a forma que o link não aceita). - A página do link de teste. A
urldo link de teste (https://solitpmt.com/teste/pagar/…) abre uma página com a descrição, o valor, a situação e os botões PIX pago, Cartão aprovado e Cartão recusado (opaycom PIX, opaycom cartão em 1 vez e ofailcom cartãorecusado), sem PIX nem cartão de verdade. Num linkbothsem forma, cada botão grava antes a forma: PIX pago, tudo no PIX; Cartão aprovado e Cartão recusado, tudo no cartão (na simulação pela API, o cartão sem forma dáplan_required). Depois disso, a página mostra só os botões dessa forma. Mande essa URL só para quem testa: quem a tiver simula pagamentos no link.
Forma, valor de cada PIX e ciclo do link
- A forma. O link
pixé todo no PIX, e ocard, todo no cartão. Obothnasce sem forma: a açãoplanescolhe tudo no PIX (pix), tudo no cartão (card) ou uma parte em cada (split, compix_cents: pelo menos R$ 10,00 no PIX e o resto no cartão, dentro da faixa do cartão). Sem forma, o primeiro PIX e ostartescolhem tudo no PIX, e o cartão dáplan_required. Depois de um PIX, pago ou tentado, dostartou de um cartão recebido e não estornado, a forma não muda mais. - O valor de cada PIX é decidido pelo servidor, como no real: até o teto por PIX
(R$ 6.000,00), sem
deixar um resto abaixo de R$ 10,00, e um PIX por vez. Com o teto de R$ 6.000,00, um link de
R$ 6.005,00 sai em R$ 5.995,00 e R$ 10,00; enquanto um PIX recebido não entra no saldo, outro
paycom PIX dátranche_open. - O ciclo.
open: ninguém começou a pagar.started: quem paga começou (informou o CPF/CNPJ ou gerou um PIX), o que não quer dizer que já pagou.paid: a parte do PIX entrou toda no saldo e a do cartão foi aprovada.expired: venceu sem pagamento.canceled: cancelado. Para saber o que foi pago, usesituation,paid_cents,received_cents,tranchesecard_payments. - O vencimento (a ação
expireou o fim do prazo do link, que o ambiente de testes aplica sozinho): sem nada pago, o link ficaexpired; com parte paga, ficacanceled, com o que foi pago mantido; nos dois casos, com o avisocobranca.canceladaemotivoexpirada. Com um PIX recebido e ainda fora do saldo,expiredápayment_in_flight, e o fim do prazo espera esse PIX entrar no saldo (release) ou ser devolvido. - O cancelamento
(
POST /v1/sandbox/payment-links/{id}/cancel) segue o real: o aberto no prazo e o iniciado sem PIX recebido são cancelados, com o avisocobranca.canceladaemotivocancelada; com um PIX recebido e ainda fora do saldo, a resposta é409 tranche_in_flight.
Depósitos de teste
POST /v1/sandbox/depositsrecebe o corpo do real (amount_centsepayer_document) e exigeIdempotency-Key. O CPF/CNPJ só passa pela conferência dos dígitos e fica guardado mascarado, e o valor segue a faixa do real (R$ 10,00 a R$ 6.000,00). Opix_copy_pasteé um código de exemplo fixo (SOLIT-TESTE-NAO-PAGAVEL-…), que não é um PIX: nenhum banco o paga, e oqr_urlvemnull.POST /v1/sandbox/deposits/{id}/simulatecom{"action": …}:pay(o PIX pago no prazo: o líquido entra em valores a entrar),release(entra no saldo disponível de teste),failcomreasonvencido,devolvidoouerro, eexpire(o código vence sem pagamento). Fora do estado,409 invalid_state. Como no real, o depósito não gera aviso no webhook.
Saldo de teste
- São dois saldos de teste, como na conta real: o dos PIX e depósitos, que
/v1/sandbox/account, o extrato e as transações mostram, e o do cartão, em reais, que a API da conta não mostra (ele só entra emincoming_centsenquanto está a entrar). A aba Testes mostra os dois. - PIX ou depósito recebido: o líquido entra em valores a entrar;
release: passa ao disponível; devolvido: sai de valores a entrar. Cartão aprovado: entra a entrar no saldo do cartão;release: passa ao disponível do cartão; estorno: sai do saldo do cartão. As taxas são as do real. - Adicionar saldo:
POST /v1/sandbox/balancecom{"amount_cents": …}, de 1 a 10.000.000 (até R$ 100.000,00 por vez), soma ao disponível dos PIX e depósitos (no extrato, como ajuste). O disponível de teste não passa de R$ 1.000.000,00: acima disso,409 invalid_statecomsandbox_balance_cap. - Zerar:
POST /v1/sandbox/reset(ou Zerar ambiente de testes, na aba Testes) começa do zero: os links, depósitos, pagamentos, o saldo e as entregas de antes saem de vista (os ids antigos dão404 not_found), os links vivos são cancelados sem aviso e as entregas pendentes param. A chave e o webhook de teste continuam. - Tetos de uso. O ambiente de testes de cada conta tem um teto de uso para
sempre: 10.000 links, 10.000 depósitos, 50.000 pagamentos, 50.000 avisos, 100.000 lançamentos
no saldo, 50.000 chaves de idempotência e 20 falhas por link. Cada
Idempotency-Keynova que fica gravada (veja a idempotência no teste, abaixo) conta no teto de chaves; a repetição de uma chave já gravada não conta. Zerar não devolve o que já foi usado. Passou do teto, a resposta é409 invalid_statecomdetails.reasonsandbox_quotaedetails.resource(links,deposits,payments,entries,events,keysoulink_failures). A aba Testes mostra o uso.
Webhook de teste
- URL e segredo próprios, configurados na aba Testes, sem a senha; o segredo aparece uma única
vez. O corpo, os cabeçalhos e a assinatura são os do
webhook da conta (
solit_v1, assinado com o segredo de teste), com"teste": truenodata, e os eventos são os mesmos:pagamento.recebido,pagamento.liberado,pagamento.falhou,pagamento.estornadoecobranca.cancelada, na mesma ordem por referência. Sem URL de teste, nenhum aviso de teste nasce. - A URL segue as regras da real: HTTPS público, porta 443 ou a partir de 1024, sem
redirecionamento.
localhoste as redes internas são recusados: para receber no seu computador, use um túnel com HTTPS público. Os domínios da solitpmt e das provedoras também são recusados. - Entrega: até 6 tentativas, em 15 s, 1 min, 5 min, 15 min e 1 h (cerca de 1 h 20 min ao todo), esperando a resposta por até 10 s; o webhook real faz até 48 tentativas e espera 15 s. Com os avisos pausados pela solitpmt, as entregas de teste também esperam.
- Enviar evento de teste (aba Testes) manda na hora um
webhook.testepara a URL de teste, assinado com o segredo de teste. O histórico e o reenvio sãoGET /v1/sandbox/webhook-eventsePOST /v1/sandbox/webhook-events/{event_id}/redeliver, como no real.
Idempotência no teste
POST /v1/sandbox/payment-linksePOST /v1/sandbox/depositsexigemIdempotency-Key, como no real, com chaves só do teste: a mesma chave no teste e no real não se misturam. No teste, a mesma chave no link e no depósito dá422 idempotency_mismatch.- A mesma chave com o mesmo corpo devolve a resposta gravada, com o cabeçalho
Idempotent-Replay: true, sem executar de novo: o recurso na situação atual (o link comurl: null; o depósito sem o código de exemplo) ou o mesmo erro4xxdefinitivo (no link, comoterms_required,409 too_many_pendingou umvalidation_errordo valor). Para tentar de novo depois de corrigir, use uma chave nova. A mesma chave com outro corpo dá422 idempotency_mismatch. - Não ficam gravados, e a mesma chave pode ser repetida: o
422do formato do corpo (campo a mais ou de outro tipo), o do CPF/CNPJ e o do valor no depósito,409 conflict(a referência em uso), o409 invalid_statedo teto de chaves (sandbox_quotacomresourcekeys),429 rate_limited,404 not_founde os5xx. - No teste, a chave vale até zerar (no real, 24 horas no link e 7 dias no depósito), e não existe
o
409 idempotency_in_progressdo real: o pedido simultâneo com a mesma chave espera o primeiro e responde como repetição.
O que é diferente do real
- Nada entra no saldo sozinho: a liberação do PIX e o fim da carência do cartão são a ação
release. Orelease_etae ograce_untilsó informam quando seria no real. - Não existem no teste: as pausas do sistema (
charges_paused,deposits_pausedecard_payments_paused), o limite de 10 pagadores diferentes por dia no PIX, o cartão indisponível (no teste, o cartão está sempre disponível), o limite de 3 PIX sem pagamento em 24 horas, a espera do cancelamento enquanto um PIX gerado não vence, a declaração de recebimento e o409 refund_insufficient_balance(nada tira reais do saldo de teste). - No depósito de teste, também não existem o limite de 24 horas por CPF/CNPJ, a trava do
documento e os limites de valor da sua conta:
document_busyedaily_limit_exceeded, da tabela de erros da API da sua conta, não saem no teste. - No real, o link iniciado e pago em parte só é encerrado 30 dias depois do prazo; no teste, o
vencimento (o fim do prazo ou a ação
expire) já o encerra, comocanceled, com o que foi pago mantido. - O que o real tem e o teste não produz: as situações
pix_geradoecartao_em_andamento, os PIXaguardandoepix_vencido, os pagamentos com cartãoprocessing,in_analysis,refunding,awaiting_card,expiredecanceled, e o depósitorefunding. O seu código precisa tratá-los, mas o teste não os mostra. Já asituationpix_vencidosai no teste: é a do link iniciado, sem nada pago, depois de um PIX não concluído (uma falha ou um PIX devolvido). - Os limites de uso são próprios: no teste, a criação de links e a de depósitos aceitam 1 a cada 2 s e 120 por hora (no real, 1 a cada 5 s e 30 por hora no link e 1 a cada 12 s e 20 por hora no depósito); a simulação, 10 a cada 10 s e 600 por hora; adicionar saldo e zerar, 1 a cada 3 s e 60 por hora; e o conjunto das rotas de teste, 120 requisições por minuto.
Ir para o real
- Troque a chave de teste pela chave real (aba Integração), a base
/v1/sandboxpor/v1/cliente o segredo do webhook de teste pelo do webhook da conta: são diferentes, como as URLs. - No servidor de produção, não entregue nada por evento com
teste: true: na URL real, só owebhook.testedo botão Enviar evento de teste vem assim. - Os ids do teste não existem no real:
GET /v1/client/payment-links/{id}com o id de um link de teste dá404 not_found.
curl -X POST https://solitpmt.com/v1/sandbox/payment-links \
-H "X-Api-Key: slt_test_..." \
-H "Idempotency-Key: teste-link-0001" \
-H "Content-Type: application/json" \
-d '{"amount_cents": 25000,
"description": "Pedido de teste",
"external_ref": "pedido-teste-1"}'
→ 201 {"id": "0193a1c4-...", "status": "open", "external_ref": "pedido-teste-1",
"url": "https://solitpmt.com/teste/pagar/…", "teste": true, …}
O PIX pago (chega pagamento.recebido no webhook de teste):
curl -X POST https://solitpmt.com/v1/sandbox/payment-links/0193a1c4-.../simulate \
-H "X-Api-Key: slt_test_..." \
-H "Content-Type: application/json" \
-d '{"action": "pay", "method": "pix"}'
→ 200 {"status": "started", "situation": "pago_a_liberar",
"tranches": [{"seq": 1, "status": "a_entrar", …}], "teste": true, …}
O valor entra no saldo de teste (chega pagamento.liberado):
curl -X POST https://solitpmt.com/v1/sandbox/payment-links/0193a1c4-.../simulate \
-H "X-Api-Key: slt_test_..." \
-H "Content-Type: application/json" \
-d '{"action": "release", "seq": 1}'
→ 200 {"status": "paid", "situation": "concluido",
"tranches": [{"seq": 1, "status": "creditado", …}], "teste": true, …}
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
- Crie a sua conta em
/registrar(ou entre na que você já tem). - 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.
- 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).
- Ainda em Integração, gere o segredo do webhook e salve a URL
https://que vai receber os avisos. - Crie a cobrança com
POST /v1/merchant/chargese mostre o PIX ao pagador. - Trate os eventos
pagamento.recebidoepagamento.liberadoconferindo 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"}'
Onde gerar a chave, no painel:
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/produtosvirahttps://loja.com.br, e o painel mostra o valor gravado. - Só
https://com domínio público: IP,localhoste 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"},
...
}
Na página de pagamento, quem paga vê:
Pagamento para Loja da Maria
lojadamaria.com.br
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-Typeapplication/jsonem 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"}
]
}
key é a chave usada na chamada
(site_id: null = vale para todos os sites) e sites traz os
seus sites ativos.
Conferência rápida da integração:
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_centsObrigatório- Inteiro de 1000 (R$ 10,00) a 10000000 (R$ 100.000,00).
payer_documentObrigatório- CPF ou CNPJ de quem paga, com dígitos verificadores válidos.
external_refObrigatório- Sua referência (1 a 100 caracteres, sem espaços). É única por conta.
descriptionOpcional- Até 200 caracteres; aparece para o pagador.
expires_in_hoursOpcional- Validade da cobrança, de 1 a 720 horas (padrão 24).
site_idOpcional- 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.
statusopen,started,paid,expiredoucanceled(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_cursorda 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) oufailed(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 aconfirmede você recebepagamento.liberado). Não existem outros valores.confirmedeconfirmed_atmarcam a liberação da parcela, o mesmo marco do eventopagamento.liberado.POST /v1/merchant/charges/{id}/tranchesgera a próxima parcela, ou um novo PIX quando o anterior expirou ou falhou.- A página
payment_urlfaz 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:
situation | Significado |
|---|---|
aguardando | Esperando pagamento (inclusive pagamento parcial). |
recebido | O cliente pagou a parcela atual; a liberação chega cerca de 24 h depois. |
liberado | Cobrança quitada e liberada. Só aparece com o valor total pago. |
falhou | O PIX falhou ou expirou sem pagamento. |
cancelado | Cobrança cancelada. |
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.
| Evento | Quando |
|---|---|
pagamento.recebido | Em todo pagamento, assim que o cliente paga. |
pagamento.liberado | Cerca de 24 h depois (D+1), quando a parcela é liberada. Traz os totais atualizados. |
pagamento.falhou | O PIX foi devolvido, expirou ou deu erro. |
cobranca.cancelada | A cobrança foi cancelada. |
- A ordem é garantida por referência:
liberadonunca chega antes derecebidoda mesma parcela. - O mesmo
event_idpode 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-eventslista as entregas;POST /v1/merchant/webhook-events/{id}/redeliverreenvia uma delas.valor_centsé o valor pago emrecebido, o valor da parcela emliberado/falhouenullemcancelado.
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_centsObrigatório- Inteiro (ou texto só com dígitos) de 1000 a 10000000.
documentoObrigatório- CPF ou CNPJ do pagador, com dígitos verificadores válidos.
referencia_externaObrigatório- Sua referência única.
descricao / validade_horasOpcionais- 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.
| HTTP | code | Quando |
|---|---|---|
| 400 | bad_request | JSON malformado |
| 401 | unauthorized | chave ausente ou inválida |
| 404 | not_found | cobrança inexistente ou de outra conta |
| 409 | invalid_state, tranche_open, tranche_in_flight, order_locked, nothing_due | a operação não cabe no estado atual |
| 409 | account_not_ready | a conta que recebe ainda não pode receber; tente mais tarde |
| 409 | document_busy | outra cobrança com o mesmo CPF/CNPJ está sendo gerada; tente de novo em instantes |
| 409 | account_frozen | a conta que recebe está em revisão; fale com o suporte |
| 413 / 415 | payload_too_large, unsupported_media_type | corpo acima de 64 KiB ou sem JSON |
| 422 | validation_error, invalid_document, idempotency_mismatch, provider_rejected, provider_blocked | dados inválidos ou recusados pela provedora |
| 429 | rate_limited | limite de uso; respeite Retry-After |
| 502 / 504 | provider_unavailable, provider_timeout | a provedora não respondeu; nada foi cobrado |
| 503 | feature_paused, service_unavailable | serviço pausado temporariamente |
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).
| Regra | Limite |
|---|---|
| Rotas de integração | 120 requisições por minuto por chave |
| Criação de links de pagamento | 1 a cada 5 s e 30 por hora, por conta |
| Reenvio de entregas do webhook | 10 por minuto e 100 por hora |
Ambiente de testes (/v1/sandbox) | Limites próprios: veja Ambiente de testes |
| Criação de cobranças | 30 por minuto por chave |
| Página de pagamento | 1 novo PIX a cada 8 s por link |
Toda resposta da API tem Cache-Control: no-store e o cabeçalho X-Request-Id.
Precisa de ajuda?
Veja o status dos serviços.
Contato: suporte@solitpmt.com.br