Kinetic Flow|API Documentation

Developer Documentation

Everything you need to integrate Flow's payment API. From quickstart to production in minutes.

Base URL: https://api.kinetic.dev

API Version: 2026-04-01

Quickstart

Get from zero to first payment in 4 steps. This guide uses the TypeScript SDK, but the same flow works with any of our 6 supported languages.

Install the SDK

bash

npm install @kinetic/flow

Initialize the client

typescript

import Kinetic from '@kinetic/flow';

const flow = new Kinetic({
  apiKey: process.env.KINETIC_API_KEY,
});

Create a payment

typescript

const payment = await flow.payments.create({
  amount: 25000,
  currency: 'usd',
  rail: 'auto',
  destination: {
    routing_number: '021000021',
    account_number: '****7890',
  },
  idempotencyKey: 'pay_abc123',
});

console.log(payment.id);     // pay_1a2b3c4d
console.log(payment.status); // completed
console.log(payment.rail);   // fednow

Listen for webhooks

typescript

// Express.js example
app.post('/webhooks/flow', (req, res) => {
  const event = flow.webhooks.verify(
    req.body,
    req.headers['kinetic-signature'],
    process.env.WEBHOOK_SECRET
  );

  switch (event.type) {
    case 'payment.completed':
      // Handle successful payment
      break;
    case 'payment.failed':
      // Handle failure
      break;
  }

  res.json({ received: true });
});

Authentication

All API requests require a Bearer token in the Authorization header. Use sk_test_ keys for sandbox and sk_live_ keys for production.

bash

curl https://api.kinetic.dev/v1/payments \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json"

Security: Never expose your API keys in client-side code. Always make API calls from your server.

API Reference

Core endpoints for payments, tokenization, webhooks, and events. All endpoints accept and return JSON.

POST/v1/payments

Create a new payment

Request

{
  "amount": 25000,
  "currency": "usd",
  "rail": "auto",
  "idempotency_key": "pay_abc123",
  "destination": {
    "routing_number": "021000021",
    "account_number": "****7890"
  },
  "metadata": {
    "invoice_id": "inv_001"
  }
}

Response

{
  "id": "pay_1a2b3c4d",
  "object": "payment",
  "status": "completed",
  "amount": 25000,
  "currency": "usd",
  "rail": "fednow",
  "destination": {
    "routing_number": "021000021",
    "account_number": "****7890"
  },
  "settled_at": "2026-04-15T09:14:02Z",
  "created_at": "2026-04-15T09:14:01Z"
}

Webhooks

Flow sends webhook events for every payment state change. Events are signed with HMAC-SHA256 and delivered with automatic retries (exponential backoff, up to 72 hours).

Payment Events

payment.created
payment.processing
payment.completed
payment.failed
payment.refunded

Other Events

refund.created
refund.completed
token.created
token.updated
payout.completed

Error Codes

Flow uses standard HTTP status codes. All error responses include a machine-readablecode and human-readable message.

Code	Name	Description
400	Bad Request	The request body is malformed or missing required fields.
401	Unauthorized	Invalid or missing API key.
403	Forbidden	The API key does not have permission for this operation.
404	Not Found	The requested resource does not exist.
409	Conflict	Idempotency conflict — a different request body was sent with the same key.
429	Rate Limited	Too many requests. Retry after the Retry-After header value.
500	Server Error	An unexpected error occurred. Contact support if this persists.

Ready to integrate?

Get sandbox API keys and start building today.