New · Instant Pix in Brazil
sparkio
Start now

Developers

Integrate in an afternoon.

One REST API, typed SDKs in ten languages, webhooks you can replay and a sandbox that behaves like production. Most teams take their first test payment before lunch.

Start nowTalk to sales
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" }

Quickstart

Four steps from zero to a live payment.

Keys, one request, one webhook, one switch. The sandbox uses the same endpoints and the same event shapes as production.

  1. 01

    Get sandbox keys

    Create an account and copy the test secret key from the dashboard. Test keys start with sk_test_ and never move real money.

    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

    Create a payment

    Amounts are integers in the smallest unit. The response carries the status, so a synchronous card payment is done in one call.

    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

    Handle the webhook

    Asynchronous methods such as Pix, boleto and bank debits finish later. Verify the signature, then act on the event — never on the redirect.

    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

    Go live

    Accept your proposal, finish business verification, then swap the key and keep the code. Live keys start with sk_live_; nothing else in the integration changes.

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

# Same endpoints, same event shapes.

SDKs

Typed clients for the stack you already have.

Every SDK is generated from the same API description, so the names match the reference and each other.

  • Node

    npm install sparkio — TypeScript types, ESM and CJS, fetch-based.

  • Python

    pip install sparkio — sync and async clients, 3.9 and later.

  • Go

    go get github.com/sparkio/sparkio-go — context-aware, zero dependencies.

  • PHP

    composer require sparkio/sparkio-php — PSR-18 client, PHP 8.1 and later.

  • Ruby

    gem install sparkio — Rails generators for webhooks included.

  • Java

    com.sparkio:sparkio-java — Java 17 and later, Kotlin-friendly.

  • iOS

    Swift Package with a drop-in checkout sheet and Apple Pay. Beta.

  • Android

    Kotlin library with a checkout sheet and Google Pay. Beta.

  • React Native

    One checkout component for both platforms, wrapping the native SDKs. Beta.

  • Flutter

    Dart package with the same checkout sheet and platform channels. Beta.

API reference

Eight resources. Predictable verbs.

Every object has the same shape everywhere it appears: in a response, in a list and inside a webhook. Idempotency keys on every POST, cursor pagination on every list.

  • JSON over HTTPS, bearer or basic auth with your secret key
  • Idempotency-Key header on every write
  • Cursor pagination with a stable order
  • Versioned by date; old versions keep working
Get your sandbox keys
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

Signed events for every state change.

Each event is delivered with an HMAC signature and a timestamp, retried with backoff for three days, and kept in a log you can read and replay from the dashboard.

  • HMAC-SHA256 signature on every delivery
  • Retries with backoff for 72 hours
  • Replay any event from the log
  • One endpoint per environment, as many as you need
Read the quickstart
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"
  }
}

Changelog

What changed, and when.

  1. Simulated

    Instant Pix settlement in Brazil

    Pix payments now settle to your BRL balance as they are confirmed. No change to the API; payout.paid events arrive sooner.

  2. Simulated

    Idempotency keys on refunds

    POST /v1/payments/:id/refunds accepts an Idempotency-Key header. Retried requests return the original refund instead of creating a second one.

  3. Simulated

    Event replay from the dashboard

    Any event in the delivery log can be replayed to one endpoint. Replays carry a fresh signature and the original event id.

Status

All systems, in one place.

  • APIOperational
  • CheckoutOperational
  • DashboardOperational
  • PayoutsOperational
  • WebhooksOperational
99.99% uptime targetplaceholder

Simulated board. The public status page reports real incidents and maintenance windows.

Questions

Questions from developers.

How do I get sandbox keys?
Create an account. Test keys are available immediately in Dashboard → Developers, before any activation step, and they never move real money.
Do the sandbox and production differ?
Only in the key prefix. Endpoints, event types and object shapes are identical; test cards and test Pix let you reproduce approvals, declines and delayed confirmations.
How are webhooks signed?
Each delivery carries a SparkIO-Signature header with a timestamp and an HMAC-SHA256 of the raw body. The SDKs verify it in one call; the reference documents the manual check.
What happens when my endpoint is down?
Deliveries retry with exponential backoff for 72 hours. Everything is kept in the delivery log and can be replayed later, so a deploy never loses an event.
How is the API versioned?
By date, pinned per account. New versions are opt-in; older versions keep working, and breaking changes are listed in the changelog before they ship.

Get your sandbox keys.

Test cards, test Pix and a sandbox that behaves like production. No card required.

Start nowTalk to sales