PayForgeDOCS
Dashboard
Getting Started

PayForge Documentation

Welcome to the PayForge API documentation. Learn how to integrate our payment processing platform, manage transactions, and leverage ML-powered fraud detection.

API Reference

Endpoints, parameters, and response formats

Webhooks

Real-time event notifications

Architecture

Event sourcing, CQRS, and domain design

Security

Encryption, auth, and compliance

Quick Start Guide

1Get Your API Keys

Sign in to your PayForge dashboard, navigate to Settings → API Keys, and create a new key pair. You'll receive a publishable key (pk_test_...) and a secret key (sk_test_...).

Security: Never expose your secret key in client-side code or version control. Use environment variables in production.

2Authenticate

All API requests require an Authorization header with your API key as a Bearer token.

Authentication headerbash
curl https://api.payforge.dev/api/v1/transactions \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json"

3Create Your First Transaction

Send a POST request to create a transaction. The payment will be automatically authorized and scored by the fraud engine. Include an idempotency key to safely retry requests.

Create a transaction
curl -X POST "https://api.payforge.dev/api/v1/transactions" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: idem_abc123" \
  -d '{
    "transaction": {
      "amount_cents": 5000,
      "currency": "USD",
      "card_last_four": "4242",
      "card_brand": "visa",
      "card_token": "tok_visa_4242",
      "idempotency_key": "idem_abc123"
    }
  }'

4Handle the Response

Every response follows a consistent envelope format with data, meta, and links fields.

Response (201 Created)json
{
  "data": {
    "id": "a1b2c3d4-...",
    "merchant_id": "e5f6g7h8-...",
    "status": "captured",
    "amount": {
      "cents": 5000,
      "currency": "USD",
      "formatted": "$50.00"
    },
    "fee_cents": 175,
    "net_cents": 4825,
    "card_last_four": "4242",
    "card_brand": "visa",
    "fraud_score": "0.0312",
    "fraud_decision": "pass",
    "idempotency_key": "idem_abc123",
    "created_at": "2026-03-06T10:30:00Z"
  },
  "meta": {
    "request_id": "req_01DEF...",
    "processing_time_ms": 42,
    "idempotency_key": "idem_abc123"
  }
}

5Capture & Manage

Authorized payments can be captured, refunded, or voided. The Saga orchestrator handles the full lifecycle automatically after creation — but you can also manage each step manually.

Capturebash
POST /api/v1/transactions/:id/capture
{ "amount_cents": 5000 }
Refundbash
POST /api/v1/transactions/:id/refund
{ "amount_cents": 2500 }
Voidbash
POST /api/v1/transactions/:id/void

Key Concepts

Payment Lifecycle

Transactions flow through a deterministic state machine: initiated -> authorized -> captured -> settled. Each transition is an immutable event.

Fraud Scoring

Every transaction is scored by a LightGBM model (0.0 to 1.0). SHAP explanations show which features contributed to the score.

Idempotency

Include X-Idempotency-Key on POST requests. Retrying with the same key returns the original response without re-processing.

Event Sourcing

Every state change is an immutable event stored in Rails Event Store. Query /transactions/:id/events for a complete audit trail.

What's Next?

Explore the full API reference

All endpoints with request/response examples

Set up webhooks

Receive real-time event notifications

Understand the architecture

Event sourcing, CQRS, and domain design