Quickstart Guide

Go from API key to first payment in 15 minutes. This guide walks through authentication, creating a test user, running a KYC check, and initiating your first ACH payment.

Authentication

All API requests require a bearer token. Use your sandbox key for testing — prefix sk_test_. Production keys use sk_live_.

# Set your API key in environment
export FINSYNCIO_API_KEY=sk_test_4xKmQrNpW9v2Y3bZ

$ curl https://api.finsyncio.com/v1/health \
  -H "Authorization: Bearer $FINSYNCIO_API_KEY"

{
  "status": "ok",
  "env": "sandbox"
}

KYC Verification

Before users can make or receive payments, they must pass KYC. Submit user identity data to POST /v1/users. Most identity checks complete in under 30 seconds.

$ curl -X POST \
  https://api.finsyncio.com/v1/users \
  -H "Authorization: Bearer $FINSYNCIO_API_KEY" \
  -d '{
    "first_name": "Jordan",
    "last_name": "Reyes",
    "email": "[email protected]",
    "date_of_birth": "1990-04-15",
    "ssn_last4": "4321",
    "address": {
      "line1": "400 Market St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105"
    }
  }'

# 201 Created
{
  "user_id": "usr_7Pk3nM2wQx",
  "kyc_status": "approved",
  "created_at": "2026-04-10T09:12:31Z"
}

Initiating a Payment

Once a user is KYC-approved, initiate ACH or RTP payments with POST /v1/payments/initiate. Include an idempotency key to prevent duplicate transactions.

$ curl -X POST \
  https://api.finsyncio.com/v1/payments/initiate \
  -H "Authorization: Bearer $FINSYNCIO_API_KEY" \
  -H "Idempotency-Key: my-unique-key-001" \
  -d '{
    "amount_cents": 25000,
    "currency": "usd",
    "recipient_id": "usr_7Pk3nM2wQx",
    "type": "ach_same_day"
  }'

{
  "payment_id": "pay_2RqMv8kXn",
  "status": "processing",
  "eta_hours": 4
}

Webhooks

Subscribe to payment and KYC events via the dashboard. Finsyncio signs each webhook with an HMAC-SHA256 signature in the X-Finsyncio-Signature header. Verify before processing.

// Node.js webhook verification
const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signature)
  );
}

Idempotency

All mutation endpoints accept an Idempotency-Key header. If a request with the same key is retried within 24 hours, the same response is returned without re-executing. Always use idempotency keys for payment mutations.

SDKs

npm install @finsyncio/node

pip install finsyncio

go get github.com/finsyncio/go-sdk

Sandbox Testing

The sandbox environment supports magic test values to simulate different outcomes:

SSN last 4	KYC outcome
`0000`	Instant approval
`0001`	Manual review triggered
`0002`	Identity mismatch rejection

Amount (cents)	Payment outcome
`100`	Instant cleared
`101`	Returns with R02 (account closed)
`102`	Network timeout (retry scenario)

Next: Full API Reference