Novo · Pix na hora no Brasil
sparkio
Comece

Desenvolvedores

Integre em uma tarde.

Uma API REST, SDKs tipados em dez linguagens, webhooks que você pode reenviar e um sandbox que se comporta como produção. A maioria das equipes faz o primeiro pagamento de teste antes do almoço.

Comece agoraFale com vendas
Create a paymentPOST /v1/payments
# Create and capture a card paymentcurl https://api.sparkio.com/v1/payments \  -u sk_test_51Hb9…: \  -H "Content-Type: application/json" \  -d '{    "amount": 24900,    "currency": "usd",    "payment_method": "pm_card_visa",    "capture": true  }'# 201 Created{ "id": "pay_1QzP0e", "status": "succeeded" }

Início rápido

Quatro passos do zero a um pagamento em produção.

Chaves, uma requisição, um webhook, uma troca. O sandbox usa os mesmos endpoints e os mesmos formatos de evento que a produção.

  1. 01

    Obtenha as chaves de sandbox

    Crie uma conta e copie a chave secreta de teste no painel. As chaves de teste começam com sk_test_ e nunca movimentam dinheiro real.

    shell
    export SPARKIO_SECRET_KEY=sk_test_51Hb9…
npm install sparkio

# Test cards: 4242 4242 4242 4242 approves,
# 4000 0000 0000 9995 declines. Test Pix settles instantly.

  2. 02

    Crie um pagamento

    Os valores são inteiros na menor unidade da moeda. A resposta traz o status, então um pagamento síncrono com cartão se resolve em uma chamada.

    create-payment.ts
    import SparkIO from "sparkio";
const sparkio = new SparkIO(process.env.SPARKIO_SECRET_KEY);

const payment = await sparkio.payments.create({
  amount: 24900,          // $249.00 in cents
  currency: "usd",
  payment_method: "pm_card_visa",
  capture: true,
});

payment.status; // "succeeded"

  3. 03

    Processe o webhook

    Formas de pagamento assíncronas, como Pix, boleto e débito bancário, terminam depois. Verifique a assinatura e aja a partir do evento — nunca do redirecionamento.

    webhooks.ts
    app.post("/webhooks", express.raw({ type: "*/*" }), (req, res) => {
  const event = sparkio.webhooks.verify(
    req.body,
    req.headers["sparkio-signature"],
    process.env.SPARKIO_WEBHOOK_KEY,
  );

  if (event.type === "payment.succeeded") fulfil(event.data.id);
  res.sendStatus(200);
});

  4. 04

    Entre em produção

    Aceite sua proposta, conclua a verificação da empresa, troque a chave e mantenha o código. As chaves de produção começam com sk_live_; nada mais muda na integração.

    shell
    # Proposal accepted, business verified:
export SPARKIO_SECRET_KEY=sk_live_51Hb9…

# Same endpoints, same event shapes.

SDKs

Clientes tipados para a stack que você já usa.

Todos os SDKs são gerados a partir da mesma descrição da API, então os nomes batem com a referência e entre si.

  • Node

    npm install sparkio — tipos TypeScript, ESM e CJS, baseado em fetch.

  • Python

    pip install sparkio — clientes síncrono e assíncrono, 3.9 ou posterior.

  • Go

    go get github.com/sparkio/sparkio-go — compatível com context, sem dependências.

  • PHP

    composer require sparkio/sparkio-php — cliente PSR-18, PHP 8.1 ou posterior.

  • Ruby

    gem install sparkio — inclui geradores Rails para webhooks.

  • Java

    com.sparkio:sparkio-java — Java 17 ou posterior, pronto para Kotlin.

  • iOS

    Swift Package com uma tela de checkout pronta para usar e Apple Pay. Beta.

  • Android

    Biblioteca Kotlin com tela de checkout e Google Pay. Beta.

  • React Native

    Um componente de checkout para as duas plataformas, sobre os SDKs nativos. Beta.

  • Flutter

    Pacote Dart com a mesma tela de checkout e platform channels. Beta.

Referência da API

Oito recursos. Verbos previsíveis.

Cada objeto tem o mesmo formato em todo lugar onde aparece: em uma resposta, em uma lista e dentro de um webhook. Chaves de idempotência em todo POST, paginação por cursor em toda lista.

  • JSON sobre HTTPS, autenticação bearer ou basic com a sua chave secreta
  • Cabeçalho Idempotency-Key em toda requisição de escrita
  • Paginação por cursor com ordem estável
  • Versionada por data; versões antigas continuam funcionando
Obtenha suas chaves de sandbox
API referencehttps://api.sparkio.com/v1

Payments

Authorize, capture, refund and inspect a single charge.

  • POST/v1/paymentsCreate a payment
  • GET/v1/payments/:idRetrieve a payment
  • POST/v1/payments/:id/captureCapture an authorization
  • POST/v1/payments/:id/refundsRefund all or part
  • GET/v1/paymentsList payments

Webhooks

Eventos assinados para cada mudança de status.

Cada evento chega com uma assinatura HMAC e um timestamp, tem novas tentativas com backoff por três dias e fica guardado em um registro que você pode ler e reenviar pelo painel.

  • Assinatura HMAC-SHA256 em toda entrega
  • Novas tentativas com backoff por 72 horas
  • Reenvie qualquer evento a partir do registro
  • Um endpoint por ambiente, quantos você precisar
Leia o início rápido
WebhooksPOST https://yourapp.example/webhooks

Recent events

  • payment.succeeded

    a payment is captured

    Delivered

  • payment.failed

    the last route declines

    Delivered

  • payout.paid

    funds reach your bank

    Delivered

  • dispute.opened

    a cardholder disputes a charge

    Delivered

  • subscription.renewed

    a renewal is paid

    Delivered

Signed payload

POST /webhooks HTTP/1.1
SparkIO-Signature: t=1792600867,v1=5f1c…9a2e
Content-Type: application/json

{
  "id": "evt_1R0a7q",
  "type": "payment.succeeded",
  "created": 1792600867,
  "data": {
    "id": "pay_1QzK8m",
    "amount": 24900,
    "currency": "usd",
    "status": "succeeded"
  }
}

Novidades

O que mudou, e quando.

  1. Simulado

    Liquidação instantânea de Pix no Brasil

    Os pagamentos Pix agora são liquidados no seu saldo em BRL assim que são confirmados. Nada muda na API; os eventos payout.paid chegam mais cedo.

  2. Simulado

    Chaves de idempotência em reembolsos

    POST /v1/payments/:id/refunds aceita o cabeçalho Idempotency-Key. Requisições repetidas devolvem o reembolso original em vez de criar um segundo.

  3. Simulado

    Reenvio de eventos pelo painel

    Qualquer evento do registro de entregas pode ser reenviado para um endpoint. Os reenvios levam uma assinatura nova e o id original do evento.

Status

Todos os sistemas, em um só lugar.

  • APIOperacional
  • CheckoutOperacional
  • PainelOperacional
  • RepassesOperacional
  • WebhooksOperacional
Meta de 99,99% de disponibilidadeprovisório

Quadro simulado. A página de status pública informa incidentes reais e janelas de manutenção.

Perguntas

Perguntas de desenvolvedores.

Como consigo chaves de sandbox?
Crie uma conta. As chaves de teste ficam disponíveis na hora em Painel → Desenvolvedores, antes de qualquer etapa de ativação, e nunca movimentam dinheiro real.
O sandbox e a produção são diferentes?
Só no prefixo da chave. Endpoints, tipos de evento e formatos de objeto são idênticos; cartões de teste e Pix de teste permitem reproduzir aprovações, recusas e confirmações atrasadas.
Como os webhooks são assinados?
Cada entrega traz um cabeçalho SparkIO-Signature com um timestamp e um HMAC-SHA256 do corpo bruto. Os SDKs fazem a verificação em uma chamada; a referência documenta a verificação manual.
O que acontece quando meu endpoint está fora do ar?
As entregas são tentadas de novo com backoff exponencial por 72 horas. Tudo fica no registro de entregas e pode ser reenviado depois, então um deploy nunca perde um evento.
Como a API é versionada?
Por data, fixada por conta. Novas versões são opcionais; as versões antigas continuam funcionando, e as mudanças incompatíveis aparecem nas novidades antes de entrar no ar.

Obtenha suas chaves de sandbox.

Cartões de teste, Pix de teste e um sandbox que se comporta como produção. Sem precisar de cartão.

Comece agoraFale com vendas