Pular para o conteúdo
solitpmt

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.

Links úteis

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.

ItemValor
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
Prazo de liberação24 h (D+1), garantido pela Solit
Depósito próprioR$ 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
Saque mínimoR$ 10,00
Saque máximo por pedidoR$ 5.000,00
Limite diário de saqueR$ 5.000,00 e 2 saques por dia
GET /v1/public/pricing
{
  "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,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.

Exemplo
{
  "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".

Esqueci a senha

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.
Exemplo de valores
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.

No painel
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.
Exemplos de valores
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.

Exemplo de valores
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.
apelido Opcional
Até 40 caracteres, para achar a chave na hora do saque.
Como aparece
Conta principal · E-mail jo***@exemplo.com
Titular: Maria Souza · ***.***.*89-01

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.
Exemplo de aviso

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.

RotaO que faz
GET /v1/client/accountSaldo disponível, reservado e valores a entrar
GET /v1/client/summaryResumo do período (?days= de 1 a 90; padrão 30)
GET /v1/client/incomingValores a entrar, com o total líquido
GET /v1/client/ledgerExtrato da conta
GET /v1/client/transactionsDepósitos, saques e transferências (?type=, ?range=, ?q=)
POST /v1/client/depositsCria o depósito e devolve o PIX copia e cola e o QR
GET /v1/client/depositsLista os seus depósitos
GET /v1/client/deposits/{id}Situação de um depósito
POST /v1/client/deposits/{id}/refreshPede uma nova consulta à provedora
POST /v1/client/payment-linksCria o link de pagamento e devolve a url da página de pagamento da solitpmt
GET /v1/client/payment-linksLista 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}/cancelCancela o link (o que já foi pago continua no saldo)
GET /v1/client/webhook-eventsEntregas do webhook da conta, com o resumo (?status=, paginado)
POST /v1/client/webhook-events/{event_id}/redeliverReenvia 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/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).
  • 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 trazem external_ref (ou null), o item do link em GET /v1/client/incoming a traz em charge.external_ref, e o aviso do webhook, em referencia_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: items traz todos os links da conta com essa referência, em qualquer situação, do mais novo ao mais antigo (até 100, com next_cursor: null). Aceite só o item cujo external_ref é igual ao do pedido e trate um 422 como erro, nunca como "sem link". section=ref sem external_ref, ou external_ref sem section=ref, dá 422 validation_error. A busca é a reserva: guarde o id do 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). O 409 pode apontar para um link aberto com situation expirado (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, com cobranca.cancelada. Ligue os avisos ao pedido pelo link_id: a referencia_externa é só o rótulo do pedido e pode repetir entre um link encerrado e o novo (o cobranca.cancelada do link vencido que a criação encerra chega depois do 201 do novo).
  • 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, 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 (plan e card) e card_payments. Antes de entregar, confira o detalhe.
  • Em /v1/client/transactions, type aceita all, deposits, payments e withdrawals; range aceita all, today, 7d e 30d.
  • 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/incoming e /v1/client/transactions são só PIX e depósitos: acompanhe o cartão pelo card_payments do 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ódigoQuando
401 unauthorizedChave ausente, revogada, amarrada a um site ou de outro tipo
403 account_disabledConta desativada
409 account_frozenConta em revisão; fale com o suporte
409 account_not_readyA conta ainda está sendo preparada; tente em instantes
400 idempotency_key_requiredDepósito ou link sem Idempotency-Key
409 too_many_pendingJá há 10 links em aberto
422 validation_errorCampo 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 conflictCom 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_stateCom 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_stateCom details.reason card_unavailable: esta conta não pode receber pagamento com cartão agora (link com card ou both)
409 invalid_stateCom 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_busyOutra operação com o mesmo CPF/CNPJ em andamento; tente em instantes
422 daily_limit_exceededPassou do limite de 24 horas do CPF/CNPJ; details.remaining_cents diz quanto ainda cabe
503 feature_pausedFunçã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)
Saldo e primeiro depósito
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

  1. No painel, abra Integração e, em Webhook, informe a URL do webhook e a sua senha e clique em Salvar.
  2. 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.
  3. Clique em Enviar evento de teste e veja a resposta do seu servidor.
  4. Trate os avisos: confira a assinatura, responda 2xx e 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 301 nem 302, que contam como falha. Cadastre a URL final, com certificado válido.

Eventos

EventoO que quer dizer
pagamento.recebidoNo 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.liberadoNo 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.falhouNo 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.estornadoNo 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.canceladaO 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.testeO evento de teste do painel. Nunca vem de um pagamento.

Criar o link e gerar o PIX não geram aviso.

Linha do tempo

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, chega pagamento.falhou com motivo devolvido.
  • PIX, no pagamento.liberado. O valor entrou no seu saldo, cerca de 24 horas depois do pagamento (situation concluido). É 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 em grace_until, nos card_payments do detalhe), e o pagamento.liberado chega quando ela acaba. Sem carência, o pagamento.liberado chega logo depois do pagamento.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 o status do link não muda (um link paid continua paid, com a situation concluido). Na consulta, o pagamento estornado fica com status refunded em card_payments e sai de received_cents; no link ainda aberto ou iniciado, a situation acompanha 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.

pagamento.recebido de um PIX
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_id nos eventos de pagamento e o link_id em cobranca.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 id do link, o mesmo de GET /v1/client/payment-links/{id}.
referencia_externa
O external_ref do link, a referência do seu pedido informada na criação (veja API da sua conta), ou null no link sem ela e no evento de teste. Ligue o aviso ao pedido pelo link_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.
metodo
pix ou cartao; null em cobranca.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 id em card_payments). null em cobranca.cancelada.
valor_cents
A parte do valor do link que este pagamento cobre, antes das taxas: no PIX, o valor pago no recebido e o valor do PIX no liberado e no falhou. null em cobranca.cancelada.
link_valor_cents
O valor do link.
status
recebido, liberado, falhou, estornado ou cancelado (teste no evento de teste).
motivo
Em pagamento.falhou e cobranca.cancelada (tabela abaixo); null nos outros eventos.
teste
true no evento de teste (webhook.teste) e em todo evento do ambiente de testes; false nos eventos de pagamentos de verdade. Em produção, não entregue nada por evento com teste: 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.

motivoQuando
vencidoO código PIX venceu sem pagamento.
devolvidoO PIX foi devolvido a quem pagou.
canceladoO código PIX foi cancelado pela provedora.
recusadoO cartão foi recusado, ou o suporte não aceitou o PIX.
parcialO PIX foi pago com valor menor que o do código.
encerradoO suporte encerrou o PIX em aberto, para o cliente gerar outro.
erroErro no PIX ou no cartão.
canceladaEm cobranca.cancelada: o link foi cancelado.
expiradaEm 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.

  1. Leia o corpo bruto: os bytes, antes de interpretar o JSON.
  2. 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).
  3. Calcule o HMAC e compare com X-Solit-Signature em tempo constante.
  4. Só então interprete o JSON. Sem assinatura válida, responda 401 e não faça nada.
Python
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"))
Node.js
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ó 2xx conta 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-Timestamp e assinatura novos; o event_id e o corpo são os mesmos.
  • O mesmo event_id pode 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.liberado nunca chega antes do pagamento.recebido do mesmo pagamento, nem o pagamento.estornado antes dos dois (depois de um estorno, o pagamento.liberado nã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 o cobranca.cancelada do link), a ordem não é garantida.

Boas práticas

  • Responda 2xx em 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 responda 2xx ao repetido, sem tratá-lo de novo.
  • Antes de entregar, reconsulte o link com GET /v1/client/payment-links/{id} (o link_id do aviso) e decida pela situation. 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 com teste: true: o webhook.teste e 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.
Node.js (Express): responder rápido, deduplicar e reconsultar
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.teste com 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 é teste e o data traz teste: 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 com 503 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-events lista as entregas, da mais nova para a mais antiga (?status= com pending, delivered ou dead, separados por vírgula; ?limit= até 100; ?cursor=), com o resumo em summary, e POST /v1/client/webhook-events/{event_id}/redeliver reenvia uma entrega, com 202. 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_id e o mesmo data, com horário e assinatura novos. Até a primeira tentativa nova, a entrega fica pending com attempts 0, e last_http_status e last_error ainda 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 respondeu 2xx) ou dead (esgotou as tentativas), e last_error traz 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 (como ConnectTimeout), waiting_previous_event (esperando o evento anterior da mesma referência), webhook_not_configured (webhook desligado) ou webhooks_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.
Entregas e reenvio pela chave
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 com POST /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.cancelada e motivo expirada. No vencimento, nenhum aviso sai: consulte o link (situation pago_em_parte e received_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, com details.cancel_blocked_until, e o detalhe do link traz can_cancel e cancel_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 do pagamento.recebido) e pagamento.estornado é o estorno concluído: na consulta do link, o pagamento estornado sai de received_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.falhou só chega se ele não for encontrado. Raramente, um pagamento achado depois disso é creditado pelo suporte e chega um pagamento.recebido depois do pagamento.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 (situation e received_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

  1. 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.
  2. No seu código, troque a base /v1/client por /v1/sandbox e a chave real pela de teste, no mesmo cabeçalho X-Api-Key. Os corpos, os campos e as respostas são os da conta real.
  3. 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 recebe 401 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: a url do link aponta para a página de teste, e o depósito traz um código de exemplo no lugar do PIX.

Rotas

RotaO que faz
GET /v1/sandbox/accountSaldo de teste, como /v1/client/account
GET /v1/sandbox/summaryResumo do período, com os dados de teste
GET /v1/sandbox/incomingValores a entrar de teste
GET /v1/sandbox/ledgerExtrato de teste
GET /v1/sandbox/transactionsDepósitos e pagamentos de teste
POST /v1/sandbox/depositsCria o depósito de teste, com um código de exemplo que nenhum banco paga
GET /v1/sandbox/depositsLista os depósitos de teste
GET /v1/sandbox/deposits/{id}Situação de um depósito de teste
POST /v1/sandbox/deposits/{id}/refreshComo no real; no teste, não muda nada
POST /v1/sandbox/deposits/{id}/simulateSimula o desfecho do depósito (só no teste)
POST /v1/sandbox/payment-linksCria o link de teste e devolve a url da página de teste
GET /v1/sandbox/payment-linksLista 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}/cancelCancela o link de teste
POST /v1/sandbox/payment-links/{id}/simulateSimula um pagamento, a entrada no saldo, uma falha, o estorno ou o vencimento (só no teste)
GET /v1/sandbox/webhook-eventsEntregas do webhook de teste, com o resumo
POST /v1/sandbox/webhook-events/{event_id}/redeliverReenvia uma entrega do webhook de teste
POST /v1/sandbox/balanceAdiciona saldo de teste (só no teste)
POST /v1/sandbox/resetZera 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çãoCamposO que faz e o aviso
planmethod: pix, card ou split; pix_cents só no splitEscolhe a forma do link both, como o menu da página de quem paga. Sem aviso
startNenhumO 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
paymethod: pixUm PIX pago, com o valor que o servidor decide; o líquido entra em valores a entrar. pagamento.recebido
paymethod: card; installments opcionalO cartão aprovado, cobrindo o que falta da parte no cartão. pagamento.recebido
releaseseq (PIX) ou payment_id; sem eles, o pagamento recebido mais antigoO 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
failmethod: pix; reason: vencido, cancelado, erro, recusado, parcial ou encerradoUma tentativa de PIX que não foi concluída, sem saldo. pagamento.falhou
failmethod: pix; reason: devolvido; seq ou payment_id de um PIX recebidoO PIX recebido devolvido a quem pagou: sai de valores a entrar. pagamento.falhou
failmethod: card; reason: recusado ou erroO cartão recusado ou com erro, sem saldo. pagamento.falhou
refundpayment_id de um cartão recebido ou liberadoO 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
expireNenhumO prazo do link acaba agora (o vencimento, abaixo). cobranca.cancelada, com motivo expirada
  • O seq de cada PIX vem de tranches[].seq no detalhe do link; o payment_id de cada cartão, de card_payments[].id, e o de qualquer pagamento, do pagamento_id do aviso.
  • A ação fora do estado do link dá 409 invalid_state com details.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 link both sem 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_flight ou method_not_allowed (a forma que o link não aceita).
  • A página do link de teste. A url do 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 (o pay com PIX, o pay com cartão em 1 vez e o fail com cartão recusado), sem PIX nem cartão de verdade. Num link both sem 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 o card, todo no cartão. O both nasce sem forma: a ação plan escolhe tudo no PIX (pix), tudo no cartão (card) ou uma parte em cada (split, com pix_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 o start escolhem tudo no PIX, e o cartão dá plan_required. Depois de um PIX, pago ou tentado, do start ou 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 pay com 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, use situation, paid_cents, received_cents, tranches e card_payments.
  • O vencimento (a ação expire ou o fim do prazo do link, que o ambiente de testes aplica sozinho): sem nada pago, o link fica expired; com parte paga, fica canceled, com o que foi pago mantido; nos dois casos, com o aviso cobranca.cancelada e motivo expirada. Com um PIX recebido e ainda fora do saldo, expire dá 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 aviso cobranca.cancelada e motivo cancelada; com um PIX recebido e ainda fora do saldo, a resposta é 409 tranche_in_flight.

Depósitos de teste

  • POST /v1/sandbox/deposits recebe o corpo do real (amount_cents e payer_document) e exige Idempotency-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). O pix_copy_paste é um código de exemplo fixo (SOLIT-TESTE-NAO-PAGAVEL-…), que não é um PIX: nenhum banco o paga, e o qr_url vem null.
  • POST /v1/sandbox/deposits/{id}/simulate com {"action": …}: pay (o PIX pago no prazo: o líquido entra em valores a entrar), release (entra no saldo disponível de teste), fail com reason vencido, devolvido ou erro, e expire (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 em incoming_cents enquanto 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/balance com {"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_state com sandbox_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ão 404 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-Key nova 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_state com details.reason sandbox_quota e details.resource (links, deposits, payments, entries, events, keys ou link_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": true no data, e os eventos são os mesmos: pagamento.recebido, pagamento.liberado, pagamento.falhou, pagamento.estornado e cobranca.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. localhost e 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.teste para a URL de teste, assinado com o segredo de teste. O histórico e o reenvio são GET /v1/sandbox/webhook-events e POST /v1/sandbox/webhook-events/{event_id}/redeliver, como no real.

Idempotência no teste

  • POST /v1/sandbox/payment-links e POST /v1/sandbox/deposits exigem Idempotency-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 com url: null; o depósito sem o código de exemplo) ou o mesmo erro 4xx definitivo (no link, como terms_required, 409 too_many_pending ou um validation_error do 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 422 do 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), o 409 invalid_state do teto de chaves (sandbox_quota com resource keys), 429 rate_limited, 404 not_found e os 5xx.
  • 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_progress do 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. O release_eta e o grace_until só informam quando seria no real.
  • Não existem no teste: as pausas do sistema (charges_paused, deposits_paused e card_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 o 409 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_busy e daily_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, como canceled, com o que foi pago mantido.
  • O que o real tem e o teste não produz: as situações pix_gerado e cartao_em_andamento, os PIX aguardando e pix_vencido, os pagamentos com cartão processing, in_analysis, refunding, awaiting_card, expired e canceled, e o depósito refunding. O seu código precisa tratá-los, mas o teste não os mostra. Já a situation pix_vencido sai 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

  1. Troque a chave de teste pela chave real (aba Integração), a base /v1/sandbox por /v1/client e o segredo do webhook de teste pelo do webhook da conta: são diferentes, como as URLs.
  2. No servidor de produção, não entregue nada por evento com teste: true: na URL real, só o webhook.teste do botão Enviar evento de teste vem assim.
  3. 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.
Um link de teste do começo ao fim
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)

Limites de uso

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

RegraLimite
Rotas de integração120 requisições por minuto por chave
Criação de links de pagamento1 a cada 5 s e 30 por hora, por conta
Reenvio de entregas do webhook10 por minuto e 100 por hora
Ambiente de testes (/v1/sandbox)Limites próprios: veja Ambiente de testes

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

Precisa de ajuda?