PixToMe - Documentação de Integração

1. Visão geral

A PixToMe é uma plataforma non-custodial que recebe pagamentos via PIX e liquida automaticamente em DePix (stablecoin lastreada em BRL na rede Liquid Network) diretamente na carteira Liquid do cliente.

Características principais:

• Liquidação direta na carteira do cliente - a PixToMe não custodia saldo.
• Cobranças PIX dinâmicas com QR Code copia-e-cola e imagem.
• Notificação via webhook com endpoint de polling como fallback.
• Split automático da taxa no momento da liquidação.
• API REST autenticada via Bearer token.

2. Como funciona

O fluxo de uma cobrança ocorre em sete etapas:

1. Seu backend chama POST /v1/deposit com o valor e os dados do pagador.
2. A PixToMe gera um QR Code dinâmico e retorna id, qrCopyPaste e qrImageUrl.
3. Você exibe o QR para o pagador na sua interface.
4. O pagador efetua o pagamento via PIX em qualquer banco.
5. O valor é convertido em DePix e enviado diretamente para sua carteira Liquid configurada, já com as taxas descontadas.
6. A PixToMe atualiza o status da cobrança para depix_sent.
7. Seu webhook recebe o evento com o status final.

3. Configuração inicial da conta

Antes de gerar a primeira cobrança, configure os seguintes campos no painel em Dashboard → Configurações:

Aviso: a PixToMe nunca tem acesso à sua chave privada. Você é o único responsável pela segurança da sua carteira. Pagamentos são irreversíveis.

Carteira Liquid recomendada

Recomendamos a SideSwap (sideswap.io) para gerenciar sua carteira Liquid e receber DePix. É a opção mais simples para começar, com suporte nativo à Liquid Network e interface intuitiva para desktop e mobile.

4. Taxas e liquidação

Fórmula do valor líquido recebido:

1líquido = valor_cobrado − (valor_cobrado × 0,025) − R$ 0,99

Exemplo - cobrança de R$ 10,00:

110,00 − 0,25 − 0,99 = R$ 8,76 em DePix na sua carteira

O valor líquido é exibido em Dashboard → Transações para conferência.

5. Autenticação da API

Todas as chamadas exigem o header:

1Authorization: Bearer ptm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Como gerar uma chave

1. Acesse Dashboard → API & Webhooks.
2. Clique em Gerar nova chave e defina um rótulo (ex.: prod-checkout).
3. Copie a chave imediatamente - ela é exibida apenas uma vez. Apenas o prefixo (ptm_live_xxxx…) fica visível posteriormente.
4. Armazene em variável de ambiente (ex.: PIXTOME_KEY). Nunca versione no repositório.

Boas práticas

• Use chaves separadas por ambiente (dev / staging / prod).
• Revogue imediatamente qualquer chave exposta.
• Nunca exponha a chave no frontend ou em aplicativos móveis - todas as chamadas devem partir do seu backend.

6. Endpoints

Base URL: https://api.pixtome.com/v1

Todas as requisições e respostas são JSON. Valores monetários em centavos (inteiros). Datas em ISO 8601 UTC.

6.1 Criar cobrança - POST /v1/deposit

Cria uma cobrança PIX dinâmica.

Request body

cURL

1curl -X POST https://api.pixtome.com/v1/deposit \
2  -H "Authorization: Bearer $PIXTOME_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "amountInCents": 4990,
6    "endUserTaxNumber": "12345678901",
7    "endUserFullName": "João da Silva",
8    "description": "Pedido #1024"
9  }'

JavaScript (Node)

1const res = await fetch("https://api.pixtome.com/v1/deposit", {
2  method: "POST",
3  headers: {
4    Authorization: `Bearer ${process.env.PIXTOME_KEY}`,
5    "Content-Type": "application/json",
6  },
7  body: JSON.stringify({
8    amountInCents: 4990,
9    endUserTaxNumber: "12345678901",
10    description: "Pedido #1024",
11  }),
12});
13const data = await res.json();

Python

1import os, requests
2
3r = requests.post(
4    "https://api.pixtome.com/v1/deposit",
5    headers={"Authorization": f"Bearer {os.environ['PIXTOME_KEY']}"},
6    json={"amountInCents": 4990, "endUserTaxNumber": "12345678901"},
7    timeout=15,
8)
9r.raise_for_status()
10data = r.json()

Resposta - 200 OK

1{
2  "id": "dep_01HXYZ...",
3  "qrId": "qr_abc123...",
4  "qrCopyPaste": "00020126580014BR.GOV.BCB.PIX...",
5  "qrImageUrl": "https://assets.pixtome.com/qr/qr_abc123.png",
6  "amountCents": 4990,
7  "expiresAt": "2026-05-05T12:30:00Z"
8}

O QR expira em 20 minutos. Use o id retornado para consultar status e correlacionar com eventos de webhook.

6.2 Consultar status - GET /v1/deposit/:id

Retorna o estado atual da cobrança. O endpoint reconcilia automaticamente com o provedor, servindo como fonte de verdade caso o webhook não tenha sido entregue.

1curl https://api.pixtome.com/v1/deposit/dep_01HXYZ \
2  -H "Authorization: Bearer $PIXTOME_KEY"

Resposta - 200 OK

1{
2  "id": "dep_01HXYZ...",
3  "qrId": "qr_abc123...",
4  "status": "depix_sent",
5  "amount_cents": 4990,
6  "expires_at": "2026-05-05T12:30:00Z",
7  "confirmed_at": "2026-05-05T12:11:42Z",
8  "blockchain_txid": "a1b2c3...",
9  "payer_name": "João da Silva",
10  "payer_tax_number": "12345678901",
11  "recipient_address": "lq1qq..."
12}

Polling: se preferir não usar webhooks, faça polling a cada 2 segundos por até 20 minutos, encerrando ao atingir um status terminal.

6.3 Listar cobranças - GET /v1/deposits

Filtros disponíveis via query string:

1curl "https://api.pixtome.com/v1/deposits?status=depix_sent&limit=50" \
2  -H "Authorization: Bearer $PIXTOME_KEY"

7. Webhooks

A PixToMe envia eventos POST para o endpoint cadastrado em Dashboard → API & Webhooks.

Headers enviados

1POST /seu-endpoint HTTP/1.1
2Content-Type: application/json
3Authorization: Basic <base64(":seu-secret")>

Payload

1{
2  "webhookType": "deposit",
3  "qrId": "qr_abc123...",
4  "status": "depix_sent",
5  "valueInCents": 4990,
6  "payerName": "João da Silva",
7  "payerTaxNumber": "12345678901",
8  "payerEUID": "...",
9  "bankTxId": "E12345...",
10  "blockchainTxID": "a1b2c3...",
11  "customerMessage": "Pagamento confirmado",
12  "expiration": "2026-05-05T12:30:00Z"
13}

Verificação de assinatura

Valide a origem do evento comparando o secret do header com o valor configurado:

1import crypto from "node:crypto";
2
3function verify(req) {
4  const header = req.headers["authorization"] ?? "";
5  const m = header.match(/^Basic\s+(.+)$/i);
6  if (!m) return false;
7  const decoded = Buffer.from(m[1], "base64").toString("utf8");
8  const provided = decoded.includes(":") ? decoded.split(":").slice(1).join(":") : decoded;
9  const a = Buffer.from(provided);
10  const b = Buffer.from(process.env.PIXTOME_WEBHOOK_SECRET);
11  return a.length === b.length && crypto.timingSafeEqual(a, b);
12}

Boas práticas para o handler

• Responda com 2xx em até 5 segundos. Respostas fora do prazo geram retry com backoff exponencial por até 24h.
• Idempotência: processe eventos com base no par qrId + status. O mesmo evento pode ser entregue mais de uma vez.
• Sempre confronte o payload com GET /v1/deposit/:id antes de liberar produto ou serviço.
• Registre qrId, status, timestamp e resposta para fins de auditoria.

Eventos

8. Status das cobranças

O ciclo de vida de uma cobrança segue a sequência abaixo:

1pending → pending_pix2fa → delayed → under_review → depix_sent
2                                                          └→ refunded
3                                  expired / canceled / error

Status terminais (não sofrem mais alterações): depix_sent, expired, canceled, refunded, error.

A plataforma garante monotonicidade: um webhook atrasado nunca regride o status de uma cobrança.

9. Limites e regras

Limites maiores podem ser solicitados via support@pixtome.com após KYC empresarial.

10. Códigos de erro

Todas as respostas de erro seguem o formato:

1{ "error": "mensagem legível", "details": { } }

11. Boas práticas / FAQ

Posso reembolsar uma cobrança?

Não pela PixToMe. Como o DePix é entregue diretamente na sua carteira Liquid, eventuais devoluções devem ser realizadas por você na rede Liquid ou via PIX.

E se o webhook falhar?

Use GET /v1/deposit/:id como fonte de verdade. Combine o handler de webhook com polling defensivo a cada 30 segundos para cobranças pending antigas.

Posso trocar a carteira Liquid?

Sim, a qualquer momento em Configurações. Cobranças já criadas continuam apontando para o endereço configurado no momento da criação.

Como evitar cobrança duplicada?

Defina um identificador próprio no campo description e consulte GET /v1/deposits?description=<seu-id> antes de criar uma nova cobrança.

Como testar em sandbox?

O ambiente sandbox está em desenvolvimento. Enquanto não é disponibilizado, valide sua integração com cobranças de valor mínimo (R$ 10,00) em produção.

Posso chamar a API direto do frontend?

Não. A chave Bearer dá acesso total à sua conta. Todas as chamadas devem partir exclusivamente do seu backend.

Suporte

• Email: support@pixtome.com
• Site: pixtome.com
• Documentação: pixtome.com/docs